LCBD_stats.c File Reference

Implements the LCBD Statistics routines. More...

#include <LCBD/LCBD_stats.h>
#include <LCBD/LCBD_msgs.h>
#include <LCBD_p.h>
#include <PBS/MTX.ih>
#include <PBI/Attribute.h>
#include <string.h>
#include <stdio.h>

Functions
static __inline void	update_32 (unsigned int *dst, unsigned int *ledger, const unsigned int *cur, int cnt)
	Updates the 32-bit oriented statistics by adding the current statistics to the ledger and storing the result both in the ledger and the destination.
static __inline void	update_evt_proto (LCBD_stats_evt_proto *dst, LCBD_stats_evt_proto *ledger, const LCBD_stats_evt_proto *cur, int cnt)
	Updates the event protocol statistics of the EVT block.
static __inline void	sub_32 (unsigned int *c, const unsigned int *a, const unsigned int *b, int cnt)
	Sums the 32-bit oriented statistics of the ISR/RESULT & EVT block.
static __inline void	sub_evt_proto (LCBD_stats_evt_proto *c, const LCBD_stats_evt_proto *b, const LCBD_stats_evt_proto *a, int cnt)
	Sums the event protocol statistics of the EVT block.
static void	update (LCBD_stats *dst, LCBD_stats *ledger, const LCBD_stats *cur)
	Updates the statistics by adding the cur to the ledger and storing the result both in the ledger and the dst.
unsigned int	LCBD_stats_init (LCBD_scb *scb)
	Initializes the statistics control block.
unsigned int	LCBD_stats_destroy (LCBD_scb *scb)
	Destroys the statistics control block.
unsigned int	LCBD_stats_get (const LCBD lcb, LCBD_stats *stats)
	Retrieves a copy of the current statistics.
unsigned int	LCBD_stats_clr (LCBD lcb)
	Clears the statistics block.
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.
static void	putSeparator (int type)
	Puts a separator line out.
static void	putRow (const char t0, const char *title, const unsigned int *cnts, int stride)
	Internal routine to format one row of the LCBD_evt_stats display.
static __inline void	putEvtProtoTitle (void)
	Internal routine to output the title line for the event protocol statitics.
static void	putEvtProtoRow (const char *title, unsigned int rcnts, unsigned long long int rwrds, unsigned int fcnts, unsigned int fcall, unsigned long long int fwrds)
	Internal routine to format one row of the LCBD_stats_evt_proto display.
static __inline void	putEvtHandler (const LCBD_stats_evt *evt)
	Outputs the LCBD_stats_evt that are accumulated in the event handler.
static __inline void	putEvtTickle (const LCBD_stats_evt_tickle *tickle)
	Outputs the LCBD_evt_tickle statistics.
static __inline void	putEvtProto (const LCBD_stats_evt_proto *proto)
	Outputs that portion of the event statistics that is by protocol.
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

Implements the LCBD Statistics routines.

Author:

Curt Brune -- curt@slac.stanford.edu

JJRussell -- russell@slac.stanford.edu

  CVS $Id

In order to achieve the twin goals of consistent statistics and not locking for too long a period of time, the method chosen shifts the the burden to user context. The locking period lasts only as long as it takes to swap two pointers. This method rests on maining 3 logical buffers

1. An active buffer, where the statistics are currently being accumulated
2. A running total buffer, referred to as the ledger, which, when added to the current buffer reflects the statistics to-date
3. A clear buffer

How the statistics are kept

When a request is made to fetch the statistics, a pointer to the active is swapped for a pointer to cleared buffer. This swap is performed with interrupts locked out. A second level of locking, based on a mutex associated with the statistics block protects the bloc while a new buffer is being cleared and the @ active buffer is added to the ledger. Doing this ensures that the next call to fetch the statistics will always find a cleared buffer and that the ledger buffer when added to the active bufer will reflect the current statistics.

The Cost of this Scheme

The price one pays for achieveing consistent statistics and low interrupt locking time is an additional copy of the data in the form of clearing a buffer, adding to the running total and making a copy for the user.

Clearing the Statistics

While a call to clear the statistics is provided, the user is discouraged from using it, since this clears the statistics for everyone in the system. Rather the user should maintain a baseline of the statistics block and subtract it from the current running total. The baseline statistics block would be gathered at the same time one would have called the clear routine. A routine to subtract the baseline from the current set is provided for user convenience. Using this scheme, multiple users can keep statistics for whatever time period or time periods he wishes without affecting other users.

---

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.

References _LCBD_scb::active, _LCBD_stats_tim::beg, _LCBD_scb::clear, _LCBD_scb::ledgerValid, _LCBD_scb::mutex, and _LCBD_stats::tim.

