How-To: saft-dm

Introduction

This tool (saft-dm: "saft Data Master") is intended to provide a primitive Data Master for local operations in the FEC. This tool might be useful

• if a central Data Master is not available or FEC is not connected to a White Rabbit network.
• for "rapid prototyping" of schedules or
• for local tests and equipment integration.

A simple schedule can be provided in a text file as a sequence of timing messages. The number of iterations is configurable. Complex things like executing alternatives or synchronization depending on external conditions are not supported. The timing messages are injected into the hardware of the timing receiver locally in the FEC, thus at the input of the ECA. This allows executing simple schedules with a precision of nanoseconds and each iteration can optionally be configured to start at the next full second.

Remark: Although actions "timing events" are executed by the ECA with hard real time and nanoseconds precision, the timing messages must be supplied to the input of the ECA early enough. As this tools is a userland application on a non-real-time operating system, the timing messages are delivered to the input of the ECA with best effort only. Thus, no guarantee for correct execution can be given.

Usage

Usage: saft-dm <device name> [OPTIONS] <file name>

  -h                   display this help and exit
  -f                   use the first attached device (and ignore <device name>)
  -p                   schedule will be added to next full second (option -p) or current time (option unused)

  -n N                 N (1..) is number of iterations of the schedule. If unspecified, N is set to 1

  The file must contain exactly one message per line. Each line must have the following format:
  '<eventID> <param> <time>', example: '0x1111000000000000 0x0 123000000', time [ns] and decimal.

Report bugs to <d.beck@gsi.de> !!!
Licensed under the GPL v3.

There are not many options. Just provide a text file with the format specified in the command line help (option -h).

Option '-n' Tell saft-dm how often the schedule provided in the text file shall be repeated.

Option '-p' The saft-dm to start each iteration of the schedule at the next full second.

• this allows to plan execution times on an absolute time scale
• if the length of a schedule is less than one second, it would in principle be possible to synchronize actions on distinct Timing Receivers, provided that
  • both receivers are connected to the same clock master
  • saft-dm is executed on both FECs with identical schedule
• this limits the frequency of iterations to 1 Hz max

Generation of Timing Events saft-dm only injects timing messages to the input of the ECA. For execution of actions "timing events", the ECA must be configured using appropriate applications. Examples for applications include

• FESA classes
• saft-ctl
• saft-io-ctl

Examples

Simple Example

Consider the text file schedule.txt

0x1111000000000000 0x0 100000000
0x2222000000000000 0x0 200000000
0x3333000000000000 0x0 300000000
0x4444000000000000 0x0 400000000

It contains four timing messages with EventIDs 0x1111..., 0x2222..., 0x3333..., 0x444... and parameter 0x0, which are scheduled for executed 100, 200, 300 and 400 ms after the start of the schedule.

saft-dm bla -fp -n 1 schedule.txt will execute that schedule once.

saft-dm bla -fp -n 3600 schedule.txt will execute that schedule every second for the next hour.

It might be instructive to do event snooping using saft-ctl.

