AliMUONTriggerDDLDecoderEventHandler.h

Go to the documentation of this file.

#ifndef ALIMUONTRIGGERDDLDECODEREVENTHANDLER_H
#define ALIMUONTRIGGERDDLDECODEREVENTHANDLER_H
/**************************************************************************
 * This file is property of and copyright by the ALICE HLT Project        *
 * All rights reserved.                                                   *
 *                                                                        *
 * Primary Authors:                                                       *
 *   Artur Szostak <artursz@iafrica.com>                                  *
 *                                                                        *
 * Permission to use, copy, modify and distribute this software and its   *
 * documentation strictly for non-commercial purposes is hereby granted   *
 * without fee, provided that the above copyright notice appears in all   *
 * copies and that both the copyright notice and this permission notice   *
 * appear in the supporting documentation. The authors make no claims     *
 * about the suitability of this software for any purpose. It is          *
 * provided "as is" without express or implied warranty.                  *
 **************************************************************************/

/* $Id$ */


#include <cassert>
#include <ostream>
#include <Rtypes.h>


// We use C binding for the structures because C is more uniform with its application
// binary interface (ABI) between compilers.
extern "C"
{

// The following structures are the headers found in the DDL payload coming from
// the muon hardware trigger. The specification is given in ALICE-INT-2005-012
// (https://edms.cern.ch/file/591904/1/ALICE-INT-2005-012.pdf)

struct AliMUONDarcScalarsStruct
{
  UInt_t     fL0R;       
  UInt_t     fL1P;       
  UInt_t     fL1S;       
  UInt_t     fL2A;       
  UInt_t     fL2R;       
  UInt_t     fClk;       
  UInt_t     fHold;      
  UInt_t     fSpare;     
};

struct AliMUONGlobalHeaderStruct
{
  UInt_t     fInput[4];    
  UInt_t     fOutput;      
};

struct AliMUONGlobalScalarsStruct
{
  UInt_t     fL0;         
  UInt_t     fClk;        
  UInt_t     fScaler[6];  
  UInt_t     fHold;       
  UInt_t     fSpare;      
};

struct AliMUONRegionalHeaderStruct
{
  UInt_t    fDarcWord;        
  UInt_t    fWord;            
  UInt_t    fInput[2];        
  UInt_t    fL0CountAndMask;  
};

struct AliMUONRegionalScalarsStruct
{
  UInt_t     fClk;        
  UInt_t     fScaler[8];  
  UInt_t     fHold;       
};


struct AliMUONLocalInfoStruct
{
  UInt_t fX2X1;  
  UInt_t fX4X3;  
  UInt_t fY2Y1;  
  UInt_t fY4Y3;  
  UInt_t fTriggerBits;  
};

struct AliMUONLocalScalarsStruct
{
  UInt_t     fL0;        
  UInt_t     fHold;      
  UInt_t     fClk;       
  
  UInt_t     fLPtNTrig;  
  UInt_t     fHPtNTrig;  
  
  UInt_t     fLPtRTrig;  
  UInt_t     fHPtRTrig;  
  
  UInt_t     fLPtLTrig;  
  UInt_t     fHPtLTrig;  
  
  UInt_t     fLPtSTrig;  
  UInt_t     fHPtSTrig;  
  
  UInt_t     fScaler[8*4];   
  UInt_t     fEOS;           
  UInt_t     fReset;         
};

} // extern "C"


class AliMUONTriggerDDLDecoderEventHandler
{
public:

  virtual ~AliMUONTriggerDDLDecoderEventHandler() {}

  enum ErrorCode
  {
    kNoError = 0,              
    kTooManyRegionals = 1,     
    kNoDarcHeader = 2,         
    kNoDarcScalars = 3,        
    kWrongEventType = 4,       
    kNoEndOfDarc = 5,          
    kBadEndOfDarc = 6,         
    kNoGlobalHeader = 7,       
    kNoGlobalScalars = 8,      
    kNoEndOfGlobal = 9,        
    kBadEndOfGlobal = 10,      
    kNoRegionalHeader = 11,    
    kNoRegionalScalars = 12,   
    kNoEndOfRegional = 13,     
    kBadEndOfRegional = 14,    
    kNoLocalStruct = 15,       
    kNoLocalScalars = 16,      
    kNoEndOfLocal = 17,        
    kBadEndOfLocal = 18,       
    kBufferTooBig = 19         
  };

