Epi s devi e driver for MRF VME-EVG-230
Jayesh Shah, NSLS2, BNL jshahbnl.gov

Last Updated: September 28, 2011

1

The Sour e

VCS Che kout
$ git

l o n e h t t p s : / / g i t h u b . om/ e p i s −modules / m r f i o 2 . g i t

Currently the driver only supports VME-EVG-230.
2

IOC Deployment

This se tion outlines a general strategy for adding an VME-EVG to an IOC.
The VME bus based EVGs are ongured using the mrmEvgSetupVME() IOC
shell fun tion.
mrmEvgSetupVME (onst har* id, // EVG ard ID
epi sInt32 slot, // VME slot
epi sUInt32 vmeAddress, // Desired VME address in A24 spa e
epi sInt32 irqLevel // IRQ Levelepi sInt32 irqVe tor, // Desired interrupt ve tor number)
mrmEvgSetupVME(EVG1, 5 , 0 x20000000 , 3 , 0 x26 )In this example EVG1 is dened to be the VME ard in slot 5 on VME rate.
It is given the A32 base address of 0x20000000 and ongured to interrupt onlevel 3 with ve tor 0x26.
You an look at example startup s ript(st. md le) for EVG in ./mro 2/io Boot/io evgmrm
dire tory.
Note: VME64x allows for jumpless onguration of the ard, but not automati ally assignment of resour es. Sele tion of an unused address range and IRQ
level/ve tor is ne essarily left to the user.
Note: Before setup is done the VME64 identifer elds are veried so that
spe ifying an in orre t slot number is dete ted and setup will safely abort.
1

3

CLASSES/SUB-COMPONENT

3

2Classes/Sub-Component

3.1

EVG

3.1.1 Global EVG Options:• Enable (bo/bi): EVG enable and disable.

3.1.2 Timestamping
The Event System provides a global timebase to atta h timestamps to all olle ted data and performed a tions at EVR. The time stamping system onsistsof 32-bit timestamp event ounter and a 32-bit se onds ounter.
This driver provides you an option of doing timestamping al ulations in software as ompared to the dedi ated hardware as used at few pla es.

Following are the EVR requirements for a urate timestamping:• At the start of every se ond, re eive the event ode 0x7D whi h would

load the 32-bit se onds ount from shift register into the se onds registerof EVR and reset the timestamp event ounter.

• Have the next 32-bit se onds ount shifted in the shift register of EVR

before the end of the urrent se ond. The shift register is updated serially by loading zeros and ones on re eipt of event ode 0x70 and 0x71
respe tively.

3

CLASSES/SUB-COMPONENT

3Timestamping at EVG:
For timestamp EVG needs a pulse from the time sour e at the start of every
se ond. EVG used this 1 pulse per se ond input to address both requirementsof EVR timestamping.
• The rst requirement is addressed by using Trigger Events of EVG. We

an ongure one of the trigger events to send out event ode 0x7D when
it re eives a pulse from the 1PPS sour e.

• For addressing se ond requirement EVG uses software events.

Whentimestamping starts the EVG driver obtains the urrent time from epi sGeneralTime interfa e(whi h inturn is syn ed to a a urate time sour e)and stores it lo ally. Now the driver uses the 1 pulse per se ond output
from the time sour e to update the se onds ount of the lo ally stored
time and then sends out next se ond using event odes 0x70 and 0x71 via
software events.

Driver handles dierent error s enarios:• EVG uses timer with 1PPS input signal. If it does not dete t the signal insome '1 + delta' se ond the timer goes o and it raises an major alarm andtimestamping stops. On e EVG re eives the pulse from the 1PPS sour e
it starts the timer again and if the timer does not go o for 5 onse utive
pulses then the EVG starts sending timestamps again.

• Before sending out the timestamps to EVR (i.e. the 32-bit se onds ount),

EVG ompares the stored time (updated by 1 PPS) with the urrent time( obtained
from epi sGeneralTime). If they do not mat h an minor alarm is raised
but the stored time is sent as the urrent time to EVR.

Advantages:• Using minimum number of EVG inputs for the timestamping purpose.

Re ords asso iated with EVG time stamping:• Syn hronize Timestamp (bo): Syn the urrent time with the NTP server.
• 1PPS sour e for Timestamping: Timestamp Input (mbbo/mbbi):∗ None : Stop timestamping∗ Front : Front Panel Input∗ Univ : Universal Input∗ Rear : Rear Transitional Input

3

CLASSES/SUB-COMPONENT

3.2

4

Event Clo k

All the operations on EVG are syn hronized to the event lo k. Whi h is derived from either externally provided RF lo k or from an on-board fra tional
synthesizer.
• Sour e (bo/bi): The event lo k may be derived from external RF lo ksignal or from an on-board fra tional synthesizer.

• RF referen e frequen y (ao/ai): Set the RF Input frequen y in MHz.

Frequen y an range from 50 to 1600.

• RF Divider (longout/longin): Divider to derive desired event lo k fromRF referen e frequen y.

• Fra tional Synthesizer frequen y (ao/ai): This frequen y ould be used toderive event lo k.

• Event Clo k Frequen y Readba k (ai): Gets the urrent event lo k fre-quen y in MHz.

3.3

Software Events

Software event is used to send out an event ode by writing that event to aparti ular register in EVG.
• Enable (bo/bi): Enable/Disable the transmission of Software Events.
• Event Code (longout/longin): Sends out the event ode onto the event

stream. Event ode an range form 0 to 255.

3.4

Trigger Events

There are urrently 8 trigger event sour es. Trigger events are used to sendout event ode into the event streams, every time a trigger is re eived. The
stimulus ould be a rising edge on an external input signal or a multiplexedounter output or the a signal.
• Enable (bo/bi): Enable/Disable the transmission of Trigger Events.
• Event Code (longout/longin): Sets the event ode to be sent out, whenevera trigger is re eived. Event Code an range form 0 to 255.

• Trigger Sour e (mbbo): The trigger ould ome from one or multiple

sour es. It ould ome from any of the external inputs and/or any multiplexed ounter output and/or from a signal. If multiple trigger sour es
are sele ted then those signal are OR'ed together and the resulting signal
works as the trigger.

3

CLASSES/SUB-COMPONENT

3.5

5

Distributed bus

The distributed bus allows transmission of eight simultaneous signals with theevent lo k rate.
• Signal Sour e/Map (mbbo): The bits of the distributed bus an be driven

by sele ting one of the following sour es.

 Ext Inp : Sampling of the external input signals at event rate.
 MXC : Sampling of the orresponding multiplexed ounter output at
event rate.
 Upstream EVG : Forwarding the state of distributed bus bit of upstream EVG.
• Sele ting the input (bo): When the sour e for the distributed bus signals

is external input signal, we need to spe ify whi h input signal needs to bemapped onto the distributed bus. If multiple inputs are mapped onto asingle distributed bus bit then those signals are logi ally OR'ed together
and the resulting signal is used to drive the distributed bus bit.

3.6

Multiplexed Counter

There are 8 32-bit multiplexed ounters that generate lo k signals with programmable frequen ies from event lo k/2^32-1 to event lo k/2. The ounter
outputs may be programmed to trigger events, drive distributed bus signals andtrigger sequen e RAMs.
• Polarity (bo/bi): Set the Multiplex Counter(Mx ) output polarity.
• Frequen y (ao/ai): Request a signal with a parti ular frequen y.
• Pres aler (longout/longin): Used as ounter to produ e a signal with aparti ular frequen y.

• Reset: Reset all the multiplexed ounters. After reset all the ounters arein phase/syn with ea h other.

3.7

Input

VME-EVG-230 has 2 Front panel, 4 Universal and 16 Transitional Inputs.
• External Input Interrupt (bo): Enable or Disable the External Interrupt.

When enabled, an interrupt is re eived on every rising edge the input
signal.

3

CLASSES/SUB-COMPONENT

3.8

6

Output

It is used to ongure the 4 front panel outputs and 4 four front panel universal
outputs.
• Sour e (mbbo/mbbi): The output ould be mapped to Any of the eight distributed bus bits
 For ed logi 1
 For ed logi 0.
3.9

AC Trigger

EVG provides syn hronization to the mains voltage frequen y or another external lo k.
• Divider (longout/longin): The mains voltage frequen y an be divided byan eight bit programmable divider.

• Phase (ao/ai): The output of the divider may be delayed by 0 to 25.5 ms

by a phase shifter in 0.1ms steps to adjust the triggering position relative
to mains voltage phase.

• AC Bypass (bo/bi): It is set to bypass the AC divider and phase shifter

ir uitry.

• Syn (bo/bi): The AC Trigger ould be syn hronized either with eventlo k or the output of multiplexed ounter 7.

3.10

Event Sequen er

Event Sequen er provides a method of transmitting or playing ba k sequen esof events stored in random a ess memory with dened timing. MRF VMEEVG-230 has 2 sequen eRams (sequen ers or hard sequen e). The sequen er
an hold up to 2048 <event ode, timeStamp> pair. When the sequen er istriggered, an internal ounter starts ounting. When the ounter value mat hes
the timeStamp of the next event, the atta hed event ode is transmitted.

3

CLASSES/SUB-COMPONENT

7

Fun tional blo k diagram of devi e support forevent sequen er

Devi e support for sequen er introdu es a on ept of software sequen e(a.k.a.
soft sequen e). The existen e of the software and hardware sequen es is an
abstra tion made to separate the pro ess of assembling a sequen e from the
pro ess of pla ing it into hardware. Software sequen e maintains a omplete
ready to run opy of all sequen es in the IOC at all times. The IOC is thenfree to hoose whi h sequen e to pla e into hardware. Sin e this is a lo al
operation it an be done qui kly and e iently. The IOC an have any numberof these soft sequen es but at a time the number of these soft sequen es thatan be loaded into the EVG hardware is restri ted by the number of hardware
sequen es.
As shown in the pi ture above IOC maintains 2 opies of sequen er data (i.e.
Event Code's, Timestamps, Trigger Sour e and Run Mode). S rat h sequen eand omplete sequen e. Users are allowed to make hanges to the s rat h sequen e dire tly. S rat h sequen e is like the working opy. When user are
satised with the hanges made to the working opy then they an ' ommit'
the soft sequen e whi h will update the omplete sequen e with the s rat h sequen e. If the software sequen e has an asso aited hardware sequen e with itthen the omplete sequen e is opied to the hardware on ommit. This is theSyn operation of sequen er.
Parts of the sequen e:• Event Code List (waveform): It is used to set the list of the eventCodes ofthe soft sequen e. These eventCodes are transmitted whenever the timeStamp asso iated with eventCode mat hes the ounter value of sequen er.

• Timestamp List (waveform): It is used to set the timeStamps for the

events in the soft sequen e.

• Timestamp Input Mode (bo): There are two mode to enter the timestamp-

ing data in the sequen er i.e. EGU and TICKS.

3

CLASSES/SUB-COMPONENT8

 EGU: In EGU mode user an enter the timestamps in units of se onds, milli-se onds, mi ro-se onds or nano-se onds.
 TICKS: Here user an provide timestamps in terms of Event Clo k
ti ks.
 All the timestamp values are oset from the time the sequen er reeives the trigger.
• Timestamp Resolution(mbbo) : If the timestamp input mode is EGU user

an use this re ord to give the units to time.

 Se - Input/Output sequen er timestamps in se onds
 mSe - Input/Output sequen er timestamps in mi ro-se onds
 uSe - Input/Output sequen er timestamps in milli-se onds
 nSe - Input/Output sequen er timestamps in nano-se onds
• Run Mode (mbbo/mbbi): Run mode is used determine what will the se-quen er do at the end of the sequen e. where mode ould be any of thefollowing: Single : Disarms the sequen er at the end of the sequen e.
 Automati : Restarts the sequen e immediately after the end of thesequen e.
 Normal : At the end of the sequen e, the sequen er rearms and waits
for the trigger to restart the sequen e.
• Trigger Sour e (mbbo/mbbi): Trigger Sr is used to sele t the sour e ofthe trigger, whi h starts the sequen er.

 Mx : Trigger from MXC0 - MXC7
 AC : Trigger from AC syn logi
 Software : Trigger from RAM0/RAM1 software trigger.
 External : Trigger is re eived from any external input.
Above re ords only deal with the s rat h opy of the soft sequen e. They do
not dire tly intera t with the hardware sequen e.
A soft sequen e ould be in dierent states like LOADED or UNLOADED,COMMITTED or DIRTY, ENABLED or DISABLED.
• Load (bo): If su essful, load auses a soft sequen e to move from UN-

LOADED state to LOADED state. In the LOADED state, an hard sequen e is assigned to a soft sequen e. If the soft sequen e is already in
LOADED state then load will return with an error message. The operation will fail if all the hard sequen es are already assigned. An allo ations heme ensures that at any given time, ea h hard sequen e is onne ted
to only one soft sequen e. Load also opies the last ommitted data to
the hardware.

3

CLASSES/SUB-COMPONENT

9• Unload (bo): The unload auses the soft sequen e to enter into UN-

LOADED state. This operation annot fail. In unloaded state the assignment of a hard sequen e to a soft sequen e is released.

• Commit (bo): Whenever you modify a soft sequen e, the s rat h opy inthe soft sequen e is modied (Refer to evg-seq diagram). Commit auses
the hanges from the 's rat h sequen e' to be opied to the ' ompletesequen e'. If the soft sequen e is loaded, ommit also initiates syn operation and opies the hanges from omplete sequen e to the hardware.
Modifying the sequen eRam while it is running gives undened behavior
hen e ' ommit' makes sure that the hanges are not written to the hardware while it is running. Hen e it waits for the urrent sequen e to nish
before writing to the hardware sequen e.

• Enable (bo): It puts the soft sequen e in the ENABLED state. In enabledstate, a loaded sequen e is armed and waits for the trigger. If is alreadyin ENABLED state the re ord does nothing.

• Disable (bo): In DISABLED state the armed sequen e is disarmed, so

even if the sequen er re eives the trigger the sequen e is does not run
again.

• Pause (bo): This stops the urrently running sequen e(if any) and thendisarms it. Pause leaves the sequen e in DISABLED state. When thesequen e starts running again(Arm + Trigger), it ontinues the from where
it was stopped.

• Abort (bo): This auses the urrently running sequen e(if any) to stopand then disarmed. Abort leaves the sequen e in DISABLED state. Afterdisarming it also resets the timestamp and eventCode registers. So when
the sequen e starts running again(Arm + Trigger), it ontinues the fromthe start.

Caveats for sequen er• In the Event Code and Timestamp arrays provided by user are of dierent

lengths then the length of the sequen e would be the length of the smallerof the two arrays. The remaining extra elements of the longer array would
be ignored.

• Driver by defaults puts the 'End of Sequen e (0x7f)' event ode at theend of the sequen e and it will be sent 'evgEndOfSeqBuf' event lo k ti kafter the last event in the sequen e has been sent out. Whi h urrently
defaults to ve event lo k ti ks. If user provides 0x7f with a timestampthen that would be used instead of the default one.

• If a soft sequen e is un ommitted and running then when the IOC restarts

the sequen e would be in un ommitted state but wont be running i.e. lastommitted sequen e is lost.

PyQt s ript. (Front end for Event Code and Timestamp arrays)

4

ACKNOWLEDGMENT

10• You need to install PyQt4 to run this python s ript. Debian pa kage is

pyqt4-dev-tools.

• You an have timestamp as 'zero' for the rst event ode in the sequen er.

So this will allow the rst event ode in the sequen er to be sent out
immediately after sequen er re eives the trigger. But adding 'zero' astimestamp anywhere else(other than for rst event ode) is an error andthe sequen e would be trun ated as soon as a zero is en ountered. e.g.
timestamp array: 0x20, 0x30, 0, 0x40 would be trun ated to 0x20, 0x30.
(Just rst two elements before zero.)4

A knowledgment

Thanks for all the help and support• Mi heal Davidsaver, NSLS2, BNL.
• Eri Bjorklund, LANSCE, LANL.