Unpacker for DDAS data recorded by NSCLDAQ. More...

#include <DDASHitUnpacker.h>

Public Member Functions
std::tuple< DDASHit, const uint32_t * >	unpack (const uint32_t beg, const uint32_t sentinel)
	Unpack data into a DDASHit. More...

const uint32_t *	unpack (const uint32_t beg, const uint32_t sentinel, DDASHit &hit)
	Unpack data into a DDASHit. More...

Protected Member Functions
const uint32_t *	parseBodySize (const uint32_t data, const uint32_t sentinel)
	Ensure there is enough data to parse. More...

const uint32_t *	parseModuleInfo (DDASHit &hit, const uint32_t *data)
	Parse the module identifying information encoded in the hit. More...

const uint32_t *	parseHeaderWord0 (DDASHit &hit, const uint32_t *data)
	Parse the word 0 of the Pixie-16 data header. More...

const uint32_t *	parseHeaderWords1And2 (DDASHit &hit, const uint32_t *data)
	Parse words 1 and 2 of the Pixie-16 data header. More...

const uint32_t *	parseHeaderWord3 (DDASHit &hit, const uint32_t *data)
	Parse word 3 of the Pixie-16 data header. More...

const uint32_t *	parseTraceData (DDASHit &hit, const uint32_t *data)
	Unpack the trace data. More...

std::tuple< double, uint32_t, uint32_t, uint32_t >	parseAndComputeCFD (uint32_t ModMSPS, uint32_t data)
	Determine the CFD correction to the leading-edge time in nanoseconds from the CFD word. More...

double	parseAndComputeCFD (DDASHit &hit, uint32_t data)
	Determine the CFD correction to the leading-edge time in nanoseconds from the CFD word. More...

uint64_t	computeCoarseTime (uint32_t adcFrequency, uint32_t timeLow, uint32_t timeHigh)
	Compute time in nanoseconds from raw data (no CFD correction). More...

const uint32_t *	extractEnergySums (const uint32_t *data, DDASHit &hit)
	Unpack energy sums. More...

const uint32_t *	extractQDC (const uint32_t *data, DDASHit &hit)
	Unpack QDC values. More...

const uint32_t *	extractExternalTimestamp (const uint32_t *data, DDASHit &hit)
	Unpack the external timestamp data. More...

Detailed Description

Unpacker for DDAS data recorded by NSCLDAQ.

This class unpacks NSCLDAQ-formatted Pixie-16 data recorded by a DDAS readout program into DDASHits which encapsulate the information recorded by a single Pixie channel. This is a generic unpacker which can accommodate information from all Pixie-16 digitizer types at FRIB. In general, all of the digitizer outputs contain the same information but importantly the meaning of the CFD data depends on the digitizer type. The unpacker class abstracts this difference away from the user.

This class does not provide any parsing capabilities like the ddasdumper. You must create a DDASHit object and unpack data into it. Here is how you do that:

DDASHit hit;
DDASHitUnpacker unpacker;
unpacker.unpack(pData, pData + sizeOfData, hit);

where pData is a pointer to the first 32-bit word of the hit body and sizeOfData is the size of the hit in 32-bit words.

Member Function Documentation

◆ computeCoarseTime()

uint64_t ddasfmt::DDASHitUnpacker::computeCoarseTime	(	uint32_t	adcFrequency,
		uint32_t	timeLow,
		uint32_t	timeHigh
	)

protected

Compute time in nanoseconds from raw data (no CFD correction).

Parameters

adcFrequency	Module ADC frequency in MSPS.
timeLow	Data word containing the lower 32 bits of the 48-bit timestamp.
timeHigh	Data word containing the upper 16 bits of the 48-bit timestamp.

Returns: The 48-bit coarse timestamp in nanoseconds.

Form the timestamp from the low and high bits and convert it to a time in nanoseconds.

The calculations for the various modules are as follows:

For the 100 MSPS module (100 MHz timestamping clock):

\[\text{time} = 10\times((\text{timeHigh} << 32) + \text{timeLow})\]

For the 250 MSPS module (125 MHz):

\[\text{time} = 8\times((\text{timeHigh} << 32) + \text{timeLow})\]

For the 500 MSPS module (100 MHz):

\[\text{time} = 10\times((\text{timeHigh} << 32) + \text{timeLow})\]

◆ extractEnergySums()

const uint32_t * ddasfmt::DDASHitUnpacker::extractEnergySums	(	const uint32_t *	data,
		DDASHit &	hit
	)

protected

Unpack energy sums.

Parameters

data	Pointer to the first 32-bit word containing the energy sum data.
hit	References the DDASHit we are unpacking.

Returns: Pointer to the word after the energy sums.

Energy sums consist of SIZE_OF_ENE_SUMS (=4) 32-bit words, which are, in order: 0. The trailing (pre-gap) sum.