  // The following methods should be overridden for specific processing to
  // take place in your own event handler.

  void OnNewBuffer(const void* /*buffer*/, UInt_t /*bufferSize*/) {}
  
  void OnEndOfBuffer(const void* /*buffer*/, UInt_t /*bufferSize*/) {}
  
  void OnDarcHeader(
      UInt_t /*header*/,
      const AliMUONDarcScalarsStruct* /*scalars*/,
      const void* /*data*/
    )
  {
  }
  
  void OnGlobalHeader(
      const AliMUONGlobalHeaderStruct* /*header*/,
      const AliMUONGlobalScalarsStruct* /*scalars*/,
      const void* /*data*/
    )
  {
  }
  
  void OnNewRegionalStruct(
      const AliMUONRegionalHeaderStruct* /*regionalStruct*/,
      const AliMUONRegionalScalarsStruct* /*scalars*/,
      const void* /*data*/
    )
  {
  }
  
  void OnNewRegionalStructV2(
      UInt_t /*num*/,
      const AliMUONRegionalHeaderStruct* /*regionalStruct*/,
      const AliMUONRegionalScalarsStruct* /*scalars*/,
      const void* /*data*/
    )
  {
  }
  
  void OnEndOfRegionalStruct(
      const AliMUONRegionalHeaderStruct* /*regionalStruct*/,
      const AliMUONRegionalScalarsStruct* /*scalars*/,
      const void* /*data*/
    )
  {
  }
  
  void OnEndOfRegionalStructV2(
      UInt_t /*num*/,
      const AliMUONRegionalHeaderStruct* /*regionalStruct*/,
      const AliMUONRegionalScalarsStruct* /*scalars*/,
      const void* /*data*/
    )
  {
  }
  
  void OnLocalStruct(
      const AliMUONLocalInfoStruct* /*localStruct*/,
      const AliMUONLocalScalarsStruct* /*scalars*/
    )
  {
  }
  
  void OnLocalStructV2(
      UInt_t /*num*/,
      const AliMUONLocalInfoStruct* /*localStruct*/,
      const AliMUONLocalScalarsStruct* /*scalars*/
    )
  {
  }
  
  // The following static methods are helper routines for decoding the
  // DARC header bits.
  
  static UChar_t GetDarcEventType(UInt_t header) { return (UChar_t)(header >> 30) & 0x3; };
  
  static UChar_t GetDarcType(UInt_t header) { return (UChar_t)(header >> 24) & 0x7; }
  
  static UChar_t GetDarcSerialNb(UInt_t header) { return (UChar_t)(header >> 20) & 0xF; }
  
  static UChar_t GetDarcVersion(UInt_t header) { return (UChar_t)(header >> 12) & 0xFF; }
  
  static bool GetDarcVMETrig(UInt_t header) { return (header & 0x800); }
  
  static bool GetDarcGlobalFlag(UInt_t header) { return (header & 0x400); }
  
  static bool GetDarcCTPTrig(UInt_t header) { return (header & 0x200); }
  
  static bool GetDarcDAQFlag(UInt_t header) { return (header & 0x100); }
  
  static UChar_t GetDarcRegPattern(UInt_t header) { return (UChar_t)(header & 0xFF); }
  
  // The following static methods are helper routines for decoding the
  // regional structure header bits.
  
  static UShort_t GetRegionalL0(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (header->fL0CountAndMask >> 16) & 0xFFFF;
  }
  
  static UShort_t GetRegionalMask(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return header->fL0CountAndMask & 0xFFFF;
  }
  
  static bool GetRegionalPhysFlag(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (header->fWord & 0x80000000) != 0;
  }
  
  static UChar_t GetRegionalResetNb(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (UChar_t)(header->fWord >> 25) &  0x3F;
  }
  
  static UChar_t GetRegionalSerialNb(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (UChar_t)(header->fWord >> 20) &  0x1F;
  }
  
