DataFormat.h

RingItemHeader

This structure appears at beginning of each ring item. The type pRingItemHeader represents a pointer to a RingItemHeader. RingItemHeader structs contain the following fields:

BodyHeader

Contains data about the event as a fragment of a larger event. The type pBodyHeader represents a pointer to this type.

The body header has the following fiels:

RingItem

This is a generic ring item. The type pRingItem defines a pointer to a ring item. This item has the following structure:

typedef struct _RingItem {
  RingItemHeader s_header;
  union {
    struct {
      uint32_t s_mbz;
      uint8_t  s_body[1];
    } u_noBodyHeader;
    struct {
        BodyHeader s_bodyHeader;
        uint8_t s_body[];
    } u_hasBodyHeader;
  } s_body;
} RingItem, *pRingItem;
                

The s_header is the RingItemHeader decribed above. The union that follows provides support for ring items that have (u_hasBodyHeader) and do not have (u_noBodyHeader) body headers.

The s_mbz field is zero indicating that the item has not body header.

The s_bodyHeader is the full body header.

In both branches of the union, the field s_body is where the actual payload (body) of the ring item actually is.

StateChangeItem

These contain information about a run state change. They have the following form:

typedef struct _StateChangeItem  {
    RingItemHeader s_header;
    union {
        struct {
            uint32_t            s_mbz;       /* Must be zero - no body header*/
            StateChangeItemBody s_body;
        } u_noBodyHeader;
        struct {
            BodyHeader          s_bodyHeader;
            StateChangeItemBody s_body;
        } u_hasBodyHeader;
    } s_body;
    
} StateChangeItem, *pStateChangeItem;
                

As you can see this is a union whose inner struture depends on whether or not there is a body header (u_hasBodyHeader) or not (u_noBodyHeader). You can tell which version of the union to use by examining the s_mbz field. If this is zero use u_noBodyHeader otherwise use u_hasBodyHeader

The s_header field is the ring item header. If there is a Body header is is s_bodyHeader

Regardless of which branch of the union you select, the payload of the ring item is a StateChangeItemBody in s_body which has the following structure:

typedef struct _StateChangeItemBody {
  uint32_t        s_runNumber;
  uint32_t        s_timeOffset;
  uint32_t        s_Timestamp;
  uint32_t        s_offsetDivisor;
  char            s_title[TITLE_MAXSIZE+1];
} StateChangeItemBody, *pStateChangeItemBody;
                

s_runNumber is the number of the run that is undergoig a transition. s_timeoffset together with s_offsetDivisor determine when relative to the start of the run this state change occured. s_timeoffset is a time offset in unites of 1/s_offsetDivisor seconds.

The unix time_t for the absolute time at which this occured is truncated to 32 bits and stored in s_Timestamp (note that on 64 bit systems time_t is 64 bits but on 32 bit systems 32 bits making it intrinsically non-portable). This 32 bit time is good into the year 2038. s_offsetDivisor stores the units of s_Timestamp in 1/seconds. Thus s_Timestamp/s_offsetDivisor is the offset in to the run in floating point seconds (floating point values are also not as portable as fixed length integers).

s_title is the run title. The title string is a null terminated string at most TITLE_MAXSIZE non null characters long. The additional char allocated ensures the title has a null terminator. See CONSTANTS below for more information about TITLE_MAXSIZE.

ScalerItem

The ScalerItem item contains a set of periodically read scaler items. Starting in NSCLDAQ-11.0 these may or may not be incremental and may have interval start/stop time values that have a sub-second resolution.

As with most ring item data, the actual structure of this is represented as a union:

typedef struct _ScalerItem {
    RingItemHeader s_header;
    union {
        struct {
            uint32_t       s_mbz;              /* Must be zero .. no header */
            ScalerItemBody s_body;
        } u_noBodyHeader;
        struct {
            BodyHeader     s_bodyHeader;
            ScalerItemBody s_body;
        } u_hasBodyHeader;
    } s_body;
} ScalerItem, *pScalerItem;
                

