EBF_cal.h File Reference

Describes the CAL data format from the event builder. More...

#include <PBI/Endianness.h>

Classes
struct	_EBF_calLogData_bf
	Maps out the 32-bit value of a CAL log data field as bit fields. More...
struct	_EBF_calLogData_cf
	Maps out the 32-bit value of a CAL log data field as bit fields. This mapping keeps the RNG and ADC value contigious. More...
union	_EBF_calLogData
	Maps out the 32-bit value of a CAL log data field both in bit fields and as an unsigned 32-bit integer. More...
struct	_EBF_cal
	Lays out the format of the CAL data block from the event builder. More...
Defines
#define	EBF_CALLOGCNT_MASK   0x0f0f0f0f
	Value to be supplied as the second argument in EBF__calLogCntM.
#define	EBF_CAL_SATURATION   ((7 * (1 << 12)) / 8)
	Suggestion ADC saturation value.
Typedefs
typedef enum _EBF_CAL_LOGDATA_S	EBF_CAL_LOGDATA_S
	Typedef for struct _EBF_CAL_LOGDATA_S.
typedef enum _EBF_CAL_LOGDATA_V	EBF_CAL_LOGDATA_V
	Typedef for struct _EBF_CAL_LOGDATA_V.
typedef enum _EBF_CAL_LOGDATA_M	EBF_CAL_LOGDATA_M
	Typedef for struct _EBF_CAL_LOGDATA_M.
typedef struct _EBF_calLogData_bf	EBF_calLogData_bf
	Typedef for struct _EBF_calLogData_bf.
typedef struct _EBF_calLogData_cf	EBF_calLogData_cf
	Typedef for struct _EBF_calLogData_cf.
typedef union _EBF_calLogData	EBF_calLogData
	Typedef for union _EBF_calLogData.
typedef struct _EBF_cal	EBF_cal
	Typedef for struct _EBF_cal.
Enumerations
enum	_EBF_CAL_LOGDATA_S {   EBF_CAL_LOGDATA_S_COL = 4,   EBF_CAL_LOGDATA_S_RNGN = 2,   EBF_CAL_LOGDATA_S_VALN = 12,   EBF_CAL_LOGDATA_S_RNGP = 2,   EBF_CAL_LOGDATA_S_VALP = 12 }
	Maps out the sizes of the bit fields for a CAL log data word. More...
enum	_EBF_CAL_LOGDATA_V {   EBF_CAL_LOGDATA_V_COL = 28,   EBF_CAL_LOGDATA_V_RNGN = 26,   EBF_CAL_LOGDATA_V_VALN = 14,   EBF_CAL_LOGDATA_V_RNGP = 12,   EBF_CAL_LOGDATA_V_VALP = 0 }
	Maps out the amount need to right justify the bit fields for a CAL log data word. More...
enum	_EBF_CAL_LOGDATA_M {   EBF_CAL_LOGDATA_M_COL = 0xf0000000,   EBF_CAL_LOGDATA_M_RNGN = 0x0c000000,   EBF_CAL_LOGDATA_M_VALN = 0x03ffc000,   EBF_CAL_LOGDATA_M_RNGP = 0x00003000,   EBF_CAL_LOGDATA_M_VALP = 0x00000fff }
	Maps out the in place mask needed to extract the bit fields of a CAL log data word. More...
Functions
static __inline unsigned char	EBF__calLogCntM (unsigned int layerCnts, unsigned int mask)
	Calculates the total number of logs struck in this contributor's CAL record.
static __inline unsigned char	EBF__calLogCnt (unsigned int layerCnts)
	Calculates the total number of logs struck in this contributor's CAL record.
static __inline unsigned int	EBF__calAutoRange (const EBF_calLogData *rngs, int inc, unsigned int saturation)
	Selects the best range to use.

---

Detailed Description

Describes the CAL data format from the event builder.

Author:

JJRussell - russell@slac.stanford.edu

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

Overview

This maps out the EBF Calorimeter data. Given that this is a variable length structure, the mapping to a C-structure is not very good. The data consists of a single 32 bit word, composed of 8 nibbles, with each nibble giving the number of struck logs in a particular layer. This is followed by a variable number of 32-bit words, each containing 3 basic fields, the ADC values for the A and B ends and the column number. The total number is determined by the sum of the 8 nibbles in the first word. The order is such that the nibble in the MSB maps out the first collection of values. The layers are from X layers (0-3) followed by the Y layers (0-3)

Calorimeter Data Word

Data structures and enumerations are defined that map out the Calorimeter data word. This word consists of 2 14-bit ADC values and one 4 bit column identifier. The ADC values are further broken down into a 2 bit range field and a 12 bit value field.

The word breakdown is presented both as a series of enumerations, which map the data word up in terms of shifts and masks, and a bit field structure. The user is free to pick the one most convenient and appropriate for his application.

---

Define Documentation

#define EBF_CAL_SATURATION   ((7 * (1 << 12)) / 8)

Suggestion ADC saturation value.

