Fixing code so that components use the new standard DDL_RAW data type.
[u/mrichter/AliRoot.git] / HLT / MUON / AliHLTMUONUtils.h
CommitLineData
26a4668d 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
6253e09b 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///
26a4668d 14
c8ec7c7e 15#include "AliHLTMUONDataTypes.h"
16
17// Forward declare structures.
18extern "C" {
90a74d7a 19struct AliHLTMUONTriggerRecordStruct;
c8ec7c7e 20struct AliHLTMUONTriggerRecordsBlockStruct;
21struct AliHLTMUONTrigRecsDebugBlockStruct;
22struct AliHLTMUONTriggerChannelsBlockStruct;
23struct AliHLTMUONRecHitsBlockStruct;
24struct AliHLTMUONClustersBlockStruct;
25struct AliHLTMUONChannelsBlockStruct;
90a74d7a 26struct AliHLTMUONMansoTrackStruct;
27struct AliHLTMUONMansoTracksBlockStruct;
28struct AliHLTMUONMansoCandidatesBlockStruct;
29struct AliHLTMUONTrackDecisionStruct;
30struct AliHLTMUONSinglesDecisionBlockStruct;
31struct AliHLTMUONPairDecisionStruct;
32struct AliHLTMUONPairsDecisionBlockStruct;
c8ec7c7e 33} // extern "C"
26a4668d 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 */
41class AliHLTMUONUtils
42{
43public:
b727f838 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(
e6357f88 53 AliHLTMUONParticleSign sign, const bool hitset[4]
b727f838 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(
e6357f88 79 AliHLTMUONParticleSign sign, const bool hitset[4]
b727f838 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 }
90a74d7a 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 );
e6357f88 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 );
26a4668d 193
86b774d9 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
668eee9f 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
698c9498 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,
9c234d7b 279 kHeaderContainsWrongRecordWidth
698c9498 280 };
281
26a4668d 282 /**
b727f838 283 * Methods used to check if the header information corresponds to the
284 * supposed type of the data block.
698c9498 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.
26a4668d 288 */
698c9498 289 static bool HeaderOk(const AliHLTMUONTriggerRecordsBlockStruct& block, WhyNotValid* reason = NULL);
c8ec7c7e 290 static bool HeaderOk(const AliHLTMUONTrigRecsDebugBlockStruct& block);
291 static bool HeaderOk(const AliHLTMUONTriggerChannelsBlockStruct& block);
b727f838 292 static bool HeaderOk(const AliHLTMUONRecHitsBlockStruct& block);
293 static bool HeaderOk(const AliHLTMUONClustersBlockStruct& block);
294 static bool HeaderOk(const AliHLTMUONChannelsBlockStruct& block);
90a74d7a 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);
b727f838 299
300 /**
90a74d7a 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.
b727f838 303 * These can be slow and should generally only be used for debugging.
304 */
90a74d7a 305 static bool IntegrityOk(const AliHLTMUONTriggerRecordStruct& tr);
b727f838 306 static bool IntegrityOk(const AliHLTMUONTriggerRecordsBlockStruct& block);
c8ec7c7e 307 static bool IntegrityOk(const AliHLTMUONTrigRecsDebugBlockStruct& block);
308 static bool IntegrityOk(const AliHLTMUONTriggerChannelsBlockStruct& block);
b727f838 309 static bool IntegrityOk(const AliHLTMUONRecHitsBlockStruct& block);
310 static bool IntegrityOk(const AliHLTMUONClustersBlockStruct& block);
311 static bool IntegrityOk(const AliHLTMUONChannelsBlockStruct& block);
90a74d7a 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);
26a4668d 319
320private:
321 // Should never have to create or destroy this object.
322 AliHLTMUONUtils();
323 ~AliHLTMUONUtils();
324};
325
b727f838 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__)
b12fe461 347// TODO: Should use iso646.h
b727f838 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;
b12fe461 369// DebugTrace("x = " << x << " and y = 0x" << std::hex << y );
b727f838 370// // statements...
371//
372#ifdef DEBUG
b4dfa1c8 373# include <iostream>
b727f838 374# define DebugTrace(message) {std::cout << message << std::endl;}
375#else // DEBUG
376# define DebugTrace(message)
377#endif // DEBUG
378
379
26a4668d 380#endif // ALIHLTMUONUTILS_H