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