How-To: saft-io-ctl

Introduction

Use this tool to configure I/Os and setup rules for I/Os in the ECA.

Usage

IO-CTL for SAFTlib 
Usage: saft-io-ctl <unique device name> [OPTIONS]

Arguments/[OPTIONS]:
  -n <name>:                                     Specify IO name or leave blank (to see all IOs/conditions)

  -o 0/1:                                        Toggle output enable
  -t 0/1:                                        Toggle termination/resistor
  -q 0/1:                                        Toggle special (output) functionality
  -e 0/1:                                        Toggle special (input) functionality
  -m 0/1:                                        Toggle BuTiS t0 + TS gate/mux
  -p 0/1:                                        Toggle WR PPS gate/mux
  -a 0/1:                                        Toggle gate (output)
  -j 0/1:                                        Toggle gate (input)
  -d 0/1:                                        Drive output value
  -k <time [ns]>                                 Change stable time

  -i:                                            List every IO and it's capability

  -s:                                            Snoop on input(s)
  -w:                                            Disable all events from input(s)
  -y:                                            Display IO input to event table
  -b <prefix>:                                   Enable event source(s) and set prefix
  -r:                                            Disable event source(s)

  -c <event id> <mask> <offset> <flags> <level>: Create a new condition (active)
  -g:                                            Negative offset (new condition)
  -u:                                            Disown the created condition
  -x:                                            Destroy all unowned conditions
  -f:                                            Flip active/inactive conditions
  -z:                                            Translate mask
  -l:                                            List all conditions

  -v:                                            Switch to verbose mode
  -U:                                            use UTC instead of TAI
  -h:                                            Print help (this message)

Condition <flags> parameter:
  Accept Late:                                   0x1 (l)
  Accept Early:                                  0x2 (e)
  Accept Conflict:                               0x4 (c)
  Accept Delayed:                                0x8 (d)

  These flags can be used in combination (e.g. flag 0x3 will accept late and early events)

Example:
saft-io-ctl exploder5a_123t -n IO1 -o 1 -t 0 -d 1
  This will enable the output and disable the input termination and drive the output high

Report bugs to <csco-tg@gsi.de>
Licensed under the GPLv3

Example

This example shows how to set up a TR (here: PEXARIA) so that a couple of actions are linked to one "timing event".

Figure: Several actions linked to one "timing event".

Output 1 will blink three times and output 2 will blink two times when output 1 is low. The sequence should start upon the reception of one single event with ID 0x1111000000000000.

List all Conditions (of the ECA)
On a fresh TR this should look like this.

saft-io-ctl pexaria -l
IO             Number      ID                  Mask                Offset      Flags       Edge     Status    Owner   
----------------------------------------------------------------------------------------------------------------------

List every IO and it's capability

saft-io-ctl pexaria -i
Name           Direction  OutputEnable  InputTermination  SpecialOut  SpecialIn  Resolution  Logic Level
--------------------------------------------------------------------------------------------------------
IO1            Out        Yes           No                No          No         1ns (LVDS)  LVTTL
IO2            Out        Yes           No                No          No         1ns (LVDS)  LVTTL
IO3            Out        Yes           No                No          No         1ns (LVDS)  LVTTL
LED1_ADD_R     Out        No            No                No          No         8ns (GPIO)  TTL
LED1_BASE_R    Out        No            No                No          No         8ns (GPIO)  TTL
LED2_ADD_B     Out        No            No                No          No         8ns (GPIO)  TTL
LED2_BASE_B    Out        No            No                No          No         8ns (GPIO)  TTL
LED3_ADD_G     Out        No            No                No          No         8ns (GPIO)  TTL
LED3_BASE_G    Out        No            No                No          No         8ns (GPIO)  TTL
LED4_ADD_W     Out        No            No                No          No         8ns (GPIO)  TTL
LED4_BASE_W    Out        No            No                No          No         8ns (GPIO)  TTL
IO1            In         No            Yes               No          No         1ns (LVDS)  LVTTL
IO2            In         No            Yes               No          No         1ns (LVDS)  LVTTL
IO3            In         No            Yes               No          No         1ns (LVDS)  LVTTL
MHDMR_SYIN     In         No            No                No          No         1ns (LVDS)  LVDS
MHDMR_TRIN     In         No            No                No          No         1ns (LVDS)  LVDS

Configure Outputs
Configure two I/Os as outputs, termination off, output value low.

