A high performance decoder class for MUON tracking DDL data. More...

#include <AliMUONTrackerDDLDecoder.h>

Public Member Functions
	AliMUONTrackerDDLDecoder ()
	Default contructor. More...

const EventHandler &	GetHandler () const
	Constant method to return the event handler instance. More...

EventHandler &	GetHandler ()
	Returns the event handler instance. More...

bool	ExitOnError () const

void	ExitOnError (bool value)

bool	TryRecover () const

void	TryRecover (bool value)

bool	SendDataOnParityError () const

void	SendDataOnParityError (bool value)

UInt_t	MaxBlocks () const
	Returns the maximum block count expected in the DDL payload. More...

void	MaxBlocks (UInt_t n)
	Sets the maximum block count expected in the DDL payload. More...

UInt_t	MaxDSPs () const

void	MaxDSPs (UInt_t n)

UInt_t	MaxBusPatches () const

void	MaxBusPatches (UInt_t n)

bool	AutoDetectTrailer () const
	Returns the value of the auto-detect trailer flag. More...

void	AutoDetectTrailer (bool value)
	Sets the value of the auto-detect trailer flag. More...

bool	CheckForTrailer () const
	Returns the value of the flag to check for the end of DDL trailer. More...

void	CheckForTrailer (bool value)
	Sets the value of the flag to check for the end of DDL trailer. More...

bool	Decode (const void *buffer, UInt_t bufferSize)
	This method decodes the DDL payload contained in the buffer. More...

bool	Decode (void *buffer, UInt_t bufferSize)
	First try fix data corruption and then decode the DDL payload. More...

Static Public Member Functions
static UInt_t	BlockDataKeyWord ()
	Returns the block marker key. More...

static UInt_t	DspDataKeyWord ()
	Returns the DSP marker key. More...

static UInt_t	BusPatchDataKeyWord ()
	Returns the bus patch marker key. More...

static UInt_t	PaddingWord ()
	Returns the expected padding word value. More...

static UInt_t	EndOfDDLWord ()
	Returns the expected end of DDL marker. More...

Private Types
enum	RecoverResult { kRecoverFailed, kStructRecovered, kContinueToNextStruct }
	Possible results that can be returned by the TryRecoverStruct method. More...

Private Member Functions
void	DecodeBuffer (const UChar_t start, const UChar_t end)

bool	DecodeBlockData (const AliMUONBlockHeaderStruct blockHeader, const UChar_t start, const UChar_t *end)

bool	DecodeDSPData (const UChar_t start, const UChar_t end)

bool	DecodeBusPatchData (const UChar_t start, const UChar_t end)

RecoverResult	TryRecoverStruct (UInt_t expectedKey, UInt_t headerSize, UInt_t totalLength, UInt_t length, const UChar_t structStart, const UChar_t bufferEnd, const UChar_t &dataEnd, const UChar_t &structEnd, const UChar_t *&current)

const UChar_t *	FindKey (UInt_t key, const UChar_t start, const UChar_t end)

bool	ParityIsOk (UInt_t data)

Private Attributes
bool	fExitOnError
	Indicates if we should exit on the very first error. More...

bool	fTryRecover
	Indicates if we should try recover from a corrupt structure header or DDL trailer. More...

bool	fSendDataOnParityError
	If set to true then we issue a OnData() event even if the data word had a parity error. More...

bool	fHadError
	Indicates if we had an error decoding the data. More...

bool	fAutoDetectTrailer
	Indicates if we should automatically check for the end of DDL trailer (Default = true). More...

bool	fCheckForTrailer
	Indicates if we should check for the end of DDL trailer (Default = true). This flag is ignored if fAutoDetectTrailer is true. More...

UInt_t	fMaxBlocks
	Maximum number of block structures allowed in a DDL stream. More...

UInt_t	fMaxDSPs
	Maximum number of DSP structures allowed in a DDL stream. More...

UInt_t	fMaxBusPatches
	Maximum number of bus patch structures allowed in a DDL stream. More...

EventHandler	fHandler
	The event handler which deals with parsing events. More...

Static Private Attributes
static const UInt_t	fgkBlockDataKey = 0xFC0000FC
	The key word expected to identify block structure headers. More...