The union has the standard branches that most RingItems have, u_noBodyHeader when s_mbz is zero indicating a lack of a body header and s_hasBodyHeader when it is the size of an action BodyHeader struct.

Regardless, s_body has the actual scaler data body and looks like this:

 typedef struct _ScalerItemBody {
  uint32_t        s_intervalStartOffset;
  uint32_t        s_intervalEndOffset;
  uint32_t        s_timestamp;
  uint32_t        s_intervalDivisor;  /* 11.0 sub second time intervals */
  uint32_t        s_scalerCount;
  uint32_t        s_isIncremental;    /* 11.0 non-incremental scaler flag */
  uint32_t        s_scalers[1];
} ScalerItemBody, *pScalerItemBody;
                

The fields s_intervalStartOffset, s_intervalEndOffset and s_intervalDivisor allow you to determine the time relative to the beginning of the run at which the counting interval started and ended. Dividing the offsets by the divisor produces seconds (if done in floating point arithmetic).

s_timetamp provides the unix time of day (trucated time_t) of the end of the counting interval.

The s_isIncremental is non-zero if the the scalers are zeroed at the start of each interval. Otherwise it is assumed that history is required to be able to compute rates.

Finally s_scalerCount is the number of scalers in item and s_scales is the location of the first element of the array of 32 bit wide scalers.

TextItem

TextItem items contain a set of text strings that are used for documentation purposes or to allow the data acquisition system to track a set of slow controls parameters. As with almost all ringt items, the top level structure is a union:

 typedef struct _TextItem {
    RingItemHeader s_header;
    union {
        struct {
            uint32_t       s_mbz;            /* Must be zero (no body header) */
            TextItemBody   s_body;
        } u_noBodyHeader;
        struct {
            BodyHeader     s_bodyHeader;
            TextItemBody   s_body;
        } u_hasBodyHeader;
    } s_body;
} TextItem, *pTextItem;
                

The TextItemBody has the following shape:

typedef struct _TextItemBody {
  uint32_t       s_timeOffset;
  uint32_t       s_timestamp;
  uint32_t       s_stringCount;
  uint32_t       s_offsetDivisor;
  char           s_strings[];
} TextItemBody, *pTextItemBody;
                

The s_timeOffset and s_offsetDivisor are used to represent the time at which this item was emitted relative to the start of the run. s_timeOffset is the offset. Doing a floating point by s_offsetDivisor produces the seconds into the run at which the item was emitted.

s_timestamp is the truncated time_t that represents the absolute time at which this item was emitted.

s_stringCount is the number of strings in the body. s_strings points to the first byte of an array of bytes that contain the null terminated strings carried by the item. The format of these strings is entirely up to the emitter.

PhysicsEventItem

This item represents the response of a readout subsystem to a trigger. This may be passed as an event fragment to an event building pipeline. The struture of the item is the normal union shape:

typedef struct _PhysicsEventItem {
    RingItemHeader s_header;
    union {
        struct {
            uint32_t      s_mbz;
            uint16_t      s_body[];      /* Aribrtary length body */
        } u_noBodyHeader;
        struct {
            BodyHeader    s_bodyHeader;
            uint16_t      s_body[];
        } u_hasBodyHeader;
    } s_body;
} PhysicsEventItem, *pPhysicsEventItem;
                

s_body is the first word of the event body. The size of the body can be determined from the s_size field of the s_header ring item header. Typically, the readout frameworks place a word or longword into the s_body that contains the length of the event.

DataFormat

This ring item (new starting in NSCLDAQ-11.0) describes the oldest version of NSCLDAQ that is capable of handling this form of data in the ring buffer. The structure of this item is:

typedef struct _DataFormat {
    RingItemHeader s_header;
    uint32_t       s_mbz;              /* No body header */
    uint16_t       s_majorVersion;     /* FORMAT_MAJOR */
    uint16_t       s_minorVersion;     /* FORMAT_MINOR */
} DataFormat, *pDataFormat;
                

