CDF_gem.c File Reference

The GEM compressed data formatting routines. More...

#include <dprintf.h>
#include <LSE/CDF_gem.h>
#include <LSE/CDF_gemdef.h>
#include <CDF_gem_def.h>
#include <LSE/LSEW_dgmFw.h>
#include <LSE/LSEW_ctxPub.h>
#include <EDS/EBF_gem.h>
#include <LDT/BFP.h>
#include <LSE/cdf_buf_print.h>
#include <PBI/FFS.ih>
#include <string.h>

Classes
struct	_CDF_gemCfg
	Static GEM configuration, this is passed into construction routines and the information is transferred into CDF_gem_cfg. More...
Defines
#define	DEFAULT_MIN_DEADTIME   529
	Defines the default minimum deadtime.
Typedefs
typedef struct _CDF_gemCfg	CDF_gemCfg
	Typedef for struct _CDF_gemCfg.
typedef enum _Method	Method
	Typedef for enum _Method.
Enumerations
enum	_Method {   STD = 0,   PED = 1 }
	Indicates the packing method, either for standard physics events or for pedestal events. More...
Functions
static __inline void	gem_reset (CDF_gem *cdf)
	Clears stale context from the GEM compression data format handle.
static unsigned int	gem_assess (CDF_gem *cdf, const EBF_gem *gem)
	Constructs a status word consisting of the trigger condition byte and its consistency with both the primitives that set the various bits and trigger condition bit. For those trigger condition primitives that are absent, it records whether the condition arrival time is 0x1f.
static unsigned int	gem_pps_pack (CDF_gem *cdf, unsigned int *buf, unsigned int pos, const EBF_gem *gem, unsigned int not_std, unsigned int status)
	Adds the introductory bits + PPS if necessary.
static unsigned int	gem_std_pack (CDF_gem *cdf, unsigned int *buf, unsigned int pos, const EBF_gem *gem, unsigned int seq, unsigned int status)
	Adds the GEM record.
static __inline unsigned int	gem_ped_pack (CDF_gem *cdf, unsigned int *buf, unsigned int pos, const EBF_gem *gem, unsigned int seq, unsigned int status)
	Compresses the GEM data when zero suppression has been disabled.
static __inline unsigned int	gem_psbcat_set (unsigned int status, unsigned int primitive, unsigned int condtime, unsigned int psb_msk, unsigned int cat_msk)
	Sets the Primitive nd Condition Arrival Time status bits.
static __inline unsigned int	gem_pack_primitives (CDF_gem *cdf, unsigned int *buf, unsigned int pos, const EBF_gem *gem, unsigned int status)
	Packs the trigger primitives status byte plus any non-0 values.
static __inline unsigned int	gem_pack_conditions (CDF_gem *cdf, unsigned int *buf, unsigned int pos, const EBF_gem *gem, unsigned int status)
	Packs the trigger condition status.
static __inline unsigned int	gem_pack_condtimes (CDF_gem *cdf, unsigned int *buf, unsigned int pos, const EBF_gem *gem, unsigned int status)
static __inline unsigned int	gem_pack_deadzone (CDF_gem *cdf, unsigned int *buf, unsigned int pos, const EBF_gem *gem, unsigned int status)
	Packs the deadzone counter value.
static __inline unsigned int	gem_pack_times (CDF_gem *cdf, unsigned int *buf, unsigned int pos, const EBF_gem *gem, unsigned int seq)
	Packs the trigger and livetime counter values.
static __inline unsigned int	gem_pack_prescaled (CDF_gem *cdf, unsigned int *buf, unsigned int pos, const EBF_gem *gem)
	Packs the prescale counter.
static __inline unsigned int	gem_pack_discarded (CDF_gem *cdf, unsigned int *buf, unsigned int pos, const EBF_gem *gem)
	Packs the discard counter.
static __inline unsigned int	gem_pack_dwinevt (CDF_gem *cdf, unsigned int *buf, unsigned int pos, const EBF_gem *gem)
	Packs the delta Window and Event times.
static __inline unsigned int	gem_pack_acd (CDF_gem *cdf, unsigned int *buf, unsigned int pos, const EBF_gem *gem, unsigned int status)
	Adds the GEM ACD information. Since one does not expect many hits, these are packed as a list of bit addresses.
int	CDF_gemCfg_sizeof (int level)
	Returns the size, in bytes of the GEM compression configuration needed to support the specified level.
