EDR_tkrUnpack.c File Reference

Routines to unpack the TKR data for all towers in the LAT. More...

#include <EDS/EDR_tkrUnpack.h>
#include <EDS/EDR_tkr.h>
#include <EDS/EBF_tkr.h>
#include <EDS/EBF_dir.h>
#include <EDS/EBF_ctb.h>
#include <PBI/Endianness.h>
#include <PBI/FFS.ih>
#include <PBI/PTR.h>
#include <string.h>

Classes
struct	_TKR_2strips_bf
	Maps out the first word containing strip addresses. More...
struct	_TKR_8strips0_bf
	Maps out the first word of the 3 strip address pattern words as bit fields. More...
struct	_TKR_8strips1_bf
	Maps out the second word of the 3 strip address pattern words as bit fields. More...
struct	_TKR_8strips2_bf
	Maps out the third word of the 3 strip address pattern words as bit fields. More...
struct	_TKR_2strips
	Maps out the first word containing strip addresses. More...
union	_TKR_8strips0
	Maps out the first word of the 3 strip address pattern words as bit fields and uninterpretted 32-bit integer. More...
union	_TKR_8strips1
	Maps out the second word of the 3 strip address pattern words as bit fields and uninterpretted 32-bit integer. More...
union	_TKR_8strips2
	Maps out the third word of the 3 strip address pattern words as bit fields and uninterpretted 32-bit integer. More...
Defines
#define	CONTIGIOUS   1
	Determines the minimum strip separation for hit strips to be considered contigious.
#define	USE_GAPS   1
	Determines whether the code translates the strip addresses by the ladder gaps.
#define	BYTE_ACCESS(_ba, _idx)   _ba[_idx];
	Addresses the TOT oriented byte array in a way that is compatiable with big or little endian machines.
#define	TKR__stripToOffset(_s, _x)   (_x[((_s) >> 7) & 0xf])
	Finds the ladder offset associated with the strip in units of a strip width.
#define	INIT_LAYERS(_lyrs, _accepts, _mlayers, _map, _layers, _hiLo, _cnt)
	Process the layer bit masks associated with the either X or Y layers.
#define	S2(_d0, _d1)   ((_d0.bf.s2a << 4) | _d1.bf.s2b)
	Assembles the 2nd strip address from its two pieces.
#define	S5(_d1, _d2)   ((_d1.bf.s5a << 8) | _d2.bf.s5b)
	Assembles the 5th strip address from its two pieces.
#define	NPROCESS(_strip, _beg, _o, _prv, _cur,_lcnt, _layer, _lyrs, _b, _bits)
	Macro to process a strip address when starting a new cluster.
#define	CPROCESS(_strip, _beg, _o, _prv, _cur,_lcnt, _layer, _lyrs, _b, _bits)
	Macro to process a strip address when a cluster is being built.
#define	PROCESS(_cb, _nb,_strip, _beg, _o, _prv, _cur, _lcnt, _layer, _layers,_bits)
	A convenience macro to drop down a process cluster in progress and a new cluster macro.
#define	GAP(_n)   ((int)((_n) * ((.974 + .2 + .974) / .228) + 0.5))
	Calculates the cumulative length due to the gaps between the ladders.
Typedefs
typedef struct _TKR_2strips_bf	TKR_2strips_bf
	Typedef for struct _TKR_2strips_bf.
typedef struct _TKR_8strips0_bf	TKR_8strips0_bf
	Typedef for struct _TKR_8strips0_bf.
typedef struct _TKR_8strips1_bf	TKR_8strips1_bf
	Typedef for struct _TKR_8strips1_bf.
typedef struct _TKR_8strips2_bf	TKR_8strips2_bf
	Typedef for struct _TKR_8strips2_bf.
typedef union _TKR_2strips	TKR_2strips
	Typedef for struct _TKR_2strips_bf.
typedef union _TKR_8strips0	TKR_8strips0
	Typedef for union _TKR_8strips0.
typedef union _TKR_8strips1	TKR_8strips1
	Typedef for union _TKR_8strips1.
typedef union _TKR_8strips2	TKR_8strips2
	Typedef for union _TKR_8strips2.
Functions
static int	init (EDR_tkrTower *ttr, unsigned int loHiLayerMaps[4], EDR_tkrLayer *layersBuf[72], unsigned int a0, unsigned int a1, unsigned int a2)
	Initializes/extracts the layer information from the accept masks.
