HLT/TPCLib/AliHLTTPCDigitReader.h

   1 // XEmacs -*-C++-*-
   2 // @(#) $Id$
   3
   4 #ifndef ALIHLTTPCDIGITREADER_H
   5 #define ALIHLTTPCDIGITREADER_H
   6
   7 //* This file is property of and copyright by the ALICE HLT Project        *
   8 //* ALICE Experiment at CERN, All rights reserved.                         *
   9 //* See cxx source for full Copyright notice                               *
  10
  11 /** @file   AliHLTTPCDigitReader.h
  12     @author Timm Steinbeck, Jochen Thaeder, Matthias Richter, Kenneth Aamodt
  13     @date
  14     @brief  An abstract reader class for TPC data.
  15 */
  16
  17 #include "AliHLTLogging.h"
  18 #include "TObject.h"
  19 #include "AliHLTTPCDigitData.h"
  20
  21 /**
  22  * @class AliHLTTPCDigitReader
  23  * An abstract reader class for the TPC data. The Data is treated as a stream
  24  * of data points, each containing row number, pad number, time bin and ADC
  25  * value. The class hides the actual encoding of the data stream for the sub-
  26  * sequent components like the cluster finder.
  27  *
  28  * Some of the data decoders allow random access of the data within one channel.
  29  * This functionality is available for all readers if caching is enabled (see
  30  * @ref EnableCaching).
  31  *
  32  * The digit reader can be locked for the current channel. If locked, function
  33  * @ref Next will return false if data of the current channel is finnished.
  34  * @ingroup alihlt_tpc
  35  */
  36 class AliHLTTPCDigitReader : public AliHLTLogging {
  37 public:
  38   /** standard constructor
  39    */
  40   AliHLTTPCDigitReader();
  41   /** destructor */
  42   virtual ~AliHLTTPCDigitReader();
  43
  44   /**
  45    * Init the reader with a data block.
  46    * The function fetches the first and last row for the readout partition
  47    * from @ref AliHLTTPCTransform. The method is pure virtual and must be implemented
  48    * by the child class.
  49    * @param ptr     pointer to data buffer
  50    * @param size    size of the data buffer
  51    * @param patch   patch (readout partition) number within the slice
  52    * @param slice   sector no (0 to 35)
  53    */
  54   virtual int InitBlock(void* ptr,unsigned long size, Int_t patch, Int_t slice)=0;
  55
  56   /**
  57    * Old Init function.
  58    * <b>Note:</b> This method is for backward compatibility only, not for further
  59    * use. The <i>firstrow</i> and <i>lastrow</i> parameters are fetched from
  60    * @ref AliHLTTPCTransform.
  61    *
  62    * @param ptr       pointer to data buffer
  63    * @param size      size of the data buffer
  64    * @param firstrow  first row occuring in the data
  65    * @param lastrow   last row occuring in the data
  66    * @param patch     patch (readout partition) number within the slice
  67    * @param slice     sector no (0 to 35)
  68    */
  69   virtual int InitBlock(void* ptr,unsigned long size,Int_t firstrow,Int_t lastrow, Int_t patch, Int_t slice);
  70
  71   /**
  72    * Reset digit reader and release internal structures.
  73    */
  74   virtual int Reset() {return 0;}
  75
  76   enum {
  77     kNextSignal = 1,
  78     kNextChannel,
  79     kNextBunch,
  80     kLastValidModifier
  81   };
  82
  83   /**
  84    * Set the reader position to the next value.
  85    * If the reader was not yet initialized, initialization is carried out and
  86    * the position set to the beginning of the stream (which is in essence the
  87    * end of the data block due to the back-linked list).
  88    *
  89    * The modifiers determine the unit of the positioning:
  90    * - @ref kNextSignal    set to the next signal value
  91    * - @ref kNextChannel   set at the beginning of the next channel
  92    * - @ref kNextBunch     set at the beginning of the next bunch within the
  93    *                       current channel.
  94    *
  95    * If the reader is locked for a pad/channel, Next operates only on the data
  96    * belonging to the current channel and returns false at the end of the
  97    * channel.
  98    *
  99    * The function does some basic stuff and forwards to @ref NextSignal, @ref
 100    * NextBunch or @ref NextChannel depending on the modifer. This function is
 101    * also necessary if the common sorting is going to be used (not yet implemented)
 102    * @return true if data is available, false if not
 103    */
 104   bool Next(int type=kNextSignal);
 105
 106   /**
 107    * Set stream position to the next Pad (ALTRO channel).
 108    * This is the direct entry to data access on a channel/bunch basis suited
 109    * for fast data access.
 110    * @return true if data is available, false if not
 111    */
 112   virtual bool NextChannel();
 113
 114   /**
 115    * Set stream to the next ALTRO bunch within the current pad.
 116    * This is the direct entry to data access on a channel/bunch basis suited
 117    * for fast data access.
 118    * @return bunch length, 0 if no data bunch available in the current pad
 119    */
 120   virtual int NextBunch();
 121
 122   /**
 123    * Get current hardware address.
 124    */
 125   virtual AliHLTUInt32_t GetAltroBlockHWaddr() const;
 126
 127   /**
 128    * Get current hardware address from row and pad number.
 129    */
 130   virtual AliHLTUInt32_t GetAltroBlockHWaddr(Int_t row, Int_t pad) const;
 131
 132   /**
 133    * Get the row number of the current value.
 134    */
 135   virtual int GetRow()=0;
 136
 137   /**
 138    * Get the pad number of the current value.
 139    */
 140   virtual int GetPad()=0;
 141
 142   /**
 143    * Get the current ADC value.
 144    */
 145   virtual int GetSignal()=0;
 146
 147   /**
 148    * Get pointer to the the current ADC value.
 149    */
 150   virtual const UInt_t* GetSignals();
 151
 152   /**
 153    * Get pointer to the the current ADC value. In UShort_t, used by the 32BitFormat decoder
 154    */
 155   virtual const UShort_t* GetSignalsShort();
 156
 157   /**
 158    * Get the time bin of the current value.
 159    * If @ref NextBunch has been used the function returns the
 160    * first time bin of the bunch.
 161    */
 162   virtual int GetTime()=0;
 163
 164   /**
 165    * Method to use old rcu fomat.
 166    */
 167   virtual void SetOldRCUFormat(Bool_t oldrcuformat);
 168
 169   /**
 170    * Method to set read unsorted flag.
 171    */
 172   virtual void SetUnsorted(Bool_t unsorted);
 173
 174   /**
 175    * Enable chaching of the current channel.
 176    * Some of the readers allow random data access within one channel.
 177    * The others have the possibility to cache the data in order to support
 178    * this functionality. Caching is off by default.
 179    * @param bCache     the current channel is cached
 180    */
 181   void EnableCaching(bool bCache=false);
 182
 183   /**
 184    * Rewind the current channel to the beginning.
 185    * The function uses the reader methods @ref RewindCurrentChannel or
 186    * @ref RewindToPrevChannel to set the stream position to the beginning of the
 187    * current channel. If the reader is locked for a channel, the function
 188    * rewinds to the begnning of that channel.
 189    */
 190   int RewindChannel();
 191
 192   /**
 193    * Returns the bunch size. Used by the fast decoder.
 194    */
 195   virtual int GetBunchSize();
 196
 197   /**
 198    * Returns the row offset. Used by the fast decoder.
 199    */
 200   virtual int GetRowOffset() const;
 201
 202   /**
 203    * Returns the trailer size.
 204    */
 205   virtual int GetRCUTrailerSize();
 206
 207   /**
 208    * Returns the trailer data.
 209    */
 210   virtual bool GetRCUTrailerData(UChar_t*& trData);
 211
 212   /**
 213    * Returns the digits
 214    */
 215   virtual const AliHLTTPCDigitData* GetBunchDigits(){return 0;}
 216
 217
 218   /**
 219    * Access operator to the data of a specific time bin.
 220    * Not clear if we can manage this.
 221    */
 222   //int operator[](int timebin);
 223
 224   class LockGuard {
 225   public:
 226     /** constructor, locks reader for the current pad */
 227     LockGuard(AliHLTTPCDigitReader& reader)
 228       : fReader(reader)
 229     {reader.fLckRow=reader.GetRow(); reader.fLckPad=reader.GetPad(); reader.SetFlag(kLocked);}
 230     /** destructor, unlocks reader */
 231     ~LockGuard()
 232     {fReader.ClearFlag(kLocked|kChannelOverwrap); fReader.fLckRow=-1; fReader.fLckPad=-1;}
 233
 234   private:
 235     /** instance of the controlled reader */
 236     AliHLTTPCDigitReader& fReader;                                //!transient
 237   };
 238
 239   enum {
 240     /** reader locked for the current channel */
 241     kLocked = 0x1,
 242     /** stream position already at the next channel */
 243     kChannelOverwrap = 0x2,
 244     /** reader doe not allow channel rewind */
 245     kNoRewind = 0x4,
 246     /** warning missing fast access methods */
 247     kWarnMissFastAccess = 0x8,
 248     /** warning on missing RCU trailer getters */
 249     kWarnMissTrailerGetters = 0x10,
 250     /** channel caching enabled */
 251     kChannelCaching = 0x100
 252   };
 253 protected:
 254   /**
 255    * Set the reader position to the next value.
 256    * This is the reader specific method called by @ref Next.
 257    * @return true if data is available, false if not
 258    */
 259   virtual bool NextSignal()=0;
 260
 261   /**
 262    * Set a status flag of the reader.
 263    * @return current value of the status flags
 264    */
 265   unsigned int SetFlag(unsigned int flag);
 266
 267   /**
 268    * Clear a status flag of the reader.
 269    * @return current value of the status flags
 270    */
 271   unsigned int ClearFlag(unsigned int flag);
 272
 273   /**
 274    * Check a status flag of the reader.
 275    */
 276   int CheckFlag(unsigned int flag) const {return (fFlags&flag)!=0;}
 277
 278   /**
 279    * Rewind to the beginning.of the current channel.
 280    */
 281   virtual int RewindCurrentChannel();
 282
 283   /**
 284    * Rewind to the beginning of the previous channel.
 285    */
 286   virtual int RewindToPrevChannel();
 287
 288 private:
 289   /**
 290    * Print a warning once for missing functionality.
 291    * Set corresponding flag to avoid repetitive warnings.
 292    */
 293   void PrintWarningOnce(int type, const char* message);
 294
 295   /** pad/channel is locked */
 296   unsigned int fFlags;                                    //!transient
 297
 298   /** row the reader is locked to */
 299   int fLckRow;                                                //!transient
 300
 301   /** pad the reader is locked to */
 302   int fLckPad;                                                //!transient
 303
 304   ClassDef(AliHLTTPCDigitReader, 0)
 305
 306 };
 307 #endif
 308