EBF_dir.h File Reference

EBF dir services, Interface. More...

#include <EDS/EBF_ebw.h>
#include <EDS/EBF_ctb.h>

Classes
struct	_EBF_dirCtbDsc
	A data structure describing a contributors data. More...
struct	_EBF_dirAuxDsc
	A data structure describing a TEMs auxillary blocks, i.e. the diagnostic and error blocks. More...
struct	_EBF_dirPktDsc
	Describes one packet from the sequence of packets that comprises the event. More...
struct	_EBF_dirCtbRestart
	Contributor restart context. More...
struct	_EBF_dirTruncated
	Collections information about truncated packets/events. This is used to reassemble the contributor. More...
struct	_EBF_dirExpected
	Captures, by value, the expected values of many of the fields in the contributor header words used when checking an event for integrity. More...
struct	_EBF_dirRedux
	Encapsulates information gleaned from the event's EDW and each contributor's EBWand ESW. More...
struct	_EBF_dir
	A data structure describing all contributors data within an event. More...
Defines
#define	EBF_DIR_K_PKTS_MAX   32
	Sets the upper limit on the number of truncated packets allowed per complete event.
#define	EBF_DIR_TEMS_CAL(_ctids)   ((_ctids) & 0xffff0000)
	Extracts the left justified bit mask giving the TEMs with CAL data.
#define	EBF_DIR_TEMS_TKR(_ctids)   ((_ctids) << 16)
	Extracts the left justified bit mask giving the TEMs with TKR data.
Typedefs
typedef enum _EBF_DIR_STATUS_V	EBF_DIR_STATUS_V
	Typedef for enum _EBF_DIR_STATUS_V.
typedef enum _EBF_DIR_STATUS_M	EBF_DIR_STATUS_M
	Typedef for enum _EBF_DIR_STATUS_M.
typedef struct _EBF_dirCtbDsc	EBF_dirCtbDsc
	Typedef for struct _EBF_dirCtbDsc.
typedef struct _EBF_dirAuxDsc	EBF_dirAuxDsc
	Typedef for struct _EBF_dirAuxDsc.
typedef struct _EBF_dirPktDsc	EBF_dirPktDsc
	Typedef for EBF_dirPktDsc.
typedef struct _EBF_dirCtbRestart	EBF_dirCtbRestart
	Typedef for struct _EBF_dirCtbRestart.
typedef struct _EBF_dirTruncated	EBF_dirTruncated
	Typedef for struct _EBF_dirTruncated.
typedef struct _EBF_dirExpected	EBF_dirExpected
	Typedef for struct _EBF_dirExpected.
typedef struct _EBF_dirRedux	EBF_dirRedux
	Typedef for struct _EBF_dirRedux.
typedef struct _EBF_dir	EBF_dir
	Typedef for struct _EBF_directory.
typedef unsigned int(*	EBF_dirAuxDscFillRtn )(void *ctx, EBF_dirAuxDsc *aux, const EBF_dirCtbDsc *ctb)
	Callback routine to fill the EBF_dirAuxFill for the specified contribution.
Enumerations
enum	_EBF_DIR_STATUS_V {   EBF_DIR_STATUS_SF_V_SUMMARY = 31,   EBF_DIR_STATUS_SF_V_UNDERRUN = 30,   EBF_DIR_STATUS_SF_V_OVERRUN = 29,   EBF_DIR_STATUS_SF_V_CTB_BADLEN = 28,   EBF_DIR_STATUS_SF_V_CTB_MISSING = 27,   EBF_DIR_STATUS_SF_V_SIV = 26,   EBF_DIR_STATUS_SF_V_ESW_MISMATCH = 25,   EBF_DIR_STATUS_SF_V_EBW_MISMATCH = 24,   EBF_DIR_STATUS_SE_V_PKTS_MAX = 19,   EBF_DIR_STATUS_SE_V_SIV = 18,   EBF_DIR_STATUS_SE_V_ESW_MISMATCH = 17,   EBF_DIR_STATUS_SE_V_EBW_MISMATCH = 16,   EBF_DIR_STATUS_SW_V_SIV = 10,   EBF_DIR_STATUS_SW_V_ESW_MISMATCH = 9,   EBF_DIR_STATUS_SW_V_EBW_MISMATCH = 8,   EBF_DIR_STATUS_SI_V_SIV = 2,   EBF_DIR_STATUS_SI_V_ESW_MISMATCH = 1,   EBF_DIR_STATUS_SI_V_EBW_MISMATCH = 0 }
	Defines the error summary bits as right-justified shifts. More...