static __inline void	setSplits (EDR_tkrTower *ttr, const unsigned int *maps)
	Sets the split points.
static void	unpackTotsFromAccepts (EDR_tkrTower *ttr, const EBF_tkr *tkr, const unsigned char *map)
	Unpacks the TOTs.
int	unpackStrips (EDR_tkrTower *ttr, const EBF_tkr *tkr, int maxwrds)
	Unpacks the data from one tower.
int	EDR_tkrUnpack (EDR_tkr *tlr, const EBF_dir *dir, unsigned int stripsTots)
	Driver routine to unpack the specified TKR towers.
int	EDR_tkrUnpackInit (EDR_tkr *tlr)
	Performs one time initialization of a Track LAT record.
void	EDR_tkrUnpackReset (EDR_tkr *tlr)
	Resets the tlr record, preparing it to receive another unpacked event.
int	EDR_tkrUnpackSizeof (void)
	Returns the size, in bytes, of a EDR_tkr.
Variables
static const unsigned char	Map [18]
	The mapping of the entries in the layer accept list to the physical layer numbers.

---

Detailed Description

Routines to unpack the TKR data for all towers in the LAT.

Author:

JJRussell - russell@slac.stanford.edu

    CVS $Id: EDR_tkrUnpack.c,v 1.8 2011/03/25 22:16:56 russell Exp $

---

Define Documentation

#define BYTE_ACCESS	(	_ba,
		_idx		)	_ba[_idx];

Addresses the TOT oriented byte array in a way that is compatiable with big or little endian machines.

Returns:

Value at the byte index

Parameters:

	_ba	the byte array to access
	_idx	The value to be transformed

#define CONTIGIOUS   1

Determines the minimum strip separation for hit strips to be considered contigious.

This variable determines when 2 strip addresses are contigious There is really only 1 right answer (1), but by setting this value to anything less than 1, no clusters will be formed, allowing debugging of this code.

#define CPROCESS	(	_strip,
		_beg,
		_o,
		_prv,
		_cur,
		_lcnt,
		_layer,
		_lyrs,
		_b,
		_bits		)

Macro to process a strip address when a cluster is being built.

Parameters:

	_strip	The strip address to process
	_beg	Beginning strip address of the cluster.
	_o	The offset associated with _beg
	_prv	Ending strip address of the cluster, i.e. the previous strip address.
	_cur	Current address to store the strip address.
	_lcnt	Number of layers left to process.
	_layer	The current EDR_tkrTower layer address
	_lyrs	A stack of the EDR_tkrTower layer addresses.
	_b	The number into this batch of 8 strips
	_bits	Returned as the bits consumed in this batch (12 * _b)

This macro is used only when a cluster is in the process of being built. The parameters _beg and _prv indicate the beginning and ending strip addresses of the current cluster.

A check is made to see if the new strip address to be stored is contiguous the current cluster. If so the ending address of the cluster is updated.

If the current cluster is not contiguous, there are two possible reasons. The first is the obvious, they two strip addresses are not contiguous. The second is that the new strip address is actually at the end of a layer. If this is so. the check for being contiguous is remade after stripping the layer end bit. If not, the old cluster centroid is stored and a new one begun.

If a cluster is in the process of being built, the flow of the code is directed to the statement label specified by _Po. If no cluster is currently being built, the flow of the code is directed to the statement label specified by _No.

#define GAP

(

_n

)

((int)((_n) * ((.974 + .2 + .974) / .228) + 0.5))

Calculates the cumulative length due to the gaps between the ladders.

Parameters:

_n

The ladder number (0-3)

Returns:

The cumulative length due to the gaps between the ladders in units of strips.

#define INIT_LAYERS	(	_lyrs,
		_accepts,
		_mlayers,
		_map,
		_layers,
		_hiLo,
		_cnt		)

Process the layer bit masks associated with the either X or Y layers.

Parameters:

	_lyrs	An array which receives the address of the layer structure for each of the struck layers.
	_accepts	The 18 bits representing on end of the layers
	_mlayers	Bit mask of the struck y layers in layer order, as opposed to readin order of the _accepts.
	_map	A an array mapping readin bit position order to the canonical layer order.
	_layers	The array layer structures.
	_hiLo	0 is doing the low end, 1 is doing the high end
	_cnt	Current number of active layers

The macro continuously scans the _accepts bit array, seeking the first set bit. Each such found bit is translated to a canonical layer number. The layer number is used to construct a bit mask of which layers are struck (this is essentially just a reordered version of the _accepts, except that the layer ends are OR'd together. In addition, the addresses of the layer structure describing the hits on each struck layer are stored in lyrs array.

Warning:

At one time this macro returned the updated _lyrs. The technique used to do this, however, is not portable. While the code read nicely, this technique has been abandoned in favor of portability. Just remember, that _lyrs is modified by this macro.

#define NPROCESS	(	_strip,
		_beg,
		_o,
		_prv,
		_cur,
		_lcnt,
		_layer,
		_lyrs,
		_b,
		_bits		)

Macro to process a strip address when starting a new cluster.

Parameters:

	_strip	The strip address to process
	_beg	Set to the new strip address if this is not the last strip on the layer.
	_o	Returned as the offset associated with _beg
	_prv	Set to the new strip address if this is not the last strip on the layer.
	_cur	Current address to store the strip address.
	_lcnt	Number of layers left to process.
	_layer	The current EDR tkrTower layer address
	_lyrs	A stack of the EDR_tkrtower layer addresses.
	_b	The number into this batch of 8 strips
	_bits	Returned as the bits consumed in this batch (12 * _b)

This macro is used only when starting the construction of a new cluster. If the strip address to be processed is not the last strip on a layer, a new cluster is initialized by setting the beginning and ending of the cluster to the strip address.

If this is the last strip on a layer, the strip address is stored along with the ending address of this layer. If there are more layers to process, the address to store the new strip addresses is retrieved and the cluster status is set to no cluster in progress by setting the beginning cluster strip address to -1.

If there are no more layers to process the action indicated by _action is taken. This is generally a break or goto statement.

#define PROCESS	(	_cb,
		_nb,
		_strip,
		_beg,
		_o,
		_prv,
		_cur,
		_lcnt,
		_layer,
		_layers,
		_bits		)

Value:

\
_N ## _cb:                                                                 \
 NPROCESS(_strip,_beg,_o, _prv, _cur, _lcnt, _layer, _layers, _nb, _bits); \
_P ## _cb:                                                                 \
 CPROCESS(_strip,_beg,_o, _prv, _cur, _lcnt, _layer, _layers, _nb, _bits);

A convenience macro to drop down a process cluster in progress and a new cluster macro.

Parameters:

	_cb	Current number of strips processed in this batch of 8
	_nb	Next number of strips processed in this batch of 8
	_strip	The strip address to process
	_beg	Beginning strip address of the cluster.
	_o	Returned as the offset associated with _beg
	_prv	Ending strip address of the cluster, i.e. the previous strip address.
	_cur	Current address to store the strip address.
	_lcnt	Number of layers left to process.
	_layer	The current EDR_tkrTower layer address
	_layers	A stack of the EDR_tkrTower layer addresses.
	_bits	Returned as the number of bits processed in this batch of 8, always 12*_nxt

#define S2	(	_d0,
		_d1		)	((_d0.bf.s2a << 4) | _d1.bf.s2b)

Assembles the 2nd strip address from its two pieces.

Parameters:

	_d0	The 32 bit word holding the upper 8 bits of the strip address
	_d1	The 32 bit word holding the lower 4 bits of the strip address

Three 32 bit words hold exactly 8 12 bit strip addresses. In this series of 8 strip addresses, two span a 32 bit boundary, the 2nd and the 5th. This macro assembles the 2nd strip address from its two halves.

#define S5	(	_d1,
		_d2		)	((_d1.bf.s5a << 8) | _d2.bf.s5b)

Assembles the 5th strip address from its two pieces.

Parameters:

	_d1	The 32 bit word holding the upper 4 bits of the strip address
	_d2	The 32 bit word holding the lower 8 bits of the strip address

Three 32 bit words hold exactly 8 12 bit strip addresses. In this series of 8 strip addresses, two span a 32 bit boundary, the 2nd and the 5th. This macro assembles the 5th strip address from its two halves.

#define TKR__stripToOffset	(	_s,
		_x		)	(_x[((_s) >> 7) & 0xf])

Finds the ladder offset associated with the strip in units of a strip width.

Parameters:

	_s	The strip address
	_x	An array of gaps to be applied to each 128 group of strips.

Returns:

The linear displacement to be associated with the specified strip address.

Each TKR tower is constructed of 4 ladders of 384 strips. There is a gap between each of the ladders of approximately 9 strips. This means that for the first ladder, the linear displacement is the strip address, for the second ladder, the linear displacement ins the strip address + the gap between ladders 0 and 1, and so forth.

The transformation is performed using an array (16) of displacements which correspond to each 128 strips. This is number was chosen because it was the largest binary power of 2 number, allowing one to do a shift rather than the more obvious, but much slower, divide by 384. The only burden on the caller is to provide an array of 16 numbers giving the offset for each group of 128 strips. Using a grouping of 128 means that the same offset will be repeated 3 times.

#define USE_GAPS   1

Determines whether the code translates the strip addresses by the ladder gaps.

This variable determines whether the code translates the strip addresses by the ladder gaps. It is used exclusively for debugging purposes. The default setting is 1, indicating that the gap correction is to be applied.

---

Typedef Documentation

TKR_2strips

Typedef for struct _TKR_2strips_bf.

The first 32-bit word containing strip addresses also contains the last 8 bits of the accept list. This structure maps these fields out as both an uninterpreted 32 bit value and as bit fields for easy access.

TKR_2strips_bf

Typedef for struct _TKR_2strips_bf.

The first 32-bit word containing strip addresses also contains the last 8 bits of the accept list. This structure maps these fields out for easy access.

---

Function Documentation

int EDR_tkrUnpack	(	EDR_tkr *	tlr,
		const EBF_dir *	dir,
		unsigned int	stripsTots
	)

Driver routine to unpack the specified TKR towers.

Parameters:

	tlr	The TKR LAT record structure to receive the unpacked data
	dir	The standard directory structure allowing the routine to traverse the LAT event record.
	stripsTots	A 32-bit word composed of two 16-bit masks. The upper 16-bit mask represents towers to unpack the strip data, the lower towers to unpack the TOT data. In both cases the MSB of the mask = Tower 0.

Returns:

Status, currently always success.

Warning:

It is very difficult to unpack the TOTs without unpacking the strips. Currently the design decision is to unpack the OR of these two masks. One, however, should not count on future implementations to unpack the towers. All that is guaranteed by this interface is that all towers specified to be unpack will be unpacked, and all towers specified to have their TOTs unpacked will have their TOTs unpacked.

Note the call

      status = EDR_tkrUnpack (tlr, tkr, -1);

Will completely unpack both the strip data and the TOT data from all towers that have data. Also note that when examining the structure field member, twrMap, that it will always be a proper subset of those towers that have data.

int EDR_tkrUnpackInit

(

EDR_tkr *

tlr

)

Performs one time initialization of a Track LAT record.

Returns:

Status, currently always SUCCESS

Parameters:

tlr

Pointer to the structure to initialize

This function should be called only once to initialize the record. After that, TFC_latReset should be called to reset the structure before each unpack.

Referenced by initIxbObjTbl().

void EDR_tkrUnpackReset

(

EDR_tkr *

tlr

)

Resets the tlr record, preparing it to receive another unpacked event.

Parameters:

tlr

Pointer to the structure to reset.

This function should be called prior to unpacking a new event. It performs the minimal work needed to prepare the structure to receive a new event. Separating this piece of work from the unpacking routine proper allows the unpacker to be called repeatedly with different tower masks. For example, one could unpack a tower at a time using the following sequence

    EDR_tkrUnpackReset (tkr);
    EDR_tkrUnpack      (tkr, dir, EDR__tkrUnpackTowerNum(1));
    EDR_tkrUnpack      (tkr, dir, EDR__tkrUnpackTowerNum(4));
    EDR_tkrUnpack      (tkr, dir, EDR__tkrUnpackTowerNum(8)
                                | EDR__tkrUnpackTowerNum(9));

References _EDR_tkrLayer::beg, _EDR_tkrLayer::cnt, and EDR_TKR_K_CLUSTERS_PER_LAYER_MAX.

Referenced by initIxbObjTbl().

int EDR_tkrUnpackSizeof

(

void

)

Returns the size, in bytes, of a EDR_tkr.

Returns:

The size, in bytes, of a EDR_tkr.

This function should be called to determine the size of an EDR_tkr structure. This allows the calling program to avoid including the structure definition an EDR_tkr.

After allocating an EDR_tkr structure, the structure should be initialized using EDR_tkrUnpackInit().

int init	(	EDR_tkrTower *	ttr,
		unsigned int	loHiLayerMaps[4],
		EDR_tkrLayer *	layersBuf[72],
		unsigned int	a0,
		unsigned int	a1,
		unsigned int	a2
	)			[static]

Initializes/extracts the layer information from the accept masks.

Returns:

The number of layers with hit strips.

Parameters:

	ttr	The TKR tower record
	loHiLayerMaps	Filled with the left-justified version of the xlo, xhi, ylo and yhi layer maps
	layersBuf	Buffer to hold a pointer to a pointer to the next layer structure to receive the unpacked hits
	a0	The first of the 3 accept masks
	a1	The second of the 3 accept masks
	a2	The last of the 3 accept masks

static __inline void setSplits	(	EDR_tkrTower *	ttr,
		const unsigned int *	maps
	)			[static]

Sets the split points.

Parameters:

	ttr	The target tower
	maps	The map of left justified low and hi layer maps (xLo, xHi, yLo, yHi)

int unpackStrips	(	EDR_tkrTower *	ttr,
		const EBF_tkr *	tkr,
		int	maxwrds
	)

Unpacks the data from one tower.

Parameters:

	ttr	Pointer to the data structure to receive the unpacked data
	tkr	The tracker data as received from the hardware
	maxwrds	The maximum number of words in tkr.

void unpackTotsFromAccepts	(	EDR_tkrTower *	ttr,
		const EBF_tkr *	tkr,
		const unsigned char *	map
	)			[static]

Unpacks the TOTs.

Parameters:

	ttr	The target tower
	tkr	The tracker data
	map	The layer remapping function

Unpack the TOT information. The TOTs are laid out in the accept bit field order.

This function has a long history. Originally there was no TOT unpacking. This clearly was not acceptable. The unpacking was then bundled with the unpacking of each tower. The routine sponged off the order list of layer pointers that was a by-product of the strip unpacking to access the TOTs. This routine added 10-15% to the unpacking time. This was thought to be unreasonable, given that only events that survive the filter need to access to the TOT data.

The next attempt tried to make the TOT unpacking dependent only on locating the TOT data. (This is non-trivial, since it comes after the strip data. This means one must serially decode the strip data to find out where the TOT data lives.) The idea was to run this separately from the the strip unpacking. In theory, a good idea, in practice the penalty from starting from almost scratch meant the routine took on the order of 8 usecs. This was thought to be an accessive penalty compared to the 3.5 usecs of the original routine.

The first compromise idea was to make the temporary layer buffer array part of the tower data structure. This, is a fairly large object (16 towers * 72 layers pointers/tower * 4 bytes/layer pointer), and was thought to be accessive.

The idea finally settled on was to stash the input layer number (i.e. the layers, not as they are numbered on the LAT, but their readout numbering) in the storage reserved for the TOTs. This added about .6 usecs to the initialization routine (init) where this was done. This number also represents the readout order of the TOTs. Therefore, at some later time, this TOTs values could be exchanged for the indices by simply zipping through the hit layers and indexing the the TOT array. The cost is about .6 usecs to stash the indices into the TOT array and about 4.4 usecs to do EBF_tkrUnpackTots. The appears to be an additional penalty of around .5 usecs to loop through the towers, calling unpackTots as opposed to calling it at the same time as the strip unpacking. Not altogether satisfying, but this appears to be about as well as one can do.

Well not quite. The routine unpackTots demanded the array of loHiLayerMaps[4] to function correctly. This array was sacrificed to maintain backward compatiability, meaning unpackTots could no longer function. Hence the old 'unpackTotsFromAccepts' was resurrected. This method is somewhat slower (not sure if this is the 8usecs penalty mentioned above or whether the 8 usecs includes locating the TOTs (here the location of the TOTs is saved in totOffset). This location is an expensive operation so it is important to know. However doing it this was means relieves frees up the loHiLayerMap array in the EDR_tkrLayer structure, so EDS can stay backwardly compatible.

---

Variable Documentation

Map [static]

Initial value:

{
    1,  3,  5,  7,  9, 11, 13, 15, 17,  
    0,  2,  4,  6,  8, 10, 12, 14, 16   
}

The mapping of the entries in the layer accept list to the physical layer numbers.

The accept list is processed as 4 pairs of cables. The first cable of the pair carries the even layers, the second carries the odd layers. The 4 pairs represent the X lo, X hi and Y lo, Y hi cable pairs. In general one would need to map all 72 layer ends, but because all cable pairs are identical, so the same map can be used for each.

This mapping could have been easily handled in the INIT_LAYERS macro, but the cost would have been some additional arthimetic. The current set bit would have to be translated into a layer number by doubling it and adding 1 iff the current bit was greater than 8. The lookup method seems simpler and faster.