This is the suggested rollover point of an ADC in a given range to be deemed saturated. The idea is that if the ADC for a given range exceeds this value, the next lower gain readings are examined in turn, stopping at the highest gain that does not saturate. The auto-ranging routine exposes this parameter, but this mainly for testing purposes. In real use, results should be fairly insensitive to this value. (The logic goes something like, it is a 12-bit ADC and the gain ranges are roughly a factor of 8 apart, i.e. 3 bits. So going from one gain range to the next lower one costs 3 bits of accuracy out of about 11 (presuming that one is setting the saturation value to at least half the range. This costs 1/512 in the accuracy of the number. This should not be relevant in a device with something at most 5% resolution.

#define EBF_CALLOGCNT_MASK   0x0f0f0f0f

Value to be supplied as the second argument in EBF__calLogCntM.

Exposing the argument in this fashion allows the compiler to optimize it into a register

Referenced by EBF__calLogCnt(), and EBF_dirCompose().

---

Typedef Documentation

EBF_cal

Typedef for struct _EBF_cal.

Since the CAL data is not a fixed length field, it is not possible to directly map it to a C-structure. Overall the CAL data looks like a 32-bit word comprised of 8 4-bit nibbles giving the number of struck logs in each layer. This is followed by a number of ADC values, each specifying the two ADC values and the column number of the log. The decode consists of picking off the specified number of logs in each column using the 8 nibbles in the first word. The order of the nibbles is big-endian, i.e. the first count to pick resides in the most significant 4 bits and corresponds to the first N ADCs. The layer order is the 4 X layers, followed by the 4 Y layers.

EBF_calLogData

Typedef for union _EBF_calLogData.

Mapping the CAL log data in this manner allows the programmer to assign a CAL log data value with a simple assignment statement, but then to access the fields using the bit field structure.

---

Enumeration Type Documentation

enum _EBF_CAL_LOGDATA_M

Maps out the in place mask needed to extract the bit fields of a CAL log data word.

Enumerator:

EBF_CAL_LOGDATA_M_COL	In place mask, column number
EBF_CAL_LOGDATA_M_RNGN	In place mask, ADC - range
EBF_CAL_LOGDATA_M_VALN	In place mask, ADC - value
EBF_CAL_LOGDATA_M_RNGP	In place mask, ADC + range
EBF_CAL_LOGDATA_M_VALP	In place mask, ADC + range

enum _EBF_CAL_LOGDATA_S

Maps out the sizes of the bit fields for a CAL log data word.

Enumerator:

EBF_CAL_LOGDATA_S_COL	Size of column number bit field
EBF_CAL_LOGDATA_S_RNGN	Size of the ADC - range bit field
EBF_CAL_LOGDATA_S_VALN	Size of the ADC - value bit field
EBF_CAL_LOGDATA_S_RNGP	Size of the ADC + range bit field
EBF_CAL_LOGDATA_S_VALP	Size of the ADC + value bit field

enum _EBF_CAL_LOGDATA_V

Maps out the amount need to right justify the bit fields for a CAL log data word.

Enumerator:

EBF_CAL_LOGDATA_V_COL	Shift for the column number bit field
EBF_CAL_LOGDATA_V_RNGN	Shift for the ADC - range bit field
EBF_CAL_LOGDATA_V_VALN	Shift for the ADC - value bit field
EBF_CAL_LOGDATA_V_RNGP	Shift for the ADC + range bit field
EBF_CAL_LOGDATA_V_VALP	Shift for the ADC + value bit field

---

Function Documentation

static __inline unsigned int EBF__calAutoRange	(	const EBF_calLogData *	rngs,
		int	inc,
		unsigned int	saturation
	)			[static]

Selects the best range to use.

Returns:

A synthesised EBF_calLogData value

Parameters:

	rngs	Pointer to the first of the four ranges
	inc	The increment, in units of 32-bit words to advance from one range to the next.
	saturation	ADC values greater than or equal to this value are considered saturated.

This routine attempts to mimic in software what the hardware does when in auto-range mode. It does this by seeking the highest gain channel whose ADC value does not exceed the saturation value. A typical value would be something like 7/8 of the full 12 bit range (3584).

References _EBF_calLogData::bf, _EBF_calLogData_bf::rngN, _EBF_calLogData_bf::rngP, _EBF_calLogData::ui, _EBF_calLogData_bf::valN, and _EBF_calLogData_bf::valP.

unsigned char EBF__calLogCnt

(

unsigned int

layerCnts

)

[static]

Calculates the total number of logs struck in this contributor's CAL record.

Parameters:

layerCnts

8 nibbles representing the number of counts in each of the 8 CAL layers.

Returns:

The total number of logs struck in all layers

References EBF__calLogCntM(), and EBF_CALLOGCNT_MASK.

unsigned char EBF__calLogCntM	(	unsigned int	layerCnts,
		unsigned int	mask
	)			[static]

Calculates the total number of logs struck in this contributor's CAL record.

Parameters:

	layerCnts	8 nibbles representing the number of counts in each of the 8 CAL layers.
	mask	A bit mask with every other nibble being 0 of 0xf. This is really not a parameter, but including allows the compiler to optimize its placement in a register.

See also:

EBF__CALLOGCNT_MASK.

Returns:

The total number of logs struck in all layers

Referenced by EBF__calLogCnt(), process_tem_normal(), and process_tem_truncated().