enum	_EBF_DIR_STATUS_M {   EBF_DIR_STATUS_SF_M_SUMMARY = 1 << EBF_DIR_STATUS_SF_V_SUMMARY,   EBF_DIR_STATUS_SF_M_UNDERRUN = 1 << EBF_DIR_STATUS_SF_V_UNDERRUN,   EBF_DIR_STATUS_SF_M_OVERRUN = 1 << EBF_DIR_STATUS_SF_V_OVERRUN,   EBF_DIR_STATUS_SF_M_CTB_BADLEN = 1 << EBF_DIR_STATUS_SF_V_CTB_BADLEN,   EBF_DIR_STATUS_SF_M_CTB_MISSING = 1 << EBF_DIR_STATUS_SF_V_CTB_MISSING,   EBF_DIR_STATUS_SF_M_SIV = 1 << EBF_DIR_STATUS_SF_V_SIV,   EBF_DIR_STATUS_SF_M_ESW_MISMATCH = 1 << EBF_DIR_STATUS_SF_V_ESW_MISMATCH,   EBF_DIR_STATUS_SF_M_EBW_MISMATCH = 1 << EBF_DIR_STATUS_SF_V_EBW_MISMATCH,   EBF_DIR_STATUS_SF_M_ANY = 0xff << 24,   EBF_DIR_STATUS_SE_M_PKTS_MAX = 1 << EBF_DIR_STATUS_SE_V_PKTS_MAX,   EBF_DIR_STATUS_SE_M_SIV = 1 << EBF_DIR_STATUS_SE_V_SIV,   EBF_DIR_STATUS_SE_M_ESW_MISMATCH = 1 << EBF_DIR_STATUS_SE_V_ESW_MISMATCH,   EBF_DIR_STATUS_SE_M_EBW_MISMATCH = 1 << EBF_DIR_STATUS_SE_V_EBW_MISMATCH,   EBF_DIR_STATUS_SE_M_ANY = 0xff << 16,   EBF_DIR_STATUS_SW_M_SIV = 1 << EBF_DIR_STATUS_SW_V_SIV,   EBF_DIR_STATUS_SW_M_ESW_MISMATCH = 1 << EBF_DIR_STATUS_SW_V_ESW_MISMATCH,   EBF_DIR_STATUS_SW_M_EBW_MISMATCH = 1 << EBF_DIR_STATUS_SW_V_EBW_MISMATCH,   EBF_DIR_STATUS_SW_M_ANY = 0xff << 8,   EBF_DIR_STATUS_SI_M_SIV = 1 << EBF_DIR_STATUS_SI_V_SIV,   EBF_DIR_STATUS_SI_M_ESW_MISMATCH = 1 << EBF_DIR_STATUS_SI_V_ESW_MISMATCH,   EBF_DIR_STATUS_SI_M_EBW_MISMATCH = 1 << EBF_DIR_STATUS_SI_V_EBW_MISMATCH,   EBF_DIR_STATUS_SI_M_ANY = 0xff }
	Defines the error summary bits as in-place masks. More...
Functions
int	EBF_dirCompose (EBF_dir *dir, unsigned int pktBytes, EBF_pkt *pkt, int siv)
int	EBF_dirInit (EBF_dir *dir)
void	EBF_dirReset (EBF_dir *dir)
int	EBF_dirSizeof (void)
int	EBF_dirReassemble (EBF_dir *dir, unsigned int cids)
int	EBF_dirCalTkrReassemble (EBF_dir *dir, unsigned int ctids)
unsigned int	EBF_dirAuxFill (EBF_dir *dir, unsigned int cids, EBF_dirAuxDscFillRtn fill_rtn, void *fill_ctx)
static __inline void	EBF__dirReset (EBF_dir *dir)
	Resets the specified EBF_dir structure, thus preparing it for the next event.
static __inline int	EBF__dirCtbLen (const EBF_dirCtbDsc *ctbDsc)
	Returns the length, in bytes, of contributor associated with the specified contributor descriptor.
static __inline EBF_cal *	EBF__dirCtbCalLocate (const EBF_dirCtbDsc *ctbDsc)
	Returns a pointer to the CAL contribution.
static __inline unsigned int	EBF__dirCtbCalSize (const EBF_dirCtbDsc *ctbDsc)
	Returns the size, in bytes, of the CAL contribution.
static __inline EBF_tkr *	EBF__dirCtbTkrLocate (const EBF_dirCtbDsc *ctbDsc)
	Returns a pointer to the TKR contribution.
static __inline void	EBF__dirAuxTkrLenSet (EBF_dir *dir, int temNum, int tkrLen)
	Convenience function to set the length of the TKR block in the auxillary descriptor.
