MIDAS Event Structure

From MidasWiki
Revision as of 16:38, 23 October 2013 by Suz (talk | contribs)
Jump to navigation Jump to search

MIDAS event structure

A diagram of the structure of an event in MIDAS format is shown below:

Figure 1: Structure of MIDAS event showing Event and Bank headers with data banks.

MEHBH.jpg


Special formats are used in MIDAS for the event header, bank header, banks and when writing to tape. The following sections explains these formats in detail.

Event Header

Each event carries a 16-byte header, generated by the Frontend Operation#Frontend with the bm_compose_event() routine and is used by consumers to distinguish between different events.

The event header is defined in the EVENT_HEADER structure in the file midas.h in the midas package. It has following structure:

EventID
the @ref FE_tbl_Event ID "eventID" describes the type of event. Usually 1 is used for triggered events, 2 for scaler events, 3 for HV events etc.
TriggerMask
the @ref FE_tbl_TrigMask "trigger mask" can be used to describe the sub-type of an event. A trigger event can have different trigger sources like "physics event", "calibration event", "clock event". These trigger sources are usually read in by the front-end in a pattern unit. Consumers can request events with a specific triggering mask.
Serial number
The serial number starts at 1 and is incremented by the front-end for each event.
Time Stamp
the time stamp is written by the front-end before an event is read out. It uses the time() function which returns the time in seconds since 1.1.1970 00:00:00 UTC.
Event Data Size
The event data size contains the size of the event in bytes excluding the header.

Event headers are always kept in the byte ordering of the local machine. If events are sent over the network between computers with different byte ordering, the event header is swapped automatically, but not the event contents.

If the byte ordering of the contents of a complete event has to be swapped, the routine bk_swap() can be used.


Data Area

The data area of the event can contain information in any user format (integer, real etc.), although only certain formats are supported when events are copied to the ODB or written by the logger in ASCII format.

The Data Area of a MIDAS event consists of a global Bank Header followed by one or more MIDAS Data Banks.

A Data Bank is a substructure of an event and can contain only one type of data, either a single value or an array of values. Each Data Bank has an individual bank header containing a name of exactly four characters, which is treated as a bank ID.

Bank Header (global)

There is one global Bank Header per event, defined in the BANK_HEADER structure in the file midas.h. It has the following structure:

All Bank Size
Size in bytes of the following data plus the size of the bank header
Flags
not used

The global Bank Header is initialized by the bk_init() call.

MIDAS Data Bank

Each data bank contains a header defined by the BANK (or BANK32) structures in the file midas.h.

It has the following structure:

Bank name
four characters for the name of each bank. Each bank in an event must have a unique name.
Bank type
one of the TID_xxx values defined in midas.h to encode the data type (e.g. TID_INT or TID_FLOAT for integer or floating point data).
Bank size
size in bytes of the following data.

Following the header is the data in the format designated by the Bank type parameter (e.g. integer or float). A separate MIDAS bank must be created for each data type needed.


Example of MIDAS event

Figure 2 shows a MIDAS event containing banks coloured to match the structure in Figure 1. This has been obtained from a MIDAS data file using the mdump application.


Figure 2: Example of MIDAS banks dumped by mdump.


Event# 2 --------------------------------

Evid:000d- Mask:0000- Serial:0- Time:0x4c7a6869- Dsize:48/0x30
\#banks:1 - Bank list:-SDAS-

Bank:SDAS Length: 32(I*1)/8(I*4)/8(Type)Type:Real*4 (FMT machine dependent)
1-> 4.000e+00 1.000e+01 1.000e+00 3.400e+00 3.400e+00 3.400e+00 3.400e+00 3.400e+00


Event# 3 --------------------------------

Evid:0001- Mask:0000- Serial:0- Time:0x4c7a686b- Dsize:344/0x158
\#banks:2 - Bank list:-MPETMCPP-

Bank:MPET Length: 304(I*1)/76(I*4)/76(Type) Type:Unsigned Integer*4
1-> 0x80010000 0x00000002 0x10010000 0x00004e21 0x80020000 0x00000002 0x20020000 0x000015f4

  9-> 0x20020000 0x00001660 0x20020000 0x0000185f 0x20020000 0x0000191e 0x20020000 0x000019d6
17-> 0x40020000 0x00001a37 0x20020000 0x00001a77 0x20020000 0x00001ba2 0x10020000 0x00004e22
25-> 0x80030000 0x00000002 0x20030000 0x00001637 0x20030000 0x000018d1 0x20030000 0x000019bc
33-> 0x20030000 0x00001b35 0x20030000 0x00001bb2 0x10030000 0x00004e21 0x80040000 0x00000002
41-> 0x10040000 0x00004e22 0x80050000 0x00000002 0x20050000 0x000013c5 0x20050000 0x000017f2
49-> 0x20050000 0x0000185f 0x20050000 0x00001976 0x20050000 0x00001aa8 0x10050000 0x00004e21
57-> 0x80060000 0x00000002 0x20060000 0x000015c3 0x20060000 0x000018d8 0x20060000 0x0000198d
65-> 0x20060000 0x00001ac4 0x10060000 0x00004e22 0x80070000 0x00000002 0x20070000 0x00001747
73-> 0x20070000 0x000019ae 0x10070000 0x00004e21


Bank:MCPP Length: 16(I*1)/4(I*4)/4(Type) Type:Unsigned Integer*4
1-> 0x00005e4c 0x0000352d 0x00006453 0x00006d5b


Tape Format

Events are written to disk files without any reformatting. For tapes, however, a fixed block size is used. The block size TAPE_BUFFER_SIZE is defined in midas.h and usually 32kB.

Three special events are produced by the system.

  • A begin-of-run (BOR) and end-of-run (EOR) event is produced which contains an ASCII dump of the ODB in its data area. Their IDs is 0x8000 (BOR) and 0x8001 (EOR).
  • A message event (ID 0x8002) is created if Log messages is enabled in the logger channel setting. The message is contained in the data area as an ASCII string.

The BOR event has the number MIDAS_MAGIC (0x494d or 'MI') as the trigger mask and the current run number as the serial number. A tape can therefore be identified as a MIDAS formatted tape.

The routine tape_copy() in the utility mtape.c is an example of how to read a tape in MIDAS format.