various fixes in the HLTOUT treatment
[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
4de7334f 43 /**
5db0e774 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
51 /**
4de7334f 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
89 /**
5db0e774 90 * Get the index of the current data block.
91 * @return index, AliHLTOUTInvalidIndex if no block selected
92 */
93 AliHLTUInt32_t GetDataBlockIndex();
94
95 /**
4de7334f 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
108 /**
109 * Locking guard for the AliHLTOUT object.
110 * If the object is locked, the selection of data blocks can not be changed.
111 */
112 class AliHLTOUTLockGuard {
113 public:
114 /** constructor */
115 AliHLTOUTLockGuard(AliHLTOUT* pInstance) : fpInstance(pInstance)
049b43b2 116 {if (fpInstance) fpInstance->SetStatusFlag(kLocked);}
4de7334f 117 /** destructor */
118 ~AliHLTOUTLockGuard()
049b43b2 119 {if (fpInstance) fpInstance->ClearStatusFlag(kLocked);}
4de7334f 120
121 private:
122 /** standard constructor prohibited */
123 AliHLTOUTLockGuard();
124 /** copy constructor prohibited */
125 AliHLTOUTLockGuard(const AliHLTOUTLockGuard&);
126 /** assignment operator prohibited */
127 AliHLTOUTLockGuard& operator=(const AliHLTOUTLockGuard&);
128
129 /** the AliHLTOUT instance the guard is locking */
130 AliHLTOUT* fpInstance; //!transient
131 };
132
133 /**
4b113031 134 * The HLT OUT Event Header.
135 * Defined between HLT and DAQ.
136 */
137 struct AliHLTOUTEventHeader {
138 /**Total length of the data in bytes, including HLT event header, excluding CDH. */
139 AliHLTUInt32_t fLength; //! see above
140 /** version of the header */
141 AliHLTUInt32_t fVersion; //! see above
142 /** event id */
143 AliHLTUInt64_t fEventID; //! see above
144 };
145
146 // definitions from ALICE internal notes ALICE-INT-2002-010 and
147 // ALICE-INT-2006-XXX
148 /** the 32bit word in the CDH containing the status flags */
149 static const unsigned char fgkCDHStatusWord; //! see above
150 /** start of the flags in word fgkCDHStatusWord */
151 static const unsigned char fgkCDHStatusFlagsOffset; //! see above
152 /** bit indicating HLT decision in the HLTOUT*/
153 static const unsigned char fgkCDHFlagsHLTDecision; //! see above
154 /** bit indicating HLT payload in the HLTOUT*/
155 static const unsigned char fgkCDHFlagsHLTPayload; //! see above
156
157 /**
4de7334f 158 * Block descriptor.
159 */
160 class AliHLTOUTBlockDescriptor {
161 public:
162 AliHLTOUTBlockDescriptor(AliHLTComponentDataType dt, AliHLTUInt32_t spec, AliHLTUInt32_t index)
163 : fDataType(dt), fSpecification(spec), fIndex(index) {};
164 ~AliHLTOUTBlockDescriptor() {}
165
166 operator AliHLTComponentDataType() const {return fDataType;}
167 operator AliHLTUInt32_t() const {return fSpecification;}
168 int operator==(AliHLTComponentDataType dt) const {return dt==fDataType;}
169 int operator==(AliHLTUInt32_t spec) const {return spec==fSpecification;}
170
171 AliHLTUInt32_t GetIndex() const {return fIndex;}
172 private:
173 /** data type of the block */
174 AliHLTComponentDataType fDataType; //!transient
175 /** data specification of the block */
176 AliHLTUInt32_t fSpecification; //!transient
177 /** index in the data stream */
178 AliHLTUInt32_t fIndex; //!transient
179 };
180
049b43b2 181 enum AliHLTOUTByteOrder_t {
182 /** no data block selected */
183 kInvalidByteOrder=-1,
184 kUnknownByteOrder=0,
185 kLittleEndian,
186 kBigEndian
187 };
188
189 enum AliHLTOUTDataType_t {
190 kUint64 = 0,
191 kUint32 = 1,
192 kUint16 = 2,
193 kUint8 = 3,
194 kDouble = 4,
195 kFloat = 5
196 };
197
198 /**
199 * Check byte order of selected block
200 */
201 AliHLTOUTByteOrder_t CheckByteOrder();
202
203 /**
204 * Check alignment of selected block
205 */
206 int CheckAlignment(AliHLTOUT::AliHLTOUTDataType_t type);
207
62bb3cd4 208 protected:
4de7334f 209 /**
210 * Add a block descriptor.
211 * This is done by the child classes generating the index. The AliHLTOUT
212 * object must be locked for index generation.
213 * @param desc the block descriptor
214 * @return 0 if success, -EPERM if access denied
215 */
216 int AddBlockDescriptor(const AliHLTOUTBlockDescriptor desc);
62bb3cd4 217
218 private:
219 /** copy constructor prohibited */
220 AliHLTOUT(const AliHLTOUT&);
221 /** assignment operator prohibited */
222 AliHLTOUT& operator=(const AliHLTOUT&);
223
4de7334f 224 /**
049b43b2 225 * Internal status flags
226 */
227 enum {
228 /** the HLTOUT object is locked with the current data block */
229 kLocked = 0x1,
230 /** childs can add block descriptors */
231 kCollecting = 0x2,
232 /** user of the data block has checked the byte order */
233 kByteOrderChecked = 0x4,
234 /** warning on byte order missmatch has been printed */
235 kByteOrderWarning = 0x8,
236 /** user of the data block has checked the alignment */
237 kAlignmentChecked = 0x10,
238 /** warning on alignment missmatch has been printed */
239 kAlignmentWarning = 0x20
240 };
241
5db0e774 242 class AliHLTOUTHandlerListEntry {
243 public:
244 AliHLTOUTHandlerListEntry(AliHLTOUTHandler* pHandler,
245 AliHLTModuleAgent::AliHLTOUTHandlerDesc& handlerDesc,
246 AliHLTModuleAgent* pAgent,
247 AliHLTUInt32_t index);
248
249 /** copy constructor for vector handling */
250 AliHLTOUTHandlerListEntry(const AliHLTOUTHandlerListEntry& src);
251
252 /** assignment operator for vector handling */
253 AliHLTOUTHandlerListEntry& operator=(const AliHLTOUTHandlerListEntry& src);
254
255 ~AliHLTOUTHandlerListEntry();
256
257 operator AliHLTOUTHandler*() const {return fpHandler;}
258 operator AliHLTModuleAgent::AliHLTOUTHandlerDesc&() {return fHandlerDesc;}
259 operator AliHLTModuleAgent*() const {return fpAgent;}
260
261 bool operator==(const AliHLTOUTHandlerListEntry& entry) const;
262
263 AliHLTUInt32_t operator[](int i) const;
264
265 void AddIndex(AliHLTUInt32_t index);
266
267 private:
268 /** standard constructor prohibited */
269 AliHLTOUTHandlerListEntry();
270
271 /** pointer to the handler */
272 AliHLTOUTHandler* fpHandler; //! transient
273
274 /** pointer to handler description */
04058ee9 275 AliHLTModuleAgent::AliHLTOUTHandlerDesc& fHandlerDesc; //! transient
5db0e774 276
277 /** pointer to module agent */
278 AliHLTModuleAgent* fpAgent; //! transient
279
280 /** list of block indexes */
281 AliHLTOUTIndexList fBlocks; //!transient
282 };
283
049b43b2 284 /**
4de7334f 285 * Generate the index of the HLTOUT data.
286 * Must be implemented by the child classes.
287 */
288 virtual int GenerateIndex()=0;
289
290 /**
5db0e774 291 * Find AliHLTOUTHandler objects for the data blocks.
292 * The available AliHLTModuleAgents are probed whether they provide
293 * handlers for data processing.
294 */
295 int InitHandlers();
296
297 /**
4de7334f 298 * Get the data buffer
299 * @param index [in] index of the block
300 * @param pBuffer [out] buffer of the selected data block
301 * @param size [out] size of the selected data block
302 */
303 virtual int GetDataBuffer(AliHLTUInt32_t index, const AliHLTUInt8_t* &pBuffer,
304 AliHLTUInt32_t& size)=0;
305
049b43b2 306 /**
307 * Check byte order of data block
308 */
309 virtual AliHLTOUTByteOrder_t CheckBlockByteOrder(AliHLTUInt32_t index)=0;
310
311 /**
312 * Check alignment of data block
313 */
314 virtual int CheckBlockAlignment(AliHLTUInt32_t index, AliHLTOUT::AliHLTOUTDataType_t type)=0;
315
316 /**
317 * Select the data block of data type and specification of the previous
318 * call to @ref SelectFirstDataBlock. Core function of @ref SelectFirstDataBlock
319 * and @ref SelectNextDataBlock, starts to find a block at the current list
320 * position.
321 * @return identifier >=0 if success, neg. error code if failed <br>
322 * -ENOENT if no block found <br>
323 * -EPERM if access denied (object locked)
324 */
325 int FindAndSelectDataBlock();
326
327 /**
328 * Set status flag.
329 * @param flag flag to set
330 * @return current status flags
331 */
332 unsigned int SetStatusFlag(unsigned int flag) {return fFlags|=flag;}
333
334 /**
335 * Clear status flag.
336 * @param flag flag to clear
337 * @return current status flags
338 */
339 unsigned int ClearStatusFlag(unsigned int flag) {return fFlags&=~flag;}
340
341 /**
342 * Check status flag.
343 * @param flag flag to check
344 * @return 1 if flag is set
345 */
346 int CheckStatusFlag(unsigned int flag) const {return (fFlags&flag)==flag;}
347
5db0e774 348 /**
349 * Insert a handler item.
350 * The current list entries are checked if the handler is already in
351 * the list. It is added if not in the list, otherwise the block index
352 * is added to the existing entry.
353 * @param entry handler list entry
354 * @return 0 if added, EEXIST (non negative!) if merged with existing entry <br>
355 * neg. error code if failed
356 */
357 int InsertHandler(const AliHLTOUTHandlerListEntry &entry);
358
4de7334f 359 /** data type for the current block search, set from @ref SelectFirstDataBlock */
360 AliHLTComponentDataType fSearchDataType; //!transient
361
362 /** data specification for the current block search */
363 AliHLTUInt32_t fSearchSpecification; //!transient
364
049b43b2 365 /** instance flags: locked, collecting, ... */
366 unsigned int fFlags; //!transient
4de7334f 367
368 /** list of block descriptors */
369 vector<AliHLTOUTBlockDescriptor> fBlockDescList; //!transient
370
371 /** current position in the list */
372 vector<AliHLTOUTBlockDescriptor>::iterator fCurrent; //!transient
373
374 /** data buffer under processing */
375 const AliHLTUInt8_t* fpBuffer; //!transient
376
5db0e774 377 /** list of AliHLTOUTHandlers */
378 vector<AliHLTOUTHandlerListEntry> fDataHandlers; // !transient
379
380 ClassDef(AliHLTOUT, 1)
62bb3cd4 381};
382#endif