How-To: saft-ctl

Introduction

This tool is intended to diagnose the status saftlib and provide ECA related information of a timing receiver. Moreover one can do simple things like event snooping.

Usage

Usage: saft-ctl <device name> [OPTIONS] [command]


  -h                   display this help and exit
  -a                   absolute time injection
  -f                   use the first attached device (and ignore <device name>)
  -d                   display values in dec format
  -x                   display values in hex format
  -v                   more verbosity, usefull with command 'snoop'
  -p                   used with command 'inject': <time> will be added to next full second (option -p) or current time (option unused)
  -i                   display saftlib info
  -j                   list all attached devices (hardware)
  -k                   display gateware version (hardware)
  -s                   display actual status of software actions
  -t                   display the current temperature in Celsius (if sensor is available) 
  -U                   display/inject absolute time in UTC instead of TAI
  -L                   used with command 'inject' and -U: if injected UTC second is ambiguous choose the later one

  inject  <eventID> <param> <time>  inject event locally, time [ns] is relative (see option -p for precise timing)
  snoop   <eventID> <mask> <offset> snoop events from DM, offset is in ns, CTRL+C to exit (try 'snoop 0x0 0x0 0' for ALL)
  usnoop  <type>       (experimental feature) snoop events from WR-UNIPZ @ UNILAC,  <type> may be one of the following
            '0'        event display, but limited to GIDs of UNILAC and special event numbers
            '1'        shows virtual accelerator (vacc) executed at the seven PZs, similar to 'rsupcycle'
                       the vacc number is accompanied by flags 'N'o chopper, 'S'hort chopper, 'R'igid beam, 'D'ry and 'H'igh current;
                       'warming pulses' are shown in brackets

  attach <path>                    instruct saftd to control a new device (admin only)
  remove                           remove the device from saftlib management (admin only)
  quit                             instructs the saftlib daemon to quit (admin only)


This tool displays Timing Receiver and related saftlib status. It can also be used to list the ECA status for
software actions. Furthermore, one can do simple things with a Timing Receiver (snoop for events, inject messages).

Tip: For using negative values with commands such as 'snoop', consider
using the special argument '--' to terminate option scanning.

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

Status of Software Actions Use saft-ctl bla -fs to display the ECA related status of the first timing receiver in the host system. The following information is provided

• White Rabbit time
• conditions
  • free: number of conditions that can still be instantiated
  • max(capacity): maximum fill state of ECA channel for software actions (total capacity). Note: several distinct action sinks share the underlying hardware.
  • early threshold: messages due further into the future than this value are early
  • latency: nanoseconds between timing message and earliest execution - due to implementation of the ECA
• list of instantiated action sink(s): Action sinks are uniquely assigned to the userland application that instantiated it and saftlib treats each application individually.
  • info on timing receiver
    • name
    • minOffset: attempts to create conditions with offsets less than this value result in an error
    • maxOffset: attempts to create conditions with offsets larger than this value result in an error
  • statistic on actions ("timing events") processed by the ECA for THIS action sink
    • actions: total number of actions processed
    • delayed: number of delayed actions. Delays can happen when the delivery rate of actions (potentially 1GHz) by the ECA exceeds the capability of the receiving component to process the actions. Note: delayed actions are never disordered.
    • conflict: number of conflicting actions. If two actions are scheduled to be executed at the same nanosecond, their relative order is undefined. This is a critical failure as this may leave the system in an undefined state.
    • late: number of late actions. This happens if the hardware was instructed to execute an action at a time in the past. This is a critical failure as it might leave the system in an undefined state. This is typically caused by either a malfunctioning data master, desynchronized clocks, or conditions with large negative offsets.
    • early: number of early actions. This happen if an action is scheduled for execution too far (see "early threshold") into the future. This is a critical failure as it can leave the system in an undefined state. By default, conditions are configured to drop early actions.
    • overflow: number of actions dropped due to overflow. This happens if the action sink overflows. This is a critical failure which may result in an undefined state. Example: This might happen if a userland application is stalled and fails to process actions ("timing events") delivered by the ECA.
  • list of condition(s)
    • EvtID: the 64 bit EventID (see here)
    • mask: used for comparing EventIDs of timing message and condition. A match is achieved if both agree on all the bits set in this mask (prefix matching only).
    • offset: added to scheduled time of the timing message to calculate the action’s time
    • active: The condition should be actively matched. Can be toggled.
    • destructible: some objects are indestructible, representing a physical resource.
    • owner: only the owner may access privileged methods. Such methods can only accessed by others, if the owner decided to "disown" the object.

Info on Hardware Use saft-ctl bla -fj to display the number of attached timing receivers and their properties.

Timing Event Snooping Use saft-ctl bla -f snoop 0x0 0x0 0x0 to snoop for all timing events. Use option "-h" for an explanation of the parameters. Important: When snooping for all timing events,

• all messages delivered by a data master to the input of the ECA will lead to the generation of a "timing event"
• the ECA will process all of them up to the maximum throughput which can be up to 1 Ghz.
• this might lead to entire saturation of the host bridge, saftlib or operating system.
• this might cause errors such as "delays" or even subsequent critical errors such as "overflows" or "conflicts" in other userland applications too.

Example: Use saft-ctl bla -fx snoop 0x1154000000000000 0xffff000000000000 0 to snoop for all messages with format ID 0x1 with timing group 0x154 (ESR).

Injection of Timing Messages Use saft-ctl bla -fp inject 0x1 0x0 1000000 to inject a timing message with EventID 0x1 at the input of the ECA. In this example, the action is scheduled for execution exactly 1ms after the next full second. Use option "-h" for details. Please note:

• such a message is processed by the ECA exactly like a message from a Data Master. Thus, this command can be used to trigger software or hardware actions.
• use the command line tool saft-dm for injecting more complex schedules

-- DietrichBeck - 13 February 2018