static const UInt_t	fgkDSPDataKey = 0xF000000F
	The key word expected to identify DSP structure headers. More...

static const UInt_t	fgkBusPatchDataKey = 0xB000000B
	The key word expected to identify bus patch headers. More...

static const UInt_t	fgkPaddingWord = 0xBEEFFACE
	The expected format of the padding word in the DDL payload. More...

static const UInt_t	fgkEndOfDDL = 0xD000000D
	The end of DDL trailer word. More...

Detailed Description

template<class EventHandler>
class AliMUONTrackerDDLDecoder< EventHandler >

A high performance decoder class for MUON tracking DDL data.

This class implements a high performance decoder for decoding DDL payload data coming from the muon spectrometers tracking chambers. It has been implemented using the event driven paradigm with templates, which allows us to minimise the number of method calls made in the inner loops of the algorithm and minimise the memory footprint. At least for optimised production compilations. The decoder class only contains the basic decoding and error checking logic. It calls methods such as OnNewBlock, OnNewBusPatch, OnData etc in the event handler during the decoding to return the decoded data. The event handler class is nothing more than a callback interface to deliver the next chunks of decoded data. To actually do something with the data, one needs to implement a custom event handler (callback) class by inheriting from AliMUONTrackerDDLDecoderEventHandler and overriding the callback methods like so:

class MyCustomHandler : public AliMUONTrackerDDLDecoderEventHandler
{
public:
   void OnData(UInt_t data, bool parityError)
   {
     // I can do something with 'data' here and check if there was
     // a parity error with 'parityError'.
   }
};

Once the custom handler is written then the decoder is instantiated as shown below, to use your new custom handler. Also to start decoding one needs to call the Decode() method of the decoder.

AliMUONTrackerDDLDecoder<MyCustomHandler> myDecoder;

muDecoder.Decoder(buffer, bufferSize);

Note that this class was written as a template on purpose. To maximise the compilers chance to make optimisations and inline the code we must use a template. Depending on exactly what you do inside your handler, the decoder could be significantly slower if run time polymorphism was used, i.e. making the class AliMUONTrackerDDLDecoderEventHandler abstract and using virtual methods.

There has been a change to the data format that the real detector generates. Two trailer words are added to the end of the DDL payload which indicated the end of data. The decoder is initialised by default to automatically check for these and deal with it correctly, if they exist or not. However, if you want to override this behaviour then set the flag fAutoDetectTrailer to false with AutoDetectTrailer(false). Then if you have data with the old data format you should set fCheckForTrailer to false with CheckForTrailer(false), otherwise for real data it should be fCheckForTrailer = true. Only when fAutoDetectTrailer is true will the fCheckForTrailer flag be ignored and no warnings will be generated for an incorrect data format.

Author: Artur Szostak artur.nosp@m.sz@i.nosp@m.afric.nosp@m.a.co.nosp@m.m

Definition at line 102 of file AliMUONTrackerDDLDecoder.h.

Member Enumeration Documentation

template<class EventHandler>

enum AliMUONTrackerDDLDecoder::RecoverResult

private

Possible results that can be returned by the TryRecoverStruct method.

Enumerator
kRecoverFailed	The recovery failed. Cannot continue parsing.
kStructRecovered	Indicates that we recovered from a corrupt structure header and can continue processing the given structure.
kContinueToNextStruct	Must continue parsing the next structure and ignore the current one.

Definition at line 228 of file AliMUONTrackerDDLDecoder.h.

Constructor & Destructor Documentation

template<class EventHandler>

AliMUONTrackerDDLDecoder< EventHandler >::AliMUONTrackerDDLDecoder ( )

inline

Default contructor.

Definition at line 107 of file AliMUONTrackerDDLDecoder.h.

Member Function Documentation

template<class EventHandler>

bool AliMUONTrackerDDLDecoder< EventHandler >::AutoDetectTrailer ( ) const

inline

Returns the value of the auto-detect trailer flag.

Definition at line 171 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

void AliMUONTrackerDDLDecoder< EventHandler >::AutoDetectTrailer ( bool value )

