MUON/AliMUONTrackerDDLDecoderEventHandler.h

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