Frontend user code: Difference between revisions

From MidasWiki
Jump to navigation Jump to search
No edit summary
(27 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Links
{{Pagelinks}}
==== Links ====
 
= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Frontend Operation]]
* [[Frontend Operation]]
* [[Frontend Application]]  
* [[Frontend Application]]  
* [[Equipment List Parameters]]
* [[Equipment List Parameters]]
* [[Slow Control System]]
* [[Equipment Flags]]
* [[Equipment Flags]]
* [[Event Notification (Hot-Link)]]
</div>
</div>


== Introduction==
= Introduction =
This section describes the features of the user-written part of a [[Frontend Operation#Frontend|Frontend]], referred to here as '''frontend.c'''. To make a custom frontend, users will usually modify one of the templates provided in the MIDAS package for their particular hardware and other requirements. A partial list of the templates provided is shown below:
This section describes the features of the user-written part of a [[Frontend Operation#Frontend|Frontend]], referred to here as '''frontend.c'''.  
 
= Frontend Templates =
To make a user-written or custom frontend, users will usually modify one of the '''templates''' provided in the MIDAS package
under [[Environment Variables#MIDASSYS|$MIDASSYS]]/examples/ for their particular hardware and other requirements. Make sure to pick the closest template, e.g. if writing a [[Slow Control System|Slow Control]] frontend, pick a slow-control template. For each example frontend, a Makefile is also provided.
 
A partial list of the templates provided is shown below:
{| style="text-align: left; width: 60%; background-color: rgb(255, 255, 255);" border="3" cellpadding="2" cellspacing="2"
{| style="text-align: left; width: 60%; background-color: rgb(255, 255, 255);" border="3" cellpadding="2" cellspacing="2"


Line 22: Line 31:
|VME  
|VME  
|fevmemodules.c
|fevmemodules.c
| ../midas/examples/Triumf/c/
| $MIDASSYS/examples/Triumf/c/
| Access to VME modules
| Access to VME modules
| C
| C
Line 29: Line 38:
|VME  
|VME  
|fevme.cxx
|fevme.cxx
| ../midas/examples/Triumf/c++/
| $MIDASSYS/examples/Triumf/c++/
| Access to VME modules
| Access to VME modules
| C++
| C++
Line 36: Line 45:
|CAMAC  
|CAMAC  
|frontend.c
|frontend.c
| ../midas/examples/experiment/
| $MIDASSYS/examples/experiment/
| Access to CAMAC modules
| Access to CAMAC modules
| C
| C
|-
|
|mtfe.c
| $MIDASSYS/examples/mtfe/
| '''Multithreaded''' using ring buffer
| C
|-
| Wiener CC-USB
|feccusb.cxx
| $MIDASSYS/examples/mtfe/
| CAMAC/USB demo
| C++


|-
|-
|RS485 bus  
|RS485 bus  
|mscb_fe.c
|mscb_fe.c
| ../midas/examples/slowcont/
| $MIDASSYS/examples/slowcont/
| Slow controls
| '''Slow control''' with [https://midas.psi.ch/mscb/ MSCB]
| C
| C


Line 50: Line 73:
|EPICS
|EPICS
|frontend.c
|frontend.c
| ../midas/examples/epics/
| $MIDASSYS/examples/epics/
| Slow controls
| '''Slow controls'''
| C
 
 
|-
|Camac
|ebfe.c
| $MIDASSYS/examples/eventbuilder/
| '''Event Builder''' (with [[mevb]])
| C
| C


Line 60: Line 91:
provided in the Midas Package.  
provided in the Midas Package.  


==Frontend code==
The following sections refer to the templates for user frontend code found in the MIDAS packages (see [[Introduction]]).


===Include files===
 
The following example (from template frontend file fevmemodules.c - see [[Introduction]]) shows the standard include files needed for VME access with VMIC. The user may add any other include files as needed. In this case, header files for several device drivers have also been added.  
=Frontend code=
The optional include file "experim.h" is often included. This is a special include file for ease of communication between the C code and the ODB, and is generated by the user (see [[experim.h]]). The example below shows a typical list of include files for a frontend:
Note that there are several kinds of frontend used for different purposes, e.g.
* frontend to read VME or CAMAC hardware, using interrupt or polling (e.g. to read experimental data)
* multithreaded frontend where polling can be in a separate thread
* slow control frontend (can be multithreaded) see also [[Slow Control System]]
* etc.
 
Templates for many types of user frontend code are provided in the MIDAS packages (see [[#Frontend Templates]]).
 
The following sections refer to these templates.
Most of the examples are taken from
[http://ladd00.triumf.ca/~daqweb/doc/midas/examples/Triumf/c/fevmemodules.c fevmemodules.c]. Documentation on the MIDAS library subroutines to access the ODB (some of which are used in the examples below) can be found at
[http://ladd00.triumf.ca/~daqweb/doc/midas/doc/html/group__odbfunctionc.html odb functions].
 
The user frontend code is then compiled and linked with the system part and the MIDAS library
(see [[Frontend Operation#Frontend|Frontend Task]]).  Makefiles are provided with the templates that can be modified as needed.
 
== Access to command line parameters ==
A new function '''mfe_get_args''' was created to allow the [[#frontend code|frontend code]] to have access to the [[Frontend Application|Frontend]] command line parameters.
 
This example shows how to use it in the frontend user code :
 
  int argc;
  char **argv; <br>
  mfe_get_args(&argc, &argv);
  for (int i=0 ; i<argc ; i++)
    puts(argv[i]);
 
 
 
==Include files==
The following example (from template frontend file ''fevmemodules.c'' - see [[#Frontend code|above]]) shows the standard include files needed for VME access with VMIC. The user may add any other include files as needed. In this case, header files for several device drivers have also been added.  
The optional file '''[[ODB#experim.h include file|experim.h]]''' is often included. This is a special include file for ease of communication between the C code and the ODB. The example ''fevmemodules.c'' includes <br>
http://ladd00.triumf.ca/~daqweb/doc/midas/examples/Triumf/c/experim.h. <br>
The file experim.h (except when using one of the examples) is generated by the user (see [[ODB#experim.h include file|experim.h]]). The example below shows a typical list of include files for a frontend:


  #include <stdio.h>    // C standard headers
  #include <stdio.h>    // C standard headers
Line 79: Line 141:
  #include "experim.h"  // user-created with odbedit make command
  #include "experim.h"  // user-created with odbedit make command


===Global declarations===
 
The following example (from template frontend file fevmemodules.c - see [[Introduction]]) shows the global declaration. The declarations are system wide.  Some may be changed to suit the user, but none should not be removed.
'''<div id="Frontend Name"></div>'''
==Global declarations==
The following example (from template frontend file fevmemodules.c - see [[#Frontend Templates]]) shows the global declaration. The declarations are system wide.  Some may be changed to suit the user, but none should not be removed.


; frontend_name  : This value can be modified to reflect the purpose of the code  
; frontend_name  : This value can be modified to reflect the purpose of the code  
Line 111: Line 175:




===Global User Declarations===
==Global User Declarations==


After the global declarations, the user may add his or her own declarations.
After the global declarations, the user may add his or her own declarations.
The following example  (from template frontend file fevmemodules.c - see [[Introduction]])  defines various VME hardware parameters.  
The following example  (from template frontend file fevmemodules.c - see [[#Frontend Templates]])  defines various VME hardware parameters.  
An example of hardware declarations in a frontend are shown below:
An example of hardware declarations in a frontend are shown below:


Line 131: Line 195:




===System Function Prototypes===
==System Function Prototypes==


These prototypes declare the pre-defined system functions which should be present.  
These prototypes declare the pre-defined system functions which should be present.  
Line 143: Line 207:




===Readout Function Prototypes===
==Readout Function Prototypes==
Following the previous group is a second group of prototypes, which define the readout functions. These depend on the defined equipments, and run when the respective equipment is triggered. In this example, two equipments will be defined, so there are two prototypes. The user functions will be described in detail in the following sections.  
Following the previous group is a second group of prototypes, which define the readout functions. These depend on the defined equipments, and run when the respective equipment is triggered. In this example, two equipments will be defined, so there are two prototypes. The user functions will be described in detail in the following sections.  


Line 156: Line 220:




===Bank Definition and Equipment List===
==Bank Definition and Equipment List==


See [[Equipment List Parameters#Bank Definition|Bank Definitions]] and [[Equipment List Parameters|Equipment List]] for detailed information.
See [[Equipment List Parameters#Bank Definition|Bank Definitions]] and [[Equipment List Parameters|Equipment List]] for detailed information.
Line 162: Line 226:
However, this may be easier to follow if first the sequence of operations, and examples of the the different types of events (polled/interrupt or periodic etc.) and the functions they require in the frontend are introduced.
However, this may be easier to follow if first the sequence of operations, and examples of the the different types of events (polled/interrupt or periodic etc.) and the functions they require in the frontend are introduced.


===Sequence of Operations in the frontend===
==Sequence of Operations in the frontend==


The following table shows the sequence of operations of the  [[Frontend Operation#Frontend|Frontend]] System functions.  These subroutines must be present in ''frontend.c'',
The following table shows the sequence of operations of the  [[Frontend Operation#Frontend|Frontend]] System functions.  These subroutines must be present in ''frontend.c'',
Line 217: Line 281:
The system transition functions all run '''prior to''' the equipment functions. This gives the system the chance to take basic action on the transition request (e.g. enable/disable interrupt) before the equipment runs. All the transition routines run with a [[Run States and Transitions#Default Transition Sequency Numbers|Transition Sequence number]] of 500 (the default). This allows users to add additional functions in the frontend that will run before or after any of the transitions (such as a prestart() or a poststop() function). See [[Run States and Transitions#Run Transition Priority|Run Transition Priority]] for more information.
The system transition functions all run '''prior to''' the equipment functions. This gives the system the chance to take basic action on the transition request (e.g. enable/disable interrupt) before the equipment runs. All the transition routines run with a [[Run States and Transitions#Default Transition Sequency Numbers|Transition Sequence number]] of 500 (the default). This allows users to add additional functions in the frontend that will run before or after any of the transitions (such as a prestart() or a poststop() function). See [[Run States and Transitions#Run Transition Priority|Run Transition Priority]] for more information.


===Function frontend_init ===
==Function frontend_init ==




No parameters.
No parameters.


This function runs '''once only''' at the application startup. Users may perform hardware checking, loading/setting of global variables, hot-link settings to the ODB etc. in frontend_init(), e.g.
This function runs '''once only''' at the application startup. Users may perform hardware checking, loading/setting of global variables, mapping of required ODB structures (see [[ODB#experim.h include file|experim.h include file]]),
[[Event Notification (Hot-Link)#How to set up a Hot-Link|setting up hot-links]] etc. in frontend_init(), e.g.




Line 229: Line 294:
   set_equipment_status(equipment[idx].name, "Initializing...", "yellow");
   set_equipment_status(equipment[idx].name, "Initializing...", "yellow");
   ....
   ....
        <br>
/* Book Setting space */
  TRIGGER_SETTINGS_STR(trigger_settings_str);
        <br>
  /* Map /equipment/Trigger/settings (structure defined in experim.h) */
  sprintf(set_str, "/Equipment/Trigger/Settings");
  status = db_create_record(hDB, 0, set_str, strcomb(trigger_settings_str));
  status = db_find_key (hDB, 0, set_str, &hSet);
  if (status != DB_SUCCESS)
    cm_msg(MINFO,"FE","Key %s not found", set_str);
  return status;
        <br>
        <br>
   // Open VME interface
   // Open VME interface
   status = mvme_open(&myvme, 0);
   status = mvme_open(&myvme, 0);
                                  //
          <br>                               
   // Set am to A24 non-privileged Data
   // Set am to A24 non-privileged Data
   mvme_set_am(myvme, MVME_AM_A24_ND);
   mvme_set_am(myvme, MVME_AM_A24_ND);
                                  //
              <br>                           
   // Set dmode to D32
   // Set dmode to D32
   mvme_set_dmode(myvme, MVME_DMODE_D32)
   mvme_set_dmode(myvme, MVME_DMODE_D32)
   ....
   ....
                                  //
                          <br>                 
   set_equipment_status(equipment[idx].name, "OK", "green");
   set_equipment_status(equipment[idx].name, "OK", "green");
   return SUCCESS;
   return SUCCESS;
Line 244: Line 322:




====Reporting Equipment Status====
===Reporting Equipment Status===
If running with run control utility mhttpd, a frontend can send an update to the main status page, to report on its progress, using the function set_equipment_status (see above example). This is useful when hardware can take a long time to respond.
If running with the webserver [[mhttpd]], a frontend can send an update to the [[Status Page]], to report on its progress, using the function set_equipment_status() (see above example). This is useful when hardware can take a long time to respond.




===Function begin_of_run===
==Function begin_of_run==


Parameters:
Parameters:
Line 259: Line 337:
  INT begin_of_run (INT runnumber, char * error)
  INT begin_of_run (INT runnumber, char * error)
  {
  {
   ......
   INT status;
  status = update_user_parameters(); // update parameters from ODB
        <br>
   // Set am to A24 non-privileged Data
   // Set am to A24 non-privileged Data
   mvme_set_am(myvme, MVME_AM_A24_ND);
   mvme_set_am(myvme, MVME_AM_A24_ND);
   // Set dmode to D32
   // Set dmode to D32
   mvme_set_dmode(myvme, MVME_DMODE_D32);
   mvme_set_dmode(myvme, MVME_DMODE_D32);
                                      //
                  <br>                           
   //-------- ADCs -------------------
   //-------- ADCs -------------------
   v792_Setup(myvme, VADC0_BASE, 2);
   v792_Setup(myvme, VADC0_BASE, 2);
Line 285: Line 365:
  }
  }


=== Accessing variables from the ODB ===
The  [http://ladd00.triumf.ca/~daqweb/doc/midas/doc/html/group__odbfunctionc.html MIDAS library] contains a number of subroutines to access the ODB.  The ODB keys can easily be accessed from a frontend or other client individually, or by using a saved C structure, which is often used when a large number of keys are to be accessed.
==== Using C structure ====
<div id="get_user_parameters"></div>
The function get_user_parameters() relies on the ODB structure <span style="color: purple; font-style:italic;">/Equipment/Trigger/settings</span> being mapped in
[[#Function frontend_init|frontend_init()]] with db_create_record() to ensure that the required ODB structure is present. Then the contents of the ODB keys can be obtained from the C structure (defined in
[[#Include files|experim.h]]) with a db_get_record() call, as demonstrated in the following example:
INT get_user_parameters(void)
{
  INT status,size;
  TRIGGER_SETTINGS ps;  // defined in experim.h
              <br>
  /* Get current  settings */
  size = sizeof(ps);
  status = db_get_record(hDB, hSet, &ps, &size, 0); // HNDLE hSet obtained in frontend_init()
  if (status != DB_SUCCESS)
    {
      cm_msg(MERROR, "get_exp_settings", "cannot retrieve trigger settings record (size of ps=%d)", size);
      return status;
    }
  // Access the required ODB keys in the /equipment/trigger/settings/ subtree from the C structure
  printf("Trigger mode = %s \n", ps.trig_mode);
  printf("Trigger delay (ms)= %f \n",ps.trigger_delay_time__ms_);
  ...
  set_trig_delay(ps.trigger_delay_time__ms_);
  return SUCCESS;
}
If a number of values in this structure are changed by the frontend, they can be written back into the ODB with one library call, i.e. db_set_record(..).
==== Accessing individual keys ====
If experim.h is not included, parameters can be accessed from the ODB using db_get_value() or db_get_data().
  char hostname[20];
  char str[128];
  int size,status;
  /* Get the camp hostname from the mdarc area of odb  */
  size = sizeof(hostname);
  sprintf(str,"/Equipment/%s/mdarc/camp/camp hostname",equipment[FIFO].name);
  status = db_get_value(hDB, 0, str, hostname, &size, TID_STRING, FALSE);
  if(status != DB_SUCCESS)
  {
    cm_msg(MERROR,"camp_update_params","cannot get Camp hostname at %s (%d)",str,status);
    return FE_ERR_ODB;
  }
Values can be written into the ODB using db_set_value() or db_set_data().


Note that all the ODB access functions mentioned here can be found in the  [http://ladd00.triumf.ca/~daqweb/doc/midas/doc/html/group__odbfunctionc.html MIDAS library], and more examples can be found in the midas package e.g. under ../midas/examples/ .


===Functions pause/resume_run===
==Functions pause/resume_run==


Parameters:
Parameters:
Line 313: Line 443:
  }
  }


===Function end_run===
==Function end_run==


Parameters:
Parameters:
Line 338: Line 468:




===Function frontend_exit===
==Function frontend_exit==


Parameters: none
Parameters: none
Line 350: Line 480:
   }
   }


===Function frontend_loop===
==Function frontend_loop==


Parameters: none
Parameters: none
Line 381: Line 511:




===Event Types and Triggers===
==Event Types and Triggers==
The frontend supports several different types of [[Frontend Operation#Frontend event triggers|event trigger]]. The event trigger type is specified by the  
The frontend supports several different types of [[Frontend Operation#Frontend event triggers|event trigger]]. The event trigger type is specified by the  
[[Equipment Flags|Equipment Flag]]  in the  [[Equipment List Parameters|Equipment Declaration]]. Common event types are "polled events" where the Equipment Flag is  [[Equipment Flags#EQ_POLLED|EQ_POLLED]], "interrupts events" where the Flag is [[Equipment Flags#EQ_INTERRUPT|EQ_INTERRUPT]], and "periodic events" where the Flag is [[Equipment Flags#EQ_PERIODIC|EQ_PERIODIC]]. The name of the associated readout routine is specified in the [[Equipment List Parameters|Equipment Declaration]] for each event type.
[[Equipment Flags|Equipment Flag]]  in the  [[Equipment List Parameters|Equipment Declaration]]. Common event types are "polled events" where the Equipment Flag is  [[Equipment Flags#EQ_POLLED|EQ_POLLED]], "interrupts events" where the Flag is [[Equipment Flags#EQ_INTERRUPT|EQ_INTERRUPT]], and "periodic events" where the Flag is [[Equipment Flags#EQ_PERIODIC|EQ_PERIODIC]]. The name of the associated readout routine is specified in the [[Equipment List Parameters|Equipment Declaration]] for each event type.
Line 388: Line 518:




===Function poll_event===
==Function poll_event==
Parameters:
Parameters:
* INT '''source'''
* INT '''source'''
Line 402: Line 532:
         {
         {
           ...
           ...
           <span style="color:red">EQ_POLLED</span>,          // equipment type
           <b>EQ_POLLED</b>,          // equipment type
           ...
           ...
           500,                // poll for 500ms  
           500,                // poll for 500ms  
Line 432: Line 562:




===Function interrupt_configure===
==Function interrupt_configure==
* INT '''cmd'''  
* INT '''cmd'''  
* INT '''source'''
* INT '''source'''
Line 475: Line 605:
An [[#Event Readout routine|event readout routine]] must also be provided by the user in the frontend.
An [[#Event Readout routine|event readout routine]] must also be provided by the user in the frontend.


===Event Readout routine===
==Event Readout routine==
In the case of [[#Polled and Interrupt Events|POLLED or INTERRUPT events]], the event readout routine is called an [[#Polled or Interrupt readout routine|Interrupt readout routine]].
In the case of [[#Polled and Interrupt Events|POLLED or INTERRUPT events]], the event readout routine is called an [[#Polled or Interrupt readout routine|Interrupt readout routine]].


Line 496: Line 626:




====Polled or Interrupt readout routine====
===General readout function===
If the Equipment type is EQ_INTERRUPT or EQ_POLLED, see also [[#Polled or Interrupt readout routine|Polled or Interrupt readout routine]].
 
 
In the case of a '''periodic''' event, the Equipment declaration may have this form:
 
    EQUIPMENT equipment[] = {
      { "Scaler",          // equipment name
        {   
            ...
            EQ_PERIODIC    // equipment type
            0,              // interrupt source (ignored)
            "MIDAS",        // event format
            ...
            10000,          // period (read every 10s)
            ...
            "", "", "",},
      read_scaler_event,  // readout routine
      ...
 
A readout event will often need to send out data. This is done using one of the supported [[Event Structure|event structures]] usually [[Event Structure#MIDAS Format Event|"MIDAS" format]] data banks.  The bank format ("MIDAS" in the example above) is declared in the [[Equipment List Parameters]]  [[Equipment List Parameters#Format|Format]] field.
 
An example of a scaler readout routine read_scaler_event() where the data is read out into [[MIDAS Event Construction|MIDAS data banks]] is shown below.
 
INT read_scaler_event(char *pevent, INT off)
{
    DWORD *pdata, a;
                              //
    /* init bank structure; */
    bk_init(pevent);
                              //
    /* create SCLR bank */
    bk_create(pevent, "SCLR", TID_DWORD, &pdata);
                              //
    /* read scaler bank (CAMAC) */
    for (a = 0; a < N_SCLR; a++)
      cam24i(CRATE, SLOT_SCLR, a, 0, pdata++);
                              //   
    /* close SCLR bank */
    bk_close(pevent, pdata);
                              //
    /* return event size in bytes */
    return bk_size(pevent);
}
 
Some other examples of event readout routines in this document are
* [[Event Structure#FIXED Event Construction|FIXED Format event construction]]
* [[#Polled or Interrupt readout routine|Polled or Interrupt readout routines]]
* [[Super Event]] construction
* [[Slow Control System|Slow Control]]
 
Many other examples of readout routines can be found in the [[#Frontend Templates|frontend templates]] in the MIDAS package.
 
===Polled or Interrupt readout routine===
In the case of a [[#Polled and Interrupt Events|Polled or Interrupt event]], the content of the memory location pointed to by '''pevent''' (see [[#Event Readout routine|Event Readout routine]]) prior to its use in the readout function, contains the interrupt source bitwise register. This feature can be exploited in order to identify which hardware module has triggered the readout when multiple interrupts have been assigned to the same readout function.
In the case of a [[#Polled and Interrupt Events|Polled or Interrupt event]], the content of the memory location pointed to by '''pevent''' (see [[#Event Readout routine|Event Readout routine]]) prior to its use in the readout function, contains the interrupt source bitwise register. This feature can be exploited in order to identify which hardware module has triggered the readout when multiple interrupts have been assigned to the same readout function.


Line 521: Line 704:
  }
  }
    
    
Note that the LAM_SOURCE macro simply codes the parameters into a bitwise register.
Note that the [[Macros#CAMAC Macros|LAM_SOURCE macro]] simply codes the parameters into a bitwise register.


The readout routine would contains code such as
The readout routine would contains code such as
Line 545: Line 728:
  }
  }


The examples fevmemodules.c (VME) and frontend.c (CAMAC) (see [[#Introduction|Introduction]] contain a complete example of read_trigger_event().
The data will be packed into banks as described for the [[General readout function|general readout function]] above.
 
The examples fevmemodules.c (VME) and frontend.c (CAMAC) (see [[#Frontend Templates]] contain a complete example of read_trigger_event().
 
====General readout function====
If the Equipment type is '''not''' EQ_INTERRUPT or EQ_POLLED (see  [[#Polled and Interrupt Events|Polled or Interrupt event]]) the readout routine is the only event routine that the user needs to provide in frontend.c .


In this case (e.g. a periodic event) the Equipment declaration may have this form:


    EQUIPMENT equipment[] = {
      { "Scaler",          // equipment name
        {   
            ...
            EQ_PERIODIC    // equipment type
            0,              // interrupt source (ignored)
            ...
            10000,          // period (read every 10s)
            ...
            "", "", "",},
      read_scaler_event,  // readout routine
      ...


An example of a scaler readout routine read_scaler_event() where the data is read out into data banks is shown below.
==Manual Trigger==
 
Another type of [[Frontend Operation#Frontend event trigger|frontend event trigger]] supported is the "manual trigger",  where the Equipment Flag is [[Equipment Flags#EQ_MANUAL_TRIGGER|EQ_MANUAL_TRIGGER]]. This flag means that an event can be triggered through the URL <code>?cmd=Trigger/<equipment_name></code> (e.g. <code>http://my.host:8080/?cmd=Trigger/MyEquipmentName</code>). If you add this URL to the [[/Alias ODB tree|/Alias]] part of the ODB, then a link will appear on midas webpages that can be clicked to trigger an event.
INT read_scaler_event(char *pevent, INT off)
{
    DWORD *pdata, a;
                              //
    /* init bank structure */
    bk_init(pevent);
                              //
    /* create SCLR bank */
    bk_create(pevent, "SCLR", TID_DWORD, &pdata);
                              //
    /* read scaler bank (CAMAC) */
    for (a = 0; a < N_SCLR; a++)
      cam24i(CRATE, SLOT_SCLR, a, 0, pdata++);
                              //   
    /* close SCLR bank */
    bk_close(pevent, pdata);
                              //
    /* return event size in bytes */
    return bk_size(pevent);
}
 
 
===Manual Trigger===
Another type of [[Frontend Operation#Frontend event trigger|frontend event trigger]] supported is the "manual trigger",  where the Equipment Flag is [[Equipment Flags#EQ_MANUAL_TRIGGER|EQ_MANUAL_TRIGGER]]. This flag causes an extra button to be present on the [[mhttpd]] web interface to enable the user to trigger the event.


In some cases, the same readout code may be used for two types of event: a manual trigger and (say) a poll event. It is possible to determine whether the readout of an event was triggered by a manual trigger or a regular trigger by adding a call to the  [[MIDAS Event Header Macros|event header Macro]] DATA_SIZE in the readout routine:
In some cases, the same readout code may be used for two types of event: a manual trigger and (say) a poll event. It is possible to determine whether the readout of an event was triggered by a manual trigger or a regular trigger by adding a call to the  [[MIDAS Event Header Macros|event header Macro]] DATA_SIZE in the readout routine:
Line 657: Line 800:
  }
  }


 
==Deferred Transition==
===Deferred Transistion===
This option permits the user to postpone any transition issued by any requester
This option permits the user to postpone any transition issued by any requester
until some condition is satisfied.
until some condition is satisfied.
Line 733: Line 875:


or  <span style="color: purple; font-style:italic;">/runinfo/Requested transition</span> can be set to 0. The transition will then take place on the next stop or start command.
or  <span style="color: purple; font-style:italic;">/runinfo/Requested transition</span> can be set to 0. The transition will then take place on the next stop or start command.
= Compilation using CMake =
Here is a "minimal" CMakeLists.txt file that can be used to compile a user-written frontend (called "myfe" in this case) that uses the mfe framework.
  cmake_minimum_required(VERSION 3.0)
  project(myfe)
 
  # Check for MIDASSYS environment variable
  if (NOT DEFINED ENV{MIDASSYS})
    message(SEND_ERROR "MIDASSYS environment variable not defined.")
  endif()
 
  set(CMAKE_CXX_STANDARD 11)
  set(MIDASSYS $ENV{MIDASSYS})
 
  if (${CMAKE_SYSTEM_NAME} MATCHES Linux)
    set(LIBS -lpthread -lutil -lrt)
  endif()
 
  # Define the executable to be built, and the source code files
  add_executable(myfe.exe myfe.cxx)
 
  # Directories to search for
  target_include_directories(myfe.exe PRIVATE ${MIDASSYS}/include)
 
  # Libraries to link to
  target_link_libraries(myfe.exe ${MIDASSYS}/lib/libmfe.a ${MIDASSYS}/lib/libmidas.a ${LIBS})
One could then build the executable using the folllowing commands:
  mkdir build
  cd build
  cmake ..
  make
Some older operating systems may require the "cmake3" command to be used instead of "cmake".
[[Category:Frontend]]

Revision as of 14:25, 25 September 2020


Links

Introduction

This section describes the features of the user-written part of a Frontend, referred to here as frontend.c.

Frontend Templates

To make a user-written or custom frontend, users will usually modify one of the templates provided in the MIDAS package under $MIDASSYS/examples/ for their particular hardware and other requirements. Make sure to pick the closest template, e.g. if writing a Slow Control frontend, pick a slow-control template. For each example frontend, a Makefile is also provided.

A partial list of the templates provided is shown below:

Hardware Filename Directory (MIDAS package) Purpose Language
VME fevmemodules.c $MIDASSYS/examples/Triumf/c/ Access to VME modules C
VME fevme.cxx $MIDASSYS/examples/Triumf/c++/ Access to VME modules C++
CAMAC frontend.c $MIDASSYS/examples/experiment/ Access to CAMAC modules C
mtfe.c $MIDASSYS/examples/mtfe/ Multithreaded using ring buffer C
Wiener CC-USB feccusb.cxx $MIDASSYS/examples/mtfe/ CAMAC/USB demo C++
RS485 bus mscb_fe.c $MIDASSYS/examples/slowcont/ Slow control with MSCB C
EPICS frontend.c $MIDASSYS/examples/epics/ Slow controls C


Camac ebfe.c $MIDASSYS/examples/eventbuilder/ Event Builder (with mevb) C


The features of a typical frontend program are best explained by reference to examples of the user code provided in the Midas Package.


Frontend code

Note that there are several kinds of frontend used for different purposes, e.g.

  • frontend to read VME or CAMAC hardware, using interrupt or polling (e.g. to read experimental data)
  • multithreaded frontend where polling can be in a separate thread
  • slow control frontend (can be multithreaded) see also Slow Control System
  • etc.

Templates for many types of user frontend code are provided in the MIDAS packages (see #Frontend Templates).

The following sections refer to these templates. Most of the examples are taken from fevmemodules.c. Documentation on the MIDAS library subroutines to access the ODB (some of which are used in the examples below) can be found at odb functions.

The user frontend code is then compiled and linked with the system part and the MIDAS library (see Frontend Task). Makefiles are provided with the templates that can be modified as needed.

Access to command line parameters

A new function mfe_get_args was created to allow the frontend code to have access to the Frontend command line parameters.

This example shows how to use it in the frontend user code :

 int argc;
 char **argv; 
mfe_get_args(&argc, &argv); for (int i=0 ; i<argc ; i++) puts(argv[i]);


Include files

The following example (from template frontend file fevmemodules.c - see above) shows the standard include files needed for VME access with VMIC. The user may add any other include files as needed. In this case, header files for several device drivers have also been added. The optional file experim.h is often included. This is a special include file for ease of communication between the C code and the ODB. The example fevmemodules.c includes
http://ladd00.triumf.ca/~daqweb/doc/midas/examples/Triumf/c/experim.h.
The file experim.h (except when using one of the examples) is generated by the user (see experim.h). The example below shows a typical list of include files for a frontend:

#include <stdio.h>     // C standard headers
#include <stdlib.h>
#include "midas.h"     // MIDAS include file
#include "mvmestd.h"   // VME header file
#include "vmicvme.h"   // VMIC header file
#include "vmeio.h"     // optional hardware header files
#include "v1190B.h"
#include "v792.h"
#include "vf48.h"
#include "v1729.h"
#include "experim.h"   // user-created with odbedit make command


Global declarations

The following example (from template frontend file fevmemodules.c - see #Frontend Templates) shows the global declaration. The declarations are system wide. Some may be changed to suit the user, but none should not be removed.

frontend_name
This value can be modified to reflect the purpose of the code
frontend_call_loop
If set to TRUE, the function frontend_loop() runs after every equipment loop. If FALSE, frontend_loop() does not run. The user can add suitable code to this routine if desired (e.g. to check for a condition).
display_period
The time interval (defined in milliseconds) between the refresh of a frontend status display. The value of zero disables the display. If the frontend is started in the background with the display enabled, the stdout should be redirected to the null device to prevent the process from hanging.
max_event_size
specifies the maximum size (in bytes) of the expected event.
event_buffer_size
specifies the maximum size (in bytes) of the buffer to be allocated by the system.

See below for an example of global declarations from a frontend.

/* The frontend name (client name) as seen by other MIDAS clients   */
char *frontend_name = "fevmemodules";
/* The frontend file name, don't change it */
char *frontend_file_name = __FILE__;
                                                                    //
/* frontend_loop is called periodically if this variable is TRUE    */
BOOL frontend_call_loop = FALSE;
                                                                    //
/* a frontend status page is displayed with this frequency in ms */
INT display_period = 000;
                                                                    //
/* maximum event size produced by this frontend */
INT max_event_size = 200000;
                                                                    //
/* maximum event size for fragmented events (EQ_FRAGMENTED) */
INT max_event_size_frag = 5 * 1024 * 1024;
                                                                    //
/* buffer size to hold events */
INT event_buffer_size = 10 * 100000;


Global User Declarations

After the global declarations, the user may add his or her own declarations. The following example (from template frontend file fevmemodules.c - see #Frontend Templates) defines various VME hardware parameters. An example of hardware declarations in a frontend are shown below:

/* Hardware */
MVME_INTERFACE *myvme;
                     //
/* VME base addresses */
DWORD VMEIO_BASE = 0x780000;
DWORD VTDC0_BASE = 0xF10000;
.......
/* Globals */
#define  N_ADC 100
#define  N_TDC 100
#define  N_PTS 5000


System Function Prototypes

These prototypes declare the pre-defined system functions which should be present.

INT frontend_init();
INT frontend_exit();
INT begin_of_run(INT run_number, char *error);
INT end_of_run(INT run_number, char *error);
INT pause_run(INT run_number, char *error);
INT resume_run(INT run_number, char *error);
INT frontend_loop();


Readout Function Prototypes

Following the previous group is a second group of prototypes, which define the readout functions. These depend on the defined equipments, and run when the respective equipment is triggered. In this example, two equipments will be defined, so there are two prototypes. The user functions will be described in detail in the following sections.

INT read_trigger_event(char *pevent, INT off);
INT read_scaler_event(char *pevent, INT off);

If using an interrupt, callback function prototypes are also included

extern void interrupt_routine(void);
void register_cnaf_callback(int debug);


Bank Definition and Equipment List

See Bank Definitions and Equipment List for detailed information.

However, this may be easier to follow if first the sequence of operations, and examples of the the different types of events (polled/interrupt or periodic etc.) and the functions they require in the frontend are introduced.

Sequence of Operations in the frontend

The following table shows the sequence of operations of the Frontend System functions. These subroutines must be present in frontend.c, but the contents are coded by the user. These functions are called by mfe.c at the appropriate time. The System Transition functions are associated with a particular Run Transition as shown below:

System Function System Transition Function Associated Transition Action
frontend_init() Runs once after system initialization, before Equipment registration.
begin_of_run() TR_START Runs after system statistics reset at each begin-of-run request.
pause_run() TR_PAUSE Runs at each pause-run request.
resume_run() TR_RESUME Runs at each resume-run request.
end_of_run() TR_STOP Runs at each end-of-run request.
frontend_exit() Runs once before any Slow Control Equipment exit


Each defined Equipment has the option to force itself to run at individual transition times (see Equipment ReadOn Flag), so that its equipment function will be called on a certain transition (or combination of transitions).

The system transition functions all run prior to the equipment functions. This gives the system the chance to take basic action on the transition request (e.g. enable/disable interrupt) before the equipment runs. All the transition routines run with a Transition Sequence number of 500 (the default). This allows users to add additional functions in the frontend that will run before or after any of the transitions (such as a prestart() or a poststop() function). See Run Transition Priority for more information.

Function frontend_init

No parameters.

This function runs once only at the application startup. Users may perform hardware checking, loading/setting of global variables, mapping of required ODB structures (see experim.h include file), setting up hot-links etc. in frontend_init(), e.g.


INT frontend_init()
{
  set_equipment_status(equipment[idx].name, "Initializing...", "yellow");
  ....
        
/* Book Setting space */ TRIGGER_SETTINGS_STR(trigger_settings_str);
/* Map /equipment/Trigger/settings (structure defined in experim.h) */ sprintf(set_str, "/Equipment/Trigger/Settings"); status = db_create_record(hDB, 0, set_str, strcomb(trigger_settings_str)); status = db_find_key (hDB, 0, set_str, &hSet); if (status != DB_SUCCESS) cm_msg(MINFO,"FE","Key %s not found", set_str); return status;

// Open VME interface status = mvme_open(&myvme, 0);
// Set am to A24 non-privileged Data mvme_set_am(myvme, MVME_AM_A24_ND);
// Set dmode to D32 mvme_set_dmode(myvme, MVME_DMODE_D32) ....
set_equipment_status(equipment[idx].name, "OK", "green"); return SUCCESS; }


Reporting Equipment Status

If running with the webserver mhttpd, a frontend can send an update to the Status Page, to report on its progress, using the function set_equipment_status() (see above example). This is useful when hardware can take a long time to respond.


Function begin_of_run

Parameters:

  • INT run number provides the number of the current run being started
  • char * error can be used for returning a message to the system. This message string will be logged into the midas.log file (see Message System.

This function is called every time a run start transition occurs, i.e. at begin-of-run. It allows the updating of user parameters, and the loading/setup/clearing of hardware. At the exit of this function, the acquisition should be armed and ready to test the interrupt (if used), e.g.


INT begin_of_run (INT runnumber, char * error)
{
  INT status;
  status = update_user_parameters(); // update parameters from ODB
        
// Set am to A24 non-privileged Data mvme_set_am(myvme, MVME_AM_A24_ND); // Set dmode to D32 mvme_set_dmode(myvme, MVME_DMODE_D32);
//-------- ADCs ------------------- v792_Setup(myvme, VADC0_BASE, 2); v792_ThresholdWrite(myvme, VADC0_BASE, (WORD *)&(ts.v792.threshold1)); v792_DataClear(myvme, VADC0_BASE); csr = v792_CSR1Read(myvme, VADC0_BASE); printf("Data Ready ADC0: 0x%x\n", csr); ........ // Disable interrupt mvme_write_value(myvme, VLAM_BASE+4, 0x0); // Reset Latch mvme_write_value(myvme, VLAM_BASE, 0x1); // Clear pending interrupts mvme_write_value(myvme, VLAM_BASE+8, 0x0); // Enable interrupt inRun = 1; mvme_write_value(myvme, VLAM_BASE+4, inRun); return SUCCESS; }

Accessing variables from the ODB

The MIDAS library contains a number of subroutines to access the ODB. The ODB keys can easily be accessed from a frontend or other client individually, or by using a saved C structure, which is often used when a large number of keys are to be accessed.

Using C structure

The function get_user_parameters() relies on the ODB structure /Equipment/Trigger/settings being mapped in frontend_init() with db_create_record() to ensure that the required ODB structure is present. Then the contents of the ODB keys can be obtained from the C structure (defined in experim.h) with a db_get_record() call, as demonstrated in the following example:

INT get_user_parameters(void)
{
 INT status,size;
 TRIGGER_SETTINGS ps;  // defined in experim.h
              
/* Get current settings */ size = sizeof(ps); status = db_get_record(hDB, hSet, &ps, &size, 0); // HNDLE hSet obtained in frontend_init() if (status != DB_SUCCESS) { cm_msg(MERROR, "get_exp_settings", "cannot retrieve trigger settings record (size of ps=%d)", size); return status; } // Access the required ODB keys in the /equipment/trigger/settings/ subtree from the C structure printf("Trigger mode = %s \n", ps.trig_mode); printf("Trigger delay (ms)= %f \n",ps.trigger_delay_time__ms_); ... set_trig_delay(ps.trigger_delay_time__ms_); return SUCCESS; }

If a number of values in this structure are changed by the frontend, they can be written back into the ODB with one library call, i.e. db_set_record(..).

Accessing individual keys

If experim.h is not included, parameters can be accessed from the ODB using db_get_value() or db_get_data().

  char hostname[20];
  char str[128];
  int size,status;
 /* Get the camp hostname from the mdarc area of odb  */
 size = sizeof(hostname); 
 sprintf(str,"/Equipment/%s/mdarc/camp/camp hostname",equipment[FIFO].name); 
 status = db_get_value(hDB, 0, str, hostname, &size, TID_STRING, FALSE);
 if(status != DB_SUCCESS)
 {
   cm_msg(MERROR,"camp_update_params","cannot get Camp hostname at %s (%d)",str,status);
   return FE_ERR_ODB;
 }

Values can be written into the ODB using db_set_value() or db_set_data().

Note that all the ODB access functions mentioned here can be found in the MIDAS library, and more examples can be found in the midas package e.g. under ../midas/examples/ .

Functions pause/resume_run

Parameters:

  • INT run number provides the number of the current run being paused/resumed.
  • char * error can be used for returning a message to the system. This message string will be logged into the midas.log file (see Message System.

These two functions are called upon "Pause" and "Resume" command respectively. Any code relevant to the upcoming run state can be included,e.g.


INT pause_run (INT run_number, char * error)
{
  disable_trigger();
  // Disable interrupt
  inRun = 0;
  mvme_write_value(myvme, VLAM_BASE+4, inRun);
  return SUCCESS;
}
                           //
INT resume_run (INT run_number, char * error)
{
  enable_trigger();
  inRun = 1;
  mvme_write_value(myvme, VLAM_BASE+4, inRun);
  return SUCCESS;
}

Function end_run

Parameters:

  • INT run number provides the number of the current run being ended.
  • char * error can be used for returning a message to the system. This message string will be logged into the midas.log file (see Message System.

This function is called at every "stop run" transition. It provides the opportunity to disable the hardware, e.g.

INT end_of_run(INT run_number, char *error)
{
  // Stop DAQ for seting up the parameters
  vf48_AcqStop(myvme, VF48_BASE);
                      //
  done = 0;
  stop_req = 0;
  inRun = 0;
  // Disable interrupt
  mvme_write_value(myvme, VLAM_BASE+4, inRun);
  trig_level = 0;
  // Close run gate
  vmeio_AsyncWrite(myvme, VMEIO_BASE, 0x0);
  return SUCCESS;
}


Function frontend_exit

Parameters: none

The function runs When the frontend program is shut down. Can be used to release any locked resources like memory, communications ports etc. e.g.

 function frontend_exit()
 {
    mvme_close(gVme);
    return;
 }

Function frontend_loop

Parameters: none

If the flag frontend_call_loop is set TRUE, this routine is called when the frontend is idle or once between every event. In the following example, it is being used to check for a timeout:

...
BOOL frontend_call_loop = TRUE;
...
                                //
INT frontend_loop()
{
  char str[128];
                  //
  if (stop_req && done==0) {
     db_set_value(hDB,0,"/logger/channels/0/Settings/Event limit", &evlimit, sizeof(evlimit), 1, TID_DWORD);
     if (cm_transition(TR_STOP, 0, str, sizeof(str), ASYNC, FALSE) != CM_SUCCESS) {
        cm_msg(MERROR, "VF48 Timeout", "cannot stop run: %s", str);
     }
     inRun = 0;
     // Disable interrupt
     mvme_write_value(myvme, VLAM_BASE+4, inRun);
     done = 1;
     cm_msg(MERROR, "VF48 Timeout","VF48 Stop requested");
  }
  return SUCCESS;
}



Event Types and Triggers

The frontend supports several different types of event trigger. The event trigger type is specified by the Equipment Flag in the Equipment Declaration. Common event types are "polled events" where the Equipment Flag is EQ_POLLED, "interrupts events" where the Flag is EQ_INTERRUPT, and "periodic events" where the Flag is EQ_PERIODIC. The name of the associated readout routine is specified in the Equipment Declaration for each event type.

Polled and interrupt events (see Event Types) require several extra functions to handle the hardware that periodic events do not require. These are described below.


Function poll_event

Parameters:

  • INT source
  • INT count
  • BOOL test

If the Equipment Type is EQ_POLLED, the poll_event() routine will be called as often as possible over the corresponding poll time (e.g. 500ms) given by each polling equipment.

In this case, the Equipment declaration would have this form:

   EQUIPMENT equipment[] = {
     { "Trigger",            // equipment name
       {
         ...
         EQ_POLLED,          // equipment type
         ...
         500,                // poll for 500ms 
         ...
         "", "", "",},
         read_trigger_event,    // readout routine 
      ...
        

The user must provide suitable code in the routine poll_event(), e.g.

INT poll_event(INT source, INT count, BOOL test)
{
   /* Polling routine for events. Returns TRUE if event  is available. If test equals TRUE, don't return. 
      The test flag is used to time the polling 
    */
    int i;
    int lam = 0;
                                //
    for (i = 0; i < count; i++, lam++) {
      lam = vmeio_CsrRead(myvme, VMEIO_BASE);
      if (lam)
        if (!test)
          return lam;
    }
    return 0;
 }

An event readout routine must also be provided by the user.


Function interrupt_configure

  • INT cmd
  • INT source
  • PTYPE adr

If the Equipment Type is EQ_INTERRUPT, an interrupt configuration routine called interrupt_configure() must be provided by the user. The interrupt configuration routine has the following declaration:

/*-- Interrupt configuration --------------------------*/
INT interrupt_configure(INT cmd, INT source, PTYPE adr)
{
 int vec = 0;
 switch (cmd) 
 {
   case CMD_INTERRUPT_ENABLE:
     if (inRun) mvme_write_value(myvme, VLAM_BASE+4, 0x1);
     break;
                                     //
   case CMD_INTERRUPT_DISABLE:
     if (inRun) mvme_write_value(myvme, VLAM_BASE+4, 0x0);
     break;
                                     //
   case CMD_INTERRUPT_ATTACH:
     mvme_set_dmode(myvme, MVME_DMODE_D32);
     mvme_interrupt_attach(myvme, INT_LEVEL, INT_VECTOR, 
               (void *)adr, &myinfo);
     mvme_write_value(myvme, VLAM_BASE+0x10, INT_VECTOR);
     vec = mvme_read_value(myvme, VLAM_BASE+0x10);
     printf("Interrupt Attached to 0x%x for vector:0x%x\n",
                    adr, vec&0xFF);
     break;
                                     //
   case CMD_INTERRUPT_DETACH:
     printf("Interrupt Detach\n");
     break;
  }
  return SUCCESS;
}

Under the four commands listed above, the user must implement the hardware operation needed to perform the requested action. In the Midas drivers directory examples can be found of such an interrupt code for CAMAC. See source code such as hyt1331.c,ces8210.c

An event readout routine must also be provided by the user in the frontend.

Event Readout routine

In the case of POLLED or INTERRUPT events, the event readout routine is called an Interrupt readout routine.

An event readout routine (called when an event occurs) is usually of the form

INT function_name ( char *pevent ... )
{
  INT event_size;
  ........  // read data from hardware
  ........  // pack into banks depending on format
  ........
  return (event_size);
}

where the first argument of the readout function (pevent) provides the pointer to the newly constructed event, and points to the first valid location for storing the data.

NOTE
  • The return value is the event size, and must be the number of bytes collected in this function.
  • The event serial number will be incremented by one for every call to the readout routine, as long as the returned size is non-zero.
  • If the returned value is set to zero, the event will be dismissed and the serial number to that event will be decremented by one.


General readout function

If the Equipment type is EQ_INTERRUPT or EQ_POLLED, see also Polled or Interrupt readout routine.


In the case of a periodic event, the Equipment declaration may have this form:

   EQUIPMENT equipment[] = {
     { "Scaler",           // equipment name
        {    
           ...
           EQ_PERIODIC     // equipment type
           0,              // interrupt source (ignored) 
           "MIDAS",        // event format
           ...
           10000,          // period (read every 10s)
           ...
           "", "", "",},
      read_scaler_event,   // readout routine 
      ...

A readout event will often need to send out data. This is done using one of the supported event structures usually "MIDAS" format data banks. The bank format ("MIDAS" in the example above) is declared in the Equipment List Parameters Format field.

An example of a scaler readout routine read_scaler_event() where the data is read out into MIDAS data banks is shown below.

INT read_scaler_event(char *pevent, INT off)
{
   DWORD *pdata, a;
                              //
   /* init bank structure; */
   bk_init(pevent);
                              //
   /* create SCLR bank */
   bk_create(pevent, "SCLR", TID_DWORD, &pdata);
                              //
   /* read scaler bank (CAMAC) */
   for (a = 0; a < N_SCLR; a++)
      cam24i(CRATE, SLOT_SCLR, a, 0, pdata++);
                              //    
   /* close SCLR bank */
   bk_close(pevent, pdata);
                              //
   /* return event size in bytes */
   return bk_size(pevent);
}

Some other examples of event readout routines in this document are

Many other examples of readout routines can be found in the frontend templates in the MIDAS package.

Polled or Interrupt readout routine

In the case of a Polled or Interrupt event, the content of the memory location pointed to by pevent (see Event Readout routine) prior to its use in the readout function, contains the interrupt source bitwise register. This feature can be exploited in order to identify which hardware module has triggered the readout when multiple interrupts have been assigned to the same readout function.

The examples below show a VME interrupt source for a given equipment. Depending whether USE_INT is defined, the Equipment will either use a Polled or an Interrupt mechanism. The Equipment declaration is of the form:

EQUIPMENT equipment[] = {
              //
   {"Trigger",  /* equipment name */
      ...
#ifdef USE_INT
      EQ_INTERRUPT, /* equipment type */
#else
      EQ_POLLED,    /* equipment type */
#endif
  /* interrupt source: crate 0, all stations */
      LAM_SOURCE(0, 0x0),
      ....
      "", "", "",
    },
    read_trigger_event, /* readout routine */
    NULL, NULL,
    trigger_bank_list,
}
 

Note that the LAM_SOURCE macro simply codes the parameters into a bitwise register.

The readout routine would contains code such as

INT read_trigger_event(char *pevent, INT off)
{
#if defined VADC0_CODE
  DWORD  *pdata;
#endif
                       //
#if defined VADC0_CODE
  /* read ADC0 data */
  v792_EvtCntRead(myvme, VADC0_BASE, &evtcnt);
  ........
  /* Read Event */
  v792_EventRead(myvme, VADC0_BASE, pdata, &nentry);
  ........
  v792_DataClear(myvme, VADC0_BASE);
#endif
                      //
  ........
  return (size);
}

The data will be packed into banks as described for the general readout function above. The examples fevmemodules.c (VME) and frontend.c (CAMAC) (see #Frontend Templates contain a complete example of read_trigger_event().


Manual Trigger

Another type of frontend event trigger supported is the "manual trigger", where the Equipment Flag is EQ_MANUAL_TRIGGER. This flag means that an event can be triggered through the URL ?cmd=Trigger/<equipment_name> (e.g. http://my.host:8080/?cmd=Trigger/MyEquipmentName). If you add this URL to the /Alias part of the ODB, then a link will appear on midas webpages that can be clicked to trigger an event.

In some cases, the same readout code may be used for two types of event: a manual trigger and (say) a poll event. It is possible to determine whether the readout of an event was triggered by a manual trigger or a regular trigger by adding a call to the event header Macro DATA_SIZE in the readout routine:

 flag = DATA_SIZE(pevent);

If the result is

 *  flag = 0 normal call
 *  flag = 1 manual trigger

It is also possible for a backend MIDAS client (such as an analyzer or custom data archiver) to trigger a manual trigger event. The client controls when an event is sent by means of a function that requests an event by triggering the event sending mechanism with a RPC call.

With a frontend Equipment declaration of a manually triggered event of the form:

   { "Histo",             /* equipment name */
      2, 0,                 /* event ID, trigger mask */
      "SYSTEM",             /* event buffer */
      EQ_MANUAL_TRIG,     /* equipment type */
      0,    
      .......
   }
   

the code fragment to manually trigger this event is:

 int main(unsigned int argc,char **argv)
 {
     .......
     bm_request_event(hBufEvent, 2, TRIGGER_ALL, GET_ALL, &request_id, process_event_TD);
     .......
 }

When it is time to save the data during the run, the function below is called:

BOOL trigger_histo_event(void)
{
  HNDLE hconn;
  BOOL event_triggered;
                           //
  event_triggered = FALSE;
  ...................
  if (run_state == STATE_RUNNING) {   // Check the frontend client exists
       if( cm_exist(ClientName,TRUE))  {    
           status = cm_connect_client (ClientName, &hconn);
           if(status != RPC_SUCCESS)
               cm_msg(MERROR,"trigger_histo_event","Cannot connect to frontend \"%s\" (%d)",
                      ClientName,status);
           else  {     // successfully connected to frontend client
               status = rpc_client_call(hconn, RPC_MANUAL_TRIG, 2); // trigger a histo event
               if (status != CM_SUCCESS)
                   cm_msg(MERROR,"trigger_histo_event","Error triggering event from frontend (%d)",status);
               else {  // successfully triggered event
                   event_triggered=TRUE;
                   status =cm_disconnect_client(hconn, FALSE);
                   if (status != CM_SUCCESS)
                       cm_msg(MERROR,"trigger_histo_event","Error disconnecting client (%d)",status);
               }
           }
       }
       else
           cm_msg(MERROR,"trigger_histo_event","Frontend client %s not running (%d)",
                  ClientName,status);
   } 
   return(event_triggered);
}

Deferred Transition

This option permits the user to postpone any transition issued by any requester until some condition is satisfied. For example:

  • It may not be advisable to pause or stop a run until some hardware has turned off a particular valve.
  • The start of the acquisition system should be postponed until the beam rate has been stable for a given period of time.
  • While active, a particular acquisition system should not be interrupted until the "cycle" is completed.

In these examples, any application having access to the state of the hardware can register to be a "transition Deferred" client. The MIDAS system will then catch any transition request and postpone the trigger of such a transition until the condition is satisfied.

The Deferred transition requires 3 steps for setup

  1. Register for the deferred transition
  2. Provide a callback function to serve the deferred transition
  3. Implement the condition code

The following example demonstrates this process:

 BOOL transition_PS_requested=FALSE; // global
                                             //
 INT frontend_init()
 {
   // register for deferred transition
                                             //
   cm_register_deferred_transition(TR_STOP, wait_end_cycle);
   cm_register_deferred_transition(TR_PAUSE, wait_end_cycle);
   ...  
 }
/*
*/ 
 //-- Deferred transition callback
 BOOL wait_end_cycle(int transition, BOOL first)
 {
   if (first) {
     transition_PS_requested = TRUE;
     return FALSE;
   }
                       //
   if (end_of_mcs_cycle){
     transition_PS_requested = FALSE;
     end_of_mcs_cycle = FALSE;
     return TRUE;
   }
   else
     return FALSE;
 }
/*
*/
 INT read_mcs_event(char *pevent, INT offset)
 {  
     ...     // read out data at end of cycle
     ...
     end_of_mcs_cycle = TRUE; // end of cycle 
                              //
     if (!transition_PS_requested)
        start_cycle(); // start a new cycle 
     return bk_size(pevent);
  }


In the example above,

  • The frontend code is registered for PAUSE and STOP using cm_register_deferred_transition(). The second argument wait_end_cycle is the declaration of the callback function.
  • The callback function wait_end_cycle will be called as soon as the transition is requested with the Boolean flag first set to TRUE.
  • By setting transition_PS_requested TRUE , the user will be provided with the acknowledgment of the transition request.
  • By returning FALSE from the callback, the transition is prevented from occurring.
  • As soon as the user condition is satisfied (end_of_mcs_cycle = TRUE), the return code in the callback will be set to TRUE and the requested transition will be issued.

While the transition is Deferred, the odb key /runinfo/Requested transition will contain the transition code, and the d mhttpd webserver main status page will indicate that a deferred transition is in progress.

Once in deferred state, an odbedit override command can be issued to force the transition to happen,

>odbedit
odb> stop now    (or "start now")

or /runinfo/Requested transition can be set to 0. The transition will then take place on the next stop or start command.

Compilation using CMake

Here is a "minimal" CMakeLists.txt file that can be used to compile a user-written frontend (called "myfe" in this case) that uses the mfe framework.

 cmake_minimum_required(VERSION 3.0)
 project(myfe)
 
 # Check for MIDASSYS environment variable
 if (NOT DEFINED ENV{MIDASSYS})
   message(SEND_ERROR "MIDASSYS environment variable not defined.")
 endif()
 
 set(CMAKE_CXX_STANDARD 11)
 set(MIDASSYS $ENV{MIDASSYS})
 
 if (${CMAKE_SYSTEM_NAME} MATCHES Linux)
   set(LIBS -lpthread -lutil -lrt)
 endif()
 
 # Define the executable to be built, and the source code files
 add_executable(myfe.exe myfe.cxx)
 
 # Directories to search for 
 target_include_directories(myfe.exe PRIVATE ${MIDASSYS}/include)
 
 # Libraries to link to
 target_link_libraries(myfe.exe ${MIDASSYS}/lib/libmfe.a ${MIDASSYS}/lib/libmidas.a ${LIBS})

One could then build the executable using the folllowing commands:

 mkdir build
 cd build
 cmake ..
 make

Some older operating systems may require the "cmake3" command to be used instead of "cmake".