1 #ifndef ALIMUONTRACKERDDLDECODEREVENTHANDLER_H
2 #define ALIMUONTRACKERDDLDECODEREVENTHANDLER_H
3 /**************************************************************************
4 * This file is property of and copyright by the ALICE HLT Project *
5 * All rights reserved. *
8 * Artur Szostak <artursz@iafrica.com> *
10 * Permission to use, copy, modify and distribute this software and its *
11 * documentation strictly for non-commercial purposes is hereby granted *
12 * without fee, provided that the above copyright notice appears in all *
13 * copies and that both the copyright notice and this permission notice *
14 * appear in the supporting documentation. The authors make no claims *
15 * about the suitability of this software for any purpose. It is *
16 * provided "as is" without express or implied warranty. *
17 **************************************************************************/
22 /// \file AliMUONTrackerDDLDecoderEventHandler.h
23 /// \author Artur Szostak <artursz@iafrica.com>
25 /// \brief Implementation of a high performance DDL decoder event handler
26 /// for the muon tracking stations.
34 // We use C binding for the structures because C is more uniform with its application
35 // binary interface (ABI) between compilers.
39 // The following structures are the headers found in the DDL payload from the
40 // muon tracking chambers. The specification is defined in ALICE-INT-2005-012
41 // (https://edms.cern.ch/file/591904/1/ALICE-INT-2005-012.pdf)
43 /// The block header structure of the Tracker DDL payload.
44 struct AliMUONBlockHeaderStruct
46 UInt_t fDataKey; ///< Data key word for CRT header
47 UInt_t fTotalLength; ///< total length of block structure (w/o padding word)
48 UInt_t fLength; ///< length of raw data
49 UInt_t fDSPId; ///< DSP id
50 UInt_t fL0Trigger; ///< L0 trigger word
51 UInt_t fMiniEventId; ///< Bunch Crossing for mini-event id (see TDR chapter 8)
52 UInt_t fEventId1; ///< Event Id in bunch crossing
53 UInt_t fEventId2; ///< Event Id in orbit number
56 /// The DSP header structure of the Tracker DDL payload.
57 struct AliMUONDSPHeaderStruct
59 UInt_t fDataKey; ///< Data key word for FRT header
60 UInt_t fTotalLength; ///< total length of block structure
61 UInt_t fLength; ///< length of raw data
62 UInt_t fDSPId; ///< DSP id
63 UInt_t fBlkL1ATrigger; ///< L1 accept in Block Structure (CRT)
64 UInt_t fMiniEventId; ///< Mini Event Id in bunch crossing
65 UInt_t fL1ATrigger; ///< Number of L1 accept in DSP Structure (FRT)
66 UInt_t fL1RTrigger; ///< Number of L1 reject in DSP Structure (FRT)
67 UInt_t fPaddingWord; ///< padding dummy word for 64 bits transfer
68 UInt_t fErrorWord; ///< Error word
71 /// The bus patch header structure of the Tracker DDL payload.
72 struct AliMUONBusPatchHeaderStruct
74 UInt_t fDataKey; ///< Data key word for bus patch header
75 UInt_t fTotalLength; ///< total length of bus patch structure
76 UInt_t fLength; ///< length of raw data
77 UInt_t fBusPatchId; ///< bus patch id
84 /// \class AliMUONTrackerDDLDecoderEventHandler
85 /// \brief Callback event handler class for the AliMUONTrackerDDLDecoder.
87 /// This class is the base class defining what methods the event handler for the
88 /// high performance decoder should have. This handler actually does nothing.
89 /// The user of this decoder will have to derive from this class a custom event
90 /// handler that actually does something within the callback methods OnNewBusPatch,
91 /// OnData, OnError etc...
93 /// \author Artur Szostak <artursz@iafrica.com>
95 class AliMUONTrackerDDLDecoderEventHandler
99 /// The only reason for a virtual destructor is to make -Weffc++ shutup.
100 /// This should not really be here since we do not need or use virtual methods.
101 virtual ~AliMUONTrackerDDLDecoderEventHandler() {}
103 /// All the possible error codes for the parsing.
106 kNoError = 0, /// Decoding was successful.
107 // Offset our error codes to stay clear of any common codes in AliMUONRawStreamTracker:
108 kBufferTooBig = 10, /// The DDL raw data is larger than indicated by the headers; extra bytes are probably just garbage.
109 kTooManyBlocks = 11, /// Too many block structures found.
110 kTooManyDSPs = 12, /// Too many DSP structures found in the block.
111 kTooManyBusPatches = 13, /// Too many bus patch structures found in the DSP structure.
112 kNoBlockHeader = 14, /// Missing a block header.
113 kBadBlockKey = 15, /// The block header key word does not contain the correct value.
114 kBadBlockLength = 16, /// The block length field points past the end of the raw data size.
115 kBadBlockTotalLength = 17, /// The total block length field points past the end of the raw data size.
116 kBlockLengthMismatch = 18, /// The block length and total length fields do not correspond. One or both of these values is incorrect.
117 kNoDSPHeader = 19, /// Missing a DSP header.
118 kBadDSPKey = 20, /// The DSP header key word does not contain the correct value.
119 kBadDSPLength = 21, /// The DSP structure length field points past the end of the block structure.
120 kBadDSPTotalLength = 22, /// The total DSP structure length field points past the end of the block structure.
121 kDSPLengthMismatch = 23, /// The DSP structure length and total length fields do not correspond. One or both of these values is incorrect.
122 kNoBusPatchHeader = 24, /// Missing a bus patch header.
123 kBadBusPatchKey = 25, /// The bus patch header key word does not contain the correct value.
124 kBadBusPatchLength = 26, /// The bus patch length field points past the end of the DSP structure.
125 kBadBusPatchTotalLength = 27, /// The total bus patch length field points past the end of the DSP structure.
126 kBusPatchLengthMismatch = 28, /// The bus patch length and total length fields do not correspond. One or both of these values is incorrect.
127 // match up error codes with AliMUONRawStreamTracker:
128 kGlitchFound = 1, /// Found a glitch. This means a 1 byte word has been randomly inserted into the raw data by mistake.
129 kBadPaddingWord = 2, /// The padding word does not contain the correct value.
130 kParityError = 3 /// Found a parity error in the data word.
133 // The following methods should be overridden for specific processing to
134 // take place in your event handler.
136 /// The OnNewBuffer method will be called whenever a new buffer containing
137 /// a DDL payload is about to be processed.
138 /// The default behaviour of this method is to do nothing.
139 /// - param const void* The pointer to the start of the memory buffer storing
141 /// - param UInt_t The size in bytes of the memory buffer.
142 void OnNewBuffer(const void* /*buffer*/, UInt_t /*bufferSize*/) {}
144 void OnEndOfBuffer(const void* /*buffer*/, UInt_t /*bufferSize*/) {}
146 /// OnNewBlock is called whenever a new block header is found in the payload.
147 /// The default behaviour of this method is to do nothing.
148 /// - param const AliMUONBlockHeaderStruct* This is a pointer to the block header as found in the
150 /// - param const void* This is a pointer to the start of the block's contents.
151 /// Note: both pointers point into the memory buffer being parsed so the
152 /// contents must not be modified. On the other hand this is very efficient
153 /// because no memory copying is required.
154 void OnNewBlock(const AliMUONBlockHeaderStruct* /*header*/, const void* /*data*/) {}
156 void OnEndOfBlock(const AliMUONBlockHeaderStruct* /*header*/, const void* /*data*/) {}
158 /// OnNewDSP is called whenever a new DSP header is found in the payload.
159 /// Every DSP header recevied by a call to OnNewDSP is associated to the
160 /// block header received in the most recent call to OnNewBlock.
161 /// The default behaviour of this method is to do nothing.
162 /// - param const AliMUONDSPHeaderStruct* This is a pointer to the DSP header as found in the
164 /// - param const void* This is a pointer to the start of the DSP's contents.
165 /// Note: both pointers point into the memory buffer being parsed so the
166 /// contents must not be modified. On the other hand this is very efficient
167 /// because no memory copying is required.
168 void OnNewDSP(const AliMUONDSPHeaderStruct* /*header*/, const void* /*data*/) {}
170 void OnEndOfDSP(const AliMUONDSPHeaderStruct* /*header*/, const void* /*data*/) {}
172 /// OnNewBusPatch is called whenever a new bus patch header is found in
173 /// the payload. Every bus patch recevied by a call to OnNewBusPatch is
174 /// associated to the DSP header received in the most recent call to OnNewDSP.
175 /// The default behaviour of this method is to do nothing.
176 /// - param const AliMUONBusPatchHeaderStruct* This is a pointer to the bus patch header as found
177 /// in the DDL payload.
178 /// - param const void* This is a pointer to the start of the bus patch's contents,
179 /// specifically the raw data words.
180 /// Note: both pointers point into the memory buffer being parsed so the
181 /// contents must not be modified. On the other hand this is very efficient
182 /// because no memory copying is required.
183 void OnNewBusPatch(const AliMUONBusPatchHeaderStruct* /*header*/, const void* /*data*/) {}
185 void OnEndOfBusPatch(const AliMUONBusPatchHeaderStruct* /*header*/, const void* /*data*/) {}
187 /// OnData is called for every raw data word found within a bus patch.
188 /// Every data ward recevied by a call to OnData is associated to the bus patch
189 /// header received in the most recent call to OnNewBusPatch.
190 /// The default behaviour of this method is to do nothing.
191 /// - param UInt_t This is the raw data word as found within the bus patch payload.
192 /// - param bool Flag indicating if the raw data word had a parity error.
193 /// This will always be set to false if fSendDataOnParityError in the
194 /// AliMUONTrackerDDLDecoder class was set to true.
195 void OnData(UInt_t /*data*/, bool /*parityError*/) {}
197 /// Whenever a parsing error of the DDL payload is encountered because of
198 /// corruption of the raw data (eg. bit flips) the OnError method is called
199 /// imediately at the point this error is discovered.
200 /// The default behaviour of this method is to do nothing.
201 /// - param ErrorCode This is an error code indicating the kind of problem
202 /// encountered with the DDL payload.
203 /// - param const void* This is a pointer into the DDL payload memory buffer
204 /// indicating the exact location where the parsing error happened
205 /// or i.e. the location of the corruption.
206 /// Note that a relative offset in bytes from the start of the memory buffer
207 /// can be calculated by: storing the buffer pointer recevied in OnNewBuffer
208 /// earlier in fBufferStart for example, and then the offset is given by:
209 /// offset = (unsigned long)location - (unsigned long)fBufferStart;
210 void OnError(ErrorCode /*error*/, const void* /*location*/) {}
212 /// This is a utility method which will unpack the MANU ID, channel ID and
213 /// ADC signal value from a raw data word. It should normally be used in
214 /// OnData() to unpack these fields.
215 /// [in] \param data This is the raw data word found in the DDL payload.
216 /// [out] \param manuId This is filled with the unpacked MANU ID.
217 /// [out] \param channelId This is filled with the unpacked MANU channel ID.
218 /// [out] \param adc This is filled with the unpacked ADC signal.
219 static void UnpackADC(
221 UShort_t& manuId, UChar_t& channelId, UShort_t& adc
224 manuId = (UShort_t)(data >> 18) & 0x7FF;
225 channelId = (Char_t)(data >> 12) & 0x3F;
226 adc = (UShort_t)(data & 0xFFF);
229 /// This is a utility method which converts an error code to a string
230 /// respresentation for printing purposes.
231 /// \param code The error code as received in OnError for example.
232 /// \return An ANSI string containing the name of the error code symbol.
233 static const char* ErrorCodeToString(ErrorCode code);
235 /// This is a utility method which converts an error code to user friendly
236 /// descriptive message useful for printing to the screen.
237 /// \param code The error code as received in OnError for example.
238 /// \return An ANSI string containing a descriptive message of the error.
239 static const char* ErrorCodeToMessage(ErrorCode code);
242 #endif // ALIMUONTRACKERDDLDECODEREVENTHANDLER_H