The gap sum.
The leading (post-gap) sum.
The 32-bit IEEE 754 floating point baseline value. Each call to this function overwrites any previous energy sum data stored in the hit.

◆ extractExternalTimestamp()

const uint32_t * ddasfmt::DDASHitUnpacker::extractExternalTimestamp	(	const uint32_t *	data,
		DDASHit &	hit
	)

protected

Unpack the external timestamp data.

Parameters

data	Pointer to the first of the two 32-bit words containing the 48-bit external timestamp.
hit	References the DDASHit we are unpacking.

Returns: Pointer to the word after the external timestamp.

Unpack and set the 48-bit external timestamp. Unlike the internal timestamp where the conversion from clock tics to nanoseconds is known, for the external timestamp no unit conversion is applied. Converting the timestamp to proper units is left to the user.

Note: The lower 32 bits of the 48-bit timestamp are in in the 32-bit word pointed to by data and the upper 16 bits are in the lower 16 bits of the next 32-bit word.

◆ extractQDC()

const uint32_t * ddasfmt::DDASHitUnpacker::extractQDC	(	const uint32_t *	data,
		DDASHit &	hit
	)

protected

Unpack QDC values.

Parameters

data	Pointer to the first 32-bit word containing the QDC sum data.
hit	References the DDASHit we are unpacking.

Returns: Pointer to the word after the QDC sums.

QDC sums consist of SIZE_OF_QDC_SUMS (=8) 32-bit words. Each call overwrites any previous QDC sum data stored in the hit.

◆ parseAndComputeCFD() [1/2]

double ddasfmt::DDASHitUnpacker::parseAndComputeCFD	(	DDASHit &	hit,
		uint32_t	data
	)

protected

Determine the CFD correction to the leading-edge time in nanoseconds from the CFD word.

Parameters

hit	References the DDASHit we are unpacking.
data	The 32-bit data word encoding the CFD information.

Exceptions

std::runtime_error If the value of ModMSPS is not 100, 250, or 500.

Returns: The CFD correction in nanoseconds.

The value of the CFD correction depends on the module. Because the module information is encoded in the data, this function should be called after parseModuleInfo().

◆ parseAndComputeCFD() [2/2]

std::tuple< double, uint32_t, uint32_t, uint32_t > ddasfmt::DDASHitUnpacker::parseAndComputeCFD	(	uint32_t	ModMSPS,
		uint32_t	data
	)

protected

Determine the CFD correction to the leading-edge time in nanoseconds from the CFD word.

Parameters

ModMSPS	The module ADC frequency in MSPS.
data	The 32-bit data word encoding the CFD information.

Exceptions

std::runtime_error If the value of ModMSPS is not 100, 250, or 500.

Returns: Tuple of (CFD correction in nanoseconds, value of the CFD encoded in the data, CFD trigger source bit, CFD fail bit).

The value of the CFD correction depends on the module. Because the module information is encoded in the data, this function should be called after parseModuleInfo().

◆ parseBodySize()

const uint32_t * ddasfmt::DDASHitUnpacker::parseBodySize	(	const uint32_t *	data,
		const uint32_t *	sentinel
	)

protected

Ensure there is enough data to parse.

Parameters

data	Pointer to the hit body.
sentinel	Pointer to the first word after the body.

Exceptions

std::runtime_error If the event data is incomplete (no valid sentinel or data exceeds sentinel boundary).

Returns: Pointer to the next data word.

The first word of the body passed to this function is the self-inclusive event size in 16-bit words.

◆ parseHeaderWord0()

const uint32_t * ddasfmt::DDASHitUnpacker::parseHeaderWord0	(	DDASHit &	hit,
		const uint32_t *	data
	)

protected

Parse the word 0 of the Pixie-16 data header.

Parameters

hit	References the DDASHit we are unpacking.
data	The 32-bit data word to parse.

Returns: Pointer to the next data word (word 1).

Word 0 contains:

Crate/slot/channel information,
The header and channel lengths in 32-bit words,
The module finish code (equals 1 if piled up).
Note
In previous versions of the Pixie data format, the ADC out-of-range bit was stored in bit 30 of word 0 and the channel length was extracted from bits [17:29]. In the current data format, the out-of-range flag has been moved to word 3, bit 31, and the channel length mask is extracted from bits [17:30] allowing up to 16383 32-bit words per channel hit.

In hardware revision H, the crate/slot/channel information is stored differently in word 0. The channel ID is stored in bits [5:0], the slot ID is stored in bits [9:6], and the crate ID is stored in bits [11:10]. The unpacker checks the hardware revision from the hit to determine how to parse the crate/slot/channel information. This implies that the module information word must be unpacked before this function is called.

◆ parseHeaderWord3()

const uint32_t * ddasfmt::DDASHitUnpacker::parseHeaderWord3	(	DDASHit &	hit,
		const uint32_t *	data
	)