unsigned int LCBD_stats_destroy

(

LCBD_scb *

scb

)

Destroys the statistics control block.

Return values:

	LCBD_OK,on	success
	Anything	else, failure

Parameters:

scb

Pointer to the statistics control block to destroy

References LCBD_OK, _LCBD_scb::ledgerValid, and _LCBD_scb::mutex.

Referenced by destroy_sw().

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

References _LCBD_stats_evt::proto, putEvtHandler(), putEvtProto(), putEvtTickle(), and _LCBD_stats_evt::tickle.

Referenced by LCBD_stats_show().

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

References _LCBD_scb::active, _LCBD_stats_tim::beg, _LCBD_scb::clear, _LCBD_stats_tim::end, _LCBD_scb::ledger, _LCBD_scb::ledgerValid, _LCBD_scb::mutex, _LCBD_stats::tim, and update().

unsigned int LCBD_stats_init

(

LCBD_scb *

scb

)

Initializes the statistics control block.

Return values:

	LCBD_OK,on	success
	LCBD_STATSIFL,on	failure

Parameters:

scb

Pointer to the statistics control block to initialize

References _LCBD_scb::active, _LCBD_stats_tim::beg, _LCBD_scb::clear, LCBD_OK, _LCBD_scb::ledger, _LCBD_scb::ledgerValid, _LCBD_scb::mutex, _LCBD_scb::stats, and _LCBD_stats::tim.

Referenced by init_sw().

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

References _LCBD_stats_isr::err, _LCBD_stats_isr::evt, and _LCBD_stats_isr::srcs.

Referenced by LCBD_stats_show().

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

References _LCBD_stats_rst::cnts, LCB_RST_ERR_XFR_IN_PCI_MASTER_ABORT, LCB_RST_ERR_XFR_IN_PCI_PARITY_ERROR, LCB_RST_ERR_XFR_IN_PCI_TARGET_ABORT, LCB_RST_ERR_XFR_IN_SUCCESS, LCB_RST_ERR_XFR_IN_UNDEFINED_4, LCB_RST_ERR_XFR_IN_UNDEFINED_5, LCB_RST_ERR_XFR_IN_UNDEFINED_6, LCB_RST_ERR_XFR_IN_UNDEFINED_7, LCB_RST_ERR_XFR_OUT_BUFFER_EMPTY, LCB_RST_ERR_XFR_OUT_PCI_MASTER_ABORT, LCB_RST_ERR_XFR_OUT_PCI_PARITY_ERROR, LCB_RST_ERR_XFR_OUT_PCI_TARGET_ABORT, LCB_RST_ERR_XFR_OUT_Q_EMPTY, LCB_RST_ERR_XFR_OUT_SUCCESS, LCB_RST_ERR_XFR_OUT_UNDEFINED_4, LCB_RST_ERR_XFR_OUT_UNDEFINED_6, LCBD_SEQ_EMPTY, LCBD_SEQ_ORDER, LCBD_SEQ_SUCCESS, LCBD_SEQ_UNKNOWN, LCBD_STATS_RST_TX_DELETED, LCBD_STATS_RST_TX_PENDED, LCBD_STATS_RST_TX_POSTED, LCBD_STATS_RST_TX_REMOVED, _LCBD_stats_rst::null, _LCBD_stats_rst::rx, _LCBD_stats_rst::seq, and _LCBD_stats_rst::tx.

Referenced by LCBD_stats_show().

void LCBD_stats_show

(

const LCBD_stats *

stats

)

Shows (prints at the terminal) all three statistics blocks.

Parameters:

stats

The statistics block to display

References _LCBD_stats::evt, _LCBD_stats::isr, LCBD_stats_evt_show(), LCBD_stats_isr_show(), LCBD_stats_rst_show(), LCBD_stats_tim_show(), _LCBD_stats::rst, and _LCBD_stats::tim.

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.

References _LCBD_stats_tim::beg, _LCBD_stats_tim::end, _LCBD_stats::evt, _LCBD_stats::isr, LCBD_EVT_PROTO_CNT, _LCBD_stats_evt::proto, sub_32(), sub_evt_proto(), and _LCBD_stats::tim.

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

References _LCBD_stats_tim::beg, and _LCBD_stats_tim::end.

Referenced by LCBD_stats_show().

static __inline void putEvtProto

(

const LCBD_stats_evt_proto *

proto

)

[static]

Outputs that portion of the event statistics that is by protocol.

Parameters:

proto

The event statistics by protocol to output

References _LCBD_stats_evt_proto_xct::cnts, _LCBD_stats_evt_proto::fre, LCBD_EVT_PROTO_CNT, _LCBD_stats_evt_proto_xct::nwrds, putEvtProtoRow(), putEvtProtoTitle(), putSeparator(), and _LCBD_stats_evt_proto::rcv.