  static UChar_t GetRegionalId(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (UChar_t)(header->fWord >> 16) &  0x0F;
  }
  
  static UChar_t GetRegionalVersion(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (UChar_t)(header->fWord >> 8)  &  0xFF;
  }
  
  static UChar_t GetRegionalOutput(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (UChar_t)(header->fWord       &  0xFF);
  }
  
  static UShort_t GetRegionalErrorBits(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (UShort_t)(header->fDarcWord >> 22) &  0x3FF;
  }
  
  static UChar_t GetRegionalFPGANumber(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (UChar_t)  (header->fDarcWord >> 19) &  0x7;
  }
  
  static bool GetRegionalDarcPhysFlag(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (header->fDarcWord  &  0x8000) != 0;
  }
  
  static bool GetRegionalPresentFlag(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (header->fDarcWord  &  0x4000) != 0;
  }
  
  static bool GetRegionalRamNotFullFlag(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (header->fDarcWord  &  0x2000) != 0;
  }
  
  static bool GetRegionalRamNotEmptyFlag(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (header->fDarcWord  &  0x1000) != 0;
  }
  
  static bool GetRegionalL2RejStatus(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (header->fDarcWord  &  0x800) != 0;
  }
  
  static bool GetRegionalL2AccStatus(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (header->fDarcWord  &  0x400) != 0;
  }
  
  static bool GetRegionalL1Status(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (header->fDarcWord  &  0x200) != 0;
  }
  
  static bool GetRegionalL0Status(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (header->fDarcWord  &  0x100) != 0;
  }
  
  static UChar_t GetRegionalEventInRam(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (UChar_t)  (header->fDarcWord >> 4)  &  0x4;
  }
  
  static UChar_t GetRegionalBusy(const AliMUONRegionalHeaderStruct* header)
  {
    assert( header != NULL );
    return (UChar_t)  (header->fDarcWord)       &  0x4;
  }
  
  // The following static methods are helper routines for decoding the
  // global header bits.
  
  static UChar_t GetGlobalOutput(const AliMUONGlobalHeaderStruct* header)
  {
    assert(header != NULL);
    return header->fOutput & 0xFF;
  }
  
  static UShort_t GetGlobalConfig(const AliMUONGlobalHeaderStruct* header)
  {
    assert(header != NULL);
    return (header->fOutput >> 16) & 0xFFFF;
  }
  
  // The following static methods are helper routines for decoding the
  // local trigger structure and scalar bits.
  
  static UShort_t GetLocalX2(const AliMUONLocalInfoStruct* local)
  {
    assert(local != NULL);
    return (local->fX2X1 >> 16) & 0xFFFF;
  }
  
  static UShort_t GetLocalX1(const AliMUONLocalInfoStruct* local)
  {
    assert(local != NULL);
    return (local->fX2X1) & 0xFFFF;
  }
  
  static UShort_t GetLocalX4(const AliMUONLocalInfoStruct* local)
  {
    assert(local != NULL);
    return (local->fX4X3 >> 16) & 0xFFFF;
  }
  
  static UShort_t GetLocalX3(const AliMUONLocalInfoStruct* local)
  {
    assert(local != NULL);
    return (local->fX4X3) & 0xFFFF;
  }

  static UShort_t GetLocalY2(const AliMUONLocalInfoStruct* local)
  {
    assert(local != NULL);
    return (local->fY2Y1 >> 16) & 0xFFFF;
  }
  
  static UShort_t GetLocalY1(const AliMUONLocalInfoStruct* local)
  {
    assert(local != NULL);
    return (local->fY2Y1) & 0xFFFF;
  }
  
  static UShort_t GetLocalY4(const AliMUONLocalInfoStruct* local)
  {
    assert(local != NULL);
    return (local->fY4Y3 >> 16) & 0xFFFF;
  }
  
  static UShort_t GetLocalY3(const AliMUONLocalInfoStruct* local)
  {
    assert(local != NULL);
    return (local->fY4Y3) & 0xFFFF;
  }
  
  static UChar_t GetLocalId(const AliMUONLocalInfoStruct* local)
  {
    assert(local != NULL);
    return local->fTriggerBits >> 19 &  0xF;
  }
  