int	CDF_gemCfg_construct (CDF_gemCfg *cfg, int level, void **mem)
	Constructs the CDF_gemCfg compression configuration.
unsigned int	CDF_gemCfg_def_min_deadtime (void)
	Returns the default the minimum deadtime.
void	CDF_gemCfg_set_min_deadtime (CDF_gemCfg *cfg, int min_deadtime)
	Sets the minimum deadtime.
int	CDF_gem_sizeof (int level, const CDF_gemCfg *cfg)
	Returns the size, in bytes of the GEM compression structure needed to support the specified level.
int	CDF_gem_construct (CDF_gem *cdf, int level, const CDF_gemCfg *cfg, const LSEW_dgmFw *dgmFw, void **mem)
	Constructs the CDF_gem compression context.
void	CDF_gem_begin (CDF_gem *cdf, CDF_gemBdy *bdy)
	Fills int the GEM portion of the datagram contribution used in when decoding an GEM event.
unsigned int	CDF_gem_std_compress (CDF_gem *cdf, unsigned int *buf, unsigned int pos, const EBF_gem *gem, unsigned int seq)
	Compresses the GEM for standard zero suppressed data.
unsigned int	CDF_gem_ped_compress (CDF_gem *cdf, unsigned int *buf, unsigned int pos, const EBF_gem *gem, unsigned int seq)
	Compresses the GEM data when zero suppression has been disabled.
void	CDF_gem_update (CDF_gem *cdf, const EBF_gem *gem, unsigned int seq)
	Updates any running context.

---

Detailed Description

The GEM compressed data formatting routines.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: CDF_gem.c,v 1.10 2011/03/26 17:35:24 russell Exp $

---

Enumeration Type Documentation

enum _Method

Indicates the packing method, either for standard physics events or for pedestal events.

Enumerator:

STD	Use standard packing method
PED	Use pedestal packing method

---

Function Documentation

void CDF_gem_begin	(	CDF_gem *	cdf,
		CDF_gemBdy *	bdy
	)

Fills int the GEM portion of the datagram contribution used in when decoding an GEM event.

Parameters:

	cdf	The CDF_gem compress context structure
	bdy	The CDF_gemBdy structure to fill

References gem_reset(), _CDF_gem::min_deadtime, and _CDF_gemBdy::min_deadtime.

int CDF_gem_construct	(	CDF_gem *	cdf,
		int	level,
		const CDF_gemCfg *	cfg,
		const LSEW_dgmFw *	dgmFw,
		void **	mem
	)

Constructs the CDF_gem compression context.

Return values:

Status

Parameters:

	cdf	The CDF_gem compression context structure to fill
	level	The maximum compression level that needs to be supported
	cfg	Target specific configuration parameter
	dgmFw	The datagram framework handle
	mem	Pointer to free memory pointer, return as the the updated pointer. If cdf is equal to the current contents of mem, then mem will be advanced by the size of CDF_gem, else this routine will believe that the only the variable allocation of cdf needs to be allocated.

References _CDF_gem::cfg, DEFAULT_MIN_DEADTIME, gem_reset(), _CDF_gem::lsew_ctx, LSEW_dgmFwCtxPub(), _CDF_gemCfg::min_deadtime, and _CDF_gem_cfg::min_deadtime.

unsigned int CDF_gem_ped_compress	(	CDF_gem *	cdf,
		unsigned int *	buf,
		unsigned int	pos,
		const EBF_gem *	gem,
		unsigned int	seq
	)

Compresses the GEM data when zero suppression has been disabled.

Returns:

The updated bit write position

Parameters:

	cdf	The GEM compressed data format context
	buf	The output buffer
	pos	The current bit offset into the output buffer buf
	gem	The GEM contribution
	seq	The event sequence number

References gem_assess(), gem_ped_pack(), gem_pps_pack(), and PED.

int CDF_gem_sizeof	(	int	level,
		const CDF_gemCfg *	cfg
	)

Returns the size, in bytes of the GEM compression structure needed to support the specified level.

Parameters:

	level	The maximum compression level to support
	cfg	Target specific configuration

unsigned int CDF_gem_std_compress	(	CDF_gem *	cdf,
		unsigned int *	buf,
		unsigned int	pos,
		const EBF_gem *	gem,
		unsigned int	seq
	)

Compresses the GEM for standard zero suppressed data.

Returns:

The next bit position to write to

Parameters:

	cdf	The GEM's Compressed Data Format context
	buf	The output buffer
	pos	The current bit offset into the output buffer buf
	gem	The GEM contribution
	seq	The event sequence number