inline

Sets the value of the auto-detect trailer flag.

Definition at line 174 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

static UInt_t AliMUONTrackerDDLDecoder< EventHandler >::BlockDataKeyWord ( )

inlinestatic

Returns the block marker key.

Definition at line 189 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

static UInt_t AliMUONTrackerDDLDecoder< EventHandler >::BusPatchDataKeyWord ( )

inlinestatic

Returns the bus patch marker key.

Definition at line 195 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

bool AliMUONTrackerDDLDecoder< EventHandler >::CheckForTrailer ( ) const

inline

Returns the value of the flag to check for the end of DDL trailer.

Definition at line 177 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

void AliMUONTrackerDDLDecoder< EventHandler >::CheckForTrailer ( bool value )

inline

Sets the value of the flag to check for the end of DDL trailer.

Definition at line 180 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler >

bool AliMUONTrackerDDLDecoder< EventHandler >::Decode	(	const void *	buffer,
		UInt_t	bufferSize
	)

This method decodes the DDL payload contained in the buffer.

This method should be called to actually decode the DDL payload contained in a memory buffer. The payload should be for a muon tracking chamber DDL stream. As the decoder progresses it will make method calls to the event handler instance (which can be accessed with the GetHandler() method) to indicate the start of the new block, DSP and bus patch headers. For every raw data word the OnData method of the event handler is called.

If an error occurs during the parse because the data is corrupt then the OnError method is called indicating what the problem was. Decoding will stop at this point unless the fExitOnError flag is set to false. Also raw data words which contain a parity error are only sent to the event handler with OnData if the fSendDataOnParityError flag is set to true. There is also an optional flag fTryRecover which can enable logic which will attempt to recover the header structures found in the DDL payload if they are found to be inconsistent (assumed corrupt). fTryRecover set to true will also enable recovery from a corrupt DDL trailer marking the end of DDL payload.

Parameters

buffer	This is the pointer to the start of the memory buffer containing the DDL payload. Remember that this must be the start of the payload and not the DDL stream. That is, this pointer should be equal to: DDL start pointer + 8 * sizeof(UInt_t).
bufferSize	This is the pointer to the first byte just past the end of the block structure.

Returns: Returns false if there was any problem with decoding the data, and true otherwise. Note: the data may have been partially decoded even if false was returned, which would be indicated by at least one call to the event handlers OnData method.

Definition at line 277 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler >

bool AliMUONTrackerDDLDecoder< EventHandler >::Decode	(	void *	buffer,
		UInt_t	bufferSize
	)

First try fix data corruption and then decode the DDL payload.

This decoding method performs a special checks to see if the DDL corruption is fixable and then fixes the buffer by modifying it directly. The fixes only apply if the fTryRecover flag is enabled.

Note: buffer might be modified.

Definition at line 326 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler >

bool AliMUONTrackerDDLDecoder< EventHandler >::DecodeBlockData	(	const AliMUONBlockHeaderStruct *	blockHeader,
		const UChar_t *	start,
		const UChar_t *	end
	)

private

This method decodes a block structure's data payload. It unpacks the DSP structures contained inside and then for each DSP it calls the OnNewDSP method for the event handler to signal the start of each new DSP structure.

Parameters

blockHeader
start	This is the pointer to the start of the block structure's data.
end	This is the pointer to the first byte just past the end of the block structure.

Returns: If the block structure's data was decoded without errors or we could recover from the errors, then true is returned. False is returned otherwise.

Definition at line 586 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler >

void AliMUONTrackerDDLDecoder< EventHandler >::DecodeBuffer	(	const UChar_t *	start,
		const UChar_t *	end
	)

private

This method decodes the buffer's payload data. It unpacks the block structures contained inside and then for each block it calls the OnNewBlock method for the event handler to signal the start of each new block structure. OnEndOfBlock is called once each block is processed.

Parameters

start	This is the pointer to the start of the buffer.
end	This is the pointer to the first byte just past the end of the buffer. fHadError is set to true if there were any errors decoding the buffer and the OnError method of the callback event handler is called for each error.

Definition at line 363 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler >

bool AliMUONTrackerDDLDecoder< EventHandler >::DecodeBusPatchData	(	const UChar_t *	start,
		const UChar_t *	end
	)

private

This method decodes a single bus patch's data payload. It will check the parity of the raw data words and send them to the event handler instance with calls to OnData.

Parameters

start	This is the pointer to the start of the bus patch structure's data.
end	This is the pointer to the first byte just past the end of the bus patch structure.

Returns: If the bus patch's data was decoded without errors or we could recover from the errors, then true is returned. False is returned otherwise.

Definition at line 905 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler >

bool AliMUONTrackerDDLDecoder< EventHandler >::DecodeDSPData	(	const UChar_t *	start,
		const UChar_t *	end
	)

private

This method decodes a DSP structure's data payload. It finds all the bus patches found inside and for each it calls the OnNewBusPatch method for the event handler to signal the start of each new bus patch.

Parameters

start	This is the pointer to the start of the DSP structure's data.
end	This is the pointer to the first byte just past the end of the DSP structure.

Returns: If the DSP structure's data was decoded without errors or we could recover from the errors, then true is returned. False is returned otherwise.

Definition at line 777 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

static UInt_t AliMUONTrackerDDLDecoder< EventHandler >::DspDataKeyWord ( )

inlinestatic

Returns the DSP marker key.

Definition at line 192 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

static UInt_t AliMUONTrackerDDLDecoder< EventHandler >::EndOfDDLWord ( )

inlinestatic

Returns the expected end of DDL marker.

Definition at line 201 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

bool AliMUONTrackerDDLDecoder< EventHandler >::ExitOnError ( ) const

inline

Returns the "exit on error" flag. i.e. should the decoder stop on the very first error found.

Definition at line 122 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

void AliMUONTrackerDDLDecoder< EventHandler >::ExitOnError ( bool value )

inline

Sets the "exit on error" flag. i.e. should the decoder stop on the very first error found.

Definition at line 126 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler >

const UChar_t * AliMUONTrackerDDLDecoder< EventHandler >::FindKey	(	UInt_t	key,
		const UChar_t *	start,
		const UChar_t *	end
	)

private

Searches for the first occurrence of the key value in the buffer marked by 'start' and 'end'. 'start' should point to the start of the buffer and 'end' should point to 'start + bufferSize', i.e. just past the last byte of the buffer. If the key was found then the pointer to that location is returned otherwise NULL is returned.

Definition at line 1203 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

const EventHandler& AliMUONTrackerDDLDecoder< EventHandler >::GetHandler ( ) const

inline

Constant method to return the event handler instance.

Definition at line 115 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

EventHandler& AliMUONTrackerDDLDecoder< EventHandler >::GetHandler ( )

inline

Returns the event handler instance.

Definition at line 118 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

UInt_t AliMUONTrackerDDLDecoder< EventHandler >::MaxBlocks ( ) const

inline

Returns the maximum block count expected in the DDL payload.

Definition at line 149 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

void AliMUONTrackerDDLDecoder< EventHandler >::MaxBlocks ( UInt_t n )

inline

Sets the maximum block count expected in the DDL payload.

Definition at line 152 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

UInt_t AliMUONTrackerDDLDecoder< EventHandler >::MaxBusPatches ( ) const

inline

Returns the maximum number of bus patches expected in any given DSP structure within the DDL payload.

Definition at line 164 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

void AliMUONTrackerDDLDecoder< EventHandler >::MaxBusPatches ( UInt_t n )

inline

Sets the maximum number of bus patches expected in any given DSP structure within the DDL payload.

Definition at line 168 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

UInt_t AliMUONTrackerDDLDecoder< EventHandler >::MaxDSPs ( ) const

inline

Returns the maximum DSP header count expected in any given block structure within the DDL payload.

Definition at line 156 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

void AliMUONTrackerDDLDecoder< EventHandler >::MaxDSPs ( UInt_t n )

inline

Sets the maximum DSP header count expected in any given block structure within the DDL payload.

Definition at line 160 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

static UInt_t AliMUONTrackerDDLDecoder< EventHandler >::PaddingWord ( )

inlinestatic

Returns the expected padding word value.

