Fix loading of TPC clusters; SEGV occured with events generated with today's HEAD.
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTOUT.h
CommitLineData
62bb3cd4 1//-*- Mode: C++ -*-
2// @(#) $Id$
3
4#ifndef ALIHLTOUT_H
5#define ALIHLTOUT_H
5db0e774 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 *
62bb3cd4 9
10/** @file AliHLTOUT.h
11 @author Matthias Richter
12 @date
13 @brief The control class for HLTOUT data.
5db0e774 14*/
62bb3cd4 15
4de7334f 16#include <vector>
62bb3cd4 17#include "AliHLTLogging.h"
5db0e774 18#include "AliHLTModuleAgent.h"
19
20class AliHLTOUTHandler;
04058ee9 21class AliHLTOUTHandlerDesc; // AliHLTModuleAgent.h
5db0e774 22
23#define AliHLTOUTInvalidIndex (~(AliHLTUInt32_t)0)
24
25typedef vector<AliHLTUInt32_t> AliHLTOUTIndexList;
62bb3cd4 26
27/**
28 * @class AliHLTOUT
29 * The control class for HLTOUT data.
30 * The output of the HLT, either from the HLTOUT nodes or simulated output,
31 * is transferred and stored in the HOMER format. The AliHLTOUT class
32 * implements scanning of the HOMER data for all HLTOUT DDL links and
33 * abstracts access to the complete HLTOUT data.
34 *
35 */
36class AliHLTOUT : public AliHLTLogging {
37 public:
38 /** standard constructor */
39 AliHLTOUT();
40 /** standard destructor */
41 virtual ~AliHLTOUT();
42
5db0e774 43 /**
44 * Init for processing.
45 * The HLTOUT is scanned for all available data blocks and the
46 * AliHLTOUTHandler objects for the data blocks are created according
47 * to the module agents (see AliHLTModuleAgent).
48 */
49 int Init();
50
4de7334f 51 /**
52 * Get number of data blocks in the HLTOUT data
53 */
54 int GetNofDataBlocks();
55
56 /**
57 * Select the first data block of a certain data type and specification.
58 * The selection criteria can be of kAliHLTAnyDataType and/or
59 * kAliHLTVoidDataSpec in order to be ignored and just match any data block.
5db0e774 60 *
61 * The search criteria can be combined with a handler type (e.g. kRawReader)
4de7334f 62 * @param dt [in] data type to match <br>
63 * @param spec [in] data specification to match <br>
5db0e774 64 * @param handlerType [in] type of the handler
65 * @return identifier >0 if success, 0 if no block found <br>
66 * neg. error code if failed <br>
4de7334f 67 * -EPERM if access denied (object locked)
68 */
18b56222 69 int SelectFirstDataBlock(AliHLTComponentDataType dt=kAliHLTAnyDataType,
70 AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
5db0e774 71 AliHLTModuleAgent::AliHLTOUTHandlerType handlerType=AliHLTModuleAgent::kUnknownOutput);
4de7334f 72
73 /**
74 * Select the next data block of data type and specification of the previous
75 * call to @ref SelectFirstDataBlock.
5db0e774 76 * @return identifier >0 if success, 0 if no block found <br>
77 * neg. error code if failed <br>
4de7334f 78 * -EPERM if access denied (object locked)
79 */
80 int SelectNextDataBlock();
81
82 /**
83 * Get properties of the selected data block.
84 * @param dt [out] data type of the selected block
85 * @param spec [out] data specification of the selected block
86 */
87 int GetDataBlockDescription(AliHLTComponentDataType& dt, AliHLTUInt32_t& spec);
88
5db0e774 89 /**
90 * Get the index of the current data block.
91 * @return index, AliHLTOUTInvalidIndex if no block selected
92 */
93 AliHLTUInt32_t GetDataBlockIndex();
94
4de7334f 95 /**
96 * Get buffer of the selected data block.
97 * @param pBuffer [out] buffer of the selected data block
98 * @param size [out] size of the selected data block
99 */
100 int GetDataBuffer(const AliHLTUInt8_t* &pBuffer, AliHLTUInt32_t& size);
101
102 /**
103 * Release buffer after use.
104 * @param pBuffer [in] buffer of the selected data block
105 */
106 int ReleaseDataBuffer(const AliHLTUInt8_t* pBuffer);
107
626bfcc1 108 /**
109 * Get handler for the selected data block.
110 */
111 AliHLTOUTHandler* GetHandler();
112
4de7334f 113 /**
114 * Locking guard for the AliHLTOUT object.
115 * If the object is locked, the selection of data blocks can not be changed.
116 */
117 class AliHLTOUTLockGuard {
118 public:
119 /** constructor */
120 AliHLTOUTLockGuard(AliHLTOUT* pInstance) : fpInstance(pInstance)
049b43b2 121 {if (fpInstance) fpInstance->SetStatusFlag(kLocked);}
4de7334f 122 /** destructor */
123 ~AliHLTOUTLockGuard()
049b43b2 124 {if (fpInstance) fpInstance->ClearStatusFlag(kLocked);}
4de7334f 125
126 private:
127 /** standard constructor prohibited */
128 AliHLTOUTLockGuard();
129 /** copy constructor prohibited */
130 AliHLTOUTLockGuard(const AliHLTOUTLockGuard&);
131 /** assignment operator prohibited */
132 AliHLTOUTLockGuard& operator=(const AliHLTOUTLockGuard&);
133
134 /** the AliHLTOUT instance the guard is locking */
135 AliHLTOUT* fpInstance; //!transient
136 };
137
4b113031 138 /**
139 * The HLT OUT Event Header.
140 * Defined between HLT and DAQ.
141 */
142 struct AliHLTOUTEventHeader {
143 /**Total length of the data in bytes, including HLT event header, excluding CDH. */
144 AliHLTUInt32_t fLength; //! see above
145 /** version of the header */
146 AliHLTUInt32_t fVersion; //! see above
147 /** event id */
148 AliHLTUInt64_t fEventID; //! see above
149 };
150
44dc7683 151 enum {
152 /// versions 1 of the HLT header
153 kVersion1 = 1,
154 /// versions 2 of the HLT header
155 kVersion2 = 2
156 };
157
158 enum {
159 /// size of HLT decision in data format version 1: 29x4
160 kSizeDecisionVersion1 = 116,
161 /// size of HLT decision in data format version 2: 30x4
162 kSizeDecisionVersion2 = 120
163 };
164
4b113031 165 // definitions from ALICE internal notes ALICE-INT-2002-010 and
166 // ALICE-INT-2006-XXX
13398559 167 enum {
168 /** the 32bit word in the CDH containing the status flags */
169 kCDHStatusWord=4, //! see above
170 /** start of the flags in word fgkCDHStatusWord */
171 kCDHStatusFlagsOffset=12, //! see above
172 /** bit indicating HLT decision in the HLTOUT*/
173 kCDHFlagsHLTDecision=6, //! see above
174 /** bit indicating HLT payload in the HLTOUT*/
175 kCDHFlagsHLTPayload=7 //! see above
176 };
4b113031 177
4de7334f 178 /**
179 * Block descriptor.
180 */
181 class AliHLTOUTBlockDescriptor {
182 public:
183 AliHLTOUTBlockDescriptor(AliHLTComponentDataType dt, AliHLTUInt32_t spec, AliHLTUInt32_t index)
184 : fDataType(dt), fSpecification(spec), fIndex(index) {};
185 ~AliHLTOUTBlockDescriptor() {}
186
187 operator AliHLTComponentDataType() const {return fDataType;}
188 operator AliHLTUInt32_t() const {return fSpecification;}
189 int operator==(AliHLTComponentDataType dt) const {return dt==fDataType;}
190 int operator==(AliHLTUInt32_t spec) const {return spec==fSpecification;}
191
192 AliHLTUInt32_t GetIndex() const {return fIndex;}
193 private:
194 /** data type of the block */
195 AliHLTComponentDataType fDataType; //!transient
196 /** data specification of the block */
197 AliHLTUInt32_t fSpecification; //!transient
198 /** index in the data stream */
199 AliHLTUInt32_t fIndex; //!transient
200 };
201
13398559 202 enum AliHLTOUTByteOrder {
049b43b2 203 /** no data block selected */
204 kInvalidByteOrder=-1,
205 kUnknownByteOrder=0,
206 kLittleEndian,
207 kBigEndian
208 };
209
13398559 210 enum AliHLTOUTDataType {
049b43b2 211 kUint64 = 0,
212 kUint32 = 1,
213 kUint16 = 2,
214 kUint8 = 3,
215 kDouble = 4,
216 kFloat = 5
217 };
218
219 /**
220 * Check byte order of selected block
221 */
13398559 222 AliHLTOUTByteOrder CheckByteOrder();
049b43b2 223
224 /**
225 * Check alignment of selected block
226 */
13398559 227 int CheckAlignment(AliHLTOUT::AliHLTOUTDataType type);
049b43b2 228
44dc7683 229 /**
230 * Helper function to byte swap a 64 bit value.
231 */
ff3b6fed 232 static AliHLTUInt64_t ByteSwap64(AliHLTUInt64_t src);
44dc7683 233
234 /**
235 * Helper function to byte swap a 32 bit value.
236 */
ff3b6fed 237 static AliHLTUInt32_t ByteSwap32(AliHLTUInt32_t src);
44dc7683 238
62bb3cd4 239 protected:
4de7334f 240 /**
241 * Add a block descriptor.
242 * This is done by the child classes generating the index. The AliHLTOUT
243 * object must be locked for index generation.
244 * @param desc the block descriptor
245 * @return 0 if success, -EPERM if access denied
246 */
247 int AddBlockDescriptor(const AliHLTOUTBlockDescriptor desc);
62bb3cd4 248
44dc7683 249 /**
250 * Print output or suppress.
251 */
252 bool BeVerbose() {return fbVerbose;}
253
254 /**
255 * Switch output.
256 */
257 void SwitchVerbosity(bool verbose) {fbVerbose=verbose;}
258
62bb3cd4 259 private:
260 /** copy constructor prohibited */
261 AliHLTOUT(const AliHLTOUT&);
262 /** assignment operator prohibited */
263 AliHLTOUT& operator=(const AliHLTOUT&);
264
049b43b2 265 /**
266 * Internal status flags
267 */
268 enum {
269 /** the HLTOUT object is locked with the current data block */
270 kLocked = 0x1,
271 /** childs can add block descriptors */
272 kCollecting = 0x2,
273 /** user of the data block has checked the byte order */
274 kByteOrderChecked = 0x4,
275 /** warning on byte order missmatch has been printed */
276 kByteOrderWarning = 0x8,
277 /** user of the data block has checked the alignment */
278 kAlignmentChecked = 0x10,
279 /** warning on alignment missmatch has been printed */
280 kAlignmentWarning = 0x20
281 };
282
5db0e774 283 class AliHLTOUTHandlerListEntry {
284 public:
285 AliHLTOUTHandlerListEntry(AliHLTOUTHandler* pHandler,
286 AliHLTModuleAgent::AliHLTOUTHandlerDesc& handlerDesc,
287 AliHLTModuleAgent* pAgent,
288 AliHLTUInt32_t index);
289
290 /** copy constructor for vector handling */
291 AliHLTOUTHandlerListEntry(const AliHLTOUTHandlerListEntry& src);
292
293 /** assignment operator for vector handling */
294 AliHLTOUTHandlerListEntry& operator=(const AliHLTOUTHandlerListEntry& src);
295
296 ~AliHLTOUTHandlerListEntry();
297
13398559 298 static const AliHLTOUTHandlerListEntry fgkVoidHandlerListEntry; //! initializer
626bfcc1 299
5db0e774 300 operator AliHLTOUTHandler*() const {return fpHandler;}
44dc7683 301
302 // please note that fpHandlerDesc is really a pointer and is created
303 // in the constructor. Thats why it is dereferenced here. The pointer
304 // type is on purpose, even though it is a bit confusing with the
305 // argument by reference in the AliHLTOUTHandlerListEntry constructor.
13398559 306 operator AliHLTModuleAgent::AliHLTOUTHandlerDesc&() const {return *fpHandlerDesc;}
5db0e774 307 operator AliHLTModuleAgent*() const {return fpAgent;}
308
a3ef3c1d 309 /**
310 * Two list entries are considered to be equal if the handlers
311 * are equal.
312 */
5db0e774 313 bool operator==(const AliHLTOUTHandlerListEntry& entry) const;
314
44dc7683 315 bool operator==(const AliHLTModuleAgent::AliHLTOUTHandlerType handlerType) const;
316
5db0e774 317 AliHLTUInt32_t operator[](int i) const;
318
a3ef3c1d 319 /**
320 * Add a block index to this descriptor.
321 * One descriptor can serve multiple blocks if the agent returns the
322 * same handler for all of the blocks. Instead of creating a new entry
323 * the block index ist just added
324 */
5db0e774 325 void AddIndex(AliHLTUInt32_t index);
326
a3ef3c1d 327 /**
328 * Add all indexes of the descriptor.
329 */
330 void AddIndex(AliHLTOUTHandlerListEntry &desc);
331
332 /**
333 * Check if an index is served by this descriptor.
334 * @return true if the index is in the table
335 */
626bfcc1 336 bool HasIndex(AliHLTUInt32_t index);
337
5db0e774 338 private:
339 /** standard constructor prohibited */
340 AliHLTOUTHandlerListEntry();
341
342 /** pointer to the handler */
343 AliHLTOUTHandler* fpHandler; //! transient
344
345 /** pointer to handler description */
626bfcc1 346 AliHLTModuleAgent::AliHLTOUTHandlerDesc* fpHandlerDesc; //! transient
5db0e774 347
348 /** pointer to module agent */
349 AliHLTModuleAgent* fpAgent; //! transient
350
351 /** list of block indexes */
352 AliHLTOUTIndexList fBlocks; //!transient
353 };
626bfcc1 354
4de7334f 355 /**
356 * Generate the index of the HLTOUT data.
357 * Must be implemented by the child classes.
358 */
359 virtual int GenerateIndex()=0;
360
5db0e774 361 /**
362 * Find AliHLTOUTHandler objects for the data blocks.
363 * The available AliHLTModuleAgents are probed whether they provide
364 * handlers for data processing.
365 */
366 int InitHandlers();
367
4de7334f 368 /**
369 * Get the data buffer
370 * @param index [in] index of the block
371 * @param pBuffer [out] buffer of the selected data block
372 * @param size [out] size of the selected data block
373 */
374 virtual int GetDataBuffer(AliHLTUInt32_t index, const AliHLTUInt8_t* &pBuffer,
375 AliHLTUInt32_t& size)=0;
376
049b43b2 377 /**
378 * Check byte order of data block
379 */
13398559 380 virtual AliHLTOUTByteOrder CheckBlockByteOrder(AliHLTUInt32_t index)=0;
049b43b2 381
382 /**
383 * Check alignment of data block
384 */
13398559 385 virtual int CheckBlockAlignment(AliHLTUInt32_t index, AliHLTOUT::AliHLTOUTDataType type)=0;
049b43b2 386
387 /**
388 * Select the data block of data type and specification of the previous
389 * call to @ref SelectFirstDataBlock. Core function of @ref SelectFirstDataBlock
390 * and @ref SelectNextDataBlock, starts to find a block at the current list
391 * position.
392 * @return identifier >=0 if success, neg. error code if failed <br>
393 * -ENOENT if no block found <br>
394 * -EPERM if access denied (object locked)
395 */
396 int FindAndSelectDataBlock();
397
398 /**
399 * Set status flag.
400 * @param flag flag to set
401 * @return current status flags
402 */
403 unsigned int SetStatusFlag(unsigned int flag) {return fFlags|=flag;}
404
405 /**
406 * Clear status flag.
407 * @param flag flag to clear
408 * @return current status flags
409 */
410 unsigned int ClearStatusFlag(unsigned int flag) {return fFlags&=~flag;}
411
412 /**
413 * Check status flag.
414 * @param flag flag to check
415 * @return 1 if flag is set
416 */
417 int CheckStatusFlag(unsigned int flag) const {return (fFlags&flag)==flag;}
418
5db0e774 419 /**
420 * Insert a handler item.
421 * The current list entries are checked if the handler is already in
422 * the list. It is added if not in the list, otherwise the block index
423 * is added to the existing entry.
424 * @param entry handler list entry
425 * @return 0 if added, EEXIST (non negative!) if merged with existing entry <br>
426 * neg. error code if failed
427 */
428 int InsertHandler(const AliHLTOUTHandlerListEntry &entry);
429
626bfcc1 430 /**
431 * Find handler description for a certain block index.
432 */
44dc7683 433 const AliHLTOUTHandlerListEntry& FindHandlerDesc(AliHLTUInt32_t blockIndex);
626bfcc1 434
4de7334f 435 /** data type for the current block search, set from @ref SelectFirstDataBlock */
436 AliHLTComponentDataType fSearchDataType; //!transient
437
438 /** data specification for the current block search */
439 AliHLTUInt32_t fSearchSpecification; //!transient
440
44dc7683 441 /** handler type for the current block search */
442 AliHLTModuleAgent::AliHLTOUTHandlerType fSearchHandlerType; // !transient
443
049b43b2 444 /** instance flags: locked, collecting, ... */
445 unsigned int fFlags; //!transient
4de7334f 446
13398559 447 typedef vector<AliHLTOUTHandlerListEntry> AliHLTOUTHandlerListEntryVector;
448 typedef vector<AliHLTOUTBlockDescriptor> AliHLTOUTBlockDescriptorVector;
449
4de7334f 450 /** list of block descriptors */
13398559 451 AliHLTOUTBlockDescriptorVector fBlockDescList; //!transient
4de7334f 452
453 /** current position in the list */
13398559 454 AliHLTOUTBlockDescriptorVector::iterator fCurrent; //!transient
4de7334f 455
456 /** data buffer under processing */
457 const AliHLTUInt8_t* fpBuffer; //!transient
458
5db0e774 459 /** list of AliHLTOUTHandlers */
13398559 460 AliHLTOUTHandlerListEntryVector fDataHandlers; // !transient
5db0e774 461
44dc7683 462 /** verbose or silent output */
463 bool fbVerbose; //!transient
464
465 ClassDef(AliHLTOUT, 2)
62bb3cd4 466};
467#endif