]>
Commit | Line | Data |
---|---|---|
e3a2b9c9 | 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. * | |
6 | * * | |
7 | * Primary Authors: * | |
8 | * Artur Szostak <artursz@iafrica.com> * | |
9 | * * | |
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 | **************************************************************************/ | |
18 | ||
19 | /* $Id$ */ | |
20 | ||
21 | /// | |
22 | /// \file AliMUONTrackerDDLDecoderEventHandler.h | |
23 | /// \author Artur Szostak <artursz@iafrica.com> | |
24 | /// \date 28-11-2007 | |
25 | /// \brief Implementation of a high performance DDL decoder event handler | |
26 | /// for the muon tracking stations. | |
27 | /// | |
28 | ||
29 | #include <cassert> | |
30 | #include <ostream> | |
31 | #include <Rtypes.h> | |
32 | ||
33 | ||
34 | // We use C binding for the structures because C is more uniform with its application | |
35 | // binary interface (ABI) between compilers. | |
36 | extern "C" | |
37 | { | |
38 | ||
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) | |
42 | ||
43 | /// The block header structure of the Tracker DDL payload. | |
44 | struct AliMUONBlockHeaderStruct | |
45 | { | |
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 | |
54 | }; | |
55 | ||
56 | /// The DSP header structure of the Tracker DDL payload. | |
57 | struct AliMUONDSPHeaderStruct | |
58 | { | |
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 | |
69 | }; | |
70 | ||
71 | /// The bus patch header structure of the Tracker DDL payload. | |
72 | struct AliMUONBusPatchHeaderStruct | |
73 | { | |
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 | |
78 | }; | |
79 | ||
80 | } // extern "C" | |
81 | ||
82 | ||
83 | /// \ingroup raw | |
84 | /// \class AliMUONTrackerDDLDecoderEventHandler | |
85 | /// \brief Callback event handler class for the AliMUONTrackerDDLDecoder. | |
86 | /// | |
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... | |
92 | /// | |
93 | /// \author Artur Szostak <artursz@iafrica.com> | |
94 | ||
95 | class AliMUONTrackerDDLDecoderEventHandler | |
96 | { | |
97 | public: | |
98 | ||
99 | /// The only reason for a virtual destructor is to make -Weffc++ shutup. | |
8a0dae7c | 100 | /// This should not really be here since we do not need or use virtual methods. |
e3a2b9c9 | 101 | virtual ~AliMUONTrackerDDLDecoderEventHandler() {} |
102 | ||
103 | /// All the possible error codes for the parsing. | |
104 | enum ErrorCode | |
105 | { | |
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. | |
131 | }; | |
132 | ||
133 | // The following methods should be overridden for specific processing to | |
134 | // take place in your event handler. | |
135 | ||
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 | |
140 | /// the DDL payload. | |
141 | /// - param UInt_t The size in bytes of the memory buffer. | |
142 | void OnNewBuffer(const void* /*buffer*/, UInt_t /*bufferSize*/) {} | |
143 | ||
e0173291 | 144 | /// The OnEndOfBuffer method will be called whenever the buffer containing |
145 | /// a DDL payload has been processed. For each OnNewBuffer method call a | |
146 | /// symmetric call to OnEndOfBuffer is made at the end of processing (after | |
147 | /// the last call to OnData) | |
148 | /// The default behaviour of this method is to do nothing. | |
149 | /// - param const void* The pointer to the start of the memory buffer storing | |
150 | /// the DDL payload. | |
151 | /// - param UInt_t The size in bytes of the memory buffer. | |
8a0dae7c | 152 | void OnEndOfBuffer(const void* /*buffer*/, UInt_t /*bufferSize*/) {} |
153 | ||
e3a2b9c9 | 154 | /// OnNewBlock is called whenever a new block header is found in the payload. |
155 | /// The default behaviour of this method is to do nothing. | |
e0173291 | 156 | /// - param const AliMUONBlockHeaderStruct* This is a pointer to the block header |
157 | /// as found in the DDL payload. | |
e3a2b9c9 | 158 | /// - param const void* This is a pointer to the start of the block's contents. |
e0173291 | 159 | /// Note: both pointers point into the memory buffer being parsed, so the |
e3a2b9c9 | 160 | /// contents must not be modified. On the other hand this is very efficient |
161 | /// because no memory copying is required. | |
162 | void OnNewBlock(const AliMUONBlockHeaderStruct* /*header*/, const void* /*data*/) {} | |
163 | ||
e0173291 | 164 | /// OnEndOfBlock is called whenever a block has been processed. Symmetric |
165 | /// calls are made to OnEndOfBlock after each call to OnNewBlock. This happens | |
166 | /// once all DSP structures contained inside the current block have been | |
167 | /// processed. | |
168 | /// The default behaviour of this method is to do nothing. | |
169 | /// - param const AliMUONBlockHeaderStruct* This is a pointer to the processed | |
170 | /// block header as found in the DDL payload. | |
171 | /// - param const void* This is a pointer to the start of the block's contents. | |
172 | /// Note: both pointers point into the memory buffer being parsed, so the | |
173 | /// contents must not be modified. On the other hand this is very efficient | |
174 | /// because no memory copying is required. | |
8a0dae7c | 175 | void OnEndOfBlock(const AliMUONBlockHeaderStruct* /*header*/, const void* /*data*/) {} |
176 | ||
e3a2b9c9 | 177 | /// OnNewDSP is called whenever a new DSP header is found in the payload. |
178 | /// Every DSP header recevied by a call to OnNewDSP is associated to the | |
179 | /// block header received in the most recent call to OnNewBlock. | |
180 | /// The default behaviour of this method is to do nothing. | |
e0173291 | 181 | /// - param const AliMUONDSPHeaderStruct* This is a pointer to the DSP header |
182 | /// as found in the DDL payload. | |
e3a2b9c9 | 183 | /// - param const void* This is a pointer to the start of the DSP's contents. |
e0173291 | 184 | /// Note: both pointers point into the memory buffer being parsed, so the |
e3a2b9c9 | 185 | /// contents must not be modified. On the other hand this is very efficient |
186 | /// because no memory copying is required. | |
187 | void OnNewDSP(const AliMUONDSPHeaderStruct* /*header*/, const void* /*data*/) {} | |
188 | ||
e0173291 | 189 | /// OnEndOfDSP is called whenever a DSP header has already been processed. |
190 | /// For every call to OnNewDSP a symmetric call to OnEndOfDSP is made once | |
191 | /// all the bus patch structured contained in the DSP are processed. | |
192 | /// The default behaviour of this method is to do nothing. | |
193 | /// - param const AliMUONDSPHeaderStruct* This is a pointer to the already | |
194 | /// processed DSP header as found in the DDL payload. | |
195 | /// - param const void* This is a pointer to the start of the DSP's contents. | |
196 | /// Note: both pointers point into the memory buffer being parsed, so the | |
197 | /// contents must not be modified. On the other hand this is very efficient | |
198 | /// because no memory copying is required. | |
8a0dae7c | 199 | void OnEndOfDSP(const AliMUONDSPHeaderStruct* /*header*/, const void* /*data*/) {} |
200 | ||
e3a2b9c9 | 201 | /// OnNewBusPatch is called whenever a new bus patch header is found in |
e0173291 | 202 | /// the payload. Every bus patch received by a call to OnNewBusPatch is |
e3a2b9c9 | 203 | /// associated to the DSP header received in the most recent call to OnNewDSP. |
204 | /// The default behaviour of this method is to do nothing. | |
e0173291 | 205 | /// - param const AliMUONBusPatchHeaderStruct* This is a pointer to the bus patch |
206 | /// header as found in the DDL payload. | |
e3a2b9c9 | 207 | /// - param const void* This is a pointer to the start of the bus patch's contents, |
208 | /// specifically the raw data words. | |
e0173291 | 209 | /// Note: both pointers point into the memory buffer being parsed, so the |
e3a2b9c9 | 210 | /// contents must not be modified. On the other hand this is very efficient |
211 | /// because no memory copying is required. | |
212 | void OnNewBusPatch(const AliMUONBusPatchHeaderStruct* /*header*/, const void* /*data*/) {} | |
213 | ||
e0173291 | 214 | /// OnEndOfBusPatch is called whenever a bus patch has been processed. |
215 | /// For every call to OnNewBusPatch a symmetric call to OnEndOfBusPatch is | |
216 | /// made once the bus patch is completely processed (no more OnData calls). | |
217 | /// The default behaviour of this method is to do nothing. | |
218 | /// - param const AliMUONBusPatchHeaderStruct* This is a pointer to the already | |
219 | /// processed bus patch header, as found in the DDL payload. | |
220 | /// - param const void* This is a pointer to the start of the bus patch's contents, | |
221 | /// specifically the raw data words. | |
222 | /// Note: both pointers point into the memory buffer being parsed so the | |
223 | /// contents must not be modified. On the other hand this is very efficient | |
224 | /// because no memory copying is required. | |
8a0dae7c | 225 | void OnEndOfBusPatch(const AliMUONBusPatchHeaderStruct* /*header*/, const void* /*data*/) {} |
226 | ||
e3a2b9c9 | 227 | /// OnData is called for every raw data word found within a bus patch. |
228 | /// Every data ward recevied by a call to OnData is associated to the bus patch | |
229 | /// header received in the most recent call to OnNewBusPatch. | |
230 | /// The default behaviour of this method is to do nothing. | |
231 | /// - param UInt_t This is the raw data word as found within the bus patch payload. | |
8a0dae7c | 232 | /// - param bool Flag indicating if the raw data word had a parity error. |
233 | /// This will always be set to false if fSendDataOnParityError in the | |
e843eb88 | 234 | /// AliMUONTrackerDDLDecoder class was set to false. |
8a0dae7c | 235 | void OnData(UInt_t /*data*/, bool /*parityError*/) {} |
e3a2b9c9 | 236 | |
237 | /// Whenever a parsing error of the DDL payload is encountered because of | |
238 | /// corruption of the raw data (eg. bit flips) the OnError method is called | |
239 | /// imediately at the point this error is discovered. | |
240 | /// The default behaviour of this method is to do nothing. | |
241 | /// - param ErrorCode This is an error code indicating the kind of problem | |
242 | /// encountered with the DDL payload. | |
243 | /// - param const void* This is a pointer into the DDL payload memory buffer | |
244 | /// indicating the exact location where the parsing error happened | |
245 | /// or i.e. the location of the corruption. | |
246 | /// Note that a relative offset in bytes from the start of the memory buffer | |
247 | /// can be calculated by: storing the buffer pointer recevied in OnNewBuffer | |
248 | /// earlier in fBufferStart for example, and then the offset is given by: | |
249 | /// offset = (unsigned long)location - (unsigned long)fBufferStart; | |
250 | void OnError(ErrorCode /*error*/, const void* /*location*/) {} | |
251 | ||
252 | /// This is a utility method which will unpack the MANU ID, channel ID and | |
253 | /// ADC signal value from a raw data word. It should normally be used in | |
254 | /// OnData() to unpack these fields. | |
255 | /// [in] \param data This is the raw data word found in the DDL payload. | |
256 | /// [out] \param manuId This is filled with the unpacked MANU ID. | |
257 | /// [out] \param channelId This is filled with the unpacked MANU channel ID. | |
258 | /// [out] \param adc This is filled with the unpacked ADC signal. | |
259 | static void UnpackADC( | |
260 | UInt_t data, | |
261 | UShort_t& manuId, UChar_t& channelId, UShort_t& adc | |
262 | ) | |
263 | { | |
264 | manuId = (UShort_t)(data >> 18) & 0x7FF; | |
265 | channelId = (Char_t)(data >> 12) & 0x3F; | |
266 | adc = (UShort_t)(data & 0xFFF); | |
267 | } | |
268 | ||
269 | /// This is a utility method which converts an error code to a string | |
270 | /// respresentation for printing purposes. | |
271 | /// \param code The error code as received in OnError for example. | |
272 | /// \return An ANSI string containing the name of the error code symbol. | |
273 | static const char* ErrorCodeToString(ErrorCode code); | |
274 | ||
275 | /// This is a utility method which converts an error code to user friendly | |
276 | /// descriptive message useful for printing to the screen. | |
277 | /// \param code The error code as received in OnError for example. | |
278 | /// \return An ANSI string containing a descriptive message of the error. | |
279 | static const char* ErrorCodeToMessage(ErrorCode code); | |
280 | }; | |
281 | ||
e0173291 | 282 | //_____________________________________________________________________________ |
283 | ||
284 | inline const char* AliMUONTrackerDDLDecoderEventHandler::ErrorCodeToString(ErrorCode code) | |
285 | { | |
286 | /// This is a utility method which converts an error code to a string | |
287 | /// representation for printing purposes. | |
288 | /// \param code The error code as received in OnError for example. | |
289 | /// \return An ANSI string containing the name of the error code symbol. | |
290 | ||
291 | switch (code) | |
292 | { | |
293 | case kNoError: return "kNoError"; | |
294 | case kBufferTooBig: return "kBufferTooBig"; | |
295 | case kTooManyBlocks: return "kTooManyBlocks"; | |
296 | case kTooManyDSPs: return "kTooManyDSPs"; | |
297 | case kTooManyBusPatches: return "kTooManyBusPatches"; | |
298 | case kNoBlockHeader: return "kNoBlockHeader"; | |
299 | case kBadBlockKey: return "kBadBlockKey"; | |
300 | case kBadBlockLength: return "kBadBlockLength"; | |
301 | case kBadBlockTotalLength: return "kBadBlockTotalLength"; | |
302 | case kBlockLengthMismatch: return "kBlockLengthMismatch"; | |
303 | case kNoDSPHeader: return "kNoDSPHeader"; | |
304 | case kBadDSPKey: return "kBadDSPKey"; | |
305 | case kBadDSPLength: return "kBadDSPLength"; | |
306 | case kBadDSPTotalLength: return "kBadDSPTotalLength"; | |
307 | case kDSPLengthMismatch: return "kDSPLengthMismatch"; | |
308 | case kNoBusPatchHeader: return "kNoBusPatchHeader"; | |
309 | case kBadBusPatchKey: return "kBadBusPatchKey"; | |
310 | case kBadBusPatchLength: return "kBadBusPatchLength"; | |
311 | case kBadBusPatchTotalLength: return "kBadBusPatchTotalLength"; | |
312 | case kBusPatchLengthMismatch: return "kBusPatchLengthMismatch"; | |
313 | case kGlitchFound: return "kGlitchFound"; | |
314 | case kBadPaddingWord: return "kBadPaddingWord"; | |
315 | case kParityError: return "kParityError"; | |
316 | default: return "INVALID"; | |
317 | } | |
318 | } | |
319 | ||
320 | ||
321 | inline const char* AliMUONTrackerDDLDecoderEventHandler::ErrorCodeToMessage(ErrorCode code) | |
322 | { | |
323 | /// This is a utility method which converts an error code to user friendly | |
324 | /// descriptive message useful for printing to the screen. | |
325 | /// \param code The error code as received in OnError for example. | |
326 | /// \return An ANSI string containing a descriptive message of the error. | |
327 | ||
328 | switch (code) | |
329 | { | |
330 | case kNoError: | |
331 | return "Decoding was successful."; | |
332 | case kBufferTooBig: | |
333 | return "The DDL raw data is larger than indicated by the headers;" | |
334 | " extra bytes are probably just garbage."; | |
335 | case kTooManyBlocks: | |
336 | return "Too many block structures found."; | |
337 | case kTooManyDSPs: | |
338 | return "Too many DSP structures found in the block."; | |
339 | case kTooManyBusPatches: | |
340 | return "Too many bus patch structures found in the DSP structure."; | |
341 | case kNoBlockHeader: | |
342 | return "Missing a block header."; | |
343 | case kBadBlockKey: | |
344 | return "The block header key word does not contain the correct value."; | |
345 | case kBadBlockLength: | |
346 | return "The block length field points past the end of the raw data size."; | |
347 | case kBadBlockTotalLength: | |
348 | return "The total block length field points past the end of the" | |
349 | " raw data size."; | |
350 | case kBlockLengthMismatch: | |
351 | return "The block length and total length fields do not correspond." | |
352 | " One or both of these values is incorrect."; | |
353 | case kNoDSPHeader: | |
354 | return "Missing a DSP header."; | |
355 | case kBadDSPKey: | |
356 | return "The DSP header key word does not contain the correct value."; | |
357 | case kBadDSPLength: | |
358 | return "The DSP structure length field points past the end of the" | |
359 | " block structure."; | |
360 | case kBadDSPTotalLength: | |
361 | return "The total DSP structure length field points past the end of" | |
362 | " the block structure."; | |
363 | case kDSPLengthMismatch: | |
364 | return "The DSP structure length and total length fields do not" | |
365 | " correspond. One or both of these values is incorrect."; | |
366 | case kNoBusPatchHeader: | |
367 | return "Missing a bus patch header."; | |
368 | case kBadBusPatchKey: | |
369 | return "The bus patch header key word does not contain the correct value."; | |
370 | case kBadBusPatchLength: | |
371 | return "The bus patch length field points past the end of the" | |
372 | " DSP structure."; | |
373 | case kBadBusPatchTotalLength: | |
374 | return "The total bus patch length field points past the end of" | |
375 | " the DSP structure."; | |
376 | case kBusPatchLengthMismatch: | |
377 | return "The bus patch length and total length fields do not correspond." | |
378 | " One or both of these values is incorrect."; | |
379 | case kGlitchFound: | |
380 | return "Found a glitch. This means a 1 byte word has been randomly" | |
381 | " inserted into the raw data by mistake."; | |
382 | case kBadPaddingWord: | |
383 | return "The padding word does not contain the correct value."; | |
384 | case kParityError: | |
385 | return "Found a parity error in the data word."; | |
386 | default: | |
387 | return "Unknown error code!"; | |
388 | } | |
389 | } | |
390 | ||
391 | ||
392 | inline std::ostream& operator << (std::ostream& os, AliMUONTrackerDDLDecoderEventHandler::ErrorCode code) | |
393 | { | |
394 | /// This is the stream operator for std::ostream classes to be able to | |
395 | /// easily write the error messages associated with the error codes generated | |
396 | /// by the decoder to 'cout' or 'cerr' for example. | |
397 | ||
398 | os << AliMUONTrackerDDLDecoderEventHandler::ErrorCodeToMessage(code); | |
399 | return os; | |
400 | } | |
401 | ||
e3a2b9c9 | 402 | #endif // ALIMUONTRACKERDDLDECODEREVENTHANDLER_H |
e0173291 | 403 |