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 beg, const uint32_t sentinel)
	Ensure there is enough data to parse. More...

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

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

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

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

const uint32_t *	parseTraceData (DDASHit &hit, const uint32_t *beg)
	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 accomodate 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:

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

For the 250 MSPS module...

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

For the 500 MSPS module,

\[\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.

If the hit is not reset between calls to this function, the energy sum data will be appended to the end of the exisiting energy sums.

◆ extractExternalTimestamp()

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

protected

Unpack the external timestamp data.

Parameters

data	Pointer to the 32-bit word containing the lower 16 bits of 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.

◆ 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. If the hit is not reset between calls to this function, the QDC sum data will be appended to the end of the exisiting QDC sums.

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

Returns: double 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.

Returns: (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 there are an incorrect number of 16-bit data words in the event (words exceed sentinal boundry) and the pointer to the last data word is not a nullptr.

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.

◆ 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 32-bit trace word to unpack. The 32-bit trace word contains two 16-bit trace ADC values.

Returns: Pointer to the next 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.

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. Prior to parsing, all data members are reset to 0 using the Reset() method.

◆ 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]