As the s_mbz implies, This item does not have a body header. All data submitted to a single ring buffer is assumed to be in a compatible format. The s_majorVersion and s_minorVersion fields are the major and minor versions of the oldest NSCLDAQ that can deal with this data. For example for NSCLDAQ-11.0 s_majorVersion is 11 while s_minorVersion is 0

PhysicsEventCountItem

This ring item provides counts of the number of triggers a readout subsystem has responded to. This can be used to keep track of trigger rates and, for software that samples data, the fraction of data that has ben seen.

The structure of this data item is the usual union:

typedef struct _PhysicsEventCountItem {
    RingItemHeader   s_header;
    union {
        struct {
            uint32_t             s_mbz;      /* Must be zero - no body header*/
            PhysicsEventCountItemBody s_body;
        } u_noBodyHeader;
        struct {
            BodyHeader           s_bodyHeader;
            PhysicsEventCountItemBody s_body;
        } u_hasBodyHeader;
    } s_body;
} PhysicsEventCountItem, *pPhysicsEventCountItem;
                

The union is used so that individual contributors of fragments to the event builder can create uniquely identifiable trigger count items.

The s_body field of both branches of the union has the following shape:

typedef struct __PhysicsEventCountItemBody {
  uint32_t       s_timeOffset;
  uint32_t       s_offsetDivisor;
  uint32_t       s_timestamp;
  uint64_t       s_eventCount;	/* Maybe 4Gevents is too small ;-) */
} PhysicsEventCountItemBody, *pPhysicsEventCountItemBody;
                

The time into the run is determined in the usual way from s_timeOffset and s_offsetDivisor. Furthermore, s_timestamp provides the truncated time_t value that identifies the absolute time at which this item was emitted.

s_eventCount are the number of triggers that have been responded to since the start of the run.

EventBuilderFragment

An event builder fragment item is produced in event builder monitor rings. These rings allow users to monitor the ordered data data from the ordering stage of the event builder pipeline. These data are produced by the teering program, and are also inputs to glom.

Since the event builder operates on timestamps and needs to know about barriers and event sources all event fragments have a body header:

typedef struct _EventBuilderFragment {
  RingItemHeader s_header;
  BodyHeader     s_bodyHeader;
  uint8_t       s_body[];	/* Really s_payload bytes of data.. */
} EventBuilderFragment, *pEventBuilderFragment;
                

s_body is the first byte of the payload of the fragment. The size of the fragment can be determined from s_header.s_size (specifically s_header.s_size - sizeof(RingItemHeader) - sizeof(BodyHeader))).

It is also not unusual for the structure of the body to describe the size of the s_body independent of the rest of the item..

GlomParameters

This item type is produced by the glom stage of the event building pipeline. glom is the stage that can glue (or glom) ordered event fragments into full events.

This event item captures the values of the run time parameters handed to ghlom at startup time so that consumers of this data know what they mean,

typedef struct _GlomParameters  {
    RingItemHeader s_header;
    uint32_t       s_mbz;
    uint64_t       s_coincidenceTicks;
    uint16_t       s_isBuilding;
    uint16_t       s_timestampPolicy;
    
} GlomParameters, *pGlomParameters;
                

As you can see by the s_mbz field, this item does not have a ring body header. The s_isBuilding, is non zero if glom is gluing events together and zero otherwise. s_coincidenceTicks is therefore only meaningful if s_isBuilding is nonzero. It represents the timestamp interval that glom considers defines a fragment coincidence window. Finally the s_timestampPolicy contains the timestamp policy that glom used to determine how timestamp fields in body headers of built events should be chosen. This is one of GLOM_TIMESTAMP_FIRST, GLOM_TIMESTAMP_LAST or GLOM_TIMESTAMP_AVERAGE.

typedef strucst _AbnormalEndItem {
    RingItemHeader s_header;
    uint32_t      s_mbz;                   // Empty body header.

} AbnormalEndItem, *pAbnormalEndItem;

                

This can be emitted to let downstream software know that a run was ended prematurely. When emitted no more data shouild be emitted for the current run.