Difference between revisions of "Equipment List Parameters"

From MidasWiki
Jump to navigation Jump to search
Line 1: Line 1:
== TABLE showing Equipment List Parameters ==
+
== Explanation of Equipment List Parameters ==
  
 
Links
 
Links
Line 11: Line 11:
 
[[#MirroredInODB]]
 
[[#MirroredInODB]]
  
'''Note''' These parameters are copied to the ODB <span style="color: purple;">''/Equipment/<equipment-name>/Common''</span> subdirectory when the frontend is initialized.
+
==Introduction==
 +
The Equipment declaration in the frontend uses the EQUIPMENT structure defined in ''midas.h'' in the MIDAS package. Only those fields that are needed by the frontend are
 +
included (see example below). Some of these parameters are copied to the ODB <span style="color: purple;">''/Equipment/<equipment-name>/Common''</span> subdirectory when the frontend is initialized.
  
{|  style="text-align: left; width: 100%; background-color: rgb(255, 255, 255);" border="3" cellpadding="2" cellspacing="2"
+
Each of the parameters found in the frontend Equipment Declaration are described below.
  
|-
+
==Example Equipment declaration in a frontend ==
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | EQUIPMENT Parameter
 
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | Explanation
 
  
'''<div id="Equipment Name"></div>'''
 
|- 
 
| colspan="1" rowspan="1"  style="vertical-align: top; background-color: rgb(255, 255, 255); color: red"  |Equipment Name
 
| Each equipment has to be assigned a <b> unique name </b> (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".
 
  
|-
+
An example of an Equipment declaration in a frontend is shown below:
|  style="text-align: center; font-weight: bold; vertical-align: top; background-color:turquoise; color: rgb(255, 255, 255);  " colspan="2" rowspan="1"  | EQUIPMENT_INFO  Structure
 
  
'''<div id="EventID"></div>'''
+
/*-- Equipment list ------------------------------------------------*/
|- style="background-color: mintcream; "   
 
| style="color: seagreen;"                |  EventID
 
| Each equipment has to be associated with a  '''unique eventID''' . The event ID will be part of the event header of that particular equipment.
 
  
'''<div id="TriggerMask"></div>'''
+
  EQUIPMENT equipment[] = {
|- style="background-color: mintcream; "   
 
| style="color: seagreen;"                | Trigger Mask
 
| Each equipment must be associated with a <b> unique Trigger Mask </b> if  the [[#Equipment Type|Equipment Type]] is  "[[#EQ_INTERRUPT|EQ_INTERRUPT]]" or "[[#EQ_MULTITHREAD|EQ_MULTITHREAD]]".  In this case, the Trigger Mask can be modified dynamically by the readout routine to define a  '''sub-event 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 16bit values. If the Trigger Mask is used in a single bit-wise mode, 16 is the maximum number of different masks available. 
 
  
'''<div id="Buffer"></div>'''  '''<div id="MirroredInODB"></div>'''
+
  {"Trigger",              /* equipment name */
|-  style="background-color: mintcream; "
+
    {1, 0,                  /* event ID, trigger mask */
| style="color: seagreen;"    | Buffer
+
    "SYSTEM",              /* event buffer */
|  Specifies the name of the Buffer to which the event will be sent. After composition of an "Equipment", the Midas  [[Frontend Operation#Frontend|Frontend]] ''mfe.c''
+
    EQ_POLLED,              /* equipment type */
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]].
+
    LAM_SOURCE(0, 0xFFFFFF),        /* event source crate 0, all stations */
 +
    "MIDAS",               /* format */
 +
    TRUE,                  /* enabled */
 +
    RO_RUNNING |           /* read only when running */
 +
    RO_ODB,                /* and update ODB */
 +
    100,                    /* poll for 100ms */
 +
    0,                      /* stop run after this event limit */
 +
    0,                      /* number of sub events */
 +
    0,                      /* don't log history */
 +
    "", "", "",},
 +
    read_trigger_event,      /* readout routine */
 +
    },
  
*  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|RO_ODB]]" flag is turned on (see @ref  FE_RO_ODB_example "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.  
+
  {"Scaler",                /* equipment name */
 +
    {2, 0,                  /* event ID, trigger mask */
 +
    "SYSTEM",              /* event 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 */
 +
    "", "", "",},
 +
    read_scaler_event,      /* readout routine */
 +
    },
 +
 
 +
  {""}
 +
};
 +
 
 +
 
 +
== EQUIPMENT Structure parameters ==
 +
===Equipment Name===
 +
Each equipment has to be assigned a unique Name. The name will be the reference name of the equipment generating the event. Examples of typical equipment Names are "Trigger","Scaler","Epics".
 +
 
 +
===EventID===
 +
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===
 +
If  the  equipment [[#Type|Type]] is  [[#EQ_INTERRUPT|EQ_INTERRUPT]] or [[#EQ_MULTITHREAD|EQ_MULTITHREAD]], each equipment must be associated with a unique Trigger Mask  In this case, 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. 
 +
 
 +
<div id="MirroredInODB"></div>
 +
===Buffer===
 +
Specifies the name of the Buffer to which the event will be sent. After composition of an equipment, the Midas  [[Frontend Operation#Frontend|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|RO_ODB]] flag is turned on (see @ref  FE_RO_ODB_example "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.  
 
* By using a buffer other than the SYSTEM buffer,  [[Event Filtering]] can be implemented.  
* If using an [[Event Builder]] [[Mevb]] ( i.e. a secondary stage on the back-end to collect and assemble events coming from different buffers in order to
+
* 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|EQ_EB]] flag must be turned on, and the events coming from the  [[Frontend Operation#Frontend|Frontend]] are called  ''fragments''.
compose a larger event) , a dedicated buffer can be specified.  In this case the [[#EQ_EB|EQ_EB]] flag must be turned on, and the events coming from the  [[Frontend Operation#Frontend|Frontend]] are called  ''fragments''.
 
  
  
 
+
===Type===
<div id="Type"></div>
+
Type specifies the type of equipment, and should be set to one of the Equipment Flags EQ_XXX selected from the [[Equipment Flags|list of valid Equipment Flags]], i.e. one of
|-  style="background-color: mintcream; "
 
| style="color: seagreen;"    | Type
 
| Equipment '''Type''' should be set to one of the Equipment Flags EQ_XXX selected
 
from the [[Equipment Flags|list of valid Equipment Flags]], i.e. one of
 
 
<div style="column-count:4;-moz-column-count:4;-webkit-column-count:4">
 
<div style="column-count:4;-moz-column-count:4;-webkit-column-count:4">
 
* [[Equipment Flags#EQ_PERIODIC|EQ_PERIODIC]]
 
* [[Equipment Flags#EQ_PERIODIC|EQ_PERIODIC]]
Line 66: Line 97:
 
</div>
 
</div>
  
<div id="Source"></div>
+
===Source===
|-  style="background-color: mintcream; "
+
This field (i.e. the  interrupt or event  source) is only used if the equipment [[#Type|Type]] is set to  [[Equipment Flags#EQ_INTERRUPT|EQ_INTERRUPT]] or [[Equipment Flags#EQ_MULTITHREAD|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).  
| style="color: seagreen;"    | Source
 
| This field (i.e. the  interrupt or event  source) is only used if the [[#Type|Equipment Type]] is set to  [[Equipment Flags#EQ_INTERRUPT|EQ_INTERRUPT]] or [[Equipment Flags#EQ_MULTITHREAD|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.
 
If not using an interrupt, this field is set to 1.
  
  
<div id="Format"></div>
+
===Format===
|-  style="background-color: mintcream; "
+
Specifies the data format used for generating the event. Only [[Event Structure#MIDAS Format Event|"MIDAS"]] and  [[Event Structure#FIXED Format Event|"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|mlogger]] in a number of formats (see  [[Keys in the ODB /Logger/Channels tree #/Logger/Channels/0/Settings/Format | mlogger format]] ).
| style="color: seagreen;"    | Format
 
|Specifies the data format used for generating the event. Only [[Event Structure#MIDAS Format Event|"MIDAS"]] and  [[Event Structure#FIXED Format Event|"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|mlogger]] in a number of formats (see  [[Keys in the ODB /Logger/Channels tree #/Logger/Channels/0/Settings/Format | mlogger format]] ).
 
 
'''NOTE'''
 
'''NOTE'''
*MIDAS or FIXED data format can be mixed at the frontend level, but <span style="color:darkcyan;">''mlogger''</span> is not able to handle this format diversity on a event-by-event basis.
+
*MIDAS or FIXED data format can be mixed at the frontend level, but <span style="color:darkcyan;">''mlogger''</span> is not able to handle this format diversity on a event-by-event basis.  
In practice
+
: 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.
** The data format (MIDAS/FIXED) should be identical throughout one equipment definition
+
* 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 [[Keys in the ODB /Logger/Channels tree #/Logger/Channels/0/Settings/Format | data logger]] ).
** 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 [[Keys in the ODB /Logger/Channels tree #/Logger/Channels/0/Settings/Format | data logger]] ).
 
 
* For FIXED events, the  [[Bank definition]] parameter may contain the  [[Init String]].
 
* For FIXED events, the  [[Bank definition]] parameter may contain the  [[Init String]].
 
 
  
 +
===Enabled===
 +
Enable switch for the equipment. Only when enabled (i.e. TRUE) is this equipment active.
  
<div id="Test1"></div>
 
|-  style="background-color: mintcream; " 
 
| style="color: seagreen;"  |
 
 
 
 
|-  style="background-color: mintcream; "
 
| style="color: seagreen;"    |
 
|
 
 
 
|-  style="background-color: mintcream; "
 
| style="color: seagreen;"    |
 
|
 
  
 +
===ReadOn===
 +
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]].
 +
<div style="column-count:5;-moz-column-count:5;-webkit-column-count:5">
 +
* [[ReadOn Flags|RO_RUNNING]]
 +
* [[ReadOn Flags|RO_STOPPED ]]
 +
* [[ReadOn Flags|RO_PAUSED ]]
 +
* [[ReadOn Flags|RO_BOR ]]
 +
* [[ReadOn Flags|RO_EOR]]
 +
* [[ReadOn Flags|RO_PAUSE]]
 +
* [[ReadOn Flags|RO_RESUME ]]
 +
* [[ReadOn Flags|RO_TRANSITIONS]]
 +
* [[ReadOn Flags|RO_ALWAYS ]]
 +
* RO_ODB
 +
</div>
 +
;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===
 +
Time interval for [[Equipment Flags#EQ_PERIODIC|EQ_PERIODIC]] equipment or time out value in the case of [[Equipment Flags#EQ_POLLED|EQ_POLLED]] or [[Equipment Flags#EQ_MULTITHREAD|EQ_MULTITHREAD]] equipments (units are milliseconds).
  
 +
===Event limit===
 +
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===
 +
Enables the [[Super Event]] capability if &gt; 0 . Specifies the maximum number of sub-events in the [[Super Event]]. (Not applicable to
 +
[[Event Structure#FIXED Format Event|FIXED format]] events.)

Revision as of 17:01, 30 October 2013

Explanation of Equipment List Parameters

Links Equipment Declaration

B

#Equipment Name #EventID #TriggerMask #Equipment Type #Test1 #Buffer

#Equipment Type EQ_PERIODIC EQ_POLLED Q_INTERRUPT Q_MULTITHREAD EQ_SLOW EQ_MANUAL_TRIG EQ_EB EQ_FRAGMENTED

#MirroredInODB

Introduction

The Equipment declaration in the frontend uses the EQUIPMENT structure defined in midas.h in the MIDAS package. Only those fields that are needed by the frontend are included (see example below). Some of these parameters are copied to the ODB /Equipment/<equipment-name>/Common subdirectory when the frontend is initialized.

Each of the parameters found in the frontend Equipment Declaration are described below.

Example Equipment declaration in a frontend

An example of an Equipment declaration in a frontend is shown below:

/*-- Equipment list ------------------------------------------------*/
EQUIPMENT equipment[] = {
  {"Trigger",               /* equipment name */
   {1, 0,                   /* event ID, trigger mask */
    "SYSTEM",               /* event buffer */
    EQ_POLLED,              /* equipment type */
    LAM_SOURCE(0, 0xFFFFFF),        /* event source crate 0, all stations */
    "MIDAS",                /* format */
    TRUE,                   /* enabled */
    RO_RUNNING |            /* read only when running */
    RO_ODB,                 /* and update ODB */
    100,                    /* poll for 100ms */
    0,                      /* stop run after this event limit */
    0,                      /* number of sub events */
    0,                      /* don't log history */
    "", "", "",},
   read_trigger_event,      /* readout routine */
   },
  {"Scaler",                /* equipment name */
   {2, 0,                   /* event ID, trigger mask */
    "SYSTEM",               /* event 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 */
    "", "", "",},
   read_scaler_event,       /* readout routine */
   },
  {""}
};


EQUIPMENT Structure parameters

Equipment Name

Each equipment has to be assigned a unique Name. The name will be the reference name of the equipment generating the event. Examples of typical equipment Names are "Trigger","Scaler","Epics".

EventID

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

If the equipment Type is EQ_INTERRUPT or EQ_MULTITHREAD, each equipment must be associated with a unique Trigger Mask In this case, 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.

Buffer

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 @ref FE_RO_ODB_example "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

Type 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 field (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

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 ).
  • For FIXED events, the Bank definition parameter may contain the Init String.

Enabled

Enable switch for the equipment. Only when enabled (i.e. TRUE) is this equipment active.


ReadOn

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

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

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

Enables the Super Event capability if > 0 . Specifies the maximum number of sub-events in the Super Event. (Not applicable to FIXED format events.)