Equipment List Parameters
Links
Equipment List
The Equipment List is a declaration of the equipment(s) in a frontend using the EQUIPMENT structure defined in midas.h in the MIDAS package.
Only those parameters that are needed by the frontend to define the equipments are included (see example below). The contents of these parameters determine the properties of each equipment. More examples of equipment declarations can be found in the ..midas/examples subdirectories in the MIDAS package. Some of these parameters are copied to the ODB /Equipment/<equipment-name>/Common subdirectory when the frontend is initialized.
The parameters found in a frontend Equipment List is described below under Explanation of Equipment List parameters.
Example Equipment List Declaration
An example of an Equipment List declaration in a frontend is shown below. Two Equipments have been defined.
/*-- Equipment list -----------------------------------------------
*/
EQUIPMENT equipment[] = { // start of EQUIPMENT structure
//
{ "Trigger", // equipment name
{ 1, // event ID
0, // trigger mask
"SYSTEM", // event buffer
#ifdef USE_INT
EQ_INTERRUPT, // equipment type
#else
EQ_POLLED, // equipment type
#endif
LAM_SOURCE(0, 0xFFFFFF), // event source crate 0, all stations
"MIDAS", // format
TRUE, // enabled
RO_RUNNING | RO_ODB // read when running and update ODB
500, // poll for 500ms
0, // stop run after this event limit
0, // number of sub events
0, // log history
"", "", "", // Reserved
},
read_trigger_event, // Readout Routine
NULL, // class driver routine
NULL, // device driver list
NULL, // bank list/init string
},
{ "Scaler", // equipment name
{ 2, // event ID
0, // trigger mask
"SYSTEM", // buffer
EQ_PERIODIC | EQ_MANUAL_TRIG, // equipment type
0, // event source
"MIDAS", // format
TRUE, // enabled
RO_RUNNING | RO_TRANSITIONS | // read when running and on transitions
RO_ODB, // and update ODB
10000, // read every 10 sec
0, // stop run after this event limit
0, // number of sub events
0, // log history
"", "", "", // Reserved
},
read_scaler_event, // readout routine
NULL, // class driver routine
NULL, // device driver list
NULL, // bank list/init string
},
{""}
}; // end of EQUIPMENT structure
Explanation of Equipment List parameters
Equipment Name
This Equipment List Parameter defines the name of the equipment. Each equipment name must be unique (i.e. no two equipments in the same experiment may have the same name). The name will be the reference name of the equipment generating the event. Examples of typical Equipment Names are "Trigger","Scaler","Epics".
EventID
This Equipment List Parameter defines the event ID for this equipment. Each equipment has to be associated with a unique event ID . The event ID will be part of the event header of that particular equipment.
TriggerMask
This Equipment List Parameter is active when the equipment Type is EQ_INTERRUPT or EQ_MULTITHREAD. In this case, each equipment must be associated with a unique Trigger Mask. The Trigger Mask can be modified dynamically by the Readout Routine to define a subevent type on an event-by-event basis. This can be used to mix "physics events" (from a physics trigger) and "calibration events" (from a clock for example) in one run and identify them later. Both parameters are declared as 16-bit values. If the Trigger Mask is used in a single bit-wise mode, 16 is the maximum number of different masks available.
If not active, set to 0.
Buffer
This Equipment List Parameter specifies the name of the Buffer to which the event will be sent. After composition of an equipment, the Midas Frontend mfe.c takes over the sending of this event to the buffer (usually the SYSTEM buffer) on the back-end computer where it may be sent to the data logger mlogger) and the analyser.
- If this field is left empty, (i.e. set to ""), the readout function associated with that equipment will still be performed, but the actual event won't be sent to the buffer. Instead, that particular equipment can be mirrored in the ODB if the RO_ODB flag is turned on (see example). The ODB is updated with a new event approximately every second. Note that this feature is generally used only for testing or monitoring, as writing large amounts of data to the ODB takes time.
- By using a buffer other than the SYSTEM buffer, Event Filtering can be implemented.
- If using an Event Builder ( i.e. a secondary stage on the back-end to collect and assemble events coming from different buffers in order to compose a larger event) , a dedicated buffer can be specified. In this case the EQ_EB flag must be turned on, and the events coming from the Frontend are called fragments.
Type
This Equipment List Parameter specifies the type of equipment, and should be set to one of the Equipment Flags EQ_XXX selected from the list of valid Equipment Flags, i.e. one of
Source
This Equipment List Parameter (i.e. the interrupt or event source) is only used if the equipment Type is set to EQ_INTERRUPT or EQ_MULTITHREAD. The interrupt Source field is a bit-wise pattern representing the interrupt that is allowed to trigger the call to the Readout Routine. The @ref FE_poll_or_interrupt_readout_routine "example" shows a CAMAC or VME source for the interrupt. A MACRO (LAM_SOURCE) calculates the bit pattern from the parameters (Crate,Slot).
If not using an interrupt, this field is set to 1.
Format
This Equipment List Parameter specifies the data format used for generating the event. Only "MIDAS" and "FIXED" formats are valid in the frontend. The format must agree with the way the event is composed in the equipment Readout Routine. It tells the system how to interpret an event when it is copied to the ODB or displayed in a user-readable form. Data in MIDAS and/or FIXED format from the frontend can be saved by the MIDAS data logger mlogger in a number of formats (see mlogger format ). NOTE
- MIDAS or FIXED data format can be mixed at the frontend level, but mlogger is not able to handle this format diversity on a event-by-event basis.
- In practice, the data format (MIDAS/FIXED) should be identical throughout one equipment definition. Different equipments can, of course, have different formats in the same frontend.
- ROOT format cannot be specified in the equipment definition. To save raw data in ROOT format, the Bank Definition must be supplied, and a conversion to ROOT format is done by the data logger ).
Enabled
This Equipment List Parameter is the enable switch for the equipment. Only when enabled (i.e. TRUE) is this equipment active.
ReadOn
This Equipment List Parameter specifies when the read-out of an event occurs or is enabled (i.e. on which transition state(s) and/or on which run state(s) respectively) by using a combination of ReadOn Flags.
- NOTE
- These flags can be combined with the logical OR operator,e.g. RO_RUNNING | RO_TRANSITIONS means that the event is read out when
running and additionally on all transitions.
Period
This Equipment List Parameter specifies the time interval for EQ_PERIODIC equipment or time out value in the case of EQ_POLLED or EQ_MULTITHREAD equipments (units are milliseconds).
Event limit
This Equipment List Parameter specifies the number of events to be taken prior to forcing an End-of-Run Run States and Transitions#transition. The value 0 disables this option.
Number of subevents
This Equipment List Parameter enables the Super Event capability if > 0 . Specifies the maximum number of sub-events in the Super Event. (Not applicable to FIXED format events.)
Log History
This Equipment List Parameter enables/disables the @ref History System for that equipment. The value (positive in seconds) specifies the time interval between subsequent history events. A positive value enables history logging, in which case the event data will also be sent automatically to the ODB in the /equipment/<equipment-name>/variables tree.
To disable history logging of this event, set this parameter to 0.
Readout Routine
This Equipment List Parameter contains the name of the user-written function to be called when the event is triggered. The name of this routine is specified by the user. This Readout Routine must be present in the frontend code. It will be called at an event trigger, which will occur under one of these conditions depending on the Type parameter.
- polled mode
- the poll_event() routine has detected a trigger request while polling on a trigger source.
- interrupt mode
- an interrupt has occurred whose source is pre-defined in the interrupt_configure() routine.
- periodic modes
- trigger occurs periodically at a time interval specified by the Period parameter.
- manual trigger mode
- trigger occurs when
- 1. the manual trigger button is pressed on the web interface or
- 2. a client requests an event by @ref FE_backend_Manual_Trigger "triggering the event sending mechanism" via a RPC.
Click for further details of a @ref FE_poll_event "poll_event routine" and an @ref FE_interrupt_event "interrupt routine".
Class Driver
For all Equipment Types except EQ_SLOW, this field must be present but set to NULL.
If Equipment Type parameter is set to EQ_SLOW this parameter is set to the main routine for the Class Driver of the hardware. See also Device Driver List.
Device Driver List
For all Equipment Types except EQ_SLOW, this field must be present but set to NULL.
If Equipment Type parameter is set to EQ_SLOW, this parameter is set to the Device Driver List. This is defined using the DEVICE_DRIVER structure defined in midas.h in the MIDAS package, e.g.
Example of Slow Control Equipment
/* device driver list */
DEVICE_DRIVER hv_driver[] = {
{"Dummy Device", nulldev, 16, null},
{""}
};
The Class Driver parameter must also be defined. The Slow Control Equipment Definition is shown below, taken from the example ../midas/examples/slowcont/frontend.c in the MIDAS package.
EQUIPMENT equipment[] = {
//
{"HV", /* equipment name */
{3, 0, /* event ID, trigger mask */
"SYSTEM", /* event buffer */
EQ_SLOW, /* equipment type */
0, /* event source */
"FIXED", /* format */
TRUE, /* enabled */
RO_RUNNING | RO_TRANSITIONS, /* read when running and on transitions */
60000, /* read every 60 sec */
0, /* stop run after this event limit */
0, /* number of sub events */
10000, /* log history every event */
"", "", ""} ,
cd_hv_read, /* readout routine */
cd_hv, /* class driver main routine */
hv_driver, /* device driver list */
NULL, /* not used */
},
{""}
};
Bank Definition/Init String
This parameter must be present. It may be set to NULL, unless performing a ROOT format conversion or a FIXED format event.
If the raw MIDAS/FIXED format data to be converted to ROOT format (by the data logger mlogger), the frontend is required to contain the definition of the bank(s) using the BANK_LIST structure defined in midas.h in the MIDAS package. This procedure is equivalent to the bank declaration in the analyser. A code fragment is shown below
Example ROOT format conversion
The formats for the ADC0 bank is "fixed", and for the TDC0 bank "MIDAS". This structure definition must be declared in the parameter Bank Definition in the equipment list.
ADC0_BANK_STR(adc0_bank_str);
BANK_LIST trigger_bank_list[] = {
{"ADC0", TID_STRUCT, sizeof(ADC0_BANK), adc0_bank_str},
{"TDC0", TID_WORD, N_TDC, NULL},
{""},
};
BANK_LIST scaler_bank_list[] = {
{"SCLR", TID_DWORD, N_ADC, NULL},
{""},
};
The NULL Bank Definition parameter in the equipment definition example would be replaced by the name of the defined structure, e.g.
...........
read_scaler_event, // readout routine
NULL, // not used
NULL, // not used
scaler_bank_list, // bank list
............
See FIXED format event construction for example of the use of the "init string" parameter.