Fixing code so that components use the new standard DDL_RAW data type.
[u/mrichter/AliRoot.git] / HLT / MUON / AliHLTMUONUtils.h
1 #ifndef ALIHLTMUONUTILS_H
2 #define ALIHLTMUONUTILS_H
3 /* Copyright(c) 1998-2007, ALICE Experiment at CERN, All rights reserved. *
4  * See cxx source for full Copyright notice                               */
5
6 /* $Id$ */
7
8 ///
9 /// @file   AliHLTMUONUtils.h
10 /// @author Artur Szostak <artursz@iafrica.com>
11 /// @date   
12 /// @brief  Class containing various dimuon HLT utility routines and macros.
13 ///
14
15 #include "AliHLTMUONDataTypes.h"
16
17 // Forward declare structures.
18 extern "C" {
19 struct AliHLTMUONTriggerRecordStruct;
20 struct AliHLTMUONTriggerRecordsBlockStruct;
21 struct AliHLTMUONTrigRecsDebugBlockStruct;
22 struct AliHLTMUONTriggerChannelsBlockStruct;
23 struct AliHLTMUONRecHitsBlockStruct;
24 struct AliHLTMUONClustersBlockStruct;
25 struct AliHLTMUONChannelsBlockStruct;
26 struct AliHLTMUONMansoTrackStruct;
27 struct AliHLTMUONMansoTracksBlockStruct;
28 struct AliHLTMUONMansoCandidatesBlockStruct;
29 struct AliHLTMUONTrackDecisionStruct;
30 struct AliHLTMUONSinglesDecisionBlockStruct;
31 struct AliHLTMUONPairDecisionStruct;
32 struct AliHLTMUONPairsDecisionBlockStruct;
33 } // extern "C"
34
35 /**
36  * AliHLTMUONUtils contains arbitrary utility methods to be used in various
37  * parts of the dimuon HLT system.
38  * These include methods to perform basic sanity checks on the integrity of
39  * data blocks.
40  */
41 class AliHLTMUONUtils
42 {
43 public:
44         /**
45          * This packs the given parameters into the bits of a word appropriate
46          * for AliHLTMUONTriggerRecordStruct::fFlags.
47          * @param sign    The particle sign.
48          * @param hitset  Flags to indicate if the corresponding fHits[i] elements
49          *                was set/filled.
50          * @return  Returns the 32 bit packed word.
51          */
52         static AliHLTUInt32_t PackTriggerRecordFlags(
53                         AliHLTMUONParticleSign sign, const bool hitset[4]
54                 );
55
56         /**
57          * This unpacks the AliHLTMUONTriggerRecordStruct::fFlags bits into
58          * its component fields.
59          * @param flags  The flags from an AliHLTMUONTriggerRecordStruct structure.
60          * @param sign    Sets this to the particle sign.
61          * @param hitset  Sets the array elements to indicate if the corresponding
62          *                fHits[i] element was set/filled.
63          */
64         static void UnpackTriggerRecordFlags(
65                         AliHLTUInt32_t flags, // [in]
66                         AliHLTMUONParticleSign& sign, // [out]
67                         bool hitset[4] // [out]
68                 );
69
70         /**
71          * This packs the given parameters into the bits of a word appropriate
72          * for AliHLTMUONMansoTrackStruct::fFlags.
73          * @param sign    The particle sign.
74          * @param hitset  Flags to indicate if the corresponding fHits[i] elements
75          *                was set/filled.
76          * @return  Returns the 32 bit packed word.
77          */
78         static AliHLTUInt32_t PackMansoTrackFlags(
79                         AliHLTMUONParticleSign sign, const bool hitset[4]
80                 )
81         {
82                 return PackTriggerRecordFlags(sign, hitset);
83         }
84
85         /**
86          * This unpacks the AliHLTMUONMansoTrackStruct::fFlags bits into
87          * its component fields.
88          * @param flags  The flags from an AliHLTMUONMansoTrackStruct structure.
89          * @param sign    Sets this to the particle sign.
90          * @param hitset  Sets the array elements to indicate if the corresponding
91          *                fHits[i] element was set/filled.
92          */
93         static void UnpackMansoTrackFlags(
94                         AliHLTUInt32_t flags, // [in]
95                         AliHLTMUONParticleSign& sign, // [out]
96                         bool hitset[4] // [out]
97                 )
98         {
99                 UnpackTriggerRecordFlags(flags, sign, hitset);
100         }
101         
102         /**
103          * This packs the given parameters into the bits of a word appropriate
104          * for AliHLTMUONTrackDecisionStruct::fTriggerBits.
105          * @param highPt  Has the track passed the high pt cut.
106          * @param lowPt   Has the track passed the low pt cut.
107          * @return  Returns the 32 bit packed word.
108          */
109         static AliHLTUInt32_t PackTrackDecisionBits(bool highPt, bool lowPt);
110         
111         /**
112          * This unpacks the AliHLTMUONTrackDecisionStruct::fTriggerBits bits into
113          * its component fields.
114          * @param bits  The trigger bits from an AliHLTMUONTrackDecisionStruct
115          *              structure.
116          * @param highPt Sets this to the value of the high pt cut bit.
117          * @param lowPt  Sets this to the value of the low pt cut bit.
118          */
119         static void UnpackTrackDecisionBits(
120                         AliHLTUInt32_t bits, // [in]
121                         bool& highPt, // [out]
122                         bool& lowPt // [out]
123                 );
124         
125         /**
126          * This packs the given parameters into the bits of a word appropriate
127          * for AliHLTMUONPairDecisionStruct::fTriggerBits.
128          *
129          * @param highMass Has the track pair passed the high invariant mass cut.
130          * @param lowMass  Has the track pair passed the low invariant mass cut.
131          * @param unlike   Does the track pair have unlike signs.
132          * @param highPtCount The number of tracks that passed the high pt cut
133          *                    in the pair.
134          * @param lowPtCount  The number of tracks that passed the low pt cut
135          *                    in the pair.
136          * @return  Returns the 32 bit packed word.
137          *
138          * Note: Must have highPtCount + lowPtCount <= 2 and unlike == true if
139          * highMass or lowMass is true.
140          */
141         static AliHLTUInt32_t PackPairDecisionBits(
142                         bool highMass, bool lowMass, bool unlike,
143                         AliHLTUInt8_t highPtCount, AliHLTUInt8_t lowPtCount
144                 );
145         
146         /**
147          * This unpacks the AliHLTMUONPairDecisionStruct::fTriggerBits bits into
148          * its component fields.
149          * @param bits  The trigger bits from an AliHLTMUONPairDecisionStruct
150          *              structure.
151          * @param highMass Sets this to the value of the high invariant mass cut bit.
152          * @param lowMass  Sets this to the value of the low invariant mass cut bit.
153          * @param unlike   Sets this if the pair is unlike sign.
154          * @param highPtCount Sets this to the high pt count bits.
155          * @param lowPtCount  Sets this to the low pt count bits.
156          */
157         static void UnpackPairDecisionBits(
158                         AliHLTUInt32_t bits, // [in]
159                         bool& highMass, // [out]
160                         bool& lowMass, // [out]
161                         bool& unlike, // [out]
162                         AliHLTUInt8_t& highPtCount, // [out]
163                         AliHLTUInt8_t& lowPtCount // [out]
164                 );
165         
166         /**
167          * This packs the given parameters into the 32bit Pub/Sub specification
168          * word in the data block descriptor.
169          *
170          * @param ddl  The list of DDLs forming part of the readout. ddl[0]
171          *             indicates DDL number 2560, ddl[1] is for DDL 2561 and so
172          *             on up to ddl[19]. ddl[20] and ddl[21] will be for the
173          *             trigger DDLs 2816 and 2817 respectively.
174          * @return  Returns the 32 bit packed specification word.
175          */
176         static AliHLTUInt32_t PackSpecBits(
177                         const bool ddl[22]
178                 );
179         
180         /**
181          * This unpacks the AliHLTMUONPairDecisionStruct::fTriggerBits bits into
182          * its component fields.
183          * @param bits  The Pub/Sub specification word from a data block descriptor.
184          * @param ddl  The output list of DDLs forming part of the readout. ddl[0]
185          *             indicates DDL number 2560, ddl[1] is for DDL 2561 and so
186          *             on up to ddl[19]. ddl[20] and ddl[21] will be for the
187          *             trigger DDLs 2816 and 2817 respectively.
188          */
189         static void UnpackSpecBits(
190                         AliHLTUInt32_t bits, // [in]
191                         bool ddl[22] // [out]
192                 );
193
194         /**
195          * This method converts the DDL number for the muon spectrometer in the
196          * range [0..21] to the equipment ID number.
197          * @param ddlNo  The DDL number in the range [0..21].
198          * @return  Returns the equipment ID number or -1 if ddlNo was invalid.
199          */
200         static AliHLTInt32_t DDLNumberToEquipId(AliHLTInt32_t ddlNo);
201         
202         /**
203          * This method converts the equipment ID number for a muon spectrometer
204          * DDL to the DDL number in the range [0..21].
205          * @param id  The equipment ID of the DDL.
206          * @return  Returns the DDL number in the range [0..21] or -1 if the
207          *          equipment ID was invalid.
208          */
209         static AliHLTInt32_t EquipIdToDDLNumber(AliHLTInt32_t id);
210         
211         /**
212          * This method converts a 32 bit data block specification for a MUON-HLT
213          * data block into its corresponding DDL equipment ID number.
214          * It is assumed that the specification is for a data block comming from
215          * a single DDL source. If more than one DDL contributed to the data block
216          * then -1 is returned.
217          * @param spec  The 32 bit specification for a data block.
218          * @return  Returns the equipment ID corresponding to the specification
219          *          or -1 if the specification was invalid.
220          */
221         static AliHLTInt32_t SpecToEquipId(AliHLTUInt32_t spec);
222         
223         /**
224          * This method converts a equipment ID number for a DDL into its corresponding
225          * 32 bit data block specification for the MUON-HLT.
226          * @param id  The equipment ID number of the DDL.
227          * @return  Returns the 32 bit data block specification or 0x0 if the
228          *          equipment ID was invalid.
229          */
230         static AliHLTUInt32_t EquipIdToSpec(AliHLTInt32_t id);
231         
232         /**
233          * This method converts a 32 bit data block specification for a MUON-HLT
234          * data block into its corresponding DDL number in the range [0..21].
235          * It is assumed that the specification is for a data block comming from
236          * a single DDL source. If more than one DDL contributed to the data block
237          * then -1 is returned.
238          * @param spec  The 32 bit specification for a data block.
239          * @return  Returns the corresponding DDL number for the specification
240          *          or -1 if the specification was invalid.
241          */
242         static AliHLTInt32_t SpecToDDLNumber(AliHLTUInt32_t spec);
243         
244         /**
245          * This method converts a DDL number in the range [0..21] into its
246          * corresponding 32 bit data block specification for the MUON-HLT.
247          * @param ddlNo  The equipment ID number of the DDL.
248          * @return  Returns the 32 bit data block specification or 0x0 if the
249          *          DDL number was invalid (out of range).
250          */
251         static AliHLTUInt32_t DDLNumberToSpec(AliHLTInt32_t ddlNo);
252
253         /**
254          * Returns true if the given specification was for a single trigger DDL.
255          */
256         static bool IsTriggerDDL(AliHLTUInt32_t spec)
257         {
258                 AliHLTInt32_t ddl = SpecToDDLNumber(spec);
259                 return (20 <= ddl and ddl <= 21);
260         }
261
262         /**
263          * Returns true if the given specification was for a single tracker DDL.
264          */
265         static bool IsTrackerDDL(AliHLTUInt32_t spec)
266         {
267                 AliHLTInt32_t ddl = SpecToDDLNumber(spec);
268                 return (0 <= ddl and ddl <= 19);
269         }
270
271         /**
272          * These codes indicate the reason why a data block failed its
273          * validity check.
274          */
275         enum WhyNotValid
276         {
277                 kNoReason,
278                 kHeaderContainsWrongType,
279                 kHeaderContainsWrongRecordWidth
280         };
281
282         /**
283          * Methods used to check if the header information corresponds to the
284          * supposed type of the data block.
285          * If the 'reason' parameter is not NULL then these methods will fill the
286          * memory pointed to by reason with a code describing of why the header
287          * is not valid, if and only if a problem is found with the data.
288          */
289         static bool HeaderOk(const AliHLTMUONTriggerRecordsBlockStruct& block, WhyNotValid* reason = NULL);
290         static bool HeaderOk(const AliHLTMUONTrigRecsDebugBlockStruct& block);
291         static bool HeaderOk(const AliHLTMUONTriggerChannelsBlockStruct& block);
292         static bool HeaderOk(const AliHLTMUONRecHitsBlockStruct& block);
293         static bool HeaderOk(const AliHLTMUONClustersBlockStruct& block);
294         static bool HeaderOk(const AliHLTMUONChannelsBlockStruct& block);
295         static bool HeaderOk(const AliHLTMUONMansoTracksBlockStruct& block);
296         static bool HeaderOk(const AliHLTMUONMansoCandidatesBlockStruct& block);
297         static bool HeaderOk(const AliHLTMUONSinglesDecisionBlockStruct& block);
298         static bool HeaderOk(const AliHLTMUONPairsDecisionBlockStruct& block);
299
300         /**
301          * Methods used to check more extensively if the integrity of various
302          * types of data blocks are Ok and returns true in that case.
303          * These can be slow and should generally only be used for debugging.
304          */
305         static bool IntegrityOk(const AliHLTMUONTriggerRecordStruct& tr);
306         static bool IntegrityOk(const AliHLTMUONTriggerRecordsBlockStruct& block);
307         static bool IntegrityOk(const AliHLTMUONTrigRecsDebugBlockStruct& block);
308         static bool IntegrityOk(const AliHLTMUONTriggerChannelsBlockStruct& block);
309         static bool IntegrityOk(const AliHLTMUONRecHitsBlockStruct& block);
310         static bool IntegrityOk(const AliHLTMUONClustersBlockStruct& block);
311         static bool IntegrityOk(const AliHLTMUONChannelsBlockStruct& block);
312         static bool IntegrityOk(const AliHLTMUONMansoTrackStruct& track);
313         static bool IntegrityOk(const AliHLTMUONMansoTracksBlockStruct& block);
314         static bool IntegrityOk(const AliHLTMUONMansoCandidatesBlockStruct& block);
315         static bool IntegrityOk(const AliHLTMUONTrackDecisionStruct& decision);
316         static bool IntegrityOk(const AliHLTMUONSinglesDecisionBlockStruct& block);
317         static bool IntegrityOk(const AliHLTMUONPairDecisionStruct& decision);
318         static bool IntegrityOk(const AliHLTMUONPairsDecisionBlockStruct& block);
319
320 private:
321         // Should never have to create or destroy this object.
322         AliHLTMUONUtils();
323         ~AliHLTMUONUtils();
324 };
325
326 //_____________________________________________________________________________
327
328 // Since c++ is missing a finally "keyword" we define one. Its usage is identical
329 // to a try..finally statement in Java etc.. however, since it is officialy a macro
330 // one must use the ( ) brackets instead of { }
331 // If the compiler supports __finally use it otherwise make our own.
332 #if defined(__BORLANDC__)
333 #       define finally(str) __finally{str}
334 #else
335 #       define finally(code) \
336                 catch(...) \
337                 { \
338                         code \
339                         throw; \
340                 }; \
341                 code
342 #endif // __BORLANDC__
343
344 // If we do not already have them, then define logical operators that are easier
345 // to read. 'and' = &&, 'or' = ||, 'not' = !
346 #if ! defined(__GNUC__) && ! defined(__CINT__)
347 // TODO: Should use iso646.h
348 #       define and &&
349 #       define or ||
350 #       define not !
351 #endif // __GNUC__ | __CINT__
352
353
354 // Here we define the DebugTrace(message) macro for easy embedding of debug
355 // information into the dimuon HLT code. Its usage is meant to be for generating
356 // traces of the program which are only useful during full scale debugging.
357 // Log messages should use the standard HLT logging mechanisms.
358 // The output is only generated in programs compiled with the DEBUG directive
359 // defined. Here is a usage example:
360 //
361 //  // statements...
362 //  DebugTrace("some debug information.");
363 //  // statements...
364 //
365 // One can also use C++ ostream operators and manipulators like so:
366 //
367 //  // statements...
368 //  int x, y;
369 //  DebugTrace("x = " << x << " and y = 0x" << std::hex << y );
370 //  // statements...
371 //
372 #ifdef DEBUG
373 #       include <iostream>
374 #       define DebugTrace(message) {std::cout << message << std::endl;}
375 #else // DEBUG
376 #       define DebugTrace(message)
377 #endif // DEBUG
378
379
380 #endif // ALIHLTMUONUTILS_H