Performance Monitoring in the SerModuleROM Sample

Performance Monitoring in the SerModuleROM Sample

The SerModuleROM sample now includes simple, conditionally compiled performance monitoring capability. Performance monitoring is enabled in the sample serial library by building it with PERF_MON defined. For example, executing the following commands from the shell in the SerModuleROM\Libraries\Ser16650\Build folder:

make clean make ExtraCFlags="-DPERF_MON"

will build the library with performance monitoring support enabled by defining the macro PERF_MON for the C compilations. Execute "make clean" first to make sure that all serial library source files get rebuilt with the extra C flags.

The actual performance monitoring settings are recorded by the serial library in the HsSerModPerfType structure(defined in HsSerModulePublic.h under SerModuleROM/Incs)that resides in the Card globals, which are managed by the CardSetup utility. This way, the performance monitoring settings persist even when the serial library is closed, and its globals are freed. However, the performance monitoring settings will be lost as soon as the module is removed from the handheld, or the handheld is reset. In your own module's code, you may want to store these settings in less volatile storage, so the data may be available even after a crash and/or system reset.

The CardSetup utility handles performance monitoring-related commands via the hsSerModCmdProcessRequest action code (see HsSerModulePublic.h). An action code may be sent to enable, disable, clear, and retrieve performance monitoring information (look for hsSerModCmdProcessRequest in CardSetup.c).

The SerialDiag application (under SerModuleROM/Apps) is a simple "stdio" application for communicating with the CardSetup utility to enable, disable, clear, and retrieve performance monitoring information. Commands may be executed from its scrolling text field by entering the name and arguments of the command followed by the return Graffiti stroke (upper right to lower left). You can execute the "help" command (without the quotes) to see a listing of all supported commands. You can get more help on each individual command by executing "help CmdName" (without the quotes), where CmdName is the name of the particular command. For ease of use, the current commands may also be executed from SerialDiag's Misc menu.

Once you have a module that contains the ROM image with the Serial Library that was built with PERF_MON defined (see above), insert the module into the handheld. Make sure that the SerialDiag app is also on the handheld (HotSync or beam it to the handheld, if necessary). Enable performance monitoring from SerialDiag's Misc menu. Then perform serial communications that uses the serial library being monitored (such as Network HotSync, Modem HotSync, Web Browsing, Faxing, etc.). Now, go back to the SerialDiag app, and use its Misc menu to display the performance monitoring statistics. Remember, if you remove the module, or reset the handheld, you will lose the performance monitoring information.

If you would like to make changes to the performance monitoring subsystem of this sample, search for PERF_MON in the sample serial library in order to familiarize yourself with how it is currently implemented. Search for hsSerModCmdProcessRequest in the sample's CardSetup.c to learn how performance monitoring settings are changed and retrieved.

The following data points are monitored by the serial library in this sample:

typedef struct
  {
  Transmitter statistics:
  DWord	serSendCalls: # of calls to SerSend
  DWord	sendReqTotal: total # of bytes requested to send
  DWord	sendQTotal: total # of bytes actually added to transmit queue
  DWord	sendTicks: # of ticks spent in SerSend
  DWord	maxSendTicks: max # of ticks spent in SerSend
  DWord	maxSendTicksReq: SerSend request bytes of maxSendTicks
  DWord	maxSendReq: max SerSend request block size
  DWord	sendErrors: total # of send errors in SerSend
  DWord	sendTimeouts: count of SerSend timeouts
  DWord	sendTotal: total # of bytes sent to TX FIFO 
  Receiver statistics (keep in mind that the Network Library uses a "Wakeup Handler" mechanism for receiving most of its data instead of calling SerReceive):
  DWord	serReceiveCalls: # of calls to SerReceive
  DWord	recvReqTotal: total # of bytes requested to receive
  DWord	recvDQTotal: total # of bytes actually dequeued
  DWord	recvTicks: # of ticks spent in SerReceive
  DWord	maxRecvTicks: max # of ticks spent in SerReceive
  DWord	maxRecvReq: max SerReceive request block size
  DWord	recvErrors: total # of SerReceive errors
  DWord	recvTimeouts;	// count of SerReceive timeouts
  DWord	recvTotal: total # of bytes pulled from RX FIFO
  Word	lineErrors: total # of line errors
  DWord	hwOverrunErrors: # of HW Overrun errors
  Word	maxSendBurst: max number of bytes placed in the transmit FIFO during a single invocation of the ISR
  Word	maxRecvBurst: max number of bytes collected from the receive FIFO during a single invocation of the ISR
  DWord	totalISRCalls: total # of times the ISR was called
  DWord	lineErrISRTriggers: # of times the Line Error interrupt was serviced
  DWord	sendISRTriggers: # of times the Transmit Holding Register Empty interrupt was serviced
  DWord	recvISRTriggers: # of times the Receiver Ready interrupt was serviced
  DWord	msrISRTriggers: # of times the Modem Status Changed interrupt was serviced
  DWord	rtsISRTriggers: # of times the RTS & CTS interrupts were serviced
  DWord	xoffISRTriggers: # of times the XOFF interrupt was serviced
  DWord	otherISRTriggers: # of times that other, unexpected interrupts were serviced
  } HsSerModPerfType;