Appendix A. Format of Ring bufffer DAQ event files

This information is provided for people who want to write programs to analyze event files written by the RingDaq. This appendix consists mostly of an annotated version of DataFormat.h in the include directory of a RingDaq installation.

RingDaq event files consist of a stream of items Each item has a header that consists of a 32 bit byte count (not word count), and a 32 bit type code for the item. Immediately following the header is the item payload. The type code must have the most significant 16 bits set to 0 this allows you to determine the endian-ness of the data by looking at which word of the type code is non-zero.

The count (which may have to be byte swapped if the type code indicates the byte order of the generating system is different than analyzing system), is self inclusive. Items can therefore be easily skipped.

32767 Types are reserved for use by the RingDaq software while the remaining 32767 types can bge used by user applications with special needs.

DataTypes.h defines the type fields as follows:

// state change item type codes:

static const uint32_t BEGIN_RUN(1);
static const uint32_t END_RUN(2);
static const uint32_t PAUSE_RUN(3);
static const uint32_t RESUME_RUN(4);

// Documentation item type codes:

static const uint32_t PACKET_TYPES(10);
static const uint32_t MONITORED_VARIABLES(11);

// Scaler data:

static const uint32_t INCREMENTAL_SCALERS(20);

// Physics events:

static const uint32_t PHYSICS_EVENT(30);
static const uint32_t PHYSICS_EVENT_COUNT(31);

// User defined item codes

static const uint32_t FIRST_USER_ITEM_CODE(32768); /* 0x8000 */
            

The payload structure descriptions will provide further information about the meaning of each of these type codes.

The structs below provide definitions used by RingDaq for both the item headers and a generic item:

typedef struct _RingItemHeader {
  uint32_t     s_size;
  uint32_t     s_type;
} RingItemHeader, *pRingItemHeader;


typedef struct _RingItem {
  RingItemHeader s_header;
  uint8_t        s_body[1];
} RingItem, *pRingItem;

        

Normally if you get a RingItem or pRingItem you will cast it to one of the specific ring item types described below. Doing that will provide a detailed break out of the payload.

Run state changes are documented by inserting state change items that have the structure shown below. These have types that are one of BEGIN_RUN, END_RUN, PAUSE_RUN or RESUME_RUN. If you receive a pointer to an item of this sort and cast it to a pStateChangeItem, you'll be able to acces the payload fields.

typedef struct _StateChangeItem {
  RingItemHeader  s_header;
  uint32_t        s_runNumber;
  uint32_t        s_timeOffset;
  time_t          s_Timestamp;
  char            s_title[TITLE_MAXSIZE+1];
} StateChangeItem, *pStateChangeItem;
        

RingDaq periodically reads scaler data. These result in ring items of type INCREMENTAL_SCALARS. The shape of this ring item is shown below:

typedef struct _ScalerItem {
  RingItemHeader  s_header;
  uint32_t        s_intervalStartOffset;
  uint32_t        s_intervalEndOffset;
  time_t          s_timestamp;
  uint32_t        s_scalerCount;
  uint32_t        s_scalers[1];
} ScalerItem, *pScalerItem;
        

Two item types have a payload which is just an array of null terminated strings. The contents of these strings depends on the actual item type. These ares stored in TextItem items. The meaning and contents of each string depends on the item type.

The complete format of the TextItem ring item is:

typedef struct _TextItem {
  RingItemHeader s_header;
  uint32_t       s_timeOffset;
  time_t         s_timestamp;
  uint32_t       s_stringCount;
  char           s_strings[1];
} TextItem, *pTextItem;
        

Each trigger produces a PHYSICS_EVENT item. The format of the event is assumed to be completely up to the readout framework (it is envisioned that in the future there will be other readout frameworks available). The PhysicsEventItem, therefore is identical in shape to the RingItem:

typedef struct _PhysicsEventItem {
  RingItemHeader s_header;
  uint16_t       s_body[1];
} PhysicsEventItem, *pPhysicsEventItem;
        

From time to time a PhysicsEventCount item is emitted. This item allows the data rate to be easily computed (accepted triggers/sec). It also allows sampling consumers such as SpecTcl to compute the fraction of the data they have analyzed. These items are of type PHYSICS_EVENT_COUNT and have the following shape:

typedef struct __PhysicsEventCountItem {
  RingItemHeader s_header;
  uint32_t       s_timeOffset;
  time_t         s_timestamp;
  uint64_t       s_eventCount;  /* Maybe 4Gevents is too small ;-) */
} PhysicsEventCountItem, *pPhysicsEventCountItem;