---

GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > LCBD / V1-2-10

Constituent: lcbd     Tag: rad750

---

         

---

LCBD_stats.h File Reference

Definitions of the LCBD statistics access routines. More...

#include "PBS/WCT.h"
#include "LCBD/LCBD_rst.h"
#include "LCBD/LCBD_evt.h"
#include "LCBD/LCB.h"

Include dependency graph for LCBD_stats.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	_LCBD_stats
	Encompassing structure for all the LCBD driver statistics. More...
struct	_LCBD_stats_evt
	Defines the statistics keep by the EVENT handler. More...
struct	_LCBD_stats_evt_proto
	This is a sub-structure of the LCBD event statistics, keeping track of events (messages) by protocol type. More...
struct	_LCBD_stats_evt_proto_xct
	This is a sub-structure of the LCBD event protocol statistics, keeping track of the events (packets) for a transaction. More...
struct	_LCBD_stats_evt_tickle
	Statistics about LCBD_stats_evt_tickle. More...
struct	_LCBD_stats_isr
	Defines the statistics keep by the LCBD ISR routine. More...
struct	_LCBD_stats_rst
	Defines the statistics keep by RESULT handler. More...
struct	_LCBD_stats_tim
	Information about the collection time. More...
Defines
#define	LCBD_OK   0
	Success return code, note that this is not an LCBD message code, but may be used as one.
Typedefs
typedef _LCBD_stats_tim	LCBD_stats_tim
	Typedef for struct _LCBD_stats_tim.
typedef enum _LCBD_STATS_ISR_K_EVT_QUE	LCBD_STATS_ISR_K_EVT_QUE
	Typedef for enum _LCBD_STATS_ISR_K_EVT_QUE.
typedef enum _LCBD_STATS_ISR_K_EVT_BUF	LCBD_STATS_ISR_K_EVT_BUF
	Typedef for enum _LCBD_STATS_ISR_K_EVT_BUF.
typedef _LCBD_stats_isr	LCBD_stats_isr
	Typedef for struct _LCBD_stats_isr.
typedef enum _LCBD_stats_rst_tx	LCBD_stats_rst_tx
	Typedef for enum _LCBD_stats_tx.
typedef _LCBD_stats_rst	LCBD_stats_rst
	Typedef for struct _LCBD_stats_rst.
typedef _LCBD_stats_evt_proto_xct	LCBD_stats_evt_proto_xct
	Typedef for the struct _LCBD_stats_evt_proto_xct.
typedef _LCBD_stats_evt_proto	LCBD_stats_evt_proto
	Typedef for the struct _LCBD_stats_evt_proto.
typedef enum _LCBD_STATS_EVT_TICKLE_K	LCBD_STATS_EVT_TICKLE_K
	Typedef for enum _LCBD_STATS_EVT_TICKLE_K.
typedef _LCBD_stats_evt_tickle	LCBD_stats_evt_tickle
	Typedef for LCBD_stats_evt_tickle.
typedef _LCBD_stats_evt	LCBD_stats_evt
	Typedef for struct _LCBD_stats_evt.
typedef _LCBD_stats	LCBD_stats
	Typedef for struct _LCBD_stats.
Enumerations
enum	_LCBD_STATS_ISR_K_EVT_QUE {   LCBD_STATS_ISR_K_EVT_QUE_NONE = 0,   LCBD_STATS_ISR_K_EVT_QUE_EMPTY = 1,   LCBD_STATS_ISR_K_EVT_QUE_PRESENT = 2,   LCBD_STATS_ISR_K_EVT_QUE_CNT = 3 }
	Enumerates the event que counters. More...
enum	_LCBD_STATS_ISR_K_EVT_BUF {   LCBD_STATS_ISR_K_EVT_BUF_NONE = 0,   LCBD_STATS_ISR_K_EVT_BUF_QUIET = 1,   LCBD_STATS_ISR_K_EVT_BUF_DISABLE = 2,   LCBD_STATS_ISR_K_EVT_BUF_CNT = 3 }
	Enumerates the event buffer counters. More...
enum	_LCBD_stats_rst_tx {   LCBD_STATS_RST_TX_POSTED = 0,   LCBD_STATS_RST_TX_PENDED = 1,   LCBD_STATS_RST_TX_REMOVED = 2,   LCBD_STATS_RST_TX_DELETED = 3,   LCBD_STATS_RST_TX_CNT = 4 }
	Enumerates the transmission statistics. More...
enum	_LCBD_STATS_EVT_TICKLE_K {   LCBD_STATS_EVT_TICKLE_K_EMPTY = 0,   LCBD_STATS_EVT_TICKLE_K_POSTED = 1,   LCBD_STATS_EVT_TICKLE_K_BUSY = 2,   LCBD_STATS_EVT_TICKLE_K_RSVD = 3,   LCBD_STATS_EVT_TICKLE_K_CNT = 4 }
	Enumerates the definitions of the LCBD_stats_evt_tickle statistics counters. More...
