HLT/BASE/AliHLTOUT.h

   1 //-*- Mode: C++ -*-
   2 // @(#) $Id$
   3
   4 #ifndef ALIHLTOUT_H
   5 #define ALIHLTOUT_H
   6 /* This file is property of and copyright by the ALICE HLT Project        *
   7  * ALICE Experiment at CERN, All rights reserved.                         *
   8  * See cxx source for full Copyright notice                               */
   9
  10 /** @file   AliHLTOUT.h
  11     @author Matthias Richter
  12     @date
  13     @brief  The control class for HLTOUT data.
  14
  15 // see below for class documentation
  16 // or
  17 // refer to README to build package
  18 // or
  19 // visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
  20
  21                                                                           */
  22 #include <vector>
  23 #include "AliHLTLogging.h"
  24
  25 /**
  26  * @class AliHLTOUT
  27  * The control class for HLTOUT data.
  28  * The output of the HLT, either from the HLTOUT nodes or simulated output,
  29  * is transferred and stored in the HOMER format. The AliHLTOUT class
  30  * implements scanning of the HOMER data for all HLTOUT DDL links and
  31  * abstracts access to the complete HLTOUT data.
  32  *
  33  */
  34 class AliHLTOUT : public AliHLTLogging {
  35  public:
  36   /** standard constructor */
  37   AliHLTOUT();
  38   /** standard destructor */
  39   virtual ~AliHLTOUT();
  40
  41   /**
  42    * Get number of data blocks in the HLTOUT data
  43    */
  44   int GetNofDataBlocks();
  45
  46   /**
  47    * Select the first data block of a certain data type and specification.
  48    * The selection criteria can be of kAliHLTAnyDataType and/or
  49    * kAliHLTVoidDataSpec in order to be ignored and just match any data block.
  50    * @param dt    [in]  data type to match                                <br>
  51    * @param spec  [in]  data specification to match                       <br>
  52    * @return identifier >=0 if success, neg. error code if failed         <br>
  53    *                        -ENOENT if no block found                     <br>
  54    *                        -EPERM if access denied (object locked)
  55    */
  56   int SelectFirstDataBlock(AliHLTComponentDataType dt, AliHLTUInt32_t spec);
  57
  58   /**
  59    * Select the next data block of data type and specification of the previous
  60    * call to @ref SelectFirstDataBlock.
  61    * @return identifier >=0 if success, neg. error code if failed         <br>
  62    *                        -ENOENT if no block found                     <br>
  63    *                        -EPERM if access denied (object locked)
  64    */
  65   int SelectNextDataBlock();
  66
  67   /**
  68    * Get properties of the selected data block.
  69    * @param dt    [out] data type of the selected block
  70    * @param spec  [out] data specification of the selected block
  71    */
  72   int GetDataBlockDescription(AliHLTComponentDataType& dt, AliHLTUInt32_t& spec);
  73
  74   /**
  75    * Get buffer of the selected data block.
  76    * @param pBuffer [out] buffer of the selected data block
  77    * @param size    [out] size of the selected data block
  78    */
  79   int GetDataBuffer(const AliHLTUInt8_t* &pBuffer, AliHLTUInt32_t& size);
  80
  81   /**
  82    * Release buffer after use.
  83    * @param pBuffer [in]  buffer of the selected data block
  84    */
  85   int ReleaseDataBuffer(const AliHLTUInt8_t* pBuffer);
  86
  87   /**
  88    * Locking guard for the AliHLTOUT object.
  89    * If the object is locked, the selection of data blocks can not be changed.
  90    */
  91   class AliHLTOUTLockGuard {
  92   public:
  93     /** constructor */
  94     AliHLTOUTLockGuard(AliHLTOUT* pInstance) : fpInstance(pInstance)
  95     {if (fpInstance) fpInstance->SetStatusFlag(kLocked);}
  96     /** destructor */
  97     ~AliHLTOUTLockGuard()
  98     {if (fpInstance) fpInstance->ClearStatusFlag(kLocked);}
  99
 100   private:
 101     /** standard constructor prohibited */
 102     AliHLTOUTLockGuard();
 103     /** copy constructor prohibited */
 104     AliHLTOUTLockGuard(const AliHLTOUTLockGuard&);
 105     /** assignment operator prohibited */
 106     AliHLTOUTLockGuard& operator=(const AliHLTOUTLockGuard&);
 107
 108     /** the AliHLTOUT instance the guard is locking */
 109     AliHLTOUT* fpInstance; //!transient
 110   };
 111
 112   /**
 113    * The HLT OUT Event Header.
 114    * Defined between HLT and DAQ.
 115    */
 116   struct AliHLTOUTEventHeader {
 117     /**Total length of the data in bytes, including HLT event header, excluding CDH. */
 118     AliHLTUInt32_t fLength; //! see above
 119     /** version of the header */
 120     AliHLTUInt32_t fVersion; //! see above
 121     /** event id */
 122     AliHLTUInt64_t fEventID; //! see above
 123   };
 124
 125   // definitions from ALICE internal notes ALICE-INT-2002-010 and
 126   // ALICE-INT-2006-XXX
 127   /** the 32bit word in the CDH containing the status flags */
 128   static const unsigned char fgkCDHStatusWord; //! see above
 129   /** start of the flags in word fgkCDHStatusWord */
 130   static const unsigned char fgkCDHStatusFlagsOffset; //! see above
 131   /** bit indicating HLT decision in the HLTOUT*/
 132   static const unsigned char fgkCDHFlagsHLTDecision; //! see above
 133   /** bit indicating HLT payload in the HLTOUT*/
 134   static const unsigned char fgkCDHFlagsHLTPayload; //! see above
 135
 136   /**
 137    * Block descriptor.
 138    */
 139   class AliHLTOUTBlockDescriptor {
 140   public:
 141     AliHLTOUTBlockDescriptor(AliHLTComponentDataType dt, AliHLTUInt32_t spec, AliHLTUInt32_t index)
 142       : fDataType(dt), fSpecification(spec), fIndex(index) {};
 143     ~AliHLTOUTBlockDescriptor() {}
 144
 145     operator AliHLTComponentDataType() const {return fDataType;}
 146     operator AliHLTUInt32_t() const {return fSpecification;}
 147     int operator==(AliHLTComponentDataType dt) const {return dt==fDataType;}
 148     int operator==(AliHLTUInt32_t spec) const {return spec==fSpecification;}
 149
 150     AliHLTUInt32_t GetIndex() const {return fIndex;}
 151   private:
 152     /** data type of the block */
 153     AliHLTComponentDataType fDataType; //!transient
 154     /** data specification of the block */
 155     AliHLTUInt32_t          fSpecification; //!transient
 156     /** index in the data stream */
 157     AliHLTUInt32_t          fIndex; //!transient
 158   };
 159
 160   enum AliHLTOUTByteOrder_t {
 161     /** no data block selected */
 162     kInvalidByteOrder=-1,
 163     kUnknownByteOrder=0,
 164     kLittleEndian,
 165     kBigEndian
 166   };
 167
 168   enum AliHLTOUTDataType_t {
 169     kUint64 = 0,
 170     kUint32 = 1,
 171     kUint16 = 2,
 172     kUint8  = 3,
 173     kDouble = 4,
 174     kFloat  = 5
 175   };
 176
 177   /**
 178    * Check byte order of selected block
 179    */
 180   AliHLTOUTByteOrder_t CheckByteOrder();
 181
 182   /**
 183    * Check alignment of selected block
 184    */
 185   int CheckAlignment(AliHLTOUT::AliHLTOUTDataType_t type);
 186
 187  protected:
 188   /**
 189    * Add a block descriptor.
 190    * This is done by the child classes generating the index. The AliHLTOUT
 191    * object must be locked for index generation.
 192    * @param desc    the block descriptor
 193    * @return 0 if success, -EPERM if access denied
 194    */
 195   int AddBlockDescriptor(const AliHLTOUTBlockDescriptor desc);
 196
 197  private:
 198   /** copy constructor prohibited */
 199   AliHLTOUT(const AliHLTOUT&);
 200   /** assignment operator prohibited */
 201   AliHLTOUT& operator=(const AliHLTOUT&);
 202
 203   /**
 204    * Internal status flags
 205    */
 206   enum {
 207     /** the HLTOUT object is locked with the current data block */
 208     kLocked = 0x1,
 209     /** childs can add block descriptors */
 210     kCollecting = 0x2,
 211     /** user of the data block has checked the byte order */
 212     kByteOrderChecked = 0x4,
 213     /** warning on byte order missmatch has been printed */
 214     kByteOrderWarning = 0x8,
 215     /** user of the data block has checked the alignment */
 216     kAlignmentChecked = 0x10,
 217     /** warning on alignment missmatch has been printed */
 218     kAlignmentWarning = 0x20
 219   };
 220
 221   /**
 222    * Generate the index of the HLTOUT data.
 223    * Must be implemented by the child classes.
 224    */
 225   virtual int GenerateIndex()=0;
 226
 227   /**
 228    * Get the data buffer
 229    * @param index   [in]  index of the block
 230    * @param pBuffer [out] buffer of the selected data block
 231    * @param size    [out] size of the selected data block
 232    */
 233   virtual int GetDataBuffer(AliHLTUInt32_t index, const AliHLTUInt8_t* &pBuffer,
 234                             AliHLTUInt32_t& size)=0;
 235
 236   /**
 237    * Check byte order of data block
 238    */
 239   virtual AliHLTOUTByteOrder_t CheckBlockByteOrder(AliHLTUInt32_t index)=0;
 240
 241   /**
 242    * Check alignment of data block
 243    */
 244   virtual int CheckBlockAlignment(AliHLTUInt32_t index, AliHLTOUT::AliHLTOUTDataType_t type)=0;
 245
 246   /**
 247    * Select the data block of data type and specification of the previous
 248    * call to @ref SelectFirstDataBlock. Core function of @ref SelectFirstDataBlock
 249    * and @ref SelectNextDataBlock, starts to find a block at the current list
 250    * position.
 251    * @return identifier >=0 if success, neg. error code if failed         <br>
 252    *                        -ENOENT if no block found                     <br>
 253    *                        -EPERM if access denied (object locked)
 254    */
 255   int FindAndSelectDataBlock();
 256
 257   /**
 258    * Set status flag.
 259    * @param flag     flag to set
 260    * @return current status flags
 261    */
 262   unsigned int SetStatusFlag(unsigned int flag) {return fFlags|=flag;}
 263
 264   /**
 265    * Clear status flag.
 266    * @param flag     flag to clear
 267    * @return current status flags
 268    */
 269   unsigned int ClearStatusFlag(unsigned int flag) {return fFlags&=~flag;}
 270
 271   /**
 272    * Check status flag.
 273    * @param flag     flag to check
 274    * @return 1 if flag is set
 275    */
 276   int CheckStatusFlag(unsigned int flag) const {return (fFlags&flag)==flag;}
 277
 278   /** data type for the current block search, set from @ref SelectFirstDataBlock */
 279   AliHLTComponentDataType fSearchDataType; //!transient
 280
 281   /** data specification for the current block search */
 282   AliHLTUInt32_t fSearchSpecification; //!transient
 283
 284   /** instance flags: locked, collecting, ... */
 285   unsigned int fFlags; //!transient
 286
 287   /** list of block descriptors */
 288   vector<AliHLTOUTBlockDescriptor> fBlockDescList; //!transient
 289
 290   /** current position in the list */
 291   vector<AliHLTOUTBlockDescriptor>::iterator fCurrent; //!transient
 292
 293   /** data buffer under processing */
 294   const AliHLTUInt8_t* fpBuffer; //!transient
 295
 296   ClassDef(AliHLTOUT, 0)
 297 };
 298 #endif