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   /**
  71    * Reset digit reader and release internal structures.
  72    */
  73   virtual int Reset() {return 0;}
  74
  75   enum {
  76     kNextSignal = 1,
  77     kNextChannel,
  78     kNextBunch,
  79     kLastValidModifier
  80   };
  81
  82   /**
  83    * Set the reader position to the next value.
  84    * If the reader was not yet initialized, initialization is carried out and
  85    * the position set to the beginning of the stream (which is in essence the
  86    * end of the data block due to the back-linked list).
  87    *
  88    * The modifiers determine the unit of the positioning:
  89    * - @ref kNextSignal    set to the next signal value
  90    * - @ref kNextChannel   set at the beginning of the next channel
  91    * - @ref kNextBunch     set at the beginning of the next bunch within the
  92    *                       current channel.
  93    *
  94    * If the reader is locked for a pad/channel, Next operates only on the data
  95    * belonging to the current channel and returns false at the end of the
  96    * channel.
  97    *
  98    * The function does some basic stuff and forwards to @ref NextSignal, @ref
  99    * NextBunch or @ref NextChannel depending on the modifer. This function is
 100    * also necessary if the common sorting is going to be used (not yet implemented)
 101    * @return true if data is available, false if not
 102    */
 103   bool Next(int type=kNextSignal);
 104
 105   /**
 106    * Set stream position to the next Pad (ALTRO channel).
 107    * This is the direct entry to data access on a channel/bunch basis suited
 108    * for fast data access.
 109    * @return true if data is available, false if not
 110    */
 111   virtual bool NextChannel();
 112
 113   /**
 114    * Set stream to the next ALTRO bunch within the current pad.
 115    * This is the direct entry to data access on a channel/bunch basis suited
 116    * for fast data access.
 117    * @return bunch length, 0 if no data bunch available in the current pad
 118    */
 119   virtual int NextBunch();
 120
 121   /**
 122    * Get current hardware address.
 123    */
 124   virtual AliHLTUInt32_t GetAltroBlockHWaddr() const;
 125
 126   /**
 127    * Get current hardware address from row and pad number.
 128    */
 129   virtual AliHLTUInt32_t GetAltroBlockHWaddr(Int_t row, Int_t pad) const;
 130
 131   /**
 132    * Get the row number of the current value.
 133    */
 134   virtual int GetRow()=0;
 135
 136   /**
 137    * Get the pad number of the current value.
 138    */
 139   virtual int GetPad()=0;
 140
 141   /**
 142    * Get the current ADC value.
 143    */
 144   virtual int GetSignal()=0;
 145
 146   /**
 147    * Get pointer to the the current ADC value.
 148    */
 149   virtual const UInt_t* GetSignals();
 150
 151   /**
 152    * Get the time bin of the current value.
 153    * If @ref NextBunch has been used the function returns the
 154    * first time bin of the bunch.
 155    */
 156   virtual int GetTime()=0;
 157
 158   /**
 159    * Method to use old rcu fomat.
 160    */
 161   virtual void SetOldRCUFormat(Bool_t oldrcuformat);
 162
 163   /**
 164    * Method to set read unsorted flag.
 165    */
 166   virtual void SetUnsorted(Bool_t unsorted);
 167
 168   /**
 169    * Enable chaching of the current channel.
 170    * Some of the readers allow random data access within one channel.
 171    * The others have the possibility to cache the data in order to support
 172    * this functionality. Caching is off by default.
 173    * @param bCache     the current channel is cached
 174    */
 175   void EnableCaching(bool bCache=false);
 176
 177   /**
 178    * Rewind the current channel to the beginning.
 179    * The function uses the reader methods @ref RewindCurrentChannel or
 180    * @ref RewindToPrevChannel to set the stream position to the beginning of the
 181    * current channel. If the reader is locked for a channel, the function
 182    * rewinds to the begnning of that channel.
 183    */
 184   int RewindChannel();
 185
 186   /**
 187    * Returns the bunch size. Used by the fast decoder.
 188    */
 189   virtual int GetBunchSize();
 190
 191   /**
 192    * Returns the row offset. Used by the fast decoder.
 193    */
 194   virtual int GetRowOffset() const;
 195
 196   /**
 197    * Returns the trailer size.
 198    */
 199   virtual int GetRCUTrailerSize();
 200
 201   /**
 202    * Returns the trailer data.
 203    */
 204   virtual bool GetRCUTrailerData(UChar_t*& trData);
 205
 206   /**
 207    * Access operator to the data of a specific time bin.
 208    * Not clear if we can manage this.
 209    */
 210   //int operator[](int timebin);
 211
 212   class LockGuard {
 213   public:
 214     /** constructor, locks reader for the current pad */
 215     LockGuard(AliHLTTPCDigitReader& reader)
 216       : fReader(reader)
 217     {reader.fLckRow=reader.GetRow(); reader.fLckPad=reader.GetPad(); reader.SetFlag(kLocked);}
 218     /** destructor, unlocks reader */
 219     ~LockGuard()
 220     {fReader.ClearFlag(kLocked|kChannelOverwrap); fReader.fLckRow=-1; fReader.fLckPad=-1;}
 221
 222   private:
 223     /** instance of the controlled reader */
 224     AliHLTTPCDigitReader& fReader;                                //!transient
 225   };
 226
 227   enum {
 228     /** reader locked for the current channel */
 229     kLocked = 0x1,
 230     /** stream position already at the next channel */
 231     kChannelOverwrap = 0x2,
 232     /** reader doe not allow channel rewind */
 233     kNoRewind = 0x4,
 234     /** warning missing fast access methods */
 235     kWarnMissFastAccess = 0x8,
 236     /** warning on missing RCU trailer getters */
 237     kWarnMissTrailerGetters = 0x10,
 238     /** channel caching enabled */
 239     kChannelCaching = 0x100
 240   };
 241 protected:
 242   /**
 243    * Set the reader position to the next value.
 244    * This is the reader specific method called by @ref Next.
 245    * @return true if data is available, false if not
 246    */
 247   virtual bool NextSignal()=0;
 248
 249   /**
 250    * Set a status flag of the reader.
 251    * @return current value of the status flags
 252    */
 253   unsigned int SetFlag(unsigned int flag);
 254
 255   /**
 256    * Clear a status flag of the reader.
 257    * @return current value of the status flags
 258    */
 259   unsigned int ClearFlag(unsigned int flag);
 260
 261   /**
 262    * Check a status flag of the reader.
 263    */
 264   int CheckFlag(unsigned int flag) const {return (fFlags&flag)!=0;}
 265
 266   /**
 267    * Rewind to the beginning.of the current channel.
 268    */
 269   virtual int RewindCurrentChannel();
 270
 271   /**
 272    * Rewind to the beginning of the previous channel.
 273    */
 274   virtual int RewindToPrevChannel();
 275
 276 private:
 277   /**
 278    * Print a warning once for missing functionality.
 279    * Set corresponding flag to avoid repetitive warnings.
 280    */
 281   void PrintWarningOnce(int type, const char* message);
 282
 283   /** pad/channel is locked */
 284   unsigned int fFlags;                                    //!transient
 285
 286   /** row the reader is locked to */
 287   int fLckRow;                                                //!transient
 288
 289   /** pad the reader is locked to */
 290   int fLckPad;                                                //!transient
 291
 292   ClassDef(AliHLTTPCDigitReader, 0)
 293
 294 };
 295 #endif
 296