static __inline void	EBF__dirAuxErrLenSet (EBF_dir *dir, int temNum, int errLen)
	Convenience function to set the length of the error block in the auxillary descriptor.
static __inline void	EBF__dirAuxDscSet (EBF_dir *dir, int temNum, int tkrLen, int auxLen)
	Convenience function to set the fields in the auxillary descriptor.

---

Detailed Description

EBF dir services, Interface.

Author:

JJRussell - russell@slac.stanford.edu

  CVS $Id: EBF_dir.h,v 1.11 2011/03/25 22:16:54 russell Exp $

This layouts out an directory used to access the various contributors to an event. The actual data structure itself is fairly complicated. To the extent possible, pieces of this data structure that are solely there for internal use have been buried one or more levels below the top structure. The user is encouraged to use the inlines when possible. This was a meager attempt to emulate the C++ concept of private and member access functions.

---

Define Documentation

#define EBF_DIR_K_PKTS_MAX   32

Sets the upper limit on the number of truncated packets allowed per complete event.

In principle, every packet could be as large as 4Kbytes and be broken into 124 byte chunks of data. This would translate into an original 4K hunk being broken into as many as 32 packets. With 18 contributors, this is a very large number. In practice, this will not happen, and if it does, it will be declared an error.

#define EBF_DIR_TEMS_CAL

(

_ctids

)

((_ctids) & 0xffff0000)

Extracts the left justified bit mask giving the TEMs with CAL data.

Returns:

The left justified bit mask of the towers with CAL data, Tower 0 = MSB

Parameters:

_ctids

The CAL/TKRs id mask

#define EBF_DIR_TEMS_TKR

(

_ctids

)

((_ctids) << 16)

Extracts the left justified bit mask giving the TEMs with TKR data.

Returns:

The left justified bit mask of the towers with TKR data, Tower 0 = MSB

Parameters:

_ctids

The CAL/TKRs id mask

---

Typedef Documentation

EBF_dirAuxDsc

Typedef for struct _EBF_dirAuxDsc.

This data structure is needed only for the TEMs and then only if the either the diagnostic or error block is present. It would be somewhat more natural to keep this data with the contributor's descriptor, EBF_dirCtbDsc, but, in order to keep a contributor's descriptor to 8 bytes, this data was separated. This makes access a little more difficult, but

1. Preserves performance from keeps descriptor block to a power of 2
2. Saves space by only defining this block for TEMs

unsigned int(* EBF_dirAuxDscFillRtn)(void *ctx, EBF_dirAuxDsc *dsc, const EBF_dirCtbDsc *ctb)

Callback routine to fill the EBF_dirAuxFill for the specified contribution.

Returns:

Bit mask of the values filled. There should only be at most two bits set, one for the TKR length (in the appropiate bit position for this contribution in the upper 16 bits) and one for the AUX length (in he appropriate bit position in the lower 16 bits.

Parameters:

	ctx	A context parameter
	aux	The auxilliary descriptor to fill
	ctb	The contributor descriptor

EBF_dirCtbDsc

Typedef for struct _EBF_dirCtbDsc.

Warning:

Although this structure is publically accessible, the most common usage is to locate the CAL and TKR data structures. For these user is encouraged to use EBF__dirCtbCalLocate and EBF__dirCtbTkrLocate to protect themselves against future changes. Note that since these are inlines, this is a compile-time protection, not a run-time protection If this structure does change, the code must be recompiled and relinked.

EBF_dirCtbRestart

Typedef for struct _EBF_dirCtbRestart.

This is a temporary structure used to maintain context information about the current contributor across truncated packets. Once the contributor is has been fully procesed this structure is useless.

One could make an argument that this context does not belong with the EBF_dir structure on the grounds that it is totally for internal use and once all the packets have been processed there is no point in caring it around. If this were a large structure, doing something else might have some merit. But given it is small, there is no use in complicating the interface.

Warning:

This structure is not meant to be publically accessible. It should be treated like a private member in C++.

EBF_dirPktDsc

Typedef for EBF_dirPktDsc.

Because of packet truncation, each complete event may be comprised of one or more packets. This list keeps of track of packets for truncated contributors.

EBF_dirRedux

Typedef for struct _EBF_dirRedux.

The idea is that the information in this structure can be generated solely from the information in the Event Descriptor Word (edw) and the Event Builder Word (ebw) and the Event Summary Words of the contribution packet header. This was violated only by the inclusion of the 32-bit mask giving the CAL and TKR contributions.

Note:

The name of this structure was pondered for quite a good measure of time. Credit (blame?) goes to APW.

EBF_dirTruncated

Typedef for struct _EBF_dirTruncated.

Warning:

This structure is not meant to be publically accessible. It should be treated like a private member in C++.

---

Enumeration Type Documentation

enum _EBF_DIR_STATUS_M

Defines the error summary bits as in-place masks.

Enumerator:

EBF_DIR_STATUS_SF_M_SUMMARY	This event has a serious to fatal error, consult the remaining error bits for the exact syndrome.
EBF_DIR_STATUS_SF_M_UNDERRUN	There was not enough data to satisfy the demands. This may indicate, for example, that the data ran out before a contributor said it should.
EBF_DIR_STATUS_SF_M_OVERRUN	Too much data was left at the end of decoding (since the packet is rounded up to 128 bytes, there must be less than 128 bytes left, in practice, since everything is 4 bytes in size, it must be <= 124
EBF_DIR_STATUS_SF_M_CTB_BADLEN	A contributor had a cell length less than the minimum size
EBF_DIR_STATUS_SF_M_CTB_MISSING	Missing contributors, all expected contributors did not show up
EBF_DIR_STATUS_SF_M_SIV	State Information Vector is in error
EBF_DIR_STATUS_SF_M_ESW_MISMATCH	Event Summary Word mismatch is at the fatal level
EBF_DIR_STATUS_SF_M_EBW_MISMATCH	Event Builder Word mismatch is at the fatal level
EBF_DIR_STATUS_SF_M_ANY	Any fatal error present
EBF_DIR_STATUS_SE_M_SIV	State Information Vector is in error
EBF_DIR_STATUS_SE_M_ESW_MISMATCH	Event Summary Word mismatch is at the error level
EBF_DIR_STATUS_SE_M_EBW_MISMATCH	Event Builder Word mismatch is at the error level
EBF_DIR_STATUS_SE_M_ANY	Any sever error present
EBF_DIR_STATUS_SW_M_SIV	State Information Vector is in warning
EBF_DIR_STATUS_SW_M_ESW_MISMATCH	Event Summary Word mismatch is at the warning level
EBF_DIR_STATUS_SW_M_EBW_MISMATCH	Event Builder Word mismatch is at the warning level
EBF_DIR_STATUS_SW_M_ANY	Any warning present
EBF_DIR_STATUS_SI_M_SIV	State Information Vector is at the informational level
EBF_DIR_STATUS_SI_M_ESW_MISMATCH	Event Summary Word mismatch is at the informational level
EBF_DIR_STATUS_SI_M_EBW_MISMATCH	Event Builder Word mismatch is at the informational level
EBF_DIR_STATUS_SI_M_ANY	Any informational error present

enum _EBF_DIR_STATUS_V

Defines the error summary bits as right-justified shifts.

Enumerator:

EBF_DIR_STATUS_SF_V_SUMMARY	This event has a serious to fatal error, consult the remaining error bits for the exact syndrome.
EBF_DIR_STATUS_SF_V_UNDERRUN	There was not enough data to satisfy the demands. This may indicate, for example, that the data ran out before a contributor said it should.
EBF_DIR_STATUS_SF_V_OVERRUN	Too much data was left at the end of decoding (since the packet is rounded up to 128 bytes, there must be less than 128 bytes left, in practice, since everythin is 4 bytes in size, it must be < 124
EBF_DIR_STATUS_SF_V_CTB_BADLEN	A contributor had a cell length less than the minimum size
EBF_DIR_STATUS_SF_V_CTB_MISSING	Missing contributors, all expected contributors did not show up
EBF_DIR_STATUS_SF_V_SIV	State Information Vector error is fatal
EBF_DIR_STATUS_SF_V_ESW_MISMATCH	Event Summary Word mismatch is at the fatal level
EBF_DIR_STATUS_SF_V_EBW_MISMATCH	Event Builder Word mismatch is at the fatal level
EBF_DIR_STATUS_SE_V_SIV	State Information Vector is in error
EBF_DIR_STATUS_SE_V_ESW_MISMATCH	Event Summary Word mismatch is at the error level
EBF_DIR_STATUS_SE_V_EBW_MISMATCH	Event Builder Word mismatch is at the error level
EBF_DIR_STATUS_SW_V_SIV	State Information Vector is in warning
EBF_DIR_STATUS_SW_V_ESW_MISMATCH	Event Summary Word mismatch is at the warning level
EBF_DIR_STATUS_SW_V_EBW_MISMATCH	Event Builder Word mismatch is at the warning level
EBF_DIR_STATUS_SI_V_SIV	State Information Vector is at the informational level
EBF_DIR_STATUS_SI_V_ESW_MISMATCH	Event Summary Word mismatch is at the informational level
EBF_DIR_STATUS_SI_V_EBW_MISMATCH	Event Builder Word mismatch is at the informational level

---

Function Documentation

static __inline void EBF__dirAuxDscSet	(	EBF_dir *	dir,
		int	temNum,
		int	tkrLen,
		int	errLen
	)			[static]

Convenience function to set the fields in the auxillary descriptor.

Parameters:

	dir	The EBF directory structure
	temNum	The target TEM
	tkrLen	The length, in bytes, of the TKR block
	errLen	The length, in bytes, of the error block

References _EBF_dir::auxs, _EBF_dirAuxDsc::errLen, and _EBF_dirAuxDsc::tkrLen.

static __inline void EBF__dirAuxErrLenSet	(	EBF_dir *	dir,
		int	temNum,
		int	errLen
	)			[static]

Convenience function to set the length of the error block in the auxillary descriptor.

Parameters:

	dir	The EBF directory structure
	temNum	The target TEM
	errLen	The length, in bytes, of the error block

References _EBF_dir::auxs, and _EBF_dirAuxDsc::errLen.

static __inline void EBF__dirAuxTkrLenSet	(	EBF_dir *	dir,
		int	temNum,
		int	tkrLen
	)			[static]

Convenience function to set the length of the TKR block in the auxillary descriptor.

Parameters:

	dir	The EBF directory structure
	temNum	The target TEM
	tkrLen	The length, in bytes, of the TKR block

References _EBF_dir::auxs, and _EBF_dirAuxDsc::tkrLen.

static __inline EBF_cal * EBF__dirCtbCalLocate

(

const EBF_dirCtbDsc *

ctbDsc

)

[static]

Returns a pointer to the CAL contribution.

Returns:

A pointer to the CAL contribution

Parameters:

ctbDsc

The TEM's contributor descriptor.

Warning:

This is meant to be a very light weight routine. It is assumed the contributor descriptor being passed in is a valid TEM contributor descriptor for this event. It is an error to pass in a contributor descriptor that is not valid because

1. this TEM does not contribute to this event
2. this is not a TEM contributor descriptor

References _EBF_dirCtbDsc::ctb, and _EBF_ctb::dat.

static __inline unsigned int EBF__dirCtbCalSize

(

const EBF_dirCtbDsc *

ctbDsc

)

[static]

Returns the size, in bytes, of the CAL contribution.

Returns:

The size, in bytes, of the CAL contribution

Parameters:

ctbDsc

The TEM's contributor descriptor.

Note:

The equivalent routine for the TKR does not exist. Finding the length of the TKR contribution is a heavyweight exercise. These inlines are meant to be lightweight; essentially when using these inlines the caller has some confidence that the routine is lightweight and exists only to provide some compile time protection against changes. In this routine, a somewhat non-straightforward, but efficient method is used to calcluate the size of the CAL. By encapsulating this in an inline the user gets the efficiency without directly tapping into the assumptions.

To get the tracker length without unpacking the tracker see EBF_tkrLenCalc and related routines.

References _EBF_dirCtbDsc::tkroff.

static __inline int EBF__dirCtbLen

(

const EBF_dirCtbDsc *

ctbDsc

)

[static]

Returns the length, in bytes, of contributor associated with the specified contributor descriptor.

Returns:

The length, in bytes, of contributor associated with the specified contributor descriptor.

Parameters:

ctbDsc

The contributor's descriptor.

References _EBF_ebw::bf, _EBF_dirCtbDsc::ctb, EBF_EBW_LEN_TO_BYTES, _EBF_ctbHdr::ebw, and _EBF_ctb::hdr.

static __inline EBF_tkr * EBF__dirCtbTkrLocate

(

const EBF_dirCtbDsc *

ctbDsc

)

[static]

Returns a pointer to the TKR contribution.

Returns:

A pointer to the TKR contribution

Parameters:

ctbDsc

The TEM's contributor descriptor.

Warning:

This is meant to be a very light weight routine. It is assumed the contributor descriptor being passed in is a valid TEM contributor descriptor for this event. It is an error to pass in a contributor descriptor that is not valid because

1. this TEM does not contribute to this event
2. this is not a TEM contributor descriptor

References _EBF_dirCtbDsc::ctb, and _EBF_dirCtbDsc::tkroff.

static __inline void EBF__dirReset

(

EBF_dir *

dir

)

[static]

Resets the specified EBF_dir structure, thus preparing it for the next event.

Parameters:

dir

The directory structure

References _EBF_dir::pkt.