Functions
unsigned int	LCBD_stats_clr (LCBD lcb)
	Clears the statistics block.
unsigned int	LCBD_stats_get (const LCBD lcb, LCBD_stats *stats)
	Retrieves a copy of the current statistics.
void	LCBD_stats_sub (LCBD_stats *result, const LCBD_stats *stats, const LCBD_stats *base)
	Convenience function to subtract a baseline statistics block from another statistics block, storing in a destination block.
void	LCBD_stats_tim_show (const LCBD_stats_tim *tim)
	Shows (prints to standard output) the collection time data.
void	LCBD_stats_isr_show (const LCBD_stats_isr *isr)
	Shows (prints to the terminal) a display of the statistics gathered in the LCBD ISR routine.
void	LCBD_stats_rst_show (const LCBD_stats_rst *rst)
	Shows (prints to the terminal) a display of the statistics gathered in the LCBD RESULTs handler routine.
void	LCBD_stats_evt_show (const LCBD_stats_evt *evt)
	Shows (prints to the terminal) a display of the statistics gathered in the LCBD EVENTs handler routine.
void	LCBD_stats_show (const LCBD_stats *stats)
	Shows (prints at the terminal) all three statistics blocks.

---

Detailed Description

Definitions of the LCBD statistics access routines.

Author:

Curt Brune -- curt@slac.stanford.edu

JJRussell -- russell@slac.stanford.edu

  CVS $Id

---

Typedef Documentation

LCBD_stats

Typedef for struct _LCBD_stats. See also: LCBD_stats_isr LCBD_stats_rst LCBD_stats_evt

LCBD_stats_evt

