QSEP.h File Reference

Interface to physics event context handling and updating routines. More...

Typedefs
typedef enum _QSEP_STATUS_K	QSEP_STATUS_K
	Typedef for QSEP_STATUS_K.
Enumerations
enum	_QSEP_STATUS_K {   QSEP_STATUS_K_ERR = -1,   QSEP_STATUS_K_TOO_SMALL = -2,   QSEP_STATUS_K_INSRSC = -3,   QSEP_STATUS_K_UNKLVL = -7,   QSEP_STATUS_K_NOGEM = -8,   QSEP_STATUS_K_UNDRUN = -9,   QSEP_STATUS_K_OVRRUN = -10,   QSEP_STATUS_K_INCLEN = -11,   QSEP_STATUS_K_DECOMPRESS = -12,   QSEP_STATUS_K_CHECKSUM = -13,   QSEP_STATUS_K_LAST_VALID = -13 }
	Enumeration of the status codes. More...
Functions
QSEP *	QSEP_alloc (int resource_level)
	Allocates and constructs the QSEP handle.
int	QSEP_ebfSizeof (void)
	Returns the maximum size, in bytes, of an EBF event.
void	QSEP_updateAtDatagram (QSEP *qsep, const LSF_datagram *dgm)
	Updates the run oriented information in the event context using the information from the event datagram.
void	QSEP_updateAtContribution (QSEP *qsep, const LSF_contribution *ctb)
	Updates the context based on the contribution.
int	QSEP_updateAtRecord (QSEP *qsep, const LSF_record *rec)
	Updates the context based on the record.
int	QSEP_expand (QSEP *qsep, const LSF_record *rec, QSE_ebfEvt *ebf, int ebf_size, unsigned int *ret_size)
	Expands the event into EBF format.
void	QSEP_destruct (QSEP *qsep)
	Destroys the QSEP handle.
const char *	QSEP_statusString (int status)
	Translates a QSEP status code to a string.
const QSE_ctx *	QSEP_stdCtxGet (const QSEP *qsep)
	Return a pointer to the standard QSE context block.
const QSEP_ctx *	QSEP_appCtxGet (const QSEP *qsep)
	Return a pointer to the public QSEP application specific context block.
int	QSEP_sizeof (unsigned int resource_level, void *prm)
	Returns the size, in bytes, of the handle for updating the standard event meta-information.
QSEP *	QSEP_construct (QSEP *qsep, unsigned int resource_level, void *prm)
	Construct (initializes) the handle for updating the standard event meta-information.

---

Detailed Description

Interface to physics event context handling and updating routines.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: QSEP.h,v 1.9 2011/03/29 18:49:03 russell Exp $

---

Typedef Documentation

QSEP_STATUS_K

Typedef for QSEP_STATUS_K.

The errors breakdown into roughly two categories

1. User errors
2. Internal errors

User Errors

Currently there are two user errors.

1. Attempting to decode an event with compression level that exceeds what the user configured the decoder to handle. This maximum level is specified when allocating the QSEP handle.
2. The user specified an output buffer that was too small to accommodate the event.

Internal Errors

The candidates for causing these errors are

1. Internal error on the encoding side, i.e. the software that formatted and wrote the event out has an error.
2. Internal error on the decoding side, i.e. the software that is decoding the event has an error.
3. The input data was corrupted (for example a memory overwrite) after it was read in.

---

Enumeration Type Documentation

enum _QSEP_STATUS_K

Enumeration of the status codes.

Enumerator:

QSEP_STATUS_K_ERR	Generic failure
QSEP_STATUS_K_TOO_SMALL	The user provided buffer is too small to accommodate the expanded event.
QSEP_STATUS_K_INSRSC	Insuffient resources to expand the requested input event format/compression level. The format/compression level is one of the known formats, but the user did not configure the expansion software with sufficient resources to handle it
QSEP_STATUS_K_UNKLVL	Unknown input event format/compression level. This is likely an internal error or an attempt to use an older version of the QSEP code that did not, at that time, support the specified format/compression level
QSEP_STATUS_K_NOGEM	The GEM contribution could not be located in the input data. Without the GEM contribution, the extended counter information cannot be updated. This is likely caused by an internal error. It is possible that there is a bug in the encoding/decoding of the data or that the input data was somehow corrupted.
QSEP_STATUS_K_UNDRUN	There was data left in the input after the event expansion thought it had completed. This is likely caused by an internal error. It is possible that there is a bug in the encoding/decoding of the data or that the input data was somehow corrupted.
QSEP_STATUS_K_OVRRUN	The input data was exhausted before the expansion thought it had completed. This is likely caused by an internal error. It is possible that there is a bug in the encoding/decoding of the data or that the input data was somehow corrupted.
QSEP_STATUS_K_INCLEN	An inconsistency in the calculation of the number of bytes to in the output stream and actual number. This is purely an internal error in the expansion/unpacking routines
QSEP_STATUS_K_DECOMPRESS	Decompression failure. This is purely an internal error likely within the compression/decompression routines
QSEP_STATUS_K_CHECKSUM	Checksum failure. This can be either an internal error, or more likely, a hardware failure that violated an assumption made by the compression routines
QSEP_STATUS_K_LAST_VALID	Last valid status code

---

Function Documentation

QSEP* QSEP_alloc

(

int

resource_level

)

Allocates and constructs the QSEP handle.

Returns:

A pointer to the allocated and constructed QSEP handle

Parameters:

resource_level

The maximum resource level that is needed

Warning:

Setting the resource_level parameter to a high value to be safe may result in the attempting to garner resources that only are not necessary but may not be available. For example, the highest levels of compression need access to CAL pedestal files. In this case, QSEP_construct will attempt to open the files and if they cannot be located, will fail.

In this case, this routine may have needlessly failed. The watch word here is set it only as high as necessary.

References QSEP_construct().

const QSEP_ctx* QSEP_appCtxGet

(

const QSEP *

qsep

)

Return a pointer to the public QSEP application specific context block.

Returns:

A pointer to the QSEP application specific context block

Parameters:

qsep

The physics event handle

This routine is just an accessor to keep the structure of QSEP private.

References _QSEP::atx.

QSEP* QSEP_construct	(	QSEP *	qsep,
		unsigned int	resource_level,
		void *	prm
	)

Construct (initializes) the handle for updating the standard event meta-information.

Returns:

The QSEP context structure or NULL on error

Parameters:

	qsep	The handle to initialize, if specified as NULL, one will be allocated
	resource_level	The maximum resource level. Attempts to expand event with resources needs above this value will return QSEP_STATUS_K_INSRSC, that is INSUFFICIENT RESOURCES.
	prm	A run-time set parameter used to stylize the configuration

References _QSEP::atx, _QSEP::ctx, _QSEP::dtx, _QSEP::evt, _QSEP::free, QSEP_ctxConstruct(), qsep_dtx_construct(), qsep_file_ctx_get(), and QSEP_sizeof().

Referenced by QSEP_alloc().

void QSEP_destruct

(

QSEP *

qsep

)

Destroys the QSEP handle.

Returns:

The QSEP context structure

Parameters:

qsep

The handle to destroy

References _QSEP::free.

int QSEP_ebfSizeof

(

void

)

Returns the maximum size, in bytes, of an EBF event.

Returns:

The maximum size, in bytes, of an EBF event

int QSEP_expand	(	QSEP *	qsep,
		const LSF_record *	rec,
		QSE_ebfEvt *	ebf,
		int	ebf_size,
		unsigned int *	ret_size
	)

Expands the event into EBF format.

Return values:

	0,Successful	expand
	<0,Failute,see	the enumeration QSEP_STATUS_K for the reasons

Parameters:

	qsep	The physics event handle
	rec	The LSF record containing the event
	ebf	The ebf buffer to expand the event into, this pointer must be 32-bit aligned
	ebf_size	The size, in bytes, of the buffer
	ret_size	Returned as the status of the expand

This just launders the call

References _QSEP_dtxEvt::decode, _QSEP::dtx, and _QSEP_dtx::evt.

int QSEP_sizeof	(	unsigned int	resource_level,
		void *	prm
	)

Returns the size, in bytes, of the handle for updating the standard event meta-information.

Returns:

The size, in bytes, of the handle for updating the standard event meta-information

Parameters:

	resource_level	The maximum resource level. Attempts to expand event with compression levels that use resources beyond this value will return QSEP_STATUS_K_INSRSC that is INSUFFICIENT RESOURCES. This must be a number between 0 and 15. This parameter plus prm must also be passed to QSEP_construct
	prm	A run-time set parameter used to stylize the configuration. This parameter plus max_level must also be passed to QSEP_construct.

References QDFP_ctxSizeof(), QDFP_evtSizeof(), and RND8.

Referenced by QSEP_construct().

const char* QSEP_statusString

(

int

status

)

Translates a QSEP status code to a string.

Returns:

Pointer to the string

Parameters:

status

The status code to translate

References QSEP_STATUS_K_LAST_VALID.

const QSE_ctx* QSEP_stdCtxGet

(

const QSEP *

qsep

)

Return a pointer to the standard QSE context block.

Returns:

A pointer to the QSE context block

Parameters:

qsep

The physics event handle

This routine is just an accessor to keep the structure of QSEP private.

References _QSEP::ctx.

void QSEP_updateAtContribution	(	QSEP *	qsep,
		const LSF_contribution *	ctb
	)

Updates the context based on the contribution.

Return values:

	0,if	the contribution is non-record
	1,if	the contribution is an contribution

Parameters:

	qsep	The physics event handle to update
	ctb	The contribution

References _QSEP::ctx, _QSEP::dtx, _QSEP_dtx::evt, QSEP_evt0_update(), QSEP_evt2_update(), QSEP_evt3_update(), and _QSEP_dtxEvt::update.

void QSEP_updateAtDatagram	(	QSEP *	qsep,
		const LSF_datagram *	dgm
	)

Updates the run oriented information in the event context using the information from the event datagram.

Parameters:

	qsep	The physics event handle
	dgm	The event datagram

Note:

The root contribution is opaque to the caller, so QSEP must handle the contributions within the root. There are two strategies one could use

1. Call LSF_scanContribtions and let it parse through them and invoke a user call back routine
2. Do the scan by hand.

Initially I have opted for strategy #1, but the second strategy makes detailed error checking easier. For example, if the sequence of the contributions is fixed, it is likely easier to do this when doing the scan by hand.

References _RootUpdateCtx::chg, _QSEP::ctx, _RootUpdateCtx::flags, _RootUpdateCtx::qsep, root_update(), and _RootUpdateCtx::tim.

int QSEP_updateAtRecord	(	QSEP *	qsep,
		const LSF_record *	rec
	)

Updates the context based on the record.

Return values:

	Positive	values indicate a successful update to an event record
	Negative	values indicate an unsuccessful update to an event record
	0	indicates that this was not an event record

Parameters:

	qsep	The physics event handle to update
	rec	The event record

References _QSEP::ctx, _QSEP::dtx, _QSEP_dtx::evt, and _QSEP_dtxEvt::update.