Fragments and FragmentGenerators

n.b. Before reading this section, please first read the artdaq-demo Overview

Representing your experiment's data

The fundamental building block: artdaq::Fragment

The artdaq::Fragment's header

In any artdaq-based DAQ system, the data provided by an experiment is stored within an object of the artdaq::Fragment class. The physical representation of the data in the class is contained within a vector called "vals_"; the datatype in the vector is called "RawDataType", a typedef of a 64-bit unsigned integer found in artdaq's RawFragmentHeader.hh file. Aside from this vector of data, the artdaq::Fragment class also provides some logical structure to the data. The vals_ vector can be thought of as consisting of an artdaq "header", containing information about the fragment itself used by the artdaq-based system (more on this below), followed by experiment-specific data (such as user-defined metadata and physics).

The header is defined in RawFragmentHeader.hh, and consists of three 64-bit unsigned integers with two more reserved for future use, organized via the following bitfield:

 RawDataType word_count          : 32; // number of RawDataTypes in this Fragment
  RawDataType version             : 16;
  RawDataType type                :  8;
  RawDataType metadata_word_count :  8;

  RawDataType sequence_id : 48;
  RawDataType fragment_id : 16;

  // 27-Feb-2013, KAB - As we discussed recently, we will go ahead
  // and reserve another longword for future needs.  The choice of
  // four 16-bit values is arbitrary and will most certainly change
  // once we identify the future needs.
  RawDataType unused1     : 16;
  RawDataType unused2     : 16;
  RawDataType unused3     : 16;
  RawDataType unused4     : 16;

The two header variables for which the user must supply values are the sequence_id (uniquely identifying an experiment's event, whether triggered or a timeslice) and the fragment_id (uniquely identifying a subset of the full amount of data representing an event, typically corresponding to a physical subsection of a detector). Optionally, a user may specify a "type" and version to the "fragment". An examination of artdaq's Fragment.hh header will reveal that it defines a datatype called "type_t", an unsigned 8-bit integer whose value provides information on the type of information a fragment contains. Some of these values are reserved for system use; the range of these values are set in artdaq's RawFragmentHeader.hh file, run from 225-255, and can be employed to tell artdaq-based DAQ systems that a run has ended, etc. Values 1-224 can be assigned experiment-specific meanings by the user; in artdaq-demo "FragmentType.hh" associates type values with different kinds of CAEN boards. "version" can be used to refer to the version of an experiment's data fragment layout if this evolves over the lifetime of the experiment, including during commissioning. The metadata_word_count and the word_count are calculated internally by the artdaq::Fragment class; the metadata_word_count describes the number of RawDataTypes within the payload which describes' the experiments metadata (e.g., the trigger bits, the upstream DAQ board's serial number, etc.), and the word_count describes the total number of RawDataTypes in the fragment ( 3 from the fragment header + metadata_word_count + the number which make up the experiment's payload). "type" can be given user-supplied meaning (in the case of the demo::V172xFragment overlay class, "type" can refer to a V1720 or a V1724 CAEN digitizer board). From a programmer's perspective, although the fragment's header data is publicly accessible within the RawFragmentHeader struct, best practices is to assign to it via setter functions in the artdaq::Fragment class : setVersion, setUserType, setSequenceID and setFragmentID; more on this below.

Setting values in artdaq::Fragment

Some native support exists for modifying the vals_ array via the artdaq::Fragment interface. The template function artdaq::Fragment::setMetadata(const T& md) allows one to pass a user-defined datatype (typically a class or struct) representing experiment-specific metadata which gets stored in the vals_ array beyond the header. In order to set the amount of data held by the fragment, one can call the resize() function which takes as its two arguments the number of RawFragmentTypes the fragment will represent beyond its header and metadata

Along with the setter functions described above, the word_count var

Describing the structure of your data via an overlay class

Beyond the information supplied in an artdaq::Fragment header, there's other information which may be of interest to a given experiment. For example, how many bits does an ADC value take? To what run number does a given fragment belong? What was the trigger configuration when the fragment was produced?

Talk about metadata, header data, payload

V172xFragment - an example overlay

FragmentGenerators: how boardreaders send fragments to event builders