online_distribution/eventlibraries/Cframe.h

0001 /*
0002 ** Cframe.h
0003 **
0004 ** Author: $Author: purschke $
0005 **   Date: $Date: 2000/07/21 01:51:10 $
0006 **
0007 ** $Log: Cframe.h,v $
0008 ** Revision 1.1.1.1  2000/07/21 01:51:10  purschke
0009 ** mlp -- adding the new automakified "basic" module to CVS.
0010 **
0011 **
0012 ** Revision 1.11  1999/05/17 20:47:24  markacs
0013 ** (stephen) last bit of addition of findNextError
0014 **
0015 ** Revision 1.10  1999/04/13 18:27:36  markacs
0016 ** (stephen) put history block access in
0017 **
0018 ** Revision 1.9  1998/12/17 15:23:01  phoncs
0019 ** (stephen markacs) OOPS, had a C++ type comment.
0020 **
0021 ** Revision 1.8  1998/12/17 15:18:16  phoncs
0022 ** (stephen markacs) more bounds checking in Cpacket.C (one instance) and removal of debugging comments from checkFrame.C
0023 **
0024 ** Revision 1.7  1998/12/16 15:40:51  markacs
0025 ** (stephen markacs) changes to rawFormat code to stop using bool,true,false
0026 **
0027 ** Revision 1.6  1998/12/11 22:01:09  markacs
0028 ** (stephen markacs) adding log into cvs tags
0029 **
0030 */
0031 /*
0032 ** Cframe.h
0033 **
0034 ** This file contains functions to access header fields.
0035 **
0036 ** The functions are named as follows:
0037 **
0038 **    get: return the value in the field
0039 **   find: return a pointer to the start of a block
0040 **    set: set the value in the field to a given value
0041 ** adjust: change some parameter (such as length) by some
0042 **           given value
0043 **  check: return true if something is valid
0044 **
0045 ** These are only general guides to what the functions do.
0046 **   There are small variations, such as getAlignBlock,
0047 **   which is passed a pointer to an area of memory to
0048 **   which it copies the alignment block.
0049 **
0050 **
0051 ** The fields are accessed through direct reading and
0052 **   writing of bits using offsets which are #defined.
0053 **   Fields which are a full PHDWORD (4 bytes) long are
0054 **   defined by a single value, the offset of the PHDWORD
0055 **   that comprises them.  The smaller fields have four
0056 **   #defined values:
0057 **
0058 ** 1.The offset of the PHDWORD the field is in
0059 **    (which word it is in)
0060 ** 2.The offset of the field in that PHDWORD
0061 **    (where it starts in that word)
0062 ** 3.The number of bits in the field
0063 **    (how big it is)
0064 ** 4.The mask used to pull out the field from its PHDWORD
0065 **    (put in by hand for optimization)
0066 **
0067 **
0068 ** The layout of this file is as follows:
0069 **
0070 ** (1) definition of field parameters (the offsets, etc.)
0071 ** (2) includes of phenixOnline.h, etc.
0072 ** (3) prototypes of functions defined later in this file
0073 **      and #defines of version-dependent function names to
0074 **      V1 function names (if in DCM mode)
0075 ** (4) include of CframeV1.h
0076 ** (5) generic functions
0077 ** (6) definition of indirection pointers and specific functions
0078 **      (if not in DCM mode)
0079 **
0080 **
0081 ** There are two types of routines in this file, those that
0082 **   work with fields whose configurations (offsets and size)
0083 **   are version-independent and those whose configurations
0084 **   are allowed to vary with version number.  Fields of the
0085 **   first type are operated on directly by routines in this
0086 **   file.  Version-dependent fields are accessed through
0087 **   an array of pointers to functions, those functions lying
0088 **   in their respective version files, such as "CframeV1.h".
0089 **   In DCM code, DCM is #defined, which causes the
0090 **   routines to access the version-dependent fields to be
0091 **   #defined directly to the corresponding function for the
0092 **   current version.
0093 **
0094 **
0095 ** There are a few compilation modes that are implemented in this
0096 **   file through #defining the appropriate name:
0097 **
0098 **         DCM: for compilation to the DCM; causes direct
0099 **              redefinition of functions names that access
0100 **              version-dependent fields to the names of the
0101 **              current version's corresponding functions
0102 **   DCM_CHECK: causes certain checks in low-level access routines
0103 **              to be skipped for optimization
0104 ** STRONGCHECK: causes some extra-careful checks to be added
0105 **
0106 **
0107 ** Nomenclature note:  The "end" of a frame, a data block, etc.,
0108 **   is taken to be the address of the LAST dword in the object,
0109 **   NOT one past the last dword in the object.
0110 **
0111 **
0112 */
0113
0114 #include <stdio.h>  /* DEBUG */
0115
0116 #ifndef _FRAMES_
0117 #define _FRAMES_
0118
0119 #ifdef __cplusplus
0120 extern "C" {
0121 #endif
0122
0123 #include "phenixOnline.h"
0124 #include "framePublic.h"
0125 #include "formatError.h"
0126 #include "frameHdr.h"
0127
0128   /* Version-INDEPENDENT functions' prototypes */
0129
0130   INLINE_P VALUE_ret getFrameHdrLength (FRAME_ptr);
0131   INLINE_P VALUE_ret getFrameHdrVersion (FRAME_ptr);
0132   INLINE_P VALUE_ret getFrameLength (FRAME_ptr);
0133   INLINE_P VALUE_ret getFrameMark (FRAME_ptr);
0134
0135   INLINE_P LOGIC_ret setFrameHdrLength(FRAME_ptr, UINT);
0136   INLINE_P LOGIC_ret setFrameHdrVersion(FRAME_ptr, UINT);
0137   INLINE_P LOGIC_ret setFrameLength(FRAME_ptr, UINT);
0138   INLINE_P LOGIC_ret setFrameMark(FRAME_ptr, UINT);
0139
0140   VALUE_ret checkFrameHdrVersion (FRAME_ptr);
0141
0142   INLINE_P LOGIC_ret validFrameHdr (FRAME_ptr);
0143   INLINE_P LOGIC_ret currentFrameHdr (FRAME_ptr);
0144   INLINE_P LOGIC_ret validFrameMark (FRAME_ptr);
0145   INLINE_P LOGIC_ret emptyFrame(FRAME_ptr);
0146
0147   VALUE_ret checkFrameEndianism(FRAME_ptr frame_ptr);
0148   INLINE_P void byteSwapFrame (FRAME_ptr frame_ptr);
0149
0150   PTR_ret findFrameEnd (FRAME_ptr);
0151   PTR_ret findFrameDataStart (FRAME_ptr);
0152   PTR_ret findFrameDataEnd (FRAME_ptr);
0153
0154   VALUE_ret adjustFrameLength (FRAME_ptr, UINT, UINT, LOGIC_ret);
0155   VALUE_ret removeFramePadding (FRAME_ptr);
0156
0157   /* Version-DEPENDENT functions' macro redirections or prototypes */
0158
0159 #ifdef DCM
0160
0161 #define makeFrameHdr makeFrameHdrV1
0162 #define getFrameDataLength getFrameDataLengthV1
0163 #define getFrameHistoryLength getFrameHistoryLengthV1
0164 #define getFrameErrorLength getFrameErrorLengthV1
0165 #define getFrameAlignLength getFrameAlignLengthV1
0166 #define getFrameSourceId getFrameSourceIdV1
0167 #define getFrameDataType getFrameDataTypeV1
0168 #define getFrameType getFrameTypeV1
0169 #define getFrameStatus getFrameStatusV1
0170 #define getFramePadding getFramePaddingV1
0171 #define setFramePadding setFramePaddingV1
0172 #define adjustFrameDataLength adjustFrameDataLengthV1
0173 #define adjustFrameHistoryLength adjustFrameHistoryLengthV1
0174 #define adjustframeErrorLength adjustFrameErrorlengthV1
0175 #define orFrameStatus orFrameStatusV1
0176 #define setDataType setDataTypeV1
0177 #define setFrameType setFrameTypeV1
0178 #define setSourceId setSourceIdV1
0179 #define setFrameHistoryLength setFrameHistoryLengthV1
0180 #define setFrameErrorLength setFrameErrorLengthV1
0181 #define setFrameAlignLength setFrameAlignLengthV1
0182 #define setFrameStatus setFrameStatusV1
0183 #define findFrameAlignBlock findFrameAlignBlockV1
0184 #define findFrameHistoryStart findFrameHistoryStartV1
0185 #define findFrameErrorStart findFrameErrorStartV1
0186 #define getAlignBlock getAlignBlockV1
0187 #define setAlignBlock setAlignBlockV1
0188 #define getHistoryEntry getHistoryEntryV1
0189 #define getHistoryStage getHistoryStageV1
0190 #define getHistorySourceIndex getHistorySourceIndexV1
0191 #define getHistoryStatus getHistoryStatusV1
0192 #define findNextError findNextErrorV1
0193
0194 #else
0195   VALUE_ret makeFrameHdr (FRAME_ptr, UINT, UINT, UINT, UINT);
0196   VALUE_ret getFrameDataLength (FRAME_ptr);
0197   VALUE_ret getFrameHistoryLength (FRAME_ptr);
0198   VALUE_ret getFrameErrorLength (FRAME_ptr);
0199   VALUE_ret getFrameAlignLength (FRAME_ptr);
0200
0201   VALUE_ret getFrameSourceId (FRAME_ptr);
0202   VALUE_ret getFrameDataType (FRAME_ptr);
0203   VALUE_ret getFrameType (FRAME_ptr);
0204   VALUE_ret getFrameStatus (FRAME_ptr);
0205   VALUE_ret getFramePadding (FRAME_ptr);
0206
0207   VALUE_ret setFramePadding (FRAME_ptr, UINT);
0208   VALUE_ret adjustFrameDataLength (FRAME_ptr, UINT);
0209   VALUE_ret adjustFrameHistoryLength (FRAME_ptr, UINT);
0210   VALUE_ret adjustFrameErrorLength (FRAME_ptr, UINT);
0211   VALUE_ret orFrameStatus (FRAME_ptr, UINT);
0212
0213   LOGIC_ret setDataType(FRAME_ptr, UINT);
0214   LOGIC_ret setFrameType(FRAME_ptr, UINT);
0215   LOGIC_ret setSourceId(FRAME_ptr, UINT);
0216   LOGIC_ret setFrameHistoryLength(FRAME_ptr, UINT);
0217   LOGIC_ret setFrameErrorLength(FRAME_ptr, UINT);
0218   LOGIC_ret setFrameAlignLength(FRAME_ptr, UINT);
0219   LOGIC_ret setFrameStatus(FRAME_ptr, UINT);
0220
0221   PTR_ret findFrameAlignBlock (FRAME_ptr);
0222   PTR_ret findFrameErrorStart (FRAME_ptr);
0223   PTR_ret findFrameHistoryStart (FRAME_ptr);
0224
0225   VALUE_ret getAlignBlock (FRAME_ptr, PHDWORD*, UINT);
0226   LOGIC_ret setAlignBlock (FRAME_ptr, PHDWORD*, UINT);
0227
0228   VALUE_ret getHistoryEntry(FRAME_ptr, UINT);
0229   VALUE_ret getHistoryStage(FRAME_ptr, UINT);
0230   VALUE_ret getHistorySourceIndex(FRAME_ptr, UINT);
0231   VALUE_ret getHistoryStatus(FRAME_ptr, UINT);
0232   PTR_ret findNextError(FRAME_ptr, FRAME_ptr);
0233
0234 #endif
0235 #ifdef __cplusplus
0236 }
0237 /* end of extern "C" */
0238 #endif
0239
0240
0241 /* Here begins the inlined code for the version-INDEPENDENT functions */
0242 /* ================================================================== */
0243
0244 /*  Return the length of the frame header
0245 */
0246 INLINE_D VALUE_ret getFrameHdrLength (FRAME_ptr frame_ptr)
0247 {
0248   UINT hdrLength = getBitsMACRO(frame_ptr,
0249                 FRAME_HDR_LENGTH_OFFSET_OF_DWORD,
0250                 FRAME_HDR_LENGTH_OFFSET_IN_DWORD,
0251                 FRAME_HDR_LENGTH_MASK        );
0252 #ifdef STRONGCHECK
0253   if (hdrLength == 0 || hdrLength > getFrameLength(frame_ptr)) {
0254     setFrameError(FORMAT_ERR_INVALID_HDRLENGTH, frame_ptr, length);
0255     return valueFailure;
0256   }
0257 #endif
0258   return hdrLength;
0259 }
0260
0261 /*  Return the version number of the frame. If enabled,
0262 **   check for invalid version.
0263 */
0264 INLINE_D VALUE_ret getFrameHdrVersion (FRAME_ptr frame_ptr)
0265 {
0266   UINT version = getBitsMACRO(frame_ptr,
0267                   FRAME_HDR_VERSION_OFFSET_OF_DWORD,
0268                   FRAME_HDR_VERSION_OFFSET_IN_DWORD,
0269                   FRAME_HDR_VERSION_MASK        );
0270     /*#ifdef STRONGCHECK */
0271   if ((version >= numFrameVersions)||(version==0))
0272   {
0273     setFrameError(FORMAT_ERR_INVALID_HDRVERSION, frame_ptr, version);
0274     return valueFailure;
0275   }
0276     /*#endif*/
0277   return version;
0278 }
0279
0280
0281 /*  Return the length of the frame. If enabled check for overflow.
0282 */
0283 INLINE_D VALUE_ret getFrameLength (FRAME_ptr frame_ptr)
0284 {
0285   PHDWORD length = getWordMACRO(frame_ptr, FRAME_LENGTH_OFFSET_OF_DWORD);
0286
0287 #ifdef STRONGCHECK
0288   if ((length&(1<<32))!=0) {
0289     setFrameError(FORMAT_ERR_LENGTH_OVERFLOW, frame_ptr, length);
0290     return valueFailure;
0291   }
0292 #endif
0293   return length;
0294 }
0295
0296 /*  Return the frame marker.
0297 */
0298 INLINE_D VALUE_ret getFrameMark (FRAME_ptr frame_ptr)
0299 {
0300   PHDWORD frameMark = getWordMACRO(frame_ptr, FRAME_MARK_OFFSET_OF_DWORD);
0301   return frameMark;
0302 }
0303
0304 /*  Store the length of the header in the header itself.
0305 */
0306 INLINE_D LOGIC_ret setFrameHdrLength (FRAME_ptr frame_ptr, UINT hdrLength)
0307 {
0308   setBitsMACRO(frame_ptr, FRAME_HDR_LENGTH_OFFSET_OF_DWORD,
0309            FRAME_HDR_LENGTH_OFFSET_IN_DWORD, FRAME_HDR_LENGTH_MASK,
0310            hdrLength);
0311   return TRUE;
0312 }
0313
0314 /*  Store the version of the header in the header itself
0315 */
0316 INLINE_D LOGIC_ret setFrameHdrVersion (FRAME_ptr frame_ptr, UINT hdrVersion)
0317 {
0318   setBitsMACRO(frame_ptr, FRAME_HDR_VERSION_OFFSET_OF_DWORD,
0319            FRAME_HDR_VERSION_OFFSET_IN_DWORD, FRAME_HDR_VERSION_MASK,
0320            hdrVersion);
0321   return TRUE;
0322 }
0323
0324 /*  Store the frame length in the header
0325 */
0326 INLINE_D LOGIC_ret setFrameLength (FRAME_ptr frame_ptr, UINT length) {
0327   setWordMACRO(frame_ptr,
0328            FRAME_LENGTH_OFFSET_OF_DWORD,
0329            length);
0330   return TRUE;
0331 }
0332
0333 /*  Store the frame marker in the header
0334 */
0335 INLINE_D LOGIC_ret setFrameMark (FRAME_ptr frame_ptr, UINT frameMark)
0336 {
0337   setWordMACRO(frame_ptr,
0338            FRAME_MARK_OFFSET_OF_DWORD,
0339            frameMark);
0340   return TRUE;
0341 }
0342
0343
0344 /*  Check for a valid frame header.
0345 */
0346 INLINE_D LOGIC_ret validFrameHdr (FRAME_ptr frame_ptr)
0347 {
0348   return (checkFrameHdrVersion(frame_ptr) != valueFailure);
0349 }
0350
0351 /*  Check to see if the frame header is of the current version.
0352 */
0353 INLINE_D LOGIC_ret currentFrameHdr (FRAME_ptr frame_ptr)
0354 {
0355   UINT version = getFrameHdrVersion (frame_ptr);
0356   return (version == currentFrameHdrVersion);
0357 }
0358
0359 /*  Check to see if the frame has a valid marker.
0360 */
0361 INLINE_D LOGIC_ret validFrameMark (FRAME_ptr frame_ptr) {
0362   UINT version = getFrameHdrVersion(frame_ptr);
0363   if (version != valueFailure)
0364     return (getFrameMark(frame_ptr) == frameMarkV[version]);
0365   else return FALSE;
0366 }
0367
0368
0369 /* Check to see if the frame is empty.
0370 **   Note that an "empty frame" consists of a header only. (No tailer)
0371 */
0372 INLINE_D LOGIC_ret emptyFrame (FRAME_ptr frame_ptr) {
0373   return (getFrameHdrLength(frame_ptr) == getFrameLength(frame_ptr));
0374 }
0375
0376 /*
0377 **  Byte-swap an entire frame using the (swapped) length stored in the first PHDWORD.
0378 **
0379 **  This routine assumes that the endianism has been determined to be wrong AND
0380 **    that the byte-swapped header satisfies a set of minimal validity tests.
0381 */
0382 INLINE_D void byteSwapFrame (FRAME_ptr frame_ptr)
0383 {
0384   PHDWORD correctLength = singleDwordByteSwap(*frame_ptr);
0385   dwordByteSwap(frame_ptr, frame_ptr, correctLength);
0386 }
0387
0388 /* ======================================================== */
0389 /* Here ends the code for the version-INDEPENDENT functions */
0390
0391
0392 #endif /* end of ifdef _FRAMES_ */
0393