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