  static UChar_t GetLocalDec(const AliMUONLocalInfoStruct* local)
  {
    assert(local != NULL);
    return local->fTriggerBits >> 15 &  0xF;
  }
  
  static bool GetLocalTrigY(const AliMUONLocalInfoStruct* local)
  {
    assert(local != NULL);
    return (local->fTriggerBits >> 14 & 0x1);
  }
  
  static bool GetLocalTriggerY(const AliMUONLocalInfoStruct* local)
  {
    return not (GetLocalTrigY(local) and GetLocalYPos(local) == 15);
  }
  
  static UChar_t GetLocalYPos(const AliMUONLocalInfoStruct* local)
  {
    assert(local != NULL);
    return local->fTriggerBits >> 10 & 0xF;
  }
  
  static bool GetLocalSXDev(const AliMUONLocalInfoStruct* local)
  {
    assert(local != NULL);
    return (local->fTriggerBits >> 9 & 0x1);
  }
  
  static UChar_t GetLocalXDev(const AliMUONLocalInfoStruct* local)
  {
    assert(local != NULL);
    return local->fTriggerBits >> 5 & 0xF;
  }
  
  static bool GetLocalTriggerX(const AliMUONLocalInfoStruct* local)
  {
    return not (GetLocalSXDev(local) and (GetLocalXDev(local) == 0)
                and GetLocalXPos(local) == 0);
  }
  
  static UChar_t GetLocalXPos(const AliMUONLocalInfoStruct* local)
  {
    assert(local != NULL);
    return local->fTriggerBits & 0x1F;
  }

  static UChar_t GetLocalLpt(const AliMUONLocalInfoStruct* local) {return (GetLocalDec(local) & 0x3);}
  
  static UChar_t GetLocalHpt(const AliMUONLocalInfoStruct* local) {return (GetLocalDec(local) >> 2) & 0x3;}
  
  static UShort_t GetLocalSwitch(const AliMUONLocalScalarsStruct* scalars)
  {
    assert(scalars != NULL);
    return (scalars->fEOS >> 1) & 0x3FF;
  }
  
  static UChar_t GetLocalComptXY(const AliMUONLocalScalarsStruct* scalars)
  {
    assert(scalars != NULL);
    return scalars->fEOS & 0x1;
  }
  
  static UShort_t GetLocalXY1(const AliMUONLocalScalarsStruct* scalars, UInt_t n)
  {
    assert(scalars != NULL and n < 16);
    return  (n % 2 == 1) ? (scalars->fScaler[(n/2)] & 0xFFFF)
                         : ((scalars->fScaler[(n/2)] >> 16) &  0xFFFF);
  }
  
  static UShort_t GetLocalXY2(const AliMUONLocalScalarsStruct* scalars, UInt_t n)
  {
    assert(scalars != NULL and n < 16);
    return  (n % 2 == 1) ? (scalars->fScaler[8 + (n/2)] & 0xFFFF)
                         : ((scalars->fScaler[8 + (n/2)] >> 16) &  0xFFFF);
  }
  
  static UShort_t GetLocalXY3(const AliMUONLocalScalarsStruct* scalars, UInt_t n)
  {
    assert(scalars != NULL and n < 16);
    return  (n % 2 == 1) ? (scalars->fScaler[8*2 + (n/2)] & 0xFFFF)
                         : ((scalars->fScaler[8*2 + (n/2)] >> 16) &  0xFFFF);
  }
  
  static UShort_t GetLocalXY4(const AliMUONLocalScalarsStruct* scalars, UInt_t n)
  {
    assert(scalars != NULL and n < 16);
    return  (n % 2 == 1) ? (scalars->fScaler[8*3 + (n/2)] & 0xFFFF)
                         : ((scalars->fScaler[8*3 + (n/2)] >> 16) &  0xFFFF);
  }
  
  void OnError(ErrorCode /*error*/, const void* /*location*/) {}
  
  static const char* ErrorCodeToString(ErrorCode code);
  
  static const char* ErrorCodeToMessage(ErrorCode code);
};

//_____________________________________________________________________________

inline const char* AliMUONTriggerDDLDecoderEventHandler::ErrorCodeToString(ErrorCode code)
{
  
  switch (code)
  {
  case kNoError: return "kNoError";
  case kTooManyRegionals: return "kTooManyRegionals";
  case kNoDarcHeader: return "kNoDarcHeader";
  case kNoDarcScalars: return "kNoDarcScalars";
  case kWrongEventType: return "kWrongEventType";
  case kNoEndOfDarc: return "kNoEndOfDarc";
  case kBadEndOfDarc: return "kBadEndOfDarc";
  case kNoGlobalHeader: return "kNoGlobalHeader";
  case kNoGlobalScalars: return "kNoGlobalScalars";
  case kNoEndOfGlobal: return "kNoEndOfGlobal";
  case kBadEndOfGlobal: return "kBadEndOfGlobal";
  case kNoRegionalHeader: return "kNoRegionalHeader";
  case kNoRegionalScalars: return "kNoRegionalScalars";
  case kNoEndOfRegional: return "kNoEndOfRegional";
  case kBadEndOfRegional: return "kBadEndOfRegional";
  case kNoLocalStruct: return "kNoLocalStruct";
  case kNoLocalScalars: return "kNoLocalScalars";
  case kNoEndOfLocal: return "kNoEndOfLocal";
  case kBadEndOfLocal: return "kBadEndOfLocal";
  case kBufferTooBig: return "kBufferTooBig";
  default: return "INVALID";
  }
}


inline const char* AliMUONTriggerDDLDecoderEventHandler::ErrorCodeToMessage(ErrorCode code)
{
  
  switch (code)
  {
  case kNoError:
    return "Decoding was successful.";
  case kTooManyRegionals:
    return "Too many regional card structures are expected in the DDL payload.";
  case kNoDarcHeader:
    return "The DARC header is missing. The DDL buffer is too short"
      " to hold a DARC header.";
  case kNoDarcScalars:
    return "The DARC scalars are missing or corrupt."
      " The DDL buffer is too short to contain them.";
  case kWrongEventType:
    return "Wrong event type obtained from the Darc header.";
  case kNoEndOfDarc:
    return "The DDL buffer is too short to contain an end of DARC"
      " header key word.";
  case kBadEndOfDarc:
    return "End of DARC header key word is incorrect or corrupt.";
  case kNoGlobalHeader:
    return "The global header is missing. The DDL buffer is too"
      " short to hold a global header.";
  case kNoGlobalScalars:
    return "The global scalars are missing or corrupt. The DDL"
      " buffer is too short to contain them.";
  case kNoEndOfGlobal:
    return "The DDL buffer is too short to contain an end of global"
      " header key word.";
  case kBadEndOfGlobal:
    return "End of global header key word is incorrect or corrupt.";
  case kNoRegionalHeader:
    return "The regional header is missing. The DDL buffer is too"
      " short to hold another regional header.";
  case kNoRegionalScalars:
    return "The regional scalars are missing or corrupt. The DDL"
      " buffer is too short to contain them.";
  case kNoEndOfRegional:
    return "The DDL buffer is too short to contain an end of regional"
      " header key word.";
  case kBadEndOfRegional:
    return "End of regional header key word is incorrect or corrupt.";
  case kNoLocalStruct:
    return "The local structure is missing. The DDL buffer is too"
      " short to hold another local structure.";
  case kNoLocalScalars:
    return "The local scalars are missing or corrupt. The DDL buffer"
      " is too short to contain them.";
  case kNoEndOfLocal:
    return "The DDL buffer is too short to contain an end of local"
      " structure key word.";
  case kBadEndOfLocal:
    return "End of local structure key word is incorrect or corrupt.";
  case kBufferTooBig:
    return "The DDL raw data is larger than indicated by the headers;"
      " extra bytes are probably just garbage.";
  default:
    return "Unknown error code!";
  }
}


inline std::ostream& operator << (std::ostream& os, AliMUONTriggerDDLDecoderEventHandler::ErrorCode code)
{
  
  os << AliMUONTriggerDDLDecoderEventHandler::ErrorCodeToMessage(code);
  return os;
}

#endif // ALIMUONTRIGGERDDLDECODEREVENTHANDLER_H