Equipment List Parameters: Difference between revisions

From MidasWiki
Jump to navigation Jump to search
No edit summary
No edit summary
(18 intermediate revisions by one other user not shown)
Line 1: Line 1:
== TABLE showing Equipment List Parameters ==
{{Pagelinks}}


== Links ==
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Frontend user code]]
* [[Frontend Operation]]
* [[Equipment Flags]]
</div>


<div id="B">B</div>
==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.


[[#Equipment Name]] [[#EventID]] [[#TriggerMask]]  [[#Equipment Type]]  [[#Test1]]  [[#Buffer]]
Only those parameters that are needed by the frontend to define the equipments are included (see [[#Example Equipment List Declaration|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.


[[#Equipment Type]] [[#EQ_PERIODIC]] [[#EQ_POLLED]] [[#EQ_INTERRUPT]] [[#EQ_MULTITHREAD]] [[#EQ_SLOW]]  [[#EQ_MANUAL_TRIG]]  [[#EQ_FRAGMENTED]]  [[#EQ_EB]]
When the frontend is first run, it will create (using ''db_create_record'') in the ODB [[/Equipment ODB tree]]  (if they do not already exist) the ''<equipment-name>'' subdirectories for all equipments defined by the frontend.  The initial values of many of the parameters in the ODB [[/Equipment ODB tree#Common subtree|/Equipment/''<equipment-name>''/Common subtree]] are taken from the corresponding Equipment List.


[[#MirroredInODB]]
The parameters found in a frontend Equipment List is described below under [[#Explanation of Equipment List parameters|Explanation of Equipment List parameters]].


'''Note''' These parameters are copied to the ODB <span style="color: purple;">''/Equipment/<equipment-name>/Common''</span> subdirectory when the frontend is initialized.
===Example Equipment List Declaration===


{|  style="text-align: left; width: 100%; background-color: rgb(255, 255, 255);" border="1" cellpadding="2" cellspacing="2"
An example of an Equipment List declaration in a frontend is shown below. Two Equipments have been defined.


|-
  /*-- Equipment list -----------------------------------------------
| 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
  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


'''<div id="Equipment Name"></div>'''
== Explanation of Equipment List parameters ==
|- 
===Equipment Name===
| colspan="1" rowspan="1"  style="vertical-align: top; background-color: rgb(255, 255, 255); color: red"  |Equipment Name
This [[#Equipment List|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".
| 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".


|-
As of October 2019, you may use the string "${HOSTNAME}" in your equipment name, and the frontend framework will automatically substitute the name of your machine.
|  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>'''
===EventID===
|- style="background-color: mintcream; "   
This [[#Equipment List|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.  
| 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>'''
The EventID (and the [[#TriggerMask]]) can be used to sort events into different streams, e.g. in [[Event Builder|Event Building]] or [[Event Filtering]].
|-  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>'''
===TriggerMask===
|-  style="background-color: mintcream; "
This [[#Equipment List|Equipment List Parameter]] can be used to sort events using a unique TriggerMask. It may be used when the
| style="color: seagreen;"    | Buffer
[[#Type|Equipment Type]] is [[Equipment Flags#EQ_INTERRUPT|EQ_INTERRUPT]] or [[Equipment Flags#EQ_MULTITHREAD|EQ_MULTITHREAD]] and/or
| 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''
in [[Event Builder|Event Building]] and [[Event Filtering]] to sort the events.
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]].
When in use, each equipment is associated with a unique TriggerMask.  The TriggerMask can be modified dynamically by the [[#Readout Routine|Readout Routine]] e.g. to define a  [[Super Event|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. TriggerMasks are declared as 16-bit values. If the TriggerMask is used in a single bit-wise mode, 16 is the maximum number of different masks available.


*  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.
Set TriggerMask to 0 if not used.
* 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
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'''.


<div id="MirroredInODB"></div>
===Buffer===
This [[#Equipment List|Equipment List Parameter]] 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|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 [[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|EQ_EB]] flag must be turned on, and the events coming from the  [[Frontend Operation#Frontend|Frontend]] are called  ''fragments''.


|-  style="background-color: mintcream; "
| style="color: seagreen;"    |
|


===Type===
This [[#Equipment List|Equipment List Parameter]] 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
<div style="column-count:4;-moz-column-count:4;-webkit-column-count:4">
* [[Equipment Flags#EQ_PERIODIC|EQ_PERIODIC]]
* [[Equipment Flags#EQ_POLLED|EQ_POLLED]]
* [[Equipment Flags#EQ_INTERRUPT|EQ_INTERRUPT]]
* [[Equipment Flags#EQ_MULTITHREAD|EQ_MULTITHREAD]]
* [[Equipment Flags#EQ_SLOW|EQ_SLOW]]
* [[Equipment Flags#EQ_MANUAL_TRIG|EQ_MANUAL_TRIG]]
* [[Equipment Flags#EQ_EB|EQ_EB]]
* [[Equipment Flags#EQ_FRAGMENTED|EQ_FRAGMENTED]]
</div>


|-  style="background-color: mintcream; "
===Source===
| style="color: seagreen;"    |
This [[#Equipment List|Equipment List Parameter]]  (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|Readout Routine]]. The  [[Frontend user code#Polled 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).
|


<div id="Test1"></div>
If not using an interrupt, this field is set to 1.
|-  style="background-color: mintcream; " 
| style="color: seagreen;"  |




|- style="background-color: mintcream; "
===Format===
| style="color: seagreen;"   |  
This [[#Equipment List|Equipment List Parameter]] 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|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'''
*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, 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|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]] ).




|-  style="background-color: mintcream; "
===Enabled===
| style="color: seagreen;"    |
This [[#Equipment List|Equipment List Parameter]] is the enable switch for the equipment. Only when enabled (i.e. TRUE) is this equipment active.
|




===ReadOn===
This [[#Equipment List|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]].
<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 ]]
* [[ReadOn Flags|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===
This [[#Equipment List|Equipment List Parameter]] specifies the 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===
'''<div id="Equipment Type"></div>'''
This [[#Equipment List|Equipment List Parameter]] specifies the number of events to be taken prior to forcing an End-of-Run  [[Run States and Transitions#transition|Transition]]. The value 0 disables this option.
Equipment Type should be set to one of the Equipment Flags EQ_XXX selected
from the following Table:


{| style="text-align: left; width: 90%; height: 90%; margin-left: 0px; margin-right: auto;background-color: azure" border="1" cellpadding="2" cellspacing="2"
===Number of subevents===
|-  style="text-align: center;"
This [[#Equipment List|Equipment List Parameter]] 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.)
| colspan="2" rowspan="1" style="vertical-align: top; font-weight:bold"| Equipment Types         
|  style="vertical-align: top; font-weight: bold;" | Explanation


'''<div id="EQ_PERIODIC"></div>'''
===Log History===
|-
This [[#Equipment List|Equipment List Parameter]] enables/disables the [[History System]] for that equipment. The value (positive in seconds) also controls how frequently the history events are generated. A reasonable value to set for the History value is "60", so that the history events are generated once per minute.
| EQ_PERIODIC
A positive value enables history logging, in which case the event data will also be sent automatically to the ODB in the
| Periodic Event
<span style="color: purple; font-style:italic;">/equipment/<equipment-name>/variables</span> tree.  
| In this mode no hardware requirement is necessary to @ref FE_tab_event_trigger "trigger" the readout function. Instead, the @ref FE_tbl_ReadoutRoutine "readout routine" associated with this equipment is called periodically.The @ref  FE_tbl_Period "Period" field in the equipment declaration is used in this case to specify the time interval between calls to the readout function.  See @ref FE_other_event "example".
The frequency of ODB writes is limited by ODB_UPDATE_TIME (1/sec in mfe.c rev 4298).
To disable history logging of this event, set this parameter to 0.  


'''<div id="EQ_POLLED"></div>'''
|-
|EQ_POLLED
|Polling Event
| In this mode,  the name of the routine performing the @ref FE_tab_event_trigger "trigger" check function is  @ref FE_poll_event "poll_event()". This routine must be provided in the frontend.c by the user.      As polling consists of checking a variable for a TRUE condition, if the loop count is infinite and the condition never becomes TRUE, the frontend would not be able to respond to any network commands. Therefore the loop count is determined when the frontend starts for the first time so that it returns
after a given time-out if no event is available.  This time-out is usually of the order of 500 milliseconds. <br> The EQ_POLLED equipment type is mainly used for
data acquisition based on a hardware condition becoming TRUE, at which time the @ref FE_tbl_ReadoutRoutine "readout routine" associated with the equipment is called. See  @ref FE_poll_event "example".


'''<div id="EQ_INTERRUPT"></div>'''
|-
| EQ_INTERRUPT
| Interrupt Event
| This modeis similar to the @ref FE_tbl_EqPolled "EQ_POLLED" mode except a hardware interrupt is used to @ref FE_tab_event_trigger "trigger" the event instead of a polling loop.  Instead of passing a pointer to the polling routine, in EQ_INTERRUPT mode a pointer to the <b> interrupt configuration routine </b> is passed to the system.  Midas requires complete configuration and control of the interrupt source. This is provided by an interrupt configuration routine called @ref  FE_interrupt_event "interrupt_configure()" that must be provided in the frontend.c by the user. When a valid interrupt is received, the @ref FE_tbl_ReadoutRoutine "readout routine" associated with the equipment is called.See  @ref FE_interrupt_event "example".


'''<div id="EQ_MULTITHREAD"></div>'''
<div id="EventTrigger"></div> <div id="ManualTriggerMode"></div>
|-
| EQ_MULTITHREAD
| Multithread Event Readout
| Thisequipment type implements themulti-threading capability within the frontend code. The polling isperformed within a separate thread and uses the@ref rbfunctionc "Midas Ring Buffer Functions" (rb_xxx) for inter-thread communication.EQ_MULTITHREAD is similar to @ref FE_tbl_EqPolled "EQ_POLLED" mode, except for the polling function which in the case of EQ_MULTITHREAD resides in a separate thread. This new type has been added to take advantage of the multi-core processor to free up CPU for tasks other than polling.


===Readout Routine===
This [[#Equipment List|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 [[Equipment List Parameters#Type|Type]] parameter.


'''<div id="EQ_SLOW"></div>'''
;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.
| EQ_SLOW
;periodic modes : trigger occurs periodically at a time interval specified by the [[Equipment List Parameters#Period|Period]] parameter.
| Slow Control Event
;manual trigger mode : trigger occurs when
| This flag declaresthe equipment as a Slow Control Equipment. This will enable the call tothe <b>idle</b> function part of the class driver. This flag also causes event data to be sent automatically to the /equipment/variables tree in the ODB.
:: 1. the manual trigger button is pressed on the web interface or
:: 2. a client requests an event by triggering the event via RPC.


See [[Frontend user code]] for details.


'''<div id="EQ_MANUAL_TRIG"></div>'''
|-
| EQ_MANUAL_TRIG
| Manual triggered event
| This flag enables the equipment to be @ref FE_Manual_trig_mode "triggered" by a remote procedure call (RPC). If EQ_MANUAL_TRIGGER is selected, the web interface will provide an extra button to trigger the equipment. The event may also be triggered by a client via RPC. @ref FE_manual_trigger "See example."




'''<div id="EQ_FRAGMENTED"></div>'''
===Class Driver===
|-
This [[#Equipment List|Equipment List Parameter]] must be present for all Equipments. This parameter is only for use by [[Slow Control System|Slow Control]] Equipments, i.e. when the  [[Equipment List Parameters#Type|Equipment Type]] is set to  [[Equipment Flags#EQ_SLOW|EQ_SLOW]]. For all other Types, this field is set to NULL.
| EQ_FRAGMENTED
| Fragmented Event
| Obsolescent flag EQ_FRAGMENTED enabled large events (beyond the Midas configuration limit) to be handled by the system (see note below). This flag required that a valid ''max_event_size_frag'' variable is defined in the user  [[Frontend Operation#Frontend|Frontend]] code. The ''max_event_size variable'' was used as fragment size in this case. This option was meant to be used in experiments where the event '''rate''' was not an issue but the  '''size''' of the data needed to be extremely large. @ref FE_fragmented_event "See example." 
The fragmented event mechanism is not to be confused with "event fragments" used by the [[Event Building|Event Builder]].


For [[Slow Control System|Slow Control]]  Equipments, this parameter is set to the main routine for the Class Driver of the hardware. See also [[#Device Driver List|Device Driver List]].


'''NOTE:'''
===Device Driver List===
: This flag was added for small memory cpus (e.g VxWorks PPC) to send very large events (beyond the Midas configuration limit) back to the host computer. With modern cpus that have large memory (e.g. VMIC), instead of using this flag, the '''buffer sizes should be increased''' to accommodate a large event (see [[Event Buffer]]). </span>


This [[#Equipment List|Equipment List Parameter]] must be present for all Equipments. This parameter is only for use by [[Slow Control System|Slow Control]] Equipments, i.e. when the  [[Equipment List Parameters#Type|Equipment Type]] is set to  [[Equipment Flags#EQ_SLOW|EQ_SLOW]]. For all other Types, this field is set to NULL.


'''<div id="EQ_EB"></div>'''
|-
| EQ_EB
| Event run through the event builder
| This flag identifies the equipment as a <b>fragment event</b>  and should be ORed with the EQ_POLLED in order to be identified by the \ref FE_Event_Builder. Not to be confused with a fragmented event (see above)!


|}
For [[Slow Control System|Slow Control]]  Equipments, 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. To turn on multithread support for a device, the flag DF_MULTITHREAD must be used in the frontend Device Driver List [https://midas.triumf.ca/elog/Midas/289].
 
==== Example of Slow Control Equipment ====
In a real frontend, the device driver "nulldev" has to be replaced with a real device driver.
 
Single thread
 
/* device driver list */
DEVICE_DRIVER hv_driver[] = {
  {"Dummy Device", nulldev, 16, null},
  {""}
};
 
 
;For multithread support
/* multithread device driver list */
DEVICE_DRIVER multi_driver[] = {
  {"Input", nulldev, 2, null, DF_INPUT | DF_MULTITHREAD},
  {"Output", nulldev, 2, null, DF_OUTPUT | DF_MULTITHREAD},
  {""}
};
 
 
The [[#Class Driver|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. In this case, the class driver is $MIDASSYS/drivers/class/hv.c which contains the routines cd_hv_read(..) and cd_hv(..).
 
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 [[#Equipment List|Equipment List 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|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 [[#Example Equipment List declaration| 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 [[Event Structure#FIXED Event Construction|FIXED format event construction]] for example of the use of the "init string" parameter.
 
[[Category:Equipment]] [[Category:Event]] [[Category:Frontend]]

Revision as of 09:46, 21 October 2019


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.

When the frontend is first run, it will create (using db_create_record) in the ODB /Equipment ODB tree (if they do not already exist) the <equipment-name> subdirectories for all equipments defined by the frontend. The initial values of many of the parameters in the ODB /Equipment/<equipment-name>/Common subtree are taken from the corresponding Equipment List.

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".

As of October 2019, you may use the string "${HOSTNAME}" in your equipment name, and the frontend framework will automatically substitute the name of your machine.

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.

The EventID (and the #TriggerMask) can be used to sort events into different streams, e.g. in Event Building or Event Filtering.

TriggerMask

This Equipment List Parameter can be used to sort events using a unique TriggerMask. It may be used when the Equipment Type is EQ_INTERRUPT or EQ_MULTITHREAD and/or in Event Building and Event Filtering to sort the events.

When in use, each equipment is associated with a unique TriggerMask. The TriggerMask can be modified dynamically by the Readout Routine e.g. 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. TriggerMasks are declared as 16-bit values. If the TriggerMask is used in a single bit-wise mode, 16 is the maximum number of different masks available.

Set TriggerMask to 0 if not used.

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 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 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 History System for that equipment. The value (positive in seconds) also controls how frequently the history events are generated. A reasonable value to set for the History value is "60", so that the history events are generated once per minute. 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. The frequency of ODB writes is limited by ODB_UPDATE_TIME (1/sec in mfe.c rev 4298). 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 triggering the event via RPC.

See Frontend user code for details.


Class Driver

This Equipment List Parameter must be present for all Equipments. This parameter is only for use by Slow Control Equipments, i.e. when the Equipment Type is set to EQ_SLOW. For all other Types, this field is set to NULL.

For Slow Control Equipments, this parameter is set to the main routine for the Class Driver of the hardware. See also Device Driver List.

Device Driver List

This Equipment List Parameter must be present for all Equipments. This parameter is only for use by Slow Control Equipments, i.e. when the Equipment Type is set to EQ_SLOW. For all other Types, this field is set to NULL.


For Slow Control Equipments, 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. To turn on multithread support for a device, the flag DF_MULTITHREAD must be used in the frontend Device Driver List [1].

Example of Slow Control Equipment

In a real frontend, the device driver "nulldev" has to be replaced with a real device driver.

Single thread

/* device driver list */
DEVICE_DRIVER hv_driver[] = {
  {"Dummy Device", nulldev, 16, null},
  {""}
};


For multithread support
/* multithread device driver list */
DEVICE_DRIVER multi_driver[] = {
  {"Input", nulldev, 2, null, DF_INPUT | DF_MULTITHREAD},
  {"Output", nulldev, 2, null, DF_OUTPUT | DF_MULTITHREAD},
  {""}
};


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. In this case, the class driver is $MIDASSYS/drivers/class/hv.c which contains the routines cd_hv_read(..) and cd_hv(..).

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 Equipment List 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.