protected

Parse word 3 of the Pixie-16 data header.

Parameters

hit	References the DDASHit we are unpacking.
data	Pointer to word 3.

Returns: Pointer to the first word of the Pixie-16 data body.

Word 3 contains:

The trace out-of-range (overflow/underflow) flag,
The trace length in samples (16-bit words),
The hit energy.
Note
In the current Pixie list mode data format, the ADC out-of-range flag is stored in word 3, bit 31 rather than word 0, bit 30. See documentation for parseHeaderWord0() for more info.

◆ parseHeaderWords1And2()

const uint32_t * ddasfmt::DDASHitUnpacker::parseHeaderWords1And2	(	DDASHit &	hit,
		const uint32_t *	data
	)

protected

Parse words 1 and 2 of the Pixie-16 data header.

Parameters

hit	References the DDASHit we are unpacking.
data	Pointer to word 1.

Returns: Pointer to word 3.

Words 1 and 2 contain the timestamp and CFD information. The meaning of the CFD word depends on the module type. The unpacker abstracts this meaning away from the user. Note that we know the module type if the module identifier word was unpacked before calling this function.

Word 1 contains:

The lower 32 bits of the 48-bit timestamp. Word 2 contains:
The upper 16 bits of the 48-bit timestamp,
The CFD result.

◆ parseModuleInfo()

const uint32_t * ddasfmt::DDASHitUnpacker::parseModuleInfo	(	DDASHit &	hit,
		const uint32_t *	data
	)

protected

Parse the module identifying information encoded in the hit.

Parameters

hit	References the DDASHit we are unpacking.
data	The 32-bit data word containing the module identifying information.

Returns: Pointer to the next data word.

The lower 16 bits encode the ADC frequency, the upper 16 bits encode the hardware revision and ADC resolution.

◆ parseTraceData()

const uint32_t * ddasfmt::DDASHitUnpacker::parseTraceData	(	DDASHit &	hit,
		const uint32_t *	data
	)

protected

Unpack the trace data.

Parameters

hit	References the hit we are unpacking.
data	Pointer to the first 32-bit word containing trace data.

Returns: Pointer to the next non-trace 32-bit word.

The 16-bit trace data is stored two samples to one 32-bit word in little-endian. The data for sample i is stored in the lower 16 bits while the data for sample i + 1 is stored in the upper 16 bits. For ADCs with less than 16-bit resolution, those bits are set to 0.

◆ unpack() [1/2]

std::tuple< ddasfmt::DDASHit, const uint32_t * > ddasfmt::DDASHitUnpacker::unpack	(	const uint32_t *	beg,
		const uint32_t *	sentinel
	)

Unpack data into a DDASHit.

Parameters

beg	Pointer to the first word of the hit body.
sentinel	Pointer to the first word after the end of the body.

Exceptions

Any	exceptions thrown but the unpacking functions called by this function (e.g. `const uint32_t *unpack()`, `parseBodySize()`, `parseHeaderWord0()`, etc.) will be propagated.

Returns: Tuple of (DDASHit, nextWord).

This expects data from a DDAS readout program. It will parse the entire body of the event in a manner that is consistent with the data present. In other words, it uses the sizes of the event encoded in the data to determine when the parsing is complete.

While it parses, it stores the results into the data members of the object hit. All member data is zero-initialized prior to parsing using the default constructor of DDASHit.

◆ unpack() [2/2]

const uint32_t * ddasfmt::DDASHitUnpacker::unpack	(	const uint32_t *	beg,
		const uint32_t *	sentinel,
		DDASHit &	hit
	)

Unpack data into a DDASHit.

Parameters

[in]	beg	Pointer to the first 32-bit word of the hit body.
[in]	sentinel	Pointer to the first word after the end of the body.
[in,out]	hit	Reference to the DDASHit object filled during unpacking.

Exceptions

std::runtime_error	If the hit data buffer is empty.
std::runtime_error	If the hit's length is not the value specified in the header.

Returns: Pointer to the next data word after the hit.

This expects data from a DDAS readout program. It will parse the entire body of the event in a manner that is consistent with the data present. In other words, it uses the sizes of the event encoded in the data to determine when the parsing is complete.

While it parses, it stores the results into the data members of the object hit. Prior to parsing, all data members are reset to 0 using the Reset() method.

The documentation for this class was generated from the following files:

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation

◆ computeCoarseTime()

◆ extractEnergySums()

◆ extractExternalTimestamp()

◆ extractQDC()

◆ parseAndComputeCFD() [1/2]

◆ parseAndComputeCFD() [2/2]

◆ parseBodySize()

◆ parseHeaderWord0()

◆ parseHeaderWord3()

◆ parseHeaderWords1And2()

◆ parseModuleInfo()

◆ parseTraceData()

◆ unpack() [1/2]

◆ unpack() [2/2]