saft-ctl bla -fxv snoop 0x0 0x0 0x0
tDeadline: 1970-01-02 04:50:05.100000000 FID: 0x1 GID: 0x0111 EVTNO: 0x0000 SID: 0x0000 BPID: 0x00000 RES: 0x0000 Param: 0x0000000000000000
tDeadline: 1970-01-02 04:50:05.200000000 FID: 0x2 GID: 0x0222 EVTNO: 0x0000 SID: 0x0000 BPID: 0x00000 RES: 0x0000 Param: 0x0000000000000000
tDeadline: 1970-01-02 04:50:05.300000000 FID: 0x3 GID: 0x0333 EVTNO: 0x0000 SID: 0x0000 BPID: 0x00000 RES: 0x0000 Param: 0x0000000000000000
tDeadline: 1970-01-02 04:50:05.400000000 FID: 0x4 GID: 0x0444 EVTNO: 0x0000 SID: 0x0000 BPID: 0x00000 RES: 0x0000 Param: 0x0000000000000000
tDeadline: 1970-01-02 04:50:06.100000000 FID: 0x1 GID: 0x0111 EVTNO: 0x0000 SID: 0x0000 BPID: 0x00000 RES: 0x0000 Param: 0x0000000000000000
tDeadline: 1970-01-02 04:50:06.200000000 FID: 0x2 GID: 0x0222 EVTNO: 0x0000 SID: 0x0000 BPID: 0x00000 RES: 0x0000 Param: 0x0000000000000000
tDeadline: 1970-01-02 04:50:06.300000000 FID: 0x3 GID: 0x0333 EVTNO: 0x0000 SID: 0x0000 BPID: 0x00000 RES: 0x0000 Param: 0x0000000000000000
tDeadline: 1970-01-02 04:50:06.400000000 FID: 0x4 GID: 0x0444 EVTNO: 0x0000 SID: 0x0000 BPID: 0x00000 RES: 0x0000 Param: 0x0000000000000000
tDeadline: 1970-01-02 04:50:07.100000000 FID: 0x1 GID: 0x0111 EVTNO: 0x0000 SID: 0x0000 BPID: 0x00000 RES: 0x0000 Param: 0x0000000000000000
...

CRYRING Injector Example

This example demonstrates that precise hardware timed schedules can be achieved locally using saft-dm using two pulses from the LEMO I/O of an SCU. Consider a schedule for the CRYRING injector

Figure: (Outdated)schedule for the CRYRING injector, timing group YRLE.

For saft-dm, a similar schedule has been created in a text file cryring_injector.txt

0x00C8101001000000 0x0 000000000
0x00C9101001000000 0x0 000000008
0x00CA101003000000 0x0 000000016
0x00CA123003000000 0x0 989000000
0x00CA124003000000 0x0 990500000
0x00CA122003000000 0x0 991500000
0x00C9118002000000 0x0 991750000
0x00CA206003000000 0x0 992000000
0x00C9206002000000 0x0 992000000  //YRLE: CMD_BEAM_ON
0x00C9119002000000 0x0 992100000  //YRLE: CMD_BI_MEAS1
0x00C911A002000000 0x0 992300000
0x00C9208002000000 0x0 993000000  //YRLE: CMD_BEAM_OFF
0x00CA208003000000 0x0 993000000 

saft-dm bla -fp -n 3600 cryring_injector.txt will repeat that schedule for every second of the next hour.

It might be instructive to use the two LEMO outputs on a SCU to view the "beam on window" and to generate a 10us long trigger pulse upon BI_MEAS1 using saft-io-ctl.

saft-io-ctl baseboard -n B1 -o1                                                           //output enabable for I/O B1
saft-io-ctl baseboard -n B2 -o1                                                           //output enabable for I/O B2
saft-io-ctl baseboard -n B1 -c 0x00c9206000000000 0xFFFFFFF000000000 0x0 0x0 1 -u         //B1 to high when CMD_BEAM_ON for YRLE is received
saft-io-ctl baseboard -n B1 -c 0x00c9208000000000 0xFFFFFFF000000000 0x0 0x0 0 -u         //B1 to low when CMD_BEAM_OFF for YRLE is received
saft-io-ctl baseboard -n B2 -c 0x00C9119000000000 0xFFFFFFF000000000 0x0 0x0 1 -u         //B2 to high when CMD_BI_MEAS1 for YRLE is received
saft-io-ctl baseboard -n B2 -c 0x00C9119000000000 0xFFFFFFF000000000 10000 0x0 0 -u       //B2 to low 10us after CMD_BI_MEAS1 for YRLE is received

Figure: A pulse indicating the "beam on window" (yellow) generated from the B1 I/O of a SCU. The schedule is generated locally using saft-dm.

Figure: A pulse indicating the "beam on window" (yellow) and a 10us long trigger synchronous to the BI_MEAS1 timing event (red) generated from the B1 and B2 I/Os of a SCU. The schedule is generated locally using saft-dm. Please note, that the rising edge of the trigger pulse happens exactly 100us after the "timing event" CMD_BEAM_ON indicated by the rising edge of the "beam on window".

-- DietrichBeck - 02 Dec 2016