code documantation and minor cleanup
[u/mrichter/AliRoot.git] / HLT / RCU / AliHLTAltroGenerator.h
1 //-*- Mode: C++ -*-
2 // $Id$
3
4 #ifndef ALIHLTALTROGENERATOR_H
5 #define ALIHLTALTROGENERATOR_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   AliHLTAltroGenerator.h
11     @author Matthias Richter
12     @date   
13     @brief  Simulation class of 10/40bit Altro Data.
14 */
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 "AliHLTLogging.h"
24 #include <vector>
25 #include <ostream>
26
27 class AliRawDataHeader;
28 class TArrayS;
29 class TArrayC;
30 class TRandom;
31
32 /**
33  * @class AliHLTAltroGenerator
34  * Helper class to generate data in the Altro format.
35  * 
36  * The class can be configured through the parameters of the
37  * AliHLTAltroGenerator(int, int, int, int, int) constructor.
38  * The data is generated by the Generate() method and stored internally 
39  * for subsequent use. The data is encoded into a buffer with the 
40  * GetData(AliHLTUInt8_t) or GetData(AliHLTUInt8_t, int) methods.
41  *
42  * A couple of functions provide access to the simulated data on a
43  * signal by signal basis (Next()) or a bunch by bunch basis
44  * (NextChannel() / NextBunch()). The scheme follows pretty much the
45  * AliRawReader or AliAltroDecoder scheme respectively.
46  *
47  * @ingroup alihlt_rcu
48  */
49 class AliHLTAltroGenerator : AliHLTLogging {
50  public:
51   /** constructor */
52   AliHLTAltroGenerator(int maxChannels=1000,
53                        int maxBunches=50,
54                        int maxBunchLength=10,
55                        int maxTimebin=1024,
56                        int maxSignal=500);
57   /** destructor */
58   virtual ~AliHLTAltroGenerator();
59
60   /**
61    * Generate a new event.
62    * Simulate new data and store internally in plain format.
63    *
64    * @return size of the encoded data in byte. If the CDH and/or RCU
65    * trailer was set, the size includes those.
66    */
67   int Generate();
68
69   /**
70    * Get the number of 40bit Altro words of the current data set.
71    * @return number of 40bit Altro words.
72    */
73   int GetNof40BitAltroWords() const;
74
75   /**
76    * Get the data size of the current data set.
77    * @return size of the encoded data in byte. If the CDH and/or RCU
78    * trailer was set, the size includes those.
79    */
80   int GetDataSize();
81
82   /**
83    * Get the simulated data.
84    * Get a pointer to the internal buffer. The buffer is filled with
85    * the encoded data from the previous simulation.
86    * @param pBuffer     target variable to receive the pointer
87    * @return size in byte, neg. error if failed
88    */
89   int GetData(AliHLTUInt8_t* &pBuffer);
90
91   /**
92    * Get the simulated data.
93    * The provided buffer is filled with the encoded data from the
94    * previous simulation.
95    * @param pBuffer     target variable to receive the pointer
96    * @param size        size of the target buffer
97    * @return size in byte, neg. error if failed
98    */
99   int GetData(AliHLTUInt8_t* pBuffer, int size);
100
101   /**
102    * Set the Common Data Header.
103    * @param pCDH        the CDH
104    * @param size        size of the header in byte
105    * @return neg. error code if failed
106    */
107   int SetCDH(AliRawDataHeader* pCDH, int size);
108
109   /**
110    * Set the RCU trailer.
111    * @param pTrailer    the trailer
112    * @param size        size of the header in byte
113    * @return neg. error code if failed
114    */
115   int SetRCUTrailer(AliHLTUInt8_t* pTrailer, int size);
116
117   /**
118    * Get list of channels in the current data set.
119    */
120   int GetChannels(vector<AliHLTUInt16_t> list);
121
122   /**
123    * Set array of channels for sorting of channels.
124    * The encoded data will be sorted according to the specified
125    * list.
126    * @param array       array of channels
127    * @param arraySize   size of the array
128    */
129   int SetSorting(AliHLTUInt16_t *array, int arraySize);
130
131   /**
132    * Get a random number in the given range.
133    */
134   int GetRandom(int min, int max);
135
136   /**
137    * Set parsing direction for the Next functions.
138    * @param direction   @ref AliHLTAltroGenerator::kBackwards (default),
139    *                    @ref AliHLTAltroGenerator::kForwards
140    */
141   void SetDirection(int direction) {fDirection=direction;}
142
143   /**
144    * Position at the next signal.
145    * The function follows the pure stream model.
146    * @return true if there is a new signal available
147    */
148   bool Next();
149
150   /**
151    * Get the current signal.
152    * The current time value can be retrieved by ::GetStartTime or
153    * ::GetEndTime which return both the current time in the stream
154    * model.
155    * @return signal value
156    */
157   AliHLTUInt16_t GetSignal();
158
159   /**
160    * Position at the beginning of the next channel.
161    * Depending on the mode, the function works either back or
162    * forwards.
163    * @return true if there is a new channel available
164    */
165   bool NextChannel();
166
167   /**
168    * Get the hardware address of the current channel.
169    */
170   AliHLTUInt16_t GetHwAddress();
171
172   /**
173    * Get bunch count of the current channel
174    */
175   int GetBunchCount();
176
177   /**
178    * Position at the beginning of the next bunch.
179    * Depending on the mode, the function works either back or
180    * forwards.
181    * @return true if there is a new bunch available
182    */
183   bool NextBunch();
184
185   /**
186    * Get size of the current bunch.
187    */
188   AliHLTUInt16_t GetBunchSize();
189
190   /**
191    * Get start time of the current bunch or signal.
192    */
193   AliHLTUInt16_t  GetStartTime();
194
195   /**
196    * Get end time of the current bunch or signal.
197    */
198   AliHLTUInt16_t  GetEndTime();
199
200   /**
201    * Get pointer to signals of current bunch.
202    * The signals are always in ascending order.
203    */
204   const Short_t* GetSignals();
205
206   /**
207    * Reset the internal position variables.
208    */
209   int Reset();
210
211   /**
212    * Rewind stream position for Next funxtions
213    */
214   int Rewind();
215
216   /**
217    * Print content of simulated data to cout.
218    */
219   void Print();
220
221   /**
222    * Printout of simulated data.
223    */
224   friend ostream &operator<<(ostream &str, AliHLTAltroGenerator &generator);
225
226   enum {
227     kBackwards = 0,
228     kForwards = 1
229   };
230
231  protected:
232  
233  private:
234   /** copy constructor prohibited */
235   AliHLTAltroGenerator(const AliHLTAltroGenerator&);
236   /** assignment operator prohibited */
237   AliHLTAltroGenerator& operator=(const AliHLTAltroGenerator&);
238
239   /**
240    * Encode the simulated data into Altro format
241    */
242   int EncodeData(AliHLTUInt8_t* pBuffer, int size);
243
244   /// internal data buffer
245   TArrayC* fpData; //!transient
246
247   /// array of simulated data
248   TArrayS* fpSimData; //! transient
249
250   struct AliChannelPosition {
251     AliHLTUInt16_t fChannel; //! transient
252     int fPosition; //! transient
253     int fEnd; //! transient
254   };
255
256   /// channels and their positions in the simulated data
257   vector<AliChannelPosition> fChannelPositions; //! transient
258
259   /// the Altro payload in the simulated data
260   int fNof10BitWords; //! transient
261
262   /// the Common Data Header
263   AliRawDataHeader* fpCDH; //!transient
264
265   /// size of the Common Data Header in byte
266   int fCDHSize; //! transient
267
268   /// the RCU trailer
269   AliHLTUInt8_t* fpTrailer; //!transient
270
271   /// size of the trailer
272   int fTrailerSize; //!transient
273
274   /// maximum number of channels
275   int fMaxChannels; //! transient
276
277   /// maximum number of bunches
278   int fMaxBunches; //! transient
279
280   /// maximum bunche length
281   int fMaxBunchLength; //! transient
282
283   /// max timebin
284   int fMaxTimebin; //!transient
285
286   /// maximum signal
287   int fMaxSignal; // transient
288
289   /// the random number generator
290   TRandom* fpRand; //! transient
291
292   /// direction of parsing
293   int fDirection; //! transient
294
295   /// current channel position for the Next functions
296   int fCurrentPosition; //! transient
297
298   /// current bunch position in the simulated data
299   int fCurrentBunch; //! transient
300
301   /// current offset in the current bunch
302   int fCurrentTimeOffset; //! transient
303
304   ClassDef(AliHLTAltroGenerator, 0);
305 };
306
307 #endif