References gem_assess(), gem_pps_pack(), gem_std_pack(), and STD.

void CDF_gem_update	(	CDF_gem *	cdf,
		const EBF_gem *	gem,
		unsigned int	seq
	)

Updates any running context.

Parameters:

	cdf	The GEM's Compressed Data Format context
	gem	The GEM contribution
	seq	The event sequence number

References _CDF_gem::cnt, _CDF_gem::ctrs, _CDF_gem_ctrs::deadzone, _CDF_gem_ctrs::discarded, _CDF_gem_ctrs::livetime, _CDF_gem_ctrs::ppstime, _CDF_gem_ctrs::prescaled, _CDF_gem_ctrs::sequence, and _CDF_gem_ctrs::trgtime.

int CDF_gemCfg_construct	(	CDF_gemCfg *	cfg,
		int	level,
		void **	mem
	)

Constructs the CDF_gemCfg compression configuration.

Return values:

Status

Parameters:

	cfg	Target specific configuration
	level	The maximum compression level that needs to be supported
	mem	Pointer to free memory pointer, return as the the updated pointer. If cfg is equal to the current contents of mem, then mem will be advanced by the size of CDF_gemCfg, else this routine will believe that the only the variable allocation of cdf needs to be allocated.

void CDF_gemCfg_set_min_deadtime	(	CDF_gemCfg *	cfg,
		int	min_deadtime
	)

Sets the minimum deadtime.

Parameters:

	cfg	The GEM configuration parameter block
	min_deadtime	The minimum deadtime. For data taken off the instrument, this will be 529. Typical value for GLEAM Monte Carlo is 400

References _CDF_gemCfg::min_deadtime.

int CDF_gemCfg_sizeof

(

int

level

)

Returns the size, in bytes of the GEM compression configuration needed to support the specified level.

Parameters:

level

The maximum compression level to support

static unsigned int gem_assess	(	CDF_gem *	cdf,
		const EBF_gem *	gem
	)			[static]

Constructs a status word consisting of the trigger condition byte and its consistency with both the primitives that set the various bits and trigger condition bit. For those trigger condition primitives that are absent, it records whether the condition arrival time is 0x1f.

Returns:

The status word. This consists of 3 bytes

