The Global Event System
Original: John Winans (APS, March 2, 1994)
Modified for the new (SLS) event system by Timo
Korhonen (
Modified for the new features (EVG-110 plus) by Babak
Kalantari (
Modified for the new features (EVG/EVR) by Babak
Kalantari (
The support for the global event system has been designed to allow an application developer to control the APS event generator and receiver boards. This is done by the use of four new record types. These records are customized and are only supported by the device support modules for the APS event generator and receiver boards.
The use of the global event system and its associated records should not be confused with the vanilla EPICS events and the associated event records. They are very different.
The Event Generator is used to generate global event codes and send them out to one or more Event Receivers. A group of interconnected event generators and receivers is referred to as an `event circuit.' There may be more than one event generator on the same event circuit. And it is possible for a single IOC to be part of multiple event circuits.
The EG record type is used to select the options of a specific event generator card. In order to properly configure it, you should first be familiar with its operating modes. This is specified in the document "Event System" by Frank Lenkzus. The details of the upgraded (Micro-Research) event cards are explained in the document "Event System Manual“ by J. Pietarinen, Micro-Research Finland (version 2.01).
2.1.1Field descriptions
OUT (Output Link) specifies the link number of the event generator board. Only the `Card' value of the link specification is used.
MOD1 (Mode Select for RAM 1) Used to select the operating mode of event sequence RAM1. It is important to know that the configuration of the events in the RAM may not be altered unless it is either `Off' or in `Alternate Mode'. Should a configuration attempt be made when the RAM is not in one of these modes, it will be deferred until the RAM mode is changed to either `Off' or `Alternate'. When MOD1 is set to alternate from any other mode, MOD2 will also be set to alternate. If MOD1 is changed from alternate to any other mode, MOD2 will be set to off.
MOD2 (Mode Select for RAM 2) The same as MOD1 except it represents the mode for sequence RAM2.
R1SP (RAM 1 Speed) Event clock 1 rate in Hz. This must be set to the clock rate of the signal source on the Event CLK 1 input. It is only used to calculate the `desired position' value of events that are placed into the sequence RAM. These events are specified by the use of `egevent' records. When the internal clock divider is used (see R1CK field), this value is calculated from the divider clock ratio. If all `egevent' record types that use the generator being configured will be using `Clock Ticks' as their `Delay Units' the value placed into R1SP is not used and may be left as zero. It is recommendable always to use Clock Ticks as Delay Units whenever possible, because the actual clock speed depends on the main clock (when EVG is synchronised to the master oscillator).
R2SP (Ram 2 Speed) Same ar R1SP for the second sequence RAM.
FIFO (FIFO Enable) Used to enable or disable the input-fifo on the generator board. The fifo is used to allow more than one event generator to exist on the same fiber-optic line.
CLR1 (Clear RAM 1) Performing a `put' operation on this field causes sequence RAM1 to be cleared. The use of this field is undefined (and will cause great problems) if there are any `egevent' records configured in the database. This is provided for testing purposes.
CLR2 (Clear RAM 2) Same as CLR1, but for sequence RAM2.
TRG1 (Manual Trigger RAM 1) If a `put' operation is performed on this field, a onetime trigger on sequence RAM1 will be initiated. The result would be that same as if there were a hardware trigger applied to the `Event TRG1' input on the card.
TRG2 (Manual Trigger RAM 2) Same as TRG1, but for sequence RAM2.
ENAB (Master Enable) Master card enable. No events are generated unless the card is enabled. In general, there should never be any reason to disable an event generator. This is provided for testing purposes.
TAXI (Taxi Violation Flag) This is set to a non-zero value when there has been a taxi violation. It simply reflects that state of the violation signal on the taxi receiver module. Taxi violations can not occur when FIFO is set to `Off.' The name of this field refers to the TAXI chips used in the original APS event cards, but the fieldname and operation are the same in the new cards, too.
VME (Manual Event Generation via VME Access) Used to send out a one-shot event code. A put to this field will cause the event to be sent. It appears to be zero if it is ever read. This can be `OUT-LINKed' to by an other record in order to generate an arbitrary event when it is processed.
ETEn (Event Trigger Enable) These are the enables for the trigger event inputs on the card. They must be set to `On' in order to send the trigger event codes.
ETn (Event Trigger) These are used to program the event codes that correspond to the trigger event inputs on the card.
R1CK (Ram 1 Clock) This field is used to set the clock divisor ratio for RAM1. The value specifies the division ratio from the internal (50 Mhz) clock. A value of 0 specifies the use of an external clock. When the internal clock divider is used, the R1SP field is calculated automatically and cannot be changed.
R2CK (Ram 2 Clock) The same as R1CK, but for RAM 2.
MDnE (Multiplexed counter Distributed bus Enable) These are the enables for the multiplexed counters to send their outputs on the distributed bus. They should be set to 'YES' to be enabled.
MEnE (Multiplexer counter Event trigger Enable) These are the enables for the multiplexed counters to send their output on the external trigger inputs of the event generator card. They should be set to 'YES' to be enabled.
MCnP (Multiplexer Counter Prescaler) These are fields to scale (divide) the multiplexed counter clock rates. These counters are 32-bits (long type) and hardware is capable of odd divisions. The frequency can be programmed as (event_clock)/(2^MCnP+1).
ASQ1 (AC input Sequence trigger enable) By setting this filed to 'YES' sequence RAM 1 is triggered form AC input divider.
ASQ2 The same as ASQ1 but for sequence RAM 2.
AEV0 ( AC input External Event trigger enable) By setting this filed to 'YES' external event input 0 of the event generator card is triggered from AC input divider.
ASYN (AC input Synchronization with multiplexed counter 7) Writing 'YES' to this field enables synchronization of the AC input trigger with output of the multiplexed counter 0.
ADIV (AC input divisor) This field is to scale the AC input signal form 50 to 50/256 Hz.
APHS (AC Phase Shifter) This filed delays output of the AC divider with respect to the AC input, in steps of 0.1 ms from 0 (APHS=0) to 25.5 ms (APHS=255).
MSQ1 (Multiplexed counter Sequence RAM 1 trigger) By setting this filed to 'YES' sequence RAM 1 is triggered by counter 0 divider output.
MSQ2 The same as MSQ1 but for sequence RAM2 (triggered by counter 1 divider output).
FPGV (FPGA Version) This field shows the firmware program version (in hexadecimal).
VAL Placed into the record to make EPICS happy and is completely worthless.
2.1.2Record Processing
It is intended that EG records be set to passive processing only. They are not altered by the device support code in response to being processed. Their purpose is only to specify the operating modes of the event generator and, as such, are processed if and when a value in it is altered by a put operation. To start things going, however, they should have their `process at init' flag set to YES.
As an observation, it is not advisable to alter the R1SP or R2SP fields. You may, but then all related egevent records must be processed again in order to recalculate their desired position values. The MOD1 and MOD2 fields can also cause some nasty side effects if they are altered between any two non-off modes. In general, the operating mode should be set to off and then to some other mode if it is desired to switch between two modes.
Note that in the new cards the RAM size is increased to 512 kB, to give a full SLS injection cycle coverage with 1 Mhz clock.
The EGEVENT record is used in conjunction with an EG record in order to specify a single event that is to be placed into a sequence RAM. The event code and its time displacement from the trigger are specified in this record.
2.2.1 Field Descriptions
OUT (Output Link) Used to specify what event generator link that this event is related to. Only the Card number is used
ENM (Event Number) The event number that is to be placed into the sequence RAM.
RAM (Sequence RAM Specifier) Which RAM the event is to be placed into. (Ignored when the generator is in `Alternate' mode.)
DELY (Desired Delay) The desired time delay between the trigger that starts the RAM sequence and when this event should be sent. This field must be expressed in the units selected in the UNIT field described below. For very long delays that should specify an absolute time value, one must take into account the fact that the clock may not be exactly 50 Mhz, but a frequency that is dependent on the operating conditions of the machine.
(note: in the future, it is planned to have a field in the eg record to directly feed in the main RF clock frequency. The positions in the RAM would then be calculated normalized to that clock rather than to constant 500 MHz , except when the value is in ticks.)
ADLY (Actual Delay) This is a read-only field that is set to the actual delay value after accounting for rounding caused by the clock resolution as well as collisions that can occur if more than one event is placed into the same sequence RAM location.
DPOS (Desired Position) This is a read-only field that represents desired position in the sequence RAM that the event should be placed. It is expressed in clock ticks.
APOS (Actual Position) This is a read-only field that represents the actual position in the sequence RAM that the event is placed. It is expressed in clock ticks.
UNIT (Delay Specifier Units) The time units used to express the delay value in the DELY and ADLY fields.
VAL Placed into the record to make EPICS happy and is completely worthless.
2.2.2Record Processing
It is intended that EGEVENT records be set to passive processing only. They are not altered by the device support code in response to being processed. Their purpose is only to specify the desired position and code of an event in a sequence RAM. The read-only fields will be updated as necessary when ever the sequence RAM is reloaded. To start things going, however, they should have their `process at init' flag set to YES.
Sequence RAMs are reloaded when ever any of the EGEVENT records related to it has its DELY, ENM or UNIT values changed. It is not advisable to alter the UNIT field unless the associated sequence RAM mode is set to `Off'.
The device support module for the event generator may be used by EG and EGEVENT record types.
In order to configure the event generator device support, a call must be made to set the address for each of the event generator cards present in the IOC. This configuration call is as follows:
EgConfigure(<card number>, <Base address in A16>)
The <card number> field may be 0-4 and is used to specify which card is to be configured. This is the card number that is referenced in the EG and EGEVENT records when building the database. The <Base address in A16> field is a 16-bit number that represents the address of the card in the A16 memory space.
Database records that specify card numbers that are not configured will generate `bad field' errors when they are initialized by iocInit. And will then be ignored by the event generator device support if ever processed.
The ER record type is used to select the options of a specific event receiver card. In order to properly configure it, you should first be familiar with its operating modes. This is specified in the document "Event System" by Frank Lenkzus.
3.1.1 Field Descriptions
OUT (Output Link) Used to specify which event receiver board is represented by this record.
ENAB (Master Enable) Master card enable. No events will be received if the card is disabled.
TAXI (Taxi Violation Flag) Set to a non-zero value if there is a taxi violation on the event receiver board.
TRGn (Trigger Enable) Trigger event enables. Setting these allows the corresponding bit to be set on the event receiver.
OTPn (One Time Pulse Enable) Setting these allows the corresponding bit to be set in the event receiver.
OTnW (One Time Pulse Width) The width of the OTP pulse. This is expressed in multiples of 20 ns clock periods, from 20 ns to 655.36 us (15-bit counter, 50 MHz clock). The default value is set to generate 100 ns pulses. (NOTE; this check could be implemented if necessary: A value of 0 would result in no pulse and is not accepted. If the pulse needs to be disabled, use the OTPn field instead.)
OTnP (One Time
Pulse Polarity) The polarity of the OTP pulse. When "
OTLn (Output Level Enable) Output level enables. Setting these allows the corresponding bit to be set in the event receiver.
DGnE (Delay Generator Enable) Programmable pulse delay enables.
DGnD (Delay Generator Delay Value) Delay value used for the programmable pulse delay outputs. These values must be expressed in periods of the clock after prescaler, i.e. 50 MHz divided by the prescaler value (DGnP).
DGnW (Delay generator Width Value) Width of the programmable pulse. These values must be expressed in clock periods.
DGnP (Delay
Generator Polarity) Programmable pulse polarity. When "
DGnC (Delay Generator Clock) The clock prescaler of the respective delay channel. The incoming clock is divided by the value specified in this field. The value can be between 0 (no division, 50 MHz, 20 ns/step clock) and 65535 (763 Hz, 1.3 ms/step clock).
OTnB (One Time pulse distributed Bus enable) Setting these fields to 'Enabled' enables the event receiver card to receive signals on the distributed bus.
FPGV (FPGA Version) This field shows the firmware program version (in hexadecimal).
RXVE (RX Violation interrupt Enable) This field enables/disables RX violation interrupt. Refer to section 6.2.6 for a detailed description.
RXVC (RX Violation error Counter) keeps the number of RX errors.
VAL Placed into the record to make EPICS happy and is completely worthless.
3.1.2Record Processing
It is intended that ER records be set to passive processing only. They are not altered by the device support code in response to being processed. Their purposes are only to specify the operating modes of the event receiver and, as such, are processed if and when a value in it is altered by a put operation. To start things going, however, they should have their `process at init' flag set to YES.
The EREVENT records are used to specify what bits are to be set in the event receiver mapping RAM. The use of these bits depends on which outputs are enabled on the event receiver card (specified in the ER record.) Additionally, this record type is used to select the VME interrupt and time-latch option.
3.2.1Field Descriptions
OUT (Output Link) Specifies the card containing the mapping RAM to be programmed.
ENAB (Event Enable) Enables the operation of this record. If this is set to `Disabled', then the values in the record are ignored.
ENM (Event Number) The event number to be described. This indicates the position in the mapping RAM that is to be programmed.
OUTn (Output Enable) May be set to `Enable' or `Disable' in order to set or clear the corresponding bit in the mapping RAM. The meanings of these bits depend on what outputs are enabled on the event receiver board (selected in the related ER record) and are described in the document "Event System" by Frank Lenkzus.
VME (VME Interrupt Enable) May be set to `Enable' or `Disable' in order to select a VME interrupt upon the occurrence of event ENM. The time is automatically latched when the VME interrupt is generated.
VAL Placed into the record to make EPICS happy and is completely worthless.
3.2.2Record Processing
It is intended that EREVENT records be set to passive processing only. They are not altered by the device support code in response to being processed. Their purpose is only to specify the desired actions to be performed upon receipt of a specific event code. To start things going, however, they should have their `process at init' flag set to YES.
3.3EVENT Records
The regular EPICS event records may be used when it is desired to cause a record to process upon a given event code by the global event system. This is accomplished by configuring an EVENT record (the regular EPICS event record) and selecting the APS event receiver for the DTYP field. The card and signal are then used to select the event receiver card and event number, respectively. Any time the event number specified is received by the event receiver, that event record will be processed (pretty cool huh?)
This is the only relationship between the vanilla EPICS event codes (and their associated records) and the global APS event system.
3.4Event Receiver Device Support
The device support for the event receiver may be used by ER, EREVENT and EVENT record types.
In order to configure the event receiver device support, a call must be made to set the address for each of the event receiver cards present in the IOC. This configuration call is as follows:
ErConfigure(<card>, <A16 board address>, <IRQ Vector>, <IRQ Level>)
Where <card> is the card to be configured, <A16 board address> is the 16-bit address of the board in A16 space, <IRQ Vector> is the vector number to use when generating VME interrupts, and <IRQ Level> is the VME backplane interrupt level.
This section describes a few observations that would otherwise be left to experimentation for the user figure out. Much of the annoyances described here have been left in the system because there are simple work arounds, or they represent situations that should never be encountered on a running system.
It is intended that the modes of the EG never be altered. It was considered that the MOD1 and MOD2 fields be made SPC_NOMOD fields. But, during the system testing of the event hardware itself, it became useful to be able to make adjustments to the operating mode. Thus the ability to change the mode was put into the record and device support. However, exactly what is done when the mode is changed is probably not useful to the database designer.
First of all, remember that the sequence RAMs can not be updated unless they are either in ALT mode or OFF. This is due to the hardware constraints. In order to alter a sequence RAM that is not set to ALT or OFF, the RAM must be changed to one of those modes, altered, and then reset back to the desired mode. (No it is not reasonable to do this automatically.) Should the mode be carelessly altered, the EG card will have the mode updated, but the sequence RAM(s) will not be updated again until the mode is set to ALT or OFF. (In an actual application program, it is not reasonable to think that the operating modes of the sequence RAMs will be changed.)
Unless you have a strong need to use more than one sequence RAM at the same time, it is strongly recommended that the ALT mode be used. This is so that you may alter the event positions on the fly when debugging.
The delay selected in an EGevent record is done by specifying the desired period of delay. The period is converted to click ticks by the use of the R1SP and R2SP values specified in the EG record. Since only one event code may be in any single sequence RAM position at any given time, any collisions are resolved at RAM load time by scanning for the `next' unused position. Thus it is possible that the same database end up loading the RAMs in two different images depending on the order that the records get processed (that earlier records get higher priority.) If this causes problems, it is recommended that the units of delay be specified in `clock ticks' and that the same delay values not be used in multiple records.
The use of `clock ticks' as the delay units specification will eliminate the rounding caused by the conversion from alternate units into clock ticks.
It should be obvious that the event system is capable of generating VME interrupts at a rate that far exceeds the CPUs ability to process them. Much care should be put into the design of the databases that control the event system so that this does not happen. It has been observed that when such a problem does occur, vxWorks dies and prints "Work queue overflow" on its console. The mv2306 ioc is capable of handling over 30 kHz interrupt rate (but keep in mind that the event system can deliver events with a rate up to 50 MHz and interrupts at several MHz.)
This section describes a few example database records that are used to set up the event system. The records shown here are those used by the global synchronous timing system. And provide a good example of event generation from database records as well as from trigger inputs. It also includes a heartbeat generator that is required by the event system itself.
The example timing system uses a free running 1000 hertz clock. This clock is input on the TRG0 line of the EG card on the master timing IOC. Each time the TRG0 input is pulsed, an Increment Time Stamp (0x7C) event should be sent out so that the ER cards can update their notion of the time.
Additionally, the timing system has to take care of high order counter truncation and slave resynchronization. This is handled by the use of the Reset Time Stamp Counters (0x7D) event (the processing of the time stamp information is described in more detail in the document on the global timing system.)
5.1.1Event Generator Database Records
The records related to the event generator card are used to initialize and generate events. The EG record used on the timing system master is:
record(eg, "$(prefix)_eg")
{
field(DESC, "")
field(ASG, "")
field(SCAN, "Passive")
field(PINI, "YES")
field(PHAS, "0")
field(EVNT, "0")
field(TSE, "0")
field(TSEL, "0")
field(DTYP, "APS event generator G")
field(DISV, "1")
field(SDIS, "0")
field(DISS, "NO_ALARM")
field(PRIO, "LOW")
field(FLNK, "0")
field(OUT, "#C0 S0 @")
field(MOD1, "Off")
field(R1SP, "0")
field(MOD2, "Off")
field(R2SP, "0")
field(FIFO, "NO")
field(ENAB, "YES")
field(ETE0, "YES")
field(ET0, "0x7c")
field(ETE1, "NO")
field(ET1, "0x0")
field(ETE2, "NO")
field(ET2, "0x0")
field(ETE3, "NO")
field(ET3, "0x0")
field(ETE4, "NO")
field(ET4, "0x0")
field(ETE5, "NO")
field(ET5, "0x0")
field(ETE6, "NO")
field(ET6, "0x0")
field(ETE7, "NO")
field(ET7, "0x0")
}
The important items of note are that ENAB is YES, ETE0 is YES, ET0 is set to 0x7C, and that the record be set to process at init time. The scan should always be set to passive since it only makes sense to process the record when the field values change.
In order to take care of the heart beat (0x7A) and time stamp reset/resync (0x7D) events, longout records are used that have their output links pointed to the VME field on the above EG record. When they are processed, the VAL field of the longout record is sent out on the event system.
record(longout, "$(prefix)_hbeat")
{
field(DESC, "")
field(ASG, "")
field(SCAN, "1 second")
field(PINI, "NO")
field(PHAS, "0")
field(EVNT, "0")
field(TSE, "0")
field(TSEL, "0")
field(DTYP, "Soft Channel")
field(DISV, "1")
field(SDIS, "0")
field(DISS, "NO_ALARM")
field(PRIO, "LOW")
field(FLNK, "0")
field(OUT, "$(prefix)_eg.VME PP NMS")
field(DOL, "122")
field(OMSL, "supervisory")
field(EGU, "rocks")
field(HOPR, "0")
field(LOPR, "0")
field(HIHI, "0")
field(LOLO, "0")
field(HIGH, "0")
field(LOW, "0")
field(HHSV, "NO_ALARM")
field(LLSV, "NO_ALARM")
field(HSV, "NO_ALARM")
field(LSV, "NO_ALARM")
field(HYST, "0")
field(ADEL, "0")
field(MDEL, "0")
field(SIOL, "0")
field(SIML, "0")
field(SIMS, "NO_ALARM")
field(IVOA, "Continue normally")
field(IVOV, "0")
}
record(longout, "$(prefix)_resync")
{
field(DESC, "")
field(ASG, "")
field(SCAN, "10 second")
field(PINI, "NO")
field(PHAS, "0")
field(EVNT, "0")
field(TSE, "0")
field(TSEL, "0")
field(DTYP, "Soft Channel") field(DISV, "1")
field(SDIS, "0")
field(DISS, "NO_ALARM")
field(PRIO, "LOW")
field(FLNK, "0")
field(OUT, "$(prefix)_eg.VME PP MS")
field(DOL, "125")
field(OMSL, "supervisory")
field(EGU, "rocks")