Typedef for struct _LCBD_stats_evt. Event Statistics - Introduction These statistics are gathered exclusively by the event handler callback routine. Notably absent are statistics dealing with transmission. That is because transactions on the event fabric are unsolicited, i.e. they could originate from any valid LATp node. Contrast this with the result fabric where a result is received only in response to a command request. One could count the number of transaction submitted to the event fabric by the LCB. To do this, each command list submitted to the LCB would have to be scanned for event transaction. This was deemed to onerous for any perceived benefits. Per Interrupt Statistics All but one statistics pertains to transactions themselves. The one statistics that does not is a count of the number of times the event handler has been called back. Since the event handler may service many items from the event queue for each time it is called back (indeed much of the complexity of the LCB design is to reduce the number of interrupts per transaction), this counter will always be less than or at most equal to the number of transactions. This number should match the number of times the LCBD ISR routine claims it calls back the result handler. Per Transaction Statistics The remaining statistics break themselves into two pieces. Errors that occur when the event engine receives a packet off the fabric Errors that occur during the transfer of the event data across the PCI bus into the CPUs ring buffer These error sets are not mutually exclusive, i.e. it is theoritically possible to get both a receive error and a transfer error on the same packet, although in practice the implementation may not support this. Receive Status The former category consists of 3 errors Error Name Meaning Header Parity Error While receiving a packet, the Event Enginer detected a parity error in the first 16 bits of the payload (the so-called payload header. The payload contents may not be valid. The remainder of the cells following the control cell (if any) were discarded. The data field contents which are present may not be valid. Data Parity Error While receiving a packet, the Event Enginer detecter an error in the parity for one of the cells of the packet. The remainder of the cells following the cell in error (if any) were discarded. The payload contents which are present may not be valid. Packet Truncated While receiving a packet, the Event Engine assert /e pause. The /e length field reflects only that fraction of the packet received before /e pause was asserted. The remainder of the cells following the truncated cell were either discarded, or will follow in a subsequent packet. Transfer Status The possible transfer status (not including success) are Error Name Meaning PCI Master Abort To be defined PCI Parity Error To be defined PCI Target Abort To be defined Buffer Full A FIFO used as an intermediate buffer became full prematurely full during a DMA which attempted to write to the FIFO. Buffer Empty A FIFO used as an intermediate buffer became prematurely empty during a DMA which attempt to read from the FIFO. INSFMEM The transfer engine attempted to transfer an event from the EVENT buffer to a location in the circular buffer. Sufficient space was not available within the circular buffer to transfer the event. The event was discarded. I believe in the current implementation by Eric Siskind, INFSMEM can no longer occur. The Buffer Full and Buffer Empty indicate an internal LCB error. Anomalities Once a transaction is successfully received, there are a couple of analomous conditions that could occur. A zero length event An event less than 4 bytes long Both these conditions are counted. LCBD_evt_tickle statistics These two counters indicate the Number of times LCBD_evt_tickle was called and the event queue was found empty Number of times LCBD_evt_tickle was called and the event queue was found non-empty

LCBD_stats_evt_proto

Typedef for the struct _LCBD_stats_evt_proto. Event Protocol Statistics - Introduction Data arriving on the event fabric is tagged with one of four protocol types (0-3). For example, one of the protocol types is for data arriving from the instrument itself. (It is unfortunate that the term event is so overloaded with multiple meanings.) This block of statistics counts the number of packets pulled from the ring buffer and the length, in 32-bit words by protocol. Note: For performance reasons, the size of this structure should be a power of 2.

LCBD_stats_evt_proto_xct

Typedef for the struct _LCBD_stats_evt_proto_xct. Event Protocol Transactions Statistics - Introduction Each transaction packet consists of a count of the transactions and the size, in 32-bit words, of the transaction. There are currently two transactions, a receive transaction and a free transaction. At the end of the day, these two records should agree, that is the number of packets received must equal the number of packets freed and the number of 32-bit words received must equal the number of 32-bit words freed. Range limitations At the upper end of the expected rates, 10KHz and at the expected size, 1Kbyte = 256 32-bit words, the range of the number of words receive counter is only about 1/2 hr. This is not enough. The simple counters will last approximately 120 hours (5 days) at 10KHz. This be sufficient.

LCBD_stats_evt_tickle

Typedef for LCBD_stats_evt_tickle. Overview This structure maintains statistics about what happens within LCB_evt_tickle. This routine wakes-up the event handler if the event queue is non-empty and is meant to provide timely response in a system where the event highwater mark has been set to something other than interrupt on empty. Statistics The statistics maintained are the number of times LCBD_evt_tickle was called and The event queue was found to be empty The event queue was found to be non-empty There was no reason to check because the event queue is already currently being serviced. They essentially count the exit state of LCBD_evt_tickle. See also: LCBD_EVT_QUE_STATE

LCBD_stats_isr

Typedef for struct _LCBD_stats_isr. ISR Statistics - Overview This set of statistics does the accounting for what happened in the driver's ISR. It is a set of 16 numbers, counting the correlated times each possible set enabled and pending interrupts occurs. Said another way, the bit mask of the set of enabled and pending interupts is formed in the ISR. This bit mask is used as an index to increment on of the 16 possible counters. The advantage of doing it this way is that each interrupt to the CPU is counted precisely once. Thus, the sum of these 16 entries represents the total number of interupts Errors In addition 1 error counter is kept for each source. In the case of a result or event interrupt, this error counter is incremented if the associated que is found empty. In the case of the clock transition interrupts, this counter is incremented if the state of clock is not consistent. For example, if it source was a ON->OFF transition the error counter will be incremented if state of the clock is on OFF. Events For every event interrupt that is deliverd a set of 9 statistics, that can logically be thought of as 3 x 3 matrix. One dimension of 3 is Que interrupt not pending Que interrupt pending, no descriptor found Que interrupt pending, descriptor found The other dimension of 3 is Buffer full interrupt not pending Buffer full interrupt pending, event interrupt not disabled Buffer full interrupt pending, event interrupt disabled

LCBD_stats_rst

Typedef for struct _LCBD_stats_rst. Result Statistics, Introduction These statistics are, with one exception, gathered exclusively in the the results handler callback routine. The one exception is the counter counting the number of command lists transmitted by the LCB. This statistic is gathered in the routine that commits a transaction to the LCB. This routine may be called either in the context of the user submitting the request or in the context of the result handler itself, when, after retiring a completed transaction, it checks for any pending transaction on a lookaside queue. Per Interrupt Statistics All but one statistics pertains to transactions themselves. The one statistics that does not is a count of the number of times the result handler has been called back. Since the result handler may service many items from the result queue, this counter will always be less than or, at most, equal to the number of transactions. This number should match the number of times the LCBD ISR routine claims it calls back the result handler. Per Transaction Statistics The remaining statistics themselves break into two pieces. One block enumerates the fate of the transmission from the CPU to the LCB, the other block counts the fate of reception to CPU from LCB. Naturally, the latter is only counted if the former succeeds. The transmission statistics are broken into three numbers The number of transactions directly submitted to the LCB hardware The number of transactions queued to the lookaside plist before submission to the LCB hardware The number of transactions queued to the hardware from the lookaside list. Naturally, when all the transaction have been processed, the last two numbers must be the same, and the some of the first and last must be the same as the number of transactions received. Sequence Statistics In addition, once a result has been successfully received it is checked for internal consistency. Since the LCB command/response unit operates in an entirely synchronous fashion, the driver the driver can keep a queue of all outstanding operations. When a result list is received, the result list can be classified in one of the following categories The result list just completed is the expected one The result list just completed is on the list of expected result lists, but it was received out of order The result list just completed is not on the list expected result lists. The list expected result lists is empty, so the result list is not expected. This is a variation of the previous syndrome, but it is deemed special enough to count separately.

LCBD_stats_tim

Typedef for struct _LCBD_stats_tim. Records collection time information. For currently accumulating records, only the beginning time is meaningful. When the statistics are fetched (LCBD_stats_get), the end time is filled in.

---

Enumeration Type Documentation

enum _LCBD_STATS_EVT_TICKLE_K

Enumerates the definitions of the LCBD_stats_evt_tickle statistics counters. Enumeration values: LCBD_STATS_EVT_TICKLE_K_EMPTY  Found the event queue empty LCBD_STATS_EVT_TICKLE_K_POSTED  Found the event queue non-empty and posted a wake-up message to the event servicing handler LCBD_STATS_EVT_TICKLE_K_BUSY  The event queue is busy being serviced by the event handler LCBD_STATS_EVT_TICKLE_K_RSVD  Reserved for future use LCBD_STATS_EVT_TICKLE_K_CNT  The number of counters

enum _LCBD_STATS_ISR_K_EVT_BUF

Enumerates the event buffer counters. Enumeration values: LCBD_STATS_ISR_K_EVT_BUF_NONE  Buf not pending LCBD_STATS_ISR_K_EVT_BUF_QUIET  Buf pending, no action LCBD_STATS_ISR_K_EVT_BUF_DISABLE  Buf pending, disable interrupt LCBD_STATS_ISR_K_EVT_BUF_CNT  Numb1xer of event que things

enum _LCBD_STATS_ISR_K_EVT_QUE

Enumerates the event que counters. Enumeration values: LCBD_STATS_ISR_K_EVT_QUE_NONE  Que not pending LCBD_STATS_ISR_K_EVT_QUE_EMPTY  Que pending, but no descriptor LCBD_STATS_ISR_K_EVT_QUE_PRESENT  Que pending, have descriptor LCBD_STATS_ISR_K_EVT_QUE_CNT  Number of event que things

enum _LCBD_stats_rst_tx

Enumerates the transmission statistics. Enumeration values: LCBD_STATS_RST_TX_POSTED  Directly submitted LCBD_STATS_RST_TX_PENDED  Placed on pending list LCBD_STATS_RST_TX_REMOVED  Removed & submitted from the pending list LCBD_STATS_RST_TX_DELETED  Deleted without submisssion LCBD_STATS_RST_TX_CNT  Number of transmission statistics

---

Function Documentation

unsigned int LCBD_stats_clr (  LCBD  lcb  )

Clears the statistics block. Parameters: lcb  The LCB driver handle Note: The casual user is discouraged from calling this routine, since clearing the statistics block affects all customers of the LCBD statistics. Rather, the scheme outlined in the preface to these routines, whereby each user maintains a baseline statistics block that is subtracted from the current statistics block, is a much better choice.

void LCBD_stats_evt_show (  const LCBD_stats_evt *  evt  )

Shows (prints to the terminal) a display of the statistics gathered in the LCBD EVENTs handler routine. See also: LCBD_stats_evt Parameters: evt  The event statistics

Here is the call graph for this function:

unsigned int LCBD_stats_get (  const LCBD  lcb, LCBD_stats *  stats )

Retrieves a copy of the current statistics. Return values: Status.  The only real way this routine can fail is if the locking mutex has not been initialized or it has been corrupted. Parameters: lcb  The LCB driver handle stats  Area to copy the latest statistics into

Here is the call graph for this function:

void LCBD_stats_isr_show (  const LCBD_stats_isr *  isr  )

Shows (prints to the terminal) a display of the statistics gathered in the LCBD ISR routine. See also: LCBD_stats_isr Parameters: isr  The driver statistics block

void LCBD_stats_rst_show (  const LCBD_stats_rst *  rst  )

Shows (prints to the terminal) a display of the statistics gathered in the LCBD RESULTs handler routine. See also: LCBD_stats_rst Parameters: rst  The results statistics block

void LCBD_stats_show (  const LCBD_stats *  stats  )

Shows (prints at the terminal) all three statistics blocks. Parameters: stats  The statistics block to display

Here is the call graph for this function:

void LCBD_stats_sub (  LCBD_stats *  result, const LCBD_stats *  stats, const LCBD_stats *  base )

Convenience function to subtract a baseline statistics block from another statistics block, storing in a destination block. Parameters: result  The results of the subtraction stats  The statistics block to subtract from base  The baseline statistics block to subtract.

Here is the call graph for this function:

void LCBD_stats_tim_show (  const LCBD_stats_tim *  tim  )

Shows (prints to standard output) the collection time data. Parameters: tim  The collection time structure to display

---