Referenced by LCBD_stats_evt_show().

static void putEvtProtoRow	(	const char *	title,
		unsigned int	rcnts,
		unsigned long long int	rwrds,
		unsigned int	fcall,
		unsigned int	fcnts,
		unsigned long long int	fwrds
	)			[static]

Internal routine to format one row of the LCBD_stats_evt_proto display.

Parameters:

	title	The title line
	rcnts	The number of packets received
	rwrds	The number of 32-bit words received
	fcall	The number of calls to LCBD_evt_free
	fcnts	The number of packets actually freed
	fwrds	The number of 32-bit words freed

Referenced by putEvtProto().

static __inline void putEvtTickle

(

const LCBD_stats_evt_tickle *

tickle

)

[static]

Outputs the LCBD_evt_tickle statistics.

Parameters:

tickle

The LCBD_evt_tickle statisttics to output

References _LCBD_stats_evt_tickle::cnts, LCBD_STATS_EVT_TICKLE_K_BUSY, LCBD_STATS_EVT_TICKLE_K_EMPTY, LCBD_STATS_EVT_TICKLE_K_POSTED, and LCBD_STATS_EVT_TICKLE_K_RSVD.

Referenced by LCBD_stats_evt_show().

static void putRow	(	const char	t0,
		const char *	title,
		const unsigned int *	cnts,
		int	stride
	)			[static]

Internal routine to format one row of the LCBD_evt_stats display.

Parameters:

	t0	Leading legend character
	title	The title of this row
	cnts	The array of 4 counts to output
	stride	The number of elements between each cnt

Referenced by putEvtHandler().

static void putSeparator

(

int

type

)

[static]

Puts a separator line out.

Parameters:

type

The type of separator

Referenced by putEvtHandler(), and putEvtProto().

static __inline void sub_32	(	unsigned int *	c,
		const unsigned int *	a,
		const unsigned int *	b,
		int	cnt
	)			[static]

Sums the 32-bit oriented statistics of the ISR/RESULT & EVT block.

Parameters:

	c	The destination statistics block
	a	The statistics to subtract from
	b	The statistics to subtract
	cnt	The number of 32-bit integers to sum

Referenced by LCBD_stats_sub().

static __inline void sub_evt_proto	(	LCBD_stats_evt_proto *	c,
		const LCBD_stats_evt_proto *	b,
		const LCBD_stats_evt_proto *	a,
		int	cnt
	)			[static]

Sums the event protocol statistics of the EVT block.

Parameters:

	c	The destination event protocol statistics block
	b	The event protocol statistics to subtract from
	a	The event protocol statistics to subtract
	cnt	The number of evt proto records to subtract

References _LCBD_stats_evt_proto_xct::cnts, _LCBD_stats_evt_proto::fre, _LCBD_stats_evt_proto_xct::nwrds, and _LCBD_stats_evt_proto::rcv.

Referenced by LCBD_stats_sub().

static void update	(	LCBD_stats *	dst,
		LCBD_stats *	ledger,
		const LCBD_stats *	cur
	)			[static]

Updates the statistics by adding the cur to the ledger and storing the result both in the ledger and the dst.

Parameters:

	dst	The destination statistics block
	ledger	The ledger, or running total block
	cur	The current contribution to the running sum

References _LCBD_stats::evt, _LCBD_stats::isr, LCBD_EVT_PROTO_CNT, _LCBD_stats_evt::proto, update_32(), and update_evt_proto().

Referenced by LCBD_stats_get().

static __inline void update_32	(	unsigned int *	dst,
		unsigned int *	ledger,
		const unsigned int *	cur,
		int	cnt
	)			[static]

Updates the 32-bit oriented statistics by adding the current statistics to the ledger and storing the result both in the ledger and the destination.

Parameters:

	dst	The destination statistics block
	ledger	The ledger, or running total block
	cur	The current contribution to the running sum
	cnt	The number of 32-bit integers to sum

Referenced by update().

static __inline void update_evt_proto	(	LCBD_stats_evt_proto *	dst,
		LCBD_stats_evt_proto *	ledger,
		const LCBD_stats_evt_proto *	cur,
		int	cnt
	)			[static]

Updates the event protocol statistics of the EVT block.

Parameters:

	dst	The destination protocol statistics block
	ledger	The ledger, or running total procotol block
	cur	The current contribution to the running sum
	cnt	The number of proto records to update

References _LCBD_stats_evt_proto_xct::cnts, _LCBD_stats_evt_proto::fre, _LCBD_stats_evt_proto_xct::nwrds, and _LCBD_stats_evt_proto::rcv.

Referenced by update().