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