documentation and cleanup
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTOUT.h
CommitLineData
62bb3cd4 1//-*- Mode: C++ -*-
2// @(#) $Id$
3
4#ifndef ALIHLTOUT_H
5#define ALIHLTOUT_H
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 */
9
10/** @file AliHLTOUT.h
11 @author Matthias Richter
12 @date
13 @brief The control class for HLTOUT data.
14
15// see below for class documentation
16// or
17// refer to README to build package
18// or
19// visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
4de7334f 20
62bb3cd4 21 */
4de7334f 22#include <vector>
62bb3cd4 23#include "AliHLTLogging.h"
24
25/**
26 * @class AliHLTOUT
27 * The control class for HLTOUT data.
28 * The output of the HLT, either from the HLTOUT nodes or simulated output,
29 * is transferred and stored in the HOMER format. The AliHLTOUT class
30 * implements scanning of the HOMER data for all HLTOUT DDL links and
31 * abstracts access to the complete HLTOUT data.
32 *
33 */
34class AliHLTOUT : public AliHLTLogging {
35 public:
36 /** standard constructor */
37 AliHLTOUT();
38 /** standard destructor */
39 virtual ~AliHLTOUT();
40
4de7334f 41 /**
42 * Get number of data blocks in the HLTOUT data
43 */
44 int GetNofDataBlocks();
45
46 /**
47 * Select the first data block of a certain data type and specification.
48 * The selection criteria can be of kAliHLTAnyDataType and/or
49 * kAliHLTVoidDataSpec in order to be ignored and just match any data block.
50 * @param dt [in] data type to match <br>
51 * @param spec [in] data specification to match <br>
52 * @return identifier >=0 if success, neg. error code if failed <br>
53 * -ENOENT if no block found <br>
54 * -EPERM if access denied (object locked)
55 */
56 int SelectFirstDataBlock(AliHLTComponentDataType dt, AliHLTUInt32_t spec);
57
58 /**
59 * Select the next data block of data type and specification of the previous
60 * call to @ref SelectFirstDataBlock.
61 * @return identifier >=0 if success, neg. error code if failed <br>
62 * -ENOENT if no block found <br>
63 * -EPERM if access denied (object locked)
64 */
65 int SelectNextDataBlock();
66
67 /**
68 * Get properties of the selected data block.
69 * @param dt [out] data type of the selected block
70 * @param spec [out] data specification of the selected block
71 */
72 int GetDataBlockDescription(AliHLTComponentDataType& dt, AliHLTUInt32_t& spec);
73
74 /**
75 * Get buffer of the selected data block.
76 * @param pBuffer [out] buffer of the selected data block
77 * @param size [out] size of the selected data block
78 */
79 int GetDataBuffer(const AliHLTUInt8_t* &pBuffer, AliHLTUInt32_t& size);
80
81 /**
82 * Release buffer after use.
83 * @param pBuffer [in] buffer of the selected data block
84 */
85 int ReleaseDataBuffer(const AliHLTUInt8_t* pBuffer);
86
87 /**
88 * Locking guard for the AliHLTOUT object.
89 * If the object is locked, the selection of data blocks can not be changed.
90 */
91 class AliHLTOUTLockGuard {
92 public:
93 /** constructor */
94 AliHLTOUTLockGuard(AliHLTOUT* pInstance) : fpInstance(pInstance)
049b43b2 95 {if (fpInstance) fpInstance->SetStatusFlag(kLocked);}
4de7334f 96 /** destructor */
97 ~AliHLTOUTLockGuard()
049b43b2 98 {if (fpInstance) fpInstance->ClearStatusFlag(kLocked);}
4de7334f 99
100 private:
101 /** standard constructor prohibited */
102 AliHLTOUTLockGuard();
103 /** copy constructor prohibited */
104 AliHLTOUTLockGuard(const AliHLTOUTLockGuard&);
105 /** assignment operator prohibited */
106 AliHLTOUTLockGuard& operator=(const AliHLTOUTLockGuard&);
107
108 /** the AliHLTOUT instance the guard is locking */
109 AliHLTOUT* fpInstance; //!transient
110 };
111
112 /**
4b113031 113 * The HLT OUT Event Header.
114 * Defined between HLT and DAQ.
115 */
116 struct AliHLTOUTEventHeader {
117 /**Total length of the data in bytes, including HLT event header, excluding CDH. */
118 AliHLTUInt32_t fLength; //! see above
119 /** version of the header */
120 AliHLTUInt32_t fVersion; //! see above
121 /** event id */
122 AliHLTUInt64_t fEventID; //! see above
123 };
124
125 // definitions from ALICE internal notes ALICE-INT-2002-010 and
126 // ALICE-INT-2006-XXX
127 /** the 32bit word in the CDH containing the status flags */
128 static const unsigned char fgkCDHStatusWord; //! see above
129 /** start of the flags in word fgkCDHStatusWord */
130 static const unsigned char fgkCDHStatusFlagsOffset; //! see above
131 /** bit indicating HLT decision in the HLTOUT*/
132 static const unsigned char fgkCDHFlagsHLTDecision; //! see above
133 /** bit indicating HLT payload in the HLTOUT*/
134 static const unsigned char fgkCDHFlagsHLTPayload; //! see above
135
136 /**
4de7334f 137 * Block descriptor.
138 */
139 class AliHLTOUTBlockDescriptor {
140 public:
141 AliHLTOUTBlockDescriptor(AliHLTComponentDataType dt, AliHLTUInt32_t spec, AliHLTUInt32_t index)
142 : fDataType(dt), fSpecification(spec), fIndex(index) {};
143 ~AliHLTOUTBlockDescriptor() {}
144
145 operator AliHLTComponentDataType() const {return fDataType;}
146 operator AliHLTUInt32_t() const {return fSpecification;}
147 int operator==(AliHLTComponentDataType dt) const {return dt==fDataType;}
148 int operator==(AliHLTUInt32_t spec) const {return spec==fSpecification;}
149
150 AliHLTUInt32_t GetIndex() const {return fIndex;}
151 private:
152 /** data type of the block */
153 AliHLTComponentDataType fDataType; //!transient
154 /** data specification of the block */
155 AliHLTUInt32_t fSpecification; //!transient
156 /** index in the data stream */
157 AliHLTUInt32_t fIndex; //!transient
158 };
159
049b43b2 160 enum AliHLTOUTByteOrder_t {
161 /** no data block selected */
162 kInvalidByteOrder=-1,
163 kUnknownByteOrder=0,
164 kLittleEndian,
165 kBigEndian
166 };
167
168 enum AliHLTOUTDataType_t {
169 kUint64 = 0,
170 kUint32 = 1,
171 kUint16 = 2,
172 kUint8 = 3,
173 kDouble = 4,
174 kFloat = 5
175 };
176
177 /**
178 * Check byte order of selected block
179 */
180 AliHLTOUTByteOrder_t CheckByteOrder();
181
182 /**
183 * Check alignment of selected block
184 */
185 int CheckAlignment(AliHLTOUT::AliHLTOUTDataType_t type);
186
62bb3cd4 187 protected:
4de7334f 188 /**
189 * Add a block descriptor.
190 * This is done by the child classes generating the index. The AliHLTOUT
191 * object must be locked for index generation.
192 * @param desc the block descriptor
193 * @return 0 if success, -EPERM if access denied
194 */
195 int AddBlockDescriptor(const AliHLTOUTBlockDescriptor desc);
62bb3cd4 196
197 private:
198 /** copy constructor prohibited */
199 AliHLTOUT(const AliHLTOUT&);
200 /** assignment operator prohibited */
201 AliHLTOUT& operator=(const AliHLTOUT&);
202
4de7334f 203 /**
049b43b2 204 * Internal status flags
205 */
206 enum {
207 /** the HLTOUT object is locked with the current data block */
208 kLocked = 0x1,
209 /** childs can add block descriptors */
210 kCollecting = 0x2,
211 /** user of the data block has checked the byte order */
212 kByteOrderChecked = 0x4,
213 /** warning on byte order missmatch has been printed */
214 kByteOrderWarning = 0x8,
215 /** user of the data block has checked the alignment */
216 kAlignmentChecked = 0x10,
217 /** warning on alignment missmatch has been printed */
218 kAlignmentWarning = 0x20
219 };
220
221 /**
4de7334f 222 * Generate the index of the HLTOUT data.
223 * Must be implemented by the child classes.
224 */
225 virtual int GenerateIndex()=0;
226
227 /**
228 * Get the data buffer
229 * @param index [in] index of the block
230 * @param pBuffer [out] buffer of the selected data block
231 * @param size [out] size of the selected data block
232 */
233 virtual int GetDataBuffer(AliHLTUInt32_t index, const AliHLTUInt8_t* &pBuffer,
234 AliHLTUInt32_t& size)=0;
235
049b43b2 236 /**
237 * Check byte order of data block
238 */
239 virtual AliHLTOUTByteOrder_t CheckBlockByteOrder(AliHLTUInt32_t index)=0;
240
241 /**
242 * Check alignment of data block
243 */
244 virtual int CheckBlockAlignment(AliHLTUInt32_t index, AliHLTOUT::AliHLTOUTDataType_t type)=0;
245
246 /**
247 * Select the data block of data type and specification of the previous
248 * call to @ref SelectFirstDataBlock. Core function of @ref SelectFirstDataBlock
249 * and @ref SelectNextDataBlock, starts to find a block at the current list
250 * position.
251 * @return identifier >=0 if success, neg. error code if failed <br>
252 * -ENOENT if no block found <br>
253 * -EPERM if access denied (object locked)
254 */
255 int FindAndSelectDataBlock();
256
257 /**
258 * Set status flag.
259 * @param flag flag to set
260 * @return current status flags
261 */
262 unsigned int SetStatusFlag(unsigned int flag) {return fFlags|=flag;}
263
264 /**
265 * Clear status flag.
266 * @param flag flag to clear
267 * @return current status flags
268 */
269 unsigned int ClearStatusFlag(unsigned int flag) {return fFlags&=~flag;}
270
271 /**
272 * Check status flag.
273 * @param flag flag to check
274 * @return 1 if flag is set
275 */
276 int CheckStatusFlag(unsigned int flag) const {return (fFlags&flag)==flag;}
277
4de7334f 278 /** data type for the current block search, set from @ref SelectFirstDataBlock */
279 AliHLTComponentDataType fSearchDataType; //!transient
280
281 /** data specification for the current block search */
282 AliHLTUInt32_t fSearchSpecification; //!transient
283
049b43b2 284 /** instance flags: locked, collecting, ... */
285 unsigned int fFlags; //!transient
4de7334f 286
287 /** list of block descriptors */
288 vector<AliHLTOUTBlockDescriptor> fBlockDescList; //!transient
289
290 /** current position in the list */
291 vector<AliHLTOUTBlockDescriptor>::iterator fCurrent; //!transient
292
293 /** data buffer under processing */
294 const AliHLTUInt8_t* fpBuffer; //!transient
295
62bb3cd4 296 ClassDef(AliHLTOUT, 0)
297};
298#endif