1. Byte 0, the least significant is whether the trigger primitive bits for a corresponding trigger condition bit are 0 or non-zero
2. Byte 1, indicates whether the trigger condition bit follows the trigger primitive in the first byte (should be 0 if the GEM is working correctly)
3. Byte 2, indicates whether, when a trigger primitive is absent, wheter the trigger primitive arrival is 0x1f (should be 0 if the GEM is working correctly

Parameters:

	cdf	The GEM's Compression Data Formatting handle
	gem	The GEM data

References _CDF_gem::cnt, _CDF_gem::ctrs, _CDF_gem_ctrs::deadzone, gem_psbcat_set(), and _CDF_gem_ctrs::ppstime.

Referenced by CDF_gem_ped_compress(), and CDF_gem_std_compress().

static __inline unsigned int gem_pack_acd	(	CDF_gem *	cdf,
		unsigned int *	buf,
		unsigned int	pos,
		const EBF_gem *	gem,
		unsigned int	status
	)			[static]

Adds the GEM ACD information. Since one does not expect many hits, these are packed as a list of bit addresses.

Returns:

The updated bit write position

Parameters:

	cdf	The GEM's Compressed Data Format context
	buf	The output buffer
	pos	The current bit offset into the output buffer buf
	gem	The GEM contribution
	status	The status from gem_assess

Referenced by gem_ped_pack().

static __inline unsigned int gem_pack_conditions	(	CDF_gem *	cdf,
		unsigned int *	buf,
		unsigned int	pos,
		const EBF_gem *	gem,
		unsigned int	status
	)			[static]

Packs the trigger condition status.

Packs the condition arrival time information.

Returns:

The bit position of the next write

Parameters:

	cdf	The GEM's compress data formatting handle
	buf	The output buffer
	pos	The current bit offset
	gem	The input EBF_gem record
	status	The result of the GEM assess (basically a summary status)

Referenced by gem_std_pack().

static __inline unsigned int gem_pack_deadzone	(	CDF_gem *	cdf,
		unsigned int *	buf,
		unsigned int	pos,
		const EBF_gem *	gem,
		unsigned int	status
	)			[static]

Packs the deadzone counter value.

Returns:

The bit position of the next write

Parameters:

	cdf	The GEM's compress data formatting handle
	buf	The output buffer
	pos	The current bit offset
	gem	The input EBF_gem record
	status	The result of the GEM assess (basically a summary status)

Referenced by gem_std_pack().

static __inline unsigned int gem_pack_discarded	(	CDF_gem *	cdf,
		unsigned int *	buf,
		unsigned int	pos,
		const EBF_gem *	gem
	)			[static]

Packs the discard counter.

Returns:

The bit position of the next write

Parameters:

	cdf	The GEM's compress data formatting handle
	buf	The output buffer
	pos	The current bit offset
	gem	The input EBF_gem record

References _CDF_gem::cnt, _CDF_gem::ctrs, and _CDF_gem_ctrs::discarded.

Referenced by gem_std_pack().

static __inline unsigned int gem_pack_dwinevt	(	CDF_gem *	cdf,
		unsigned int *	buf,
		unsigned int	pos,
		const EBF_gem *	gem
	)			[static]

Packs the delta Window and Event times.

Returns:

The bit position of the next write

Parameters:

	cdf	The GEM's compress data formatting handle
	buf	The output buffer
	pos	The current bit offset
	gem	The input EBF_gem record

Referenced by gem_std_pack().

static __inline unsigned int gem_pack_prescaled	(	CDF_gem *	cdf,
		unsigned int *	buf,
		unsigned int	pos,
		const EBF_gem *	gem
	)			[static]

Packs the prescale counter.

Returns:

The bit position of the next write

Parameters:

	cdf	The GEM's compress data formatting handle
	buf	The output buffer
	pos	The current bit offset
	gem	The input EBF_gem record

References _CDF_gem::cnt, _CDF_gem::ctrs, and _CDF_gem_ctrs::prescaled.

Referenced by gem_std_pack().

static __inline unsigned int gem_pack_primitives	(	CDF_gem *	cdf,
		unsigned int *	buf,
		unsigned int	pos,
		const EBF_gem *	gem,
		unsigned int	status
	)			[static]

Packs the trigger primitives status byte plus any non-0 values.

Returns:

The bit position of the next write

Parameters:

	cdf	The GEM's compress data formatting handle
	buf	The output buffer
	pos	The current bit offset
	gem	The input EBF_gem record
	status	The result of the GEM assess (basically a summary status)

Referenced by gem_std_pack().

static __inline unsigned int gem_pack_times	(	CDF_gem *	cdf,
		unsigned int *	buf,
		unsigned int	pos,
		const EBF_gem *	gem,
		unsigned int	seq
	)			[static]

Packs the trigger and livetime counter values.

Returns:

The bit position of the next write

Parameters:

	cdf	The GEM's compress data formatting handle
	buf	The output buffer
	pos	The current bit offset
	gem	The input EBF_gem record
	seq	The current event sequence number

This is one of the more complicated encodings.

Case 0: First event in the datagram

The defined bits of the trigger time and the livetime registers are placed directly into the output stream.

Case 1: Not the first event

The incremental livetime is encoded next. It is defined as the difference between the current livetime register and the previous livetime register. For a system with an average output rate of 250Hz (and little deadtime) the incremental livetime should be around 4 x 10--3 seconds * 20 x 10**6 clock ticks/sect = 80,000 or around 16-17 bits. Believing that the last 9 bits are random (this is a time scale on the order of 25 usecs), the first 16 bits are encoded as 4 bits giving the number of bits to the first 1 (more truthfully it is 15 - that value). The remaining bits are then encoded. This is a modest saving of 3-15 bits out of 25.

Next the deadtime is encoded. The deadtime is defined as the difference between the elapsed time and the incremental livetime. For a system running at 10% deadtime (90% livetime), this number should be a factor 9 smaller than the livetime. A refinement can be made to this number. One can calculate the adjusted deadtime by subtracting off the known fix deadtime that comes from the 529 clock ticks associated with each event. If this fixed deadtime is the only source of deadtime, then the adjusted deadtime will be 0. In the case it is not zero, then deadtime is coming from somewhere else. One has no reason to believe it is a number close to 0. This is because the scale of this additional deadtime could be almost anything. Even 20 usecs of deadtime leads to a 9 bit number.

However, because this code assumes nothing that would invalid the encoding, one must be prepared to handle the case that the adjusted deadtime might be negative. In practice, the only place that this should happen is with Monte Carlo data where the fixed deadtime was not specified to be 529.

case 1a: The adjusted deadtime is >= 0

The coding is as follows, a single bit of 0 indicates that the adjusted deadtime is, in fact 0. If this is not the case, 2 bits, a 1 (indicating the alternative encoding) and a zero (indicating that the adjusted deadtime to follow is positive are emmitted, followed by the encoding of the adjusted deadtime using the same scheme as for the livetime.

case 1b: The adjusted deadtime is < 0

This means that the fixed per event deadtime being used is incorrect. Two bits 11, are emitted. The first indicates that the deadtime is not 0, while the second indicates that recalculate per event deadtime follows. The adjusted deadtime is then recalculated. By definition this must be 0.

References _CDF_gem::cnt, _CDF_gem::ctrs, _CDF_gem_ctrs::livetime, _CDF_gem::min_deadtime, _CDF_gemCfg::min_deadtime, _CDF_gem_ctrs::sequence, and _CDF_gem_ctrs::trgtime.

Referenced by gem_std_pack().

static __inline unsigned int gem_ped_pack	(	CDF_gem *	cdf,
		unsigned int *	buf,
		unsigned int	pos,
		const EBF_gem *	gem,
		unsigned int	seq,
		unsigned int	status
	)			[static]

Compresses the GEM data when zero suppression has been disabled.

Returns:

The updated bit write position

Parameters:

	cdf	The GEM's Compressed Data Format context
	buf	The output buffer
	pos	The current bit offset into the output buffer buf
	gem	The GEM contribution
	seq	The event sequence number
	status	The status from CDF_gem_assess

References gem_pack_acd(), and gem_std_pack().

Referenced by CDF_gem_ped_compress().

static unsigned int gem_pps_pack	(	CDF_gem *	cdf,
		unsigned int *	buf,
		unsigned int	pos,
		const EBF_gem *	gem,
		unsigned int	not_std,
		unsigned int	status
	)			[static]

Adds the introductory bits + PPS if necessary.

Returns:

The next available bit position in the output buffer

Parameters:

	cdf	The GEM's compress data formatting handle
	buf	The output buffer
	pos	The current bit offset
	gem	The input EBF_gem record
	not_std	If true, the not standard packing
	status	The status from gem_assess

Referenced by CDF_gem_ped_compress(), and CDF_gem_std_compress().

static __inline unsigned gem_psbcat_set	(	unsigned int	status,
		unsigned int	primitive,
		unsigned int	condtime,
		unsigned int	psb_msk,
		unsigned int	cat_msk
	)			[static]

Sets the Primitive nd Condition Arrival Time status bits.

Returns:

The modified status word

Parameters:

	status	The current status word
	primitive	The value of the trigger primitive. All that really counts is whether it is 0 or non-zero
	condtime	The condition arrival time for this primitive
	psb_msk	The primitive status bit mask
	cat_msk	The condition arrival time bit mask

This routine does two things

1. Sets the primitive status bit in the status word if the primitive is non-zero
2. Composes a mask of the unpredictable condition arrival times The rule of being predictalbe is simple
   1. If the primitive is non-zero, then the condition arrival time is predicted to be 0.
   2. If the primitive is zero, then the condition arrival time is predicted to be 0x1f If the predicted arrival time matches the actual condition arrival time, the condition arrival time is said to be predictable.

Referenced by gem_assess().

static __inline void gem_reset

(

CDF_gem *

cdf

)

[static]

Clears stale context from the GEM compression data format handle.

Parameters:

cdf

The GEM compressed data format context

References _CDF_gem::cfg, _CDF_gem::cnt, _CDF_gem::ctrs, _CDF_gem_cfg::min_deadtime, and _CDF_gem::min_deadtime.

Referenced by CDF_gem_begin(), and CDF_gem_construct().

static unsigned int gem_std_pack	(	CDF_gem *	cdf,
		unsigned int *	buf,
		unsigned int	pos,
		const EBF_gem *	gem,
		unsigned int	seq,
		unsigned int	status
	)			[static]

Adds the GEM record.

Returns:

The next available bit position in the output buffer

Parameters:

	cdf	The GEM's compress data formatting handle
	buf	The output buffer
	pos	The current bit offset
	gem	The input EBF_gem record
	seq	The event sequence number
	status	The status from gem_assess

References gem_pack_conditions(), gem_pack_deadzone(), gem_pack_discarded(), gem_pack_dwinevt(), gem_pack_prescaled(), gem_pack_primitives(), and gem_pack_times().

Referenced by CDF_gem_std_compress(), and gem_ped_pack().