Analysis Software
Documentation for sPHENIX simulation software
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Cframe.h
Go to the documentation of this file. Or view the newest version in sPHENIX GitHub for file Cframe.h
1 /*
2 ** Cframe.h
3 **
4 ** Author: $Author: purschke $
5 ** Date: $Date: 2000/07/21 01:51:10 $
6 **
7 ** $Log: Cframe.h,v $
8 ** Revision 1.1.1.1 2000/07/21 01:51:10 purschke
9 ** mlp -- adding the new automakified "basic" module to CVS.
10 **
11 **
12 ** Revision 1.11 1999/05/17 20:47:24 markacs
13 ** (stephen) last bit of addition of findNextError
14 **
15 ** Revision 1.10 1999/04/13 18:27:36 markacs
16 ** (stephen) put history block access in
17 **
18 ** Revision 1.9 1998/12/17 15:23:01 phoncs
19 ** (stephen markacs) OOPS, had a C++ type comment.
20 **
21 ** Revision 1.8 1998/12/17 15:18:16 phoncs
22 ** (stephen markacs) more bounds checking in Cpacket.C (one instance) and removal of debugging comments from checkFrame.C
23 **
24 ** Revision 1.7 1998/12/16 15:40:51 markacs
25 ** (stephen markacs) changes to rawFormat code to stop using bool,true,false
26 **
27 ** Revision 1.6 1998/12/11 22:01:09 markacs
28 ** (stephen markacs) adding log into cvs tags
29 **
30 */
31 /*
32 ** Cframe.h
33 **
34 ** This file contains functions to access header fields.
35 **
36 ** The functions are named as follows:
37 **
38 ** get: return the value in the field
39 ** find: return a pointer to the start of a block
40 ** set: set the value in the field to a given value
41 ** adjust: change some parameter (such as length) by some
42 ** given value
43 ** check: return true if something is valid
44 **
45 ** These are only general guides to what the functions do.
46 ** There are small variations, such as getAlignBlock,
47 ** which is passed a pointer to an area of memory to
48 ** which it copies the alignment block.
49 **
50 **
51 ** The fields are accessed through direct reading and
52 ** writing of bits using offsets which are #defined.
53 ** Fields which are a full PHDWORD (4 bytes) long are
54 ** defined by a single value, the offset of the PHDWORD
55 ** that comprises them. The smaller fields have four
56 ** #defined values:
57 **
58 ** 1.The offset of the PHDWORD the field is in
59 ** (which word it is in)
60 ** 2.The offset of the field in that PHDWORD
61 ** (where it starts in that word)
62 ** 3.The number of bits in the field
63 ** (how big it is)
64 ** 4.The mask used to pull out the field from its PHDWORD
65 ** (put in by hand for optimization)
66 **
67 **
68 ** The layout of this file is as follows:
69 **
70 ** (1) definition of field parameters (the offsets, etc.)
71 ** (2) includes of phenixOnline.h, etc.
72 ** (3) prototypes of functions defined later in this file
73 ** and #defines of version-dependent function names to
74 ** V1 function names (if in DCM mode)
75 ** (4) include of CframeV1.h
76 ** (5) generic functions
77 ** (6) definition of indirection pointers and specific functions
78 ** (if not in DCM mode)
79 **
80 **
81 ** There are two types of routines in this file, those that
82 ** work with fields whose configurations (offsets and size)
83 ** are version-independent and those whose configurations
84 ** are allowed to vary with version number. Fields of the
85 ** first type are operated on directly by routines in this
86 ** file. Version-dependent fields are accessed through
87 ** an array of pointers to functions, those functions lying
88 ** in their respective version files, such as "CframeV1.h".
89 ** In DCM code, DCM is #defined, which causes the
90 ** routines to access the version-dependent fields to be
91 ** #defined directly to the corresponding function for the
92 ** current version.
93 **
94 **
95 ** There are a few compilation modes that are implemented in this
96 ** file through #defining the appropriate name:
97 **
98 ** DCM: for compilation to the DCM; causes direct
99 ** redefinition of functions names that access
100 ** version-dependent fields to the names of the
101 ** current version's corresponding functions
102 ** DCM_CHECK: causes certain checks in low-level access routines
103 ** to be skipped for optimization
104 ** STRONGCHECK: causes some extra-careful checks to be added
105 **
106 **
107 ** Nomenclature note: The "end" of a frame, a data block, etc.,
108 ** is taken to be the address of the LAST dword in the object,
109 ** NOT one past the last dword in the object.
110 **
111 **
112 */
113 
114 #include <stdio.h> /* DEBUG */
115 
116 #ifndef _FRAMES_
117 #define _FRAMES_
118 
119 #ifdef __cplusplus
120 extern "C" {
121 #endif
122 
123 #include "phenixOnline.h"
124 #include "framePublic.h"
125 #include "formatError.h"
126 #include "frameHdr.h"
127 
128  /* Version-INDEPENDENT functions' prototypes */
129 
130  INLINE_P VALUE_ret getFrameHdrLength (FRAME_ptr);
131  INLINE_P VALUE_ret getFrameHdrVersion (FRAME_ptr);
132  INLINE_P VALUE_ret getFrameLength (FRAME_ptr);
133  INLINE_P VALUE_ret getFrameMark (FRAME_ptr);
134 
135  INLINE_P LOGIC_ret setFrameHdrLength(FRAME_ptr, UINT);
136  INLINE_P LOGIC_ret setFrameHdrVersion(FRAME_ptr, UINT);
137  INLINE_P LOGIC_ret setFrameLength(FRAME_ptr, UINT);
138  INLINE_P LOGIC_ret setFrameMark(FRAME_ptr, UINT);
139 
140  VALUE_ret checkFrameHdrVersion (FRAME_ptr);
141 
142  INLINE_P LOGIC_ret validFrameHdr (FRAME_ptr);
143  INLINE_P LOGIC_ret currentFrameHdr (FRAME_ptr);
144  INLINE_P LOGIC_ret validFrameMark (FRAME_ptr);
145  INLINE_P LOGIC_ret emptyFrame(FRAME_ptr);
146 
147  VALUE_ret checkFrameEndianism(FRAME_ptr frame_ptr);
148  INLINE_P void byteSwapFrame (FRAME_ptr frame_ptr);
149 
150  PTR_ret findFrameEnd (FRAME_ptr);
151  PTR_ret findFrameDataStart (FRAME_ptr);
152  PTR_ret findFrameDataEnd (FRAME_ptr);
153 
154  VALUE_ret adjustFrameLength (FRAME_ptr, UINT, UINT, LOGIC_ret);
155  VALUE_ret removeFramePadding (FRAME_ptr);
156 
157  /* Version-DEPENDENT functions' macro redirections or prototypes */
158 
159 #ifdef DCM
160 
161 #define makeFrameHdr makeFrameHdrV1
162 #define getFrameDataLength getFrameDataLengthV1
163 #define getFrameHistoryLength getFrameHistoryLengthV1
164 #define getFrameErrorLength getFrameErrorLengthV1
165 #define getFrameAlignLength getFrameAlignLengthV1
166 #define getFrameSourceId getFrameSourceIdV1
167 #define getFrameDataType getFrameDataTypeV1
168 #define getFrameType getFrameTypeV1
169 #define getFrameStatus getFrameStatusV1
170 #define getFramePadding getFramePaddingV1
171 #define setFramePadding setFramePaddingV1
172 #define adjustFrameDataLength adjustFrameDataLengthV1
173 #define adjustFrameHistoryLength adjustFrameHistoryLengthV1
174 #define adjustframeErrorLength adjustFrameErrorlengthV1
175 #define orFrameStatus orFrameStatusV1
176 #define setDataType setDataTypeV1
177 #define setFrameType setFrameTypeV1
178 #define setSourceId setSourceIdV1
179 #define setFrameHistoryLength setFrameHistoryLengthV1
180 #define setFrameErrorLength setFrameErrorLengthV1
181 #define setFrameAlignLength setFrameAlignLengthV1
182 #define setFrameStatus setFrameStatusV1
183 #define findFrameAlignBlock findFrameAlignBlockV1
184 #define findFrameHistoryStart findFrameHistoryStartV1
185 #define findFrameErrorStart findFrameErrorStartV1
186 #define getAlignBlock getAlignBlockV1
187 #define setAlignBlock setAlignBlockV1
188 #define getHistoryEntry getHistoryEntryV1
189 #define getHistoryStage getHistoryStageV1
190 #define getHistorySourceIndex getHistorySourceIndexV1
191 #define getHistoryStatus getHistoryStatusV1
192 #define findNextError findNextErrorV1
193 
194 #else
195  VALUE_ret makeFrameHdr (FRAME_ptr, UINT, UINT, UINT, UINT);
196  VALUE_ret getFrameDataLength (FRAME_ptr);
197  VALUE_ret getFrameHistoryLength (FRAME_ptr);
198  VALUE_ret getFrameErrorLength (FRAME_ptr);
199  VALUE_ret getFrameAlignLength (FRAME_ptr);
200 
201  VALUE_ret getFrameSourceId (FRAME_ptr);
202  VALUE_ret getFrameDataType (FRAME_ptr);
203  VALUE_ret getFrameType (FRAME_ptr);
204  VALUE_ret getFrameStatus (FRAME_ptr);
205  VALUE_ret getFramePadding (FRAME_ptr);
206 
207  VALUE_ret setFramePadding (FRAME_ptr, UINT);
208  VALUE_ret adjustFrameDataLength (FRAME_ptr, UINT);
209  VALUE_ret adjustFrameHistoryLength (FRAME_ptr, UINT);
210  VALUE_ret adjustFrameErrorLength (FRAME_ptr, UINT);
211  VALUE_ret orFrameStatus (FRAME_ptr, UINT);
212 
213  LOGIC_ret setDataType(FRAME_ptr, UINT);
214  LOGIC_ret setFrameType(FRAME_ptr, UINT);
215  LOGIC_ret setSourceId(FRAME_ptr, UINT);
216  LOGIC_ret setFrameHistoryLength(FRAME_ptr, UINT);
217  LOGIC_ret setFrameErrorLength(FRAME_ptr, UINT);
218  LOGIC_ret setFrameAlignLength(FRAME_ptr, UINT);
219  LOGIC_ret setFrameStatus(FRAME_ptr, UINT);
220 
221  PTR_ret findFrameAlignBlock (FRAME_ptr);
222  PTR_ret findFrameErrorStart (FRAME_ptr);
223  PTR_ret findFrameHistoryStart (FRAME_ptr);
224 
225  VALUE_ret getAlignBlock (FRAME_ptr, PHDWORD*, UINT);
226  LOGIC_ret setAlignBlock (FRAME_ptr, PHDWORD*, UINT);
227 
228  VALUE_ret getHistoryEntry(FRAME_ptr, UINT);
229  VALUE_ret getHistoryStage(FRAME_ptr, UINT);
230  VALUE_ret getHistorySourceIndex(FRAME_ptr, UINT);
231  VALUE_ret getHistoryStatus(FRAME_ptr, UINT);
232  PTR_ret findNextError(FRAME_ptr, FRAME_ptr);
233 
234 #endif
235 #ifdef __cplusplus
236 }
237 /* end of extern "C" */
238 #endif
239 
240 
241 /* Here begins the inlined code for the version-INDEPENDENT functions */
242 /* ================================================================== */
243 
244 /* Return the length of the frame header
245 */
246 INLINE_D VALUE_ret getFrameHdrLength (FRAME_ptr frame_ptr)
247 {
248  UINT hdrLength = getBitsMACRO(frame_ptr,
249  FRAME_HDR_LENGTH_OFFSET_OF_DWORD,
250  FRAME_HDR_LENGTH_OFFSET_IN_DWORD,
251  FRAME_HDR_LENGTH_MASK );
252 #ifdef STRONGCHECK
253  if (hdrLength == 0 || hdrLength > getFrameLength(frame_ptr)) {
254  setFrameError(FORMAT_ERR_INVALID_HDRLENGTH, frame_ptr, length);
255  return valueFailure;
256  }
257 #endif
258  return hdrLength;
259 }
260 
261 /* Return the version number of the frame. If enabled,
262 ** check for invalid version.
263 */
264 INLINE_D VALUE_ret getFrameHdrVersion (FRAME_ptr frame_ptr)
265 {
266  UINT version = getBitsMACRO(frame_ptr,
267  FRAME_HDR_VERSION_OFFSET_OF_DWORD,
268  FRAME_HDR_VERSION_OFFSET_IN_DWORD,
269  FRAME_HDR_VERSION_MASK );
270  /*#ifdef STRONGCHECK */
271  if ((version >= numFrameVersions)||(version==0))
272  {
273  setFrameError(FORMAT_ERR_INVALID_HDRVERSION, frame_ptr, version);
274  return valueFailure;
275  }
276  /*#endif*/
277  return version;
278 }
279 
280 
281 /* Return the length of the frame. If enabled check for overflow.
282 */
283 INLINE_D VALUE_ret getFrameLength (FRAME_ptr frame_ptr)
284 {
285  PHDWORD length = getWordMACRO(frame_ptr, FRAME_LENGTH_OFFSET_OF_DWORD);
286 
287 #ifdef STRONGCHECK
288  if ((length&(1<<32))!=0) {
289  setFrameError(FORMAT_ERR_LENGTH_OVERFLOW, frame_ptr, length);
290  return valueFailure;
291  }
292 #endif
293  return length;
294 }
295 
296 /* Return the frame marker.
297 */
298 INLINE_D VALUE_ret getFrameMark (FRAME_ptr frame_ptr)
299 {
300  PHDWORD frameMark = getWordMACRO(frame_ptr, FRAME_MARK_OFFSET_OF_DWORD);
301  return frameMark;
302 }
303 
304 /* Store the length of the header in the header itself.
305 */
306 INLINE_D LOGIC_ret setFrameHdrLength (FRAME_ptr frame_ptr, UINT hdrLength)
307 {
308  setBitsMACRO(frame_ptr, FRAME_HDR_LENGTH_OFFSET_OF_DWORD,
309  FRAME_HDR_LENGTH_OFFSET_IN_DWORD, FRAME_HDR_LENGTH_MASK,
310  hdrLength);
311  return TRUE;
312 }
313 
314 /* Store the version of the header in the header itself
315 */
316 INLINE_D LOGIC_ret setFrameHdrVersion (FRAME_ptr frame_ptr, UINT hdrVersion)
317 {
318  setBitsMACRO(frame_ptr, FRAME_HDR_VERSION_OFFSET_OF_DWORD,
319  FRAME_HDR_VERSION_OFFSET_IN_DWORD, FRAME_HDR_VERSION_MASK,
320  hdrVersion);
321  return TRUE;
322 }
323 
324 /* Store the frame length in the header
325 */
326 INLINE_D LOGIC_ret setFrameLength (FRAME_ptr frame_ptr, UINT length) {
327  setWordMACRO(frame_ptr,
328  FRAME_LENGTH_OFFSET_OF_DWORD,
329  length);
330  return TRUE;
331 }
332 
333 /* Store the frame marker in the header
334 */
335 INLINE_D LOGIC_ret setFrameMark (FRAME_ptr frame_ptr, UINT frameMark)
336 {
337  setWordMACRO(frame_ptr,
338  FRAME_MARK_OFFSET_OF_DWORD,
339  frameMark);
340  return TRUE;
341 }
342 
343 
344 /* Check for a valid frame header.
345 */
346 INLINE_D LOGIC_ret validFrameHdr (FRAME_ptr frame_ptr)
347 {
348  return (checkFrameHdrVersion(frame_ptr) != valueFailure);
349 }
350 
351 /* Check to see if the frame header is of the current version.
352 */
353 INLINE_D LOGIC_ret currentFrameHdr (FRAME_ptr frame_ptr)
354 {
355  UINT version = getFrameHdrVersion (frame_ptr);
356  return (version == currentFrameHdrVersion);
357 }
358 
359 /* Check to see if the frame has a valid marker.
360 */
361 INLINE_D LOGIC_ret validFrameMark (FRAME_ptr frame_ptr) {
362  UINT version = getFrameHdrVersion(frame_ptr);
363  if (version != valueFailure)
364  return (getFrameMark(frame_ptr) == frameMarkV[version]);
365  else return FALSE;
366 }
367 
368 
369 /* Check to see if the frame is empty.
370 ** Note that an "empty frame" consists of a header only. (No tailer)
371 */
372 INLINE_D LOGIC_ret emptyFrame (FRAME_ptr frame_ptr) {
373  return (getFrameHdrLength(frame_ptr) == getFrameLength(frame_ptr));
374 }
375 
376 /*
377 ** Byte-swap an entire frame using the (swapped) length stored in the first PHDWORD.
378 **
379 ** This routine assumes that the endianism has been determined to be wrong AND
380 ** that the byte-swapped header satisfies a set of minimal validity tests.
381 */
382 INLINE_D void byteSwapFrame (FRAME_ptr frame_ptr)
383 {
384  PHDWORD correctLength = singleDwordByteSwap(*frame_ptr);
385  dwordByteSwap(frame_ptr, frame_ptr, correctLength);
386 }
387 
388 /* ======================================================== */
389 /* Here ends the code for the version-INDEPENDENT functions */
390 
391 
392 #endif /* end of ifdef _FRAMES_ */
393