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 
134 
139 
141 
146 
148  INLINE_P void byteSwapFrame (FRAME_ptr frame_ptr);
149 
153 
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
200 
206 
212 
220 
224 
227 
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 */
247 {
248  UINT hdrLength = getBitsMACRO(frame_ptr,
252 #ifdef STRONGCHECK
253  if (hdrLength == 0 || hdrLength > getFrameLength(frame_ptr)) {
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 */
265 {
266  UINT version = getBitsMACRO(frame_ptr,
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 */
284 {
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 */
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 */
307 {
310  hdrLength);
311  return TRUE;
312 }
313 
314 /* Store the version of the header in the header itself
315 */
317 {
320  hdrVersion);
321  return TRUE;
322 }
323 
324 /* Store the frame length in the header
325 */
327  setWordMACRO(frame_ptr,
329  length);
330  return TRUE;
331 }
332 
333 /* Store the frame marker in the header
334 */
336 {
337  setWordMACRO(frame_ptr,
339  frameMark);
340  return TRUE;
341 }
342 
343 
344 /* Check for a valid frame header.
345 */
347 {
348  return (checkFrameHdrVersion(frame_ptr) != valueFailure);
349 }
350 
351 /* Check to see if the frame header is of the current version.
352 */
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 */
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 */
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 */
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