---

GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> EDS / V2-10-2 > eds / linux-gcc

---

         

---

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 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)
	Composes the directory of the contributor descriptors.
int	EBF_dirInit (EBF_dir *dir)
	One-time intialization function for the specified EBF_dir structure.
void	EBF_dirReset (EBF_dir *dir)
	Resets the specified EBF_dir structure, thus preparing it for the next event.
int	EBF_dirSizeof (void)
	Returns the size, in bytes, of an EBF_dir structure.
int	EBF_dirReassemble (EBF_dir *dir, unsigned int cids)
	Reassembles (that is, makes contigious) the specified contributors.
int	EBF_dirCalTkrReassemble (EBF_dir *dir, unsigned int ctids)
	Reassembles (that is, makes contigious) the specified CAL and TKR contributors.
unsigned int	EBF_dirAuxFill (EBF_dir *dir, unsigned int cids, EBF_dirAuxDscFillRtn fill_rtn, void *fill_ctx)
	Fills the auxillary descriptor with the specified list of TEM TKR lengths and ERR lengths.
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.10 2009/06/19 16:43:05 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

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

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

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

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.

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.

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

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

unsigned int EBF_dirAuxFill	(	EBF_dir *	dir,
		unsigned int	cids,
		EBF_dirAuxDscFillRtn	fill_rtn,
		void *	fill_ctx
	)

Fills the auxillary descriptor with the specified list of TEM TKR lengths and ERR lengths.

Returns:

The set of auxilliary lengths that are filled

Parameters:

	dir	The EBF directory
	cids	The list of TKR and ERR lengths to fill. This is really two 16 bit lists, with the Upper 16 bits specifying the TKR lengths to fill Lower 16 bits specifying the AUX lengths to fill
	fill_rtn	An optional user provided fill routine. Since the calculation of these lengths is potentially computationally expensive, if the user has apriori knowledge of these values, this allows the user to avoid a recomputation. If this routine is not provided, the lengths will be computed using EBF_tkrLenCalc and EBF_errLenCalc. See EBF_dirAuxTemFillRtn for the exact calling sequence.
	fill_ctx	An arbitrary context parameter provided to fill_rtn

Note:

Since the calculation of the ERR length necessarily involves calculating the size of the TKR length, the user may wish to ensure that ERR length set is a subset of the TKR set.

int EBF_dirCalTkrReassemble	(	EBF_dir *	dir,
		unsigned int	ctids
	)

Reassembles (that is, makes contigious) the specified CAL and TKR contributors.

Returns:

Status

Parameters:

	dir	The directory structure
	ctids	Bit map of the CAL/TKR contributors to reassemble, (MSB = CAL contributor 0).

On any given TEM contributor, it is possible that

• The CAL is chopped in two pieces
• The TKR is chopped in two pieces
• Both are chopped

This routine performs a rather trivial optimization, only reassembling those packets that have the contributor in question chopped. It does not go the whole way and only make the contributor in question contigious. This would be possible if, say the CAL was perfectly in tack, but the TKR spanned packets. In this case, the CAL could be left in place and the upper portion of the TKR could be moved down to join its remaining piece. It could also be possible that the CAL was chopped. In this case the lower portion of the CAL could be moved up to join the upper portion, leaving the TKR in place. If both were chopped, the most optimal move would be to move the smaller of each piece towards the large. This is way more code than can be undertaken at this time. The data structures are rich enough to accommodate this, so implementation will be deferred and the trivial optimization of only reassembly the whole contributor if either portion is requested will be made.

int EBF_dirCompose	(	EBF_dir *	dir,
		unsigned int	pktBytes,
		EBF_pkt *	pkt,
		int	siv
	)

Composes the directory of the contributor descriptors.

Returns:

A bit mask of status values, see EBF_DIR_STATUS_M If < 0, there is a serious error that likely calls into question the structural integrity of the event. Other non-zero values indicate less serious conditions. In These cases the event is can be navigated, but some of the data may be missing or in error.

Parameters:

	dir	An array of directories to be filled in
	pktBytes	The size of the packet, in bytes. This includes the 8-word packet header
	pkt	The source event packet
	siv	The state information vector. This is from EBF_sivUpdate and is used for dealing with truncated packets.

This is used to add packets to either a new or, in the case of an event spanning multiple packets, existing an existing directory. The siv, state information vector, comes from EBF_sivUpdate provides the context so that the routine knows whether the packet being added is the only packet in the event or the first, middle or last in a sequence.

A design choice was made to make the user responsible for constructing the siv. The state information vector is useful in many applications independent of the EBF_dir facility that wish to also know the context of a packet.

int EBF_dirInit

(

EBF_dir *

dir

)

One-time intialization function for the specified EBF_dir structure.

Parameters:

dir

The directory structure

int EBF_dirReassemble	(	EBF_dir *	dir,
		unsigned int	cids
	)

Reassembles (that is, makes contigious) the specified contributors.

Returns:

Status

Parameters:

	dir	The directory structure
	cids	Bit map of the contributors to reassemble, (MSB = contributor 0).

Function

This routine is used in the case of an event spanning multiple packets. It can be called only when all the packets of an event have been added by EBF_dirCompose. It is safe, but unnecessary, to call in the case of an event being confined to a single packet.

Reasemble Philosophy

The EBF directory philosophy is to do the minimum work possible. To that end, in the case of an event spanning multiple packets, EBF_dirReassembly will only make a list of specified contributors contigious in memory by eliminating the header pad area and the restart word separating subsequent packets. Contrast this with the idea of making the whole event contigious in memory.

Future Improvement

Two future improvements can be to made to the TEM contributors. The first improvement has to do with how to make a block contigious. Currently the lower portion of the block is moved up to meet the upper portion. However, the wise thing to do is move that smallest piece towards the larger. In some cases this will indeed involve moving the lower piece upwards. However in some cases this will involve moving the upper piece downwards.

A second improvement can be made because the TEM is itself composed of multiple pieces, the CAL, the TKR and optionally the TEM diagnostic block and the TKR error block. The philosophy of laziness can be taken extended to making only these sub-blocks contigious. The user can protect himself against this eventuality by using the access functions EBF_calLocate and EBF_tkrLocate to point to these subblocks.

void EBF_dirReset

(

EBF_dir *

dir

)

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

Parameters:

dir

The directory structure

int EBF_dirSizeof

(

void

)

Returns the size, in bytes, of an EBF_dir structure.

Returns:

The size, in bytes, of an EBF_dir structure

This function, while on the face of it unnecessary because the EBF_dir structure is public, allows one to construct an abstract interfaces to event decoding objects. The core interface is generally something like

• sizeof - To get the necessary amount of memory
• init - To initialize the object once allocated
• reset - To prepare it for the next event

---