saft-io-ctl pexaria -n IO1 -o 1 -t 0 -d 0
saft-io-ctl pexaria -n IO2 -o 1 -t 0 -d 0

You may check the current state using saft-io-ctl pexaria -n IO1 .

Configure Conditions for Outputs
First, configure three blinks on IO1. with a on-off period of 200ms each.
Second, configure two blinks on IO2 that is alternating to the ones on IO1.
Use saft-io-ctl -h to get an explanation on the syntax.

saft-io-ctl pexaria -n IO1 -u -c 0x1111000000000000 0xFFFF000000000000 100000000 0x0 1
saft-io-ctl pexaria -n IO1 -u -c 0x1111000000000000 0xFFFF000000000000 200000000 0x0 0
saft-io-ctl pexaria -n IO1 -u -c 0x1111000000000000 0xFFFF000000000000 300000000 0x0 1
saft-io-ctl pexaria -n IO1 -u -c 0x1111000000000000 0xFFFF000000000000 400000000 0x0 0
saft-io-ctl pexaria -n IO1 -u -c 0x1111000000000000 0xFFFF000000000000 500000000 0x0 1
saft-io-ctl pexaria -n IO1 -u -c 0x1111000000000000 0xFFFF000000000000 600000000 0x0 0
saft-io-ctl pexaria -n IO2 -u -c 0x1111000000000000 0xFFFF000000000000 200000000 0x0 1
saft-io-ctl pexaria -n IO2 -u -c 0x1111000000000000 0xFFFF000000000000 300000000 0x0 0
saft-io-ctl pexaria -n IO2 -u -c 0x1111000000000000 0xFFFF000000000000 400000000 0x0 1
saft-io-ctl pexaria -n IO2 -u -c 0x1111000000000000 0xFFFF000000000000 500000000 0x0 0

Please note: The programmed action will be executed within the FPGA with nanoseconds precision, when the "timing event" 0x1111000000000000 becomes true. Execution does not depend on the host system (OS, drivers, software). In this example the blink frequency is only 5Hz for convenience; the blinking LEDs can be inspected by the naked eye. However, the FPGA supports rates up to a couple of hundreds of MHz, depending on the hardware.

It may be instructive to list the conditions once more by using saft-io-ctl pexaria -l again.

Check the Results
To see what is going on

• have a look at the LEDs
• use saft-io-ctl pexaria -s
• wait for the event with ID 0x1111000000000000. There are several possibilities
  • wait until a central Data Master broadcasts that messages via the White Rabbit network
  • inject a single timing message locally using saft-ctl bla -f inject 0x1111000000000000 0x0 0
  • inject a series of timing messages locally using saft-dm bla -fp -n 100 schedule.txt, (where schedule.txt contains a line '0x1111000000000000 0x0 123000000')

Below is a result one would get when a timing message is received and the ECA generates the "timing event" at the full second.

saft-io-ctl pexaria -s
IO             Edge     Flags       ID                  Timestamp           Formatted Date               
---------------------------------------------------------------------------------------------------------
IO1            Rising   .... (0x0)  0xfffe000000000001  0x148d5fb07d8c70f8  2016-12-05 13:37:44.099999992
IO2            Rising   .... (0x0)  0xfffe000000000003  0x148d5fb0838251f8  2016-12-05 13:37:44.199999992
IO1            Falling  d... (0x8)  0xfffe000000000000  0x148d5fb0838251f8  2016-12-05 13:37:44.199999992
IO2            Falling  .... (0x0)  0xfffe000000000002  0x148d5fb0897832f8  2016-12-05 13:37:44.299999992
IO1            Rising   d... (0x8)  0xfffe000000000001  0x148d5fb0897832f8  2016-12-05 13:37:44.299999992
IO2            Rising   .... (0x0)  0xfffe000000000003  0x148d5fb08f6e13f8  2016-12-05 13:37:44.399999992
IO1            Falling  d... (0x8)  0xfffe000000000000  0x148d5fb08f6e13f8  2016-12-05 13:37:44.399999992
IO2            Falling  .... (0x0)  0xfffe000000000002  0x148d5fb09563f4f8  2016-12-05 13:37:44.499999992
IO1            Rising   d... (0x8)  0xfffe000000000001  0x148d5fb09563f4f8  2016-12-05 13:37:44.499999992
IO1            Falling  .... (0x0)  0xfffe000000000000  0x148d5fb09b59d5f8  2016-12-05 13:37:44.599999992

-- DietrichBeck - 30 Sep 2020