HLT/rec/AliRawReaderHLT.h

   1 //-*- Mode: C++ -*-
   2 // $Id$
   3
   4 #ifndef ALIRAWREADERHLT_H
   5 #define ALIRAWREADERHLT_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   AliRawReaderHLT.h
  11     @author Matthias Richter
  12     @date
  13     @brief  AliRawReader implementation which replaces original input of
  14             detectors with the appropriate HLT output.                    */
  15
  16 // see below for class documentation
  17 // or
  18 // refer to README to build package
  19 // or
  20 // visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
  21
  22 #include "AliHLTDataTypes.h"
  23 #include "AliRawReader.h"      // RAW, base class
  24 #include "TString.h"
  25 #include <vector>
  26
  27 class AliHLTOUT;
  28 class AliHLTOUTHandler;
  29 class AliHLTPluginBase;
  30
  31 /**
  32  * @class AliRawReaderHLT
  33  * A specific AliRawReader for detector input replacement by HLTOUT data blocks.
  34  *
  35  * HLT components can produce output data in the detector ddl raw format.
  36  * Data blocks of this format can be fed into the normal detector reconstruction
  37  * without changes in the actual reconstruction code by means of the
  38  * AliRawReaderHLT implementation of the AliRawReader.
  39  *
  40  * @section sec_alirawreaderhlt_concept Conceptual design
  41  * The AliRawReader provides an abstract interface to the ddl raw data. All
  42  * reconstruction code uses this interface to access the data.
  43  * HLT components can send their data in the original ddl raw format. The only
  44  * difference of such data blocks is the location since they are shipped as
  45  * part of the HLTOUT data stream. The AliRawReaderHLT provides redirection of
  46  * those data blocks.
  47  *
  48  * The AliRawReaderHLT needs the original AliRawReader in order to get the
  49  * data. Furthermore, a string containing the detector specification defines
  50  * which data should be read from the HLT stream and which from the original
  51  * reader.
  52  *
  53  * @note An HLTOUT handler must be available for the HLTOUT data blocks to
  54  * be redirected. Please read @ref sec_alirawreaderhlt_module carefully.
  55  *
  56  * @section sec_alirawreaderhlt_usage   Selection of the HLTOUT data stream
  57  * The input data of a detector can be replaced by the corresponding HLT
  58  * data by calling the <tt>AliReconstruction::SetUseHLTData("...")</tt>, e.g.
  59  * <pre>
  60  *    AliReconstruction rec;
  61  *    rec.SetUseHLTData("TPC TRD");
  62  * </pre>
  63  * will replace the input of TPC and TRD.
  64  *
  65  * The reader can be used directly. In order to avoid library dependencies
  66  * downwards, the methed AliRawHLTManager::CreateRawReaderHLT is available
  67  * in the RAW package.
  68  * <pre>
  69  * {
  70  *   AliRawReader* orgReader=AliRawReader::Create("raw.root");
  71  *   AliRawReader* rawreader=AliRawHLTManager::CreateRawReaderHLT(orgReader, "ITSSDD");
  72  *   rawreader->Select("ITSSDD");
  73  *   int count=0;
  74  *   while (rawreader->NextEvent()) {
  75  *     cout << "scanning event " << count++ << endl;
  76  *     UChar_t* pSrc=NULL;
  77  *     while (rawreader->ReadNextData(pSrc)) {
  78  *       cout << "  equipment: " << rawreader->GetEquipmentId() << endl;
  79  *     }
  80  *   }
  81  * }
  82  * </pre>
  83  *
  84  * @section sec_alirawreaderhlt_detectorids  Detector selection
  85  * The constructor gets a detector selection string as parameter and initializes
  86  * the redirection according to that. Detector Ids are according to AliDAQ.
  87  * Please note the special strings for for ITS and MUON sub-detectors, ITSSPD,
  88  * ITSSDD, ITSSSD, and MUONTRK and MUONTRG respectively.
  89  *
  90  * @section sec_alirawreaderhlt_module  Module implementation
  91  * In order to determine the equipment id for the data block, the HLT module
  92  * must implement an HLTOUT handler of class AliHLTOUTHandlerEquId which is of
  93  * type @ref AliHLTModuleAgent::AliHLTOUTHandlerType ::kRawReader.
  94  * The handler must implement the method
  95  * <pre>
  96  *  // AliHLTOUTHandlerEquId::ProcessData(AliHLTOUT*)
  97  *  virtual int ProcessData(AliHLTOUT* pData);
  98  * </pre>
  99  * which returns the equipment id and eventually decodes data to be retrieved
 100  * by calling AliHLTOUTHandler::GetProcessedData(). If the equipment id of the
 101  * DDL has been sent as data specification of the block, the AliHLTOUTHandlerEquId
 102  * can be used directly.
 103  *
 104  * Secondly, the AliHLTModuleAgent implementation of the module has to create
 105  * the handler for the data blocks. Depending on the data type and specification,
 106  * the the following interface methods return handler description and handler.
 107  * <pre>
 108  *   int AliHLTModuleAgent::GetHandlerDescription(AliHLTComponentDataType dt,
 109  *                                                AliHLTUInt32_t spec,
 110  *                                                AliHLTOUTHandlerDesc& desc) const;
 111  *
 112  *   AliHLTOUTHandler* AliHLTModuleAgent::GetOutputHandler(AliHLTComponentDataType dt,
 113  *                                                         AliHLTUInt32_t spec);
 114  * </pre>
 115  * See section @ref tut_alirawreaderhlt for sample implementation.
 116  *
 117  * @ingroup alihlt_aliroot_reconstruction
 118  */
 119 class AliRawReaderHLT : public AliRawReader {
 120  public:
 121   /** constructor */
 122   AliRawReaderHLT(AliRawReader* pParentReader, const char* options=NULL);
 123   /** destructor */
 124   virtual ~AliRawReaderHLT();
 125
 126   // interface methods of AliRawReader
 127   void     Select(Int_t detectorID,
 128                   Int_t minDDLID = -1, Int_t maxDDLID = -1);
 129 //   void     Select(const char *detectorName,
 130 //                Int_t minDDLID = -1, Int_t maxDDLID = -1);
 131
 132   using AliRawReader::Select;
 133
 134   void     SelectEquipment(Int_t equipmentType,
 135                            Int_t minEquipmentId = -1,
 136                            Int_t maxEquipmentId = -1);
 137   void     SkipInvalid(Bool_t skip = kTRUE);
 138   //  void     SelectEvents(Int_t type);
 139
 140   UInt_t   GetType() const;
 141   UInt_t   GetRunNumber() const;
 142   const UInt_t* GetEventId() const;
 143   const UInt_t* GetTriggerPattern() const;
 144   const UInt_t* GetDetectorPattern() const;
 145   const UInt_t* GetAttributes() const;
 146   const UInt_t* GetSubEventAttributes() const;
 147   UInt_t   GetLDCId() const;
 148   UInt_t   GetGDCId() const;
 149   UInt_t   GetTimestamp() const;
 150
 151   const UInt_t* GetEquipmentAttributes() const;
 152   Int_t    GetEquipmentElementSize() const;
 153   Int_t    GetEquipmentHeaderSize() const;
 154
 155   Int_t    GetEquipmentSize() const;
 156   Int_t    GetEquipmentType() const;
 157   Int_t    GetEquipmentId() const;
 158   Bool_t   ReadHeader();
 159   Bool_t   ReadNextData(UChar_t*& data);
 160   Bool_t   ReadNextInt(UInt_t& data);
 161   Bool_t   ReadNextShort(UShort_t& data);
 162   Bool_t   ReadNextChar(UChar_t& data);
 163   Bool_t   ReadNext(UChar_t* data, Int_t size);
 164
 165   Bool_t   Reset();
 166
 167   Bool_t   NextEvent();
 168   Bool_t   RewindEvents();
 169
 170  protected:
 171
 172  private:
 173   /** standard constructor prohibited */
 174   AliRawReaderHLT();
 175   /** copy constructor prohibited */
 176   AliRawReaderHLT(const AliRawReaderHLT&);
 177   /** assignment operator prohibited */
 178   AliRawReaderHLT& operator=(const AliRawReaderHLT&);
 179
 180   /**
 181    * Scan the options.
 182    * Set the ids for the specified detectors in the detector
 183    * list. Currently, no other options are available.
 184    */
 185   int ScanOptions(const char* options);
 186
 187   /**
 188    * Read the next data block from the HLT stream
 189    */
 190   Bool_t ReadNextHLTData();
 191
 192   /**
 193    * Check if a ddlid is part of the ones which are selected for
 194    * input replacement.
 195    */
 196   Bool_t IsHLTInput(int ddlid);
 197
 198   /**
 199    * Check if redirection is enabled for at least one detector in the
 200    * selected range.
 201    * Set the fbHaveHLTData variable
 202    * @return true if data has to be read from the HLT stream.
 203    */
 204   Bool_t EvaluateSelection();
 205
 206   /**
 207    * Release the current HLT data.
 208    * Releases the current buffer of either the active HLTOUT data
 209    * block handler or the HLTOUT instance. The latter implies a
 210    * reset of the reader concerning the HLT data blocks.
 211    * @param bReleaseHLTOUT   release HLTOUT instance if \em true
 212    *                         only current data buffer if \em false
 213    * @return neg. error code if failed
 214    */
 215   int ReleaseHLTData(bool bReleaseHLTOUT=true);
 216
 217   /**
 218    * Backbone of all Read functions.
 219    * Reads the next data into the internal buffer and switches to next
 220    * block if enabled.
 221    *
 222    * @param data             target to receive pointer
 223    * @param readHeader       kTRUE: switch to next block if no more data
 224    */
 225   Bool_t   ReadNextData(UChar_t*& data, Bool_t readHeader);
 226
 227   /** the rawreader */
 228   AliRawReader* fpParentReader; //!transient
 229
 230   /** options */
 231   TString fOptions; //!transient
 232
 233   /** system options = options w/o detector strings */
 234   TString fSystemOptions; //!transient
 235
 236   /** current data set, either extracted from the HLT stream or parent raw reader */
 237   const AliHLTUInt8_t* fpData; // !transient
 238
 239   /** size of the current data set */
 240   int fDataSize; // !transient
 241
 242   /** current stream offset in the data set */
 243   int fOffset; // !transient
 244
 245   /** current stream position for the ReadNextData function */
 246   int fPosition; // !transient
 247
 248   /** equipment id of the current data set, >0 indicates data set from HLT stream */
 249   int fEquipmentId; // !transient
 250
 251   /** indicates the availibility of data from the HLT stream */
 252   bool fbHaveHLTData; // !transient
 253
 254   /** list of detectors for which data will be taken from HLT stream */
 255   vector<int> fDetectors; // !transient
 256
 257   /** instance of the HLTOUT handler */
 258   AliHLTOUT* fpHLTOUT; // !transient
 259
 260   /** start reading HLTOUT from beginning */
 261   bool fbReadFirst; //!transient
 262
 263   /** instance of the data handler providing the current data buffer */
 264   AliHLTOUTHandler* fpDataHandler; // !transient
 265
 266   /** base class for AliRoot HLT plugins */
 267   AliHLTPluginBase* fpPluginBase;                                     //!transient
 268
 269   ClassDef(AliRawReaderHLT, 5)
 270 };
 271
 272 #define ALIHLTREC_LIBRARY                   "libHLTrec.so"
 273 #define ALIHLTREC_LIBRARY_VERSION           0
 274 #define ALIRAWREADERHLT_CREATE_INSTANCE     "AliRawReaderHLTCreateInstance"
 275
 276 #ifdef __cplusplus
 277 extern "C" {
 278 #endif
 279   typedef AliRawReader* (*AliRawReaderHLTCreateInstance_t)(AliRawReader* pParentReader, const char* options);
 280
 281   /**
 282    * Create an instance of the AliRawReader class
 283    */
 284   AliRawReader* AliRawReaderHLTCreateInstance(AliRawReader* pParentReader, const char* options);
 285 #ifdef __cplusplus
 286 }
 287 #endif
 288 #endif