Definition at line 198 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler >

bool AliMUONTrackerDDLDecoder< EventHandler >::ParityIsOk ( UInt_t data )

private

Optimised parity check addapted from: http://graphics.stanford.edu/~seander/bithacks.html#ParityParallel

Definition at line 1226 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

bool AliMUONTrackerDDLDecoder< EventHandler >::SendDataOnParityError ( ) const

inline

Returns the flag indicating if the raw data words in the bus patches that failed their parity tests (i.e. parity error / bit flip in the raw data word) will be sent to the event handler anyway through OnData.

Definition at line 141 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

void AliMUONTrackerDDLDecoder< EventHandler >::SendDataOnParityError ( bool value )

inline

Sets the flag indicating if the raw data words in the bus patches that failed their parity tests (i.e. parity error / bit flip in the raw data word) will be sent to the event handler anyway through OnData.

Definition at line 146 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

bool AliMUONTrackerDDLDecoder< EventHandler >::TryRecover ( ) const

inline

Returns the "try to recover from errors" flag. i.e. should the decoder try to recover from errors found in the payload headers or trailers.

Definition at line 131 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler>

void AliMUONTrackerDDLDecoder< EventHandler >::TryRecover ( bool value )

inline

Sets the "try to recover from errors" flag. i.e. should the decoder try to recover from errors found in the payload headers or trailers.

Definition at line 136 of file AliMUONTrackerDDLDecoder.h.

template<class EventHandler >

AliMUONTrackerDDLDecoder< EventHandler >::RecoverResult AliMUONTrackerDDLDecoder< EventHandler >::TryRecoverStruct	(	UInt_t	expectedKey,
		UInt_t	headerSize,
		UInt_t	totalLength,
		UInt_t	length,
		const UChar_t *	structStart,
		const UChar_t *	bufferEnd,
		const UChar_t *&	dataEnd,
		const UChar_t *&	structEnd,
		const UChar_t *&	current
	)

private

This method attempts to recover from a corrupt structure header by figuring out which of the structure size indicators is correct. This is possible because each header has some redundant information. The recovery procedure is only attempted if fTryRecover was set to true. If the recovery procedure is successful then this method will also update the pointers indicating the start of data, end of structure and current parsing position with the correct values.

[in]

Parameters

expectedKey	This is the expected block key for the header currently being processed. [in]
headerSize	The expected header size as given by the sizeof operator for example. [in]
totalLength	The total length as given by the fTotalLength field in the current header being handled. [in]
length	The data length as given by the fLength field in the current header being handled. [in]
structStart	A pointer to the start of the structure header. [in]
bufferEnd	A pointer to the first byte just past the end of the buffer. This could be the pointer to the first byte just past the end of the parent structure if we are dealing with a DSP structure or bus patch. The parent structure for the DSP is a block structure and for a bus patch it is a DSP. [out]
dataEnd	This is the pointer to the first byte just past the end of the structure being processed. It should be equal to structStart + sizeof(structure header) + fLength, where fLength is the field found in the structure's header itself. This value will be corrected and updated if we could recover from the corruption in the header. [out]
structEnd	A pointer to the first byte just past the end of the structure. This value should be set equal to structStart + fTotalLength * sizeof(UInt_t), where fTotalLength is the field found in the structure's header itself. This value will be corrected and updated if we could recover from the corruption in the header. [out]
current	This is the pointer to the current location in the DDL payload being parsed. It should in principle point to the start of the structures data. This value will be corrected and updated if we could recover from the corruption in the header.

Returns: Returns the result of the recovery attempt, which can be one of the following: kRecoverFailed - The recovery failed completely so the caller cannot continue parsing any more structures. If the failure is within a DSP then one could still continue parsing from the next block. Similarly for bus patches, parsing could continue from the next DSP structure. kStructRecovered - Indicates that we recovered from a corrupt structure header and can continue processing the data of the structure in question. kContinueToNextStruct - Either fTryRecover was set to false or we could not recover from the corrupt header but we did find the start of another header matching the expected key so parsing can continue from the updated current position.

Definition at line 956 of file AliMUONTrackerDDLDecoder.h.