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
  16 #include <vector>
  17 #include "AliHLTLogging.h"
  18 #include "AliHLTModuleAgent.h"
  19
  20 class AliHLTOUTHandler;
  21 class AliHLTOUTHandlerDesc; // AliHLTModuleAgent.h
  22
  23 #define AliHLTOUTInvalidIndex (~(AliHLTUInt32_t)0)
  24
  25 typedef vector<AliHLTUInt32_t> AliHLTOUTIndexList;
  26
  27 /**
  28  * @class AliHLTOUT
  29  * The control class for HLTOUT data.
  30  * The output of the HLT, either from the HLTOUT nodes or simulated output,
  31  * is transferred and stored in the HOMER format. The AliHLTOUT class
  32  * implements scanning of the HOMER data for all HLTOUT DDL links and
  33  * abstracts access to the complete HLTOUT data.
  34  *
  35  */
  36 class AliHLTOUT : public AliHLTLogging {
  37  public:
  38   /** standard constructor */
  39   AliHLTOUT();
  40   /** standard destructor */
  41   virtual ~AliHLTOUT();
  42
  43   /**
  44    * Init for processing.
  45    * The HLTOUT is scanned for all available data blocks and the
  46    * AliHLTOUTHandler objects for the data blocks are created according
  47    * to the module agents (see AliHLTModuleAgent).
  48    */
  49   int Init();
  50
  51   /**
  52    * Get number of data blocks in the HLTOUT data
  53    */
  54   int GetNofDataBlocks();
  55
  56   /**
  57    * Select the first data block of a certain data type and specification.
  58    * The selection criteria can be of kAliHLTAnyDataType and/or
  59    * kAliHLTVoidDataSpec in order to be ignored and just match any data block.
  60    *
  61    * The search criteria can be combined with a handler type (e.g. kRawReader)
  62    * @param dt    [in]  data type to match                                <br>
  63    * @param spec  [in]  data specification to match                       <br>
  64    * @param handlerType [in]  type of the handler
  65    * @return identifier >0 if success, 0 if no block found                <br>
  66    *         neg. error code if failed                                    <br>
  67    *                        -EPERM if access denied (object locked)
  68    */
  69   int SelectFirstDataBlock(AliHLTComponentDataType dt=kAliHLTAnyDataType,
  70                            AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
  71                            AliHLTModuleAgent::AliHLTOUTHandlerType handlerType=AliHLTModuleAgent::kUnknownOutput);
  72
  73   /**
  74    * Select the next data block of data type and specification of the previous
  75    * call to @ref SelectFirstDataBlock.
  76    * @return identifier >0 if success, 0 if no block found                <br>
  77    *         neg. error code if failed                                    <br>
  78    *                        -EPERM if access denied (object locked)
  79    */
  80   int SelectNextDataBlock();
  81
  82   /**
  83    * Get properties of the selected data block.
  84    * @param dt    [out] data type of the selected block
  85    * @param spec  [out] data specification of the selected block
  86    */
  87   int GetDataBlockDescription(AliHLTComponentDataType& dt, AliHLTUInt32_t& spec);
  88
  89   /**
  90    * Get the index of the current data block.
  91    * @return index, AliHLTOUTInvalidIndex if no block selected
  92    */
  93   AliHLTUInt32_t GetDataBlockIndex();
  94
  95   /**
  96    * Get buffer of the selected data block.
  97    * @param pBuffer [out] buffer of the selected data block
  98    * @param size    [out] size of the selected data block
  99    */
 100   int GetDataBuffer(const AliHLTUInt8_t* &pBuffer, AliHLTUInt32_t& size);
 101
 102   /**
 103    * Release buffer after use.
 104    * @param pBuffer [in]  buffer of the selected data block
 105    */
 106   int ReleaseDataBuffer(const AliHLTUInt8_t* pBuffer);
 107
 108   /**
 109    * Get handler for the selected data block.
 110    */
 111   AliHLTOUTHandler* GetHandler();
 112
 113   /**
 114    * Locking guard for the AliHLTOUT object.
 115    * If the object is locked, the selection of data blocks can not be changed.
 116    */
 117   class AliHLTOUTLockGuard {
 118   public:
 119     /** constructor */
 120     AliHLTOUTLockGuard(AliHLTOUT* pInstance) : fpInstance(pInstance)
 121     {if (fpInstance) fpInstance->SetStatusFlag(kLocked);}
 122     /** destructor */
 123     ~AliHLTOUTLockGuard()
 124     {if (fpInstance) fpInstance->ClearStatusFlag(kLocked);}
 125
 126   private:
 127     /** standard constructor prohibited */
 128     AliHLTOUTLockGuard();
 129     /** copy constructor prohibited */
 130     AliHLTOUTLockGuard(const AliHLTOUTLockGuard&);
 131     /** assignment operator prohibited */
 132     AliHLTOUTLockGuard& operator=(const AliHLTOUTLockGuard&);
 133
 134     /** the AliHLTOUT instance the guard is locking */
 135     AliHLTOUT* fpInstance; //!transient
 136   };
 137
 138   /**
 139    * The HLT OUT Event Header.
 140    * Defined between HLT and DAQ.
 141    */
 142   struct AliHLTOUTEventHeader {
 143     /**Total length of the data in bytes, including HLT event header, excluding CDH. */
 144     AliHLTUInt32_t fLength; //! see above
 145     /** version of the header */
 146     AliHLTUInt32_t fVersion; //! see above
 147     /** event id */
 148     AliHLTUInt64_t fEventID; //! see above
 149   };
 150
 151   enum {
 152     /// versions 1 of the HLT header
 153     kVersion1 = 1,
 154     /// versions 2 of the HLT header
 155     kVersion2 = 2
 156   };
 157
 158   enum {
 159     /// size of HLT decision in data format version 1: 29x4
 160     kSizeDecisionVersion1 = 116,
 161     /// size of HLT decision in data format version 2: 30x4
 162     kSizeDecisionVersion2 = 120
 163   };
 164
 165   // definitions from ALICE internal notes ALICE-INT-2002-010 and
 166   // ALICE-INT-2006-XXX
 167   enum {
 168     /** the 32bit word in the CDH containing the status flags */
 169     kCDHStatusWord=4, //! see above
 170     /** start of the flags in word fgkCDHStatusWord */
 171     kCDHStatusFlagsOffset=12, //! see above
 172     /** bit indicating HLT decision in the HLTOUT*/
 173     kCDHFlagsHLTDecision=6, //! see above
 174     /** bit indicating HLT payload in the HLTOUT*/
 175     kCDHFlagsHLTPayload=7 //! see above
 176   };
 177
 178   /**
 179    * Block descriptor.
 180    */
 181   class AliHLTOUTBlockDescriptor {
 182   public:
 183     AliHLTOUTBlockDescriptor(AliHLTComponentDataType dt, AliHLTUInt32_t spec, AliHLTUInt32_t index)
 184       : fDataType(dt), fSpecification(spec), fIndex(index) {};
 185     ~AliHLTOUTBlockDescriptor() {}
 186
 187     operator AliHLTComponentDataType() const {return fDataType;}
 188     operator AliHLTUInt32_t() const {return fSpecification;}
 189     int operator==(AliHLTComponentDataType dt) const {return dt==fDataType;}
 190     int operator==(AliHLTUInt32_t spec) const {return spec==fSpecification;}
 191
 192     AliHLTUInt32_t GetIndex() const {return fIndex;}
 193   private:
 194     /** data type of the block */
 195     AliHLTComponentDataType fDataType; //!transient
 196     /** data specification of the block */
 197     AliHLTUInt32_t          fSpecification; //!transient
 198     /** index in the data stream */
 199     AliHLTUInt32_t          fIndex; //!transient
 200   };
 201
 202   enum AliHLTOUTByteOrder {
 203     /** no data block selected */
 204     kInvalidByteOrder=-1,
 205     kUnknownByteOrder=0,
 206     kLittleEndian,
 207     kBigEndian
 208   };
 209
 210   enum AliHLTOUTDataType {
 211     kUint64 = 0,
 212     kUint32 = 1,
 213     kUint16 = 2,
 214     kUint8  = 3,
 215     kDouble = 4,
 216     kFloat  = 5
 217   };
 218
 219   /**
 220    * Check byte order of selected block
 221    */
 222   AliHLTOUTByteOrder CheckByteOrder();
 223
 224   /**
 225    * Check alignment of selected block
 226    */
 227   int CheckAlignment(AliHLTOUT::AliHLTOUTDataType type);
 228
 229   /**
 230    * Helper function to byte swap a 64 bit value.
 231    */
 232   static AliHLTUInt64_t ByteSwap64(AliHLTUInt64_t src);
 233
 234   /**
 235    * Helper function to byte swap a 32 bit value.
 236    */
 237   static AliHLTUInt32_t ByteSwap32(AliHLTUInt32_t src);
 238
 239  protected:
 240   /**
 241    * Add a block descriptor.
 242    * This is done by the child classes generating the index. The AliHLTOUT
 243    * object must be locked for index generation.
 244    * @param desc    the block descriptor
 245    * @return 0 if success, -EPERM if access denied
 246    */
 247   int AddBlockDescriptor(const AliHLTOUTBlockDescriptor desc);
 248
 249   /**
 250    * Print output or suppress.
 251    */
 252   bool BeVerbose() {return fbVerbose;}
 253
 254   /**
 255    * Switch output.
 256    */
 257   void SwitchVerbosity(bool verbose) {fbVerbose=verbose;}
 258
 259  private:
 260   /** copy constructor prohibited */
 261   AliHLTOUT(const AliHLTOUT&);
 262   /** assignment operator prohibited */
 263   AliHLTOUT& operator=(const AliHLTOUT&);
 264
 265   /**
 266    * Internal status flags
 267    */
 268   enum {
 269     /** the HLTOUT object is locked with the current data block */
 270     kLocked = 0x1,
 271     /** childs can add block descriptors */
 272     kCollecting = 0x2,
 273     /** user of the data block has checked the byte order */
 274     kByteOrderChecked = 0x4,
 275     /** warning on byte order missmatch has been printed */
 276     kByteOrderWarning = 0x8,
 277     /** user of the data block has checked the alignment */
 278     kAlignmentChecked = 0x10,
 279     /** warning on alignment missmatch has been printed */
 280     kAlignmentWarning = 0x20
 281   };
 282
 283   class AliHLTOUTHandlerListEntry {
 284   public:
 285     AliHLTOUTHandlerListEntry(AliHLTOUTHandler* pHandler,
 286                               AliHLTModuleAgent::AliHLTOUTHandlerDesc& handlerDesc,
 287                               AliHLTModuleAgent* pAgent,
 288                               AliHLTUInt32_t index);
 289
 290     /** copy constructor for vector handling */
 291     AliHLTOUTHandlerListEntry(const AliHLTOUTHandlerListEntry& src);
 292
 293     /** assignment operator for vector handling */
 294     AliHLTOUTHandlerListEntry& operator=(const AliHLTOUTHandlerListEntry& src);
 295
 296     ~AliHLTOUTHandlerListEntry();
 297
 298     static const AliHLTOUTHandlerListEntry fgkVoidHandlerListEntry; //! initializer
 299
 300     operator AliHLTOUTHandler*() const {return fpHandler;}
 301
 302     // please note that fpHandlerDesc is really a pointer and is created
 303     // in the constructor. Thats why it is dereferenced here. The pointer
 304     // type is on purpose, even though it is a bit confusing with the
 305     // argument by reference in the AliHLTOUTHandlerListEntry constructor.
 306     operator AliHLTModuleAgent::AliHLTOUTHandlerDesc&() const {return *fpHandlerDesc;}
 307     operator AliHLTModuleAgent*() const {return fpAgent;}
 308
 309     /**
 310      * Two list entries are considered to be equal if the handlers
 311      * are equal.
 312      */
 313     bool operator==(const AliHLTOUTHandlerListEntry& entry) const;
 314
 315     bool operator==(const AliHLTModuleAgent::AliHLTOUTHandlerType handlerType) const;
 316
 317     AliHLTUInt32_t operator[](int i) const;
 318
 319     /**
 320      * Add a block index to this descriptor.
 321      * One descriptor can serve multiple blocks if the agent returns the
 322      * same handler for all of the blocks. Instead of creating a new entry
 323      * the block index ist just added
 324      */
 325     void AddIndex(AliHLTUInt32_t index);
 326
 327     /**
 328      * Add all indexes of the descriptor.
 329      */
 330     void AddIndex(AliHLTOUTHandlerListEntry &desc);
 331
 332     /**
 333      * Check if an index is served by this descriptor.
 334      * @return true if the index is in the table
 335      */
 336     bool HasIndex(AliHLTUInt32_t index);
 337
 338   private:
 339     /** standard constructor prohibited */
 340     AliHLTOUTHandlerListEntry();
 341
 342     /** pointer to the handler */
 343     AliHLTOUTHandler* fpHandler; //! transient
 344
 345     /** pointer to handler description */
 346     AliHLTModuleAgent::AliHLTOUTHandlerDesc* fpHandlerDesc; //! transient
 347
 348     /** pointer to module agent */
 349     AliHLTModuleAgent* fpAgent; //! transient
 350
 351     /** list of block indexes */
 352     AliHLTOUTIndexList fBlocks; //!transient
 353   };
 354
 355   /**
 356    * Generate the index of the HLTOUT data.
 357    * Must be implemented by the child classes.
 358    */
 359   virtual int GenerateIndex()=0;
 360
 361   /**
 362    * Find AliHLTOUTHandler objects for the data blocks.
 363    * The available AliHLTModuleAgents are probed whether they provide
 364    * handlers for data processing.
 365    */
 366   int InitHandlers();
 367
 368   /**
 369    * Get the data buffer
 370    * @param index   [in]  index of the block
 371    * @param pBuffer [out] buffer of the selected data block
 372    * @param size    [out] size of the selected data block
 373    */
 374   virtual int GetDataBuffer(AliHLTUInt32_t index, const AliHLTUInt8_t* &pBuffer,
 375                             AliHLTUInt32_t& size)=0;
 376
 377   /**
 378    * Check byte order of data block
 379    */
 380   virtual AliHLTOUTByteOrder CheckBlockByteOrder(AliHLTUInt32_t index)=0;
 381
 382   /**
 383    * Check alignment of data block
 384    */
 385   virtual int CheckBlockAlignment(AliHLTUInt32_t index, AliHLTOUT::AliHLTOUTDataType type)=0;
 386
 387   /**
 388    * Select the data block of data type and specification of the previous
 389    * call to @ref SelectFirstDataBlock. Core function of @ref SelectFirstDataBlock
 390    * and @ref SelectNextDataBlock, starts to find a block at the current list
 391    * position.
 392    * @return identifier >=0 if success, neg. error code if failed         <br>
 393    *                        -ENOENT if no block found                     <br>
 394    *                        -EPERM if access denied (object locked)
 395    */
 396   int FindAndSelectDataBlock();
 397
 398   /**
 399    * Set status flag.
 400    * @param flag     flag to set
 401    * @return current status flags
 402    */
 403   unsigned int SetStatusFlag(unsigned int flag) {return fFlags|=flag;}
 404
 405   /**
 406    * Clear status flag.
 407    * @param flag     flag to clear
 408    * @return current status flags
 409    */
 410   unsigned int ClearStatusFlag(unsigned int flag) {return fFlags&=~flag;}
 411
 412   /**
 413    * Check status flag.
 414    * @param flag     flag to check
 415    * @return 1 if flag is set
 416    */
 417   int CheckStatusFlag(unsigned int flag) const {return (fFlags&flag)==flag;}
 418
 419   /**
 420    * Insert a handler item.
 421    * The current list entries are checked if the handler is already in
 422    * the list. It is added if not in the list, otherwise the block index
 423    * is added to the existing entry.
 424    * @param entry    handler list entry
 425    * @return 0 if added, EEXIST (non negative!) if merged with existing entry <br>
 426    *         neg. error code if failed
 427    */
 428   int InsertHandler(const AliHLTOUTHandlerListEntry &entry);
 429
 430   /**
 431    * Find handler description for a certain block index.
 432    */
 433   const AliHLTOUTHandlerListEntry& FindHandlerDesc(AliHLTUInt32_t blockIndex);
 434
 435   /** data type for the current block search, set from @ref SelectFirstDataBlock */
 436   AliHLTComponentDataType fSearchDataType; //!transient
 437
 438   /** data specification for the current block search */
 439   AliHLTUInt32_t fSearchSpecification; //!transient
 440
 441   /** handler type for the current block search */
 442   AliHLTModuleAgent::AliHLTOUTHandlerType fSearchHandlerType; // !transient
 443
 444   /** instance flags: locked, collecting, ... */
 445   unsigned int fFlags; //!transient
 446
 447   typedef vector<AliHLTOUTHandlerListEntry> AliHLTOUTHandlerListEntryVector;
 448   typedef vector<AliHLTOUTBlockDescriptor>  AliHLTOUTBlockDescriptorVector;
 449
 450   /** list of block descriptors */
 451   AliHLTOUTBlockDescriptorVector fBlockDescList; //!transient
 452
 453   /** current position in the list */
 454   AliHLTOUTBlockDescriptorVector::iterator fCurrent; //!transient
 455
 456   /** data buffer under processing */
 457   const AliHLTUInt8_t* fpBuffer; //!transient
 458
 459   /** list of AliHLTOUTHandlers */
 460   AliHLTOUTHandlerListEntryVector fDataHandlers; // !transient
 461
 462   /** verbose or silent output */
 463   bool fbVerbose; //!transient
 464
 465   ClassDef(AliHLTOUT, 2)
 466 };
 467 #endif