---

GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> QSE / V2-3-0 > qse / sun-gcc

---

         

---

QSE_tkrUnpack.c File Reference

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

#include "QSE/QSE_tkrUnpack.h"
#include "QSE/QSE_tkr.h"
#include "QSE/QSE_map.h"
#include "EDS/EBF_tkr.h"
#include "EDS/EBF_dir.h"
#include "EDS/EBF_ctb.h"
#include "PBI/Endianness.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	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	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	RPROCESS(_strip, _cur, _lyrCnt, _lyr, _lyrs, _n, _c)
	Macro to process a strip address when starting a new cluster.
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 (QSE_tkrTwr *twr, QSE_tkrLyr *lyrsBuf[72], unsigned int a0, unsigned int a1, unsigned int a2)
	Initializes/extracts the layer information from the accept masks.
static void	unpackTots (QSE_tkrTwr *twr, const unsigned char *tots)
	Unpacks the TOTs.
static int	unpackTwr (QSE_tkrTwr *twr, const EBF_tkr *tkr, int maxwrds)
	Unpacks the data from one tower.
int	QSE_tkrUnpack (QSE_tkr *tkr, const EBF_dir *dir)
	Driver routine to unpack the specified TKR towers.
int	QSE_tkrUnpackInit (QSE_tkr *tkr)
	Performs one time initialization of a Track LAT record.
int	QSE_tkrUnpackSizeof (void)
	Returns the size, in bytes, of a QSE_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: QSE_tkrUnpack.c,v 1.6 2006/09/13 22:05:00 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 INIT_LAYERS	(	_lyrs,
		_accepts,
		_mlayers,
		_map,
		_layers,
		_hiLo,
		_cnt		)

Value:

{                                                                      \
   _mlayers = 0;                                                       \
   while (_accepts)                                                    \
   {                                                                   \
       int               n;                                            \
       int        layerNum;                                            \
       QSE_tkrLyr   *layer;                                            \
                                                                       \
       n           = QSE_mapScanR  (_accepts);                         \
       _accepts    = QSE_mapRemove (_accepts, n^31);                   \
       layerNum    = _map[n];                                          \
       layer       = &_layers[layerNum];                               \
     *_lyrs++      = layer;                                            \
                                                                       \
       /* KLUDGE */                                                    \
       layer->tots[_hiLo] = _cnt;                                      \
       layer->nstrips     = 0;                                         \
      _mlayers           |= 1 << layerNum;                             \
      _cnt               += 1;                                         \
   }                                                                   \
}

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 RPROCESS	(	_strip,
		_cur,
		_lyrCnt,
		_lyr,
		_lyrs,
		_n,
		_c		)

Value:

{                                                                \
          int adr = _strip;                                           \
                                                                      \
          /* Store the strip, without the terminator */               \
          *_cur++  = adr & ~(1 << 11);                                \
                                                                      \
          /* Check if their was a terminator */                       \
          if ((adr & (1 << 11)))                                      \
          {                                                           \
             int           cnt;                                       \
             QSE_tkrStrip *beg;                                       \
                                                                      \
             /* Do the usual end of layer processing */               \
             _lyrCnt      -= 1;                                       \
              beg          = _lyr->beg;                               \
              cnt          = _cur - beg;                              \
             _lyr->nsplit  = _lyr->nstrips;                           \
             _lyr->nstrips =  cnt;                                    \
                                                                      \
              /* Is this the last layer ? */                          \
              if (_lyrCnt <= 0) { _c = _n; break; }                   \
                                                                      \
             _lyr       = *_lyrs++;                                   \
             _cur       =  _lyr->beg + _lyr->nstrips;                 \
          }                                                           \
     }

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

Parameters:

	_strip	The strip address to process
	_cur	Current address to store the strip address.
	_lyrCnt	Number of layers left to process.
	_lyr	The current QSE_tkrTwr layer address
	_lyrs	A stack of the QSE_tkrTwr layer addresses. may be a member of the strips in progress
	_n	The number of strips processed in the current group of 8 This number may be negative
	_c	Returned as _n if hit the last strip

#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.

---

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 init	(	QSE_tkrTwr *	twr,
		QSE_tkrLyr *	lyrsBuf[72],
		unsigned int	a0,
		unsigned int	a1,
		unsigned int	a2
	)			[static]

Initializes/extracts the layer information from the accept masks.

Parameters:

	twr	The TKR tower record
	lyrsBuf	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

Returns:

The number of layers with hit strips.

int QSE_tkrUnpack	(	QSE_tkr *	tkr,
		const EBF_dir *	dir
	)

Driver routine to unpack the specified TKR towers.

Parameters:

	tkr	The QSE_tkr record structure to receive the unpacked data
	dir	The standard directory structure allowing the routine to traverse the LAT event record.

Returns:

Status, currently always success.

int QSE_tkrUnpackInit

(

QSE_tkr *

tkr

)

Performs one time initialization of a Track LAT record.

Returns:

Status, currently always SUCCESS

Parameters:

tkr

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.

int QSE_tkrUnpackSizeof

(

void

)

Returns the size, in bytes, of a QSE_tkr.

Returns:

The size, in bytes, of a QSE_tkr.

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

After allocating an QSE_tkr structure, the structure should be initialized using QSE_tkrUnpackInit().

static void unpackTots	(	QSE_tkrTwr *	twr,
		const unsigned char *	tots
	)			[static]

Unpacks the TOTs.

Parameters:

	twr	The target tower
	tots	The TOT data

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.

int unpackTwr	(	QSE_tkrTwr *	twr,
		const EBF_tkr *	tkr,
		int	maxwrds
	)			[static]

Unpacks the data from one tower.

The number of strips on this tower

Parameters:

	twr	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.

---

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.

---