Simple API For Timing (SaftLib)

Simple API For Timing (SAFT). The design and implementation of SaftLib is a major project.


The key features SaftLib have already described in the specification of the timing receiver nodes for FAIR [1]. For a public compilation see here.

Fig1: Software stack of a timing receiver using SaftLib, which provides interfaces to various components of the FPGA. As an exampl, the ECA is shown as a component. For more details see text.

The figure above depicts the SaftLib software stack of a Timing Receiver (TR) with focus on the Event Condition Action unit (ECA). SaftLib implements an interface towards third party user software such as a FESA class. It abstracts the TR by hiding its Wishbone architecture and address layout and provides high level functionality of the TR. SaftLib supports various components of the FPGA (only the ECA is shown here). Despite hiding the complexity of the gateware, one of its prime features is to provide and manage access to the resources of the FPGA, which is vital if a resource cannot be shared.

  • Hardware Abstraction: SaftLib auto-detects available resources of the hardware by probing the gateware. Userland applications will work on all types of timing receivers providing relevant Wishbone devices.
  • Userland applications must not bypass SaftLib for gaining access to resources that can't be shared. SaftLib provides the features of such resources to applications via Inter Process Communication (IPC).
  • Userland applications must not bypass SaftLib for gaining access to resources that are already taken by SaftLib. Otherwise, consistency of states or data cached in SaftLib will brake.
  • For Wishbone components where SaftLib does not provide a dedicated driver, userland applications may use the Etherbone API.

Interface to ECA

As interface to the ECA SaftLib provides the following
  • A TR can be configured such, that userland application receive on-time information from the timing system ("timing event").
  • Configure System-on-Chip components to execute on-time actions such as digital output.
  • Provide access to configurable I/O - direction (in/out), termination (on/off).
  • Provide means for generating pulses, clocks, delays - triggered by combination of digital input or "timing events".
  • Provide statistics such as # of processed timing messages, # of errors, ...

USB support

Since version 2.2.4 saftlib can work with Timing receivers attached via USB.

TL;DR: When using saftlib with a USB timing receiver (e.g. saftd tr0:dev/ttyUSB0) all eb-tools must use $(saft-eb-fwd tr0) instead of dev/ttyUSB0 (e.g. eb-ls $(saft-eb-fwd tr0)).

A timing receiver attached via USB is controlled through a generic serial driver in Linux which does not support multiple etherbone connections at the same time. When saftlib is running, the saftd process always occupies the connection. If another etherbone tools uses the same device, both, the tool and saftd will crash. Therfore, saftd creates a pseudoterminal (e.g. /dev/pts/8), that emulates an etherbone device and forwards all data to the real hardware device. This is done in a way that all etherbone transactions are completed and the communication will work for all eb-tools using this pseudo terminal. In Linux, the pseudoterminal devices are named /dev/pts/x, where x is an integer number. There is a saftlib tool (saft-eb-fwd) to find out the name of the pseudoterminal for a given saftlib device (e.g. tr0). This can be used to replace the device name (e.g. dev/ttyUSB0) when calling an eb-tool (e.g. eb-ls $(saft-eb-fwd tr0)).

Environment Variables

Since version 2.2.0 the location of saflib's IPC socket (saftbus) can be changed with the environment variable SAFTBUS_SOCKET_PATH.
  • default location for the saftbus socket is /var/run/saftbus/saftbus
  • can be changed by setting e.g. export SAFTBUS_SOCKET_PATH=/tmp/saftbus
  • prior to verions 2.2.0 the saftbus socket location was /tmp/saftbus and could not be changed by users

Since version 2.1.0 a file with a leap-seconds list ist needed
  • This is nomally installed to <saftlib_prefix>/share/saftlib/leap-seconds.list
  • A different file can be used by setting the environment variable SAFTLIB_LEAPSECONDSLIST , e.g. export SAFTLIB_LEAPSECONDSLIST=/tmp/my-leap-seconds.list

Concept and more Details

Figure: SaftLib with (left) and without (right) D-Bus. Userland software is shown in blue and FPGA based hardware is shown in green.

A simiplified concept of SaftLib is shown in the figure above. Features of SaftLib are implemented using a saftd daemon that has direct access to the hardware. The userland applications saft-ctl and a FESA class communicate with the hardware via saftd. Originally, the required inter-process communication has been implemented on D-Bus (more information on D-Bus withing SaftLib can be found here).

As indicated on the right side of the above figure, D-Bus is being replaced by pipes and sockets (autumn 2018). This has the following advantages.
  • reduced latency
  • simplified real-time scheduling of userland processes
  • simpler deployment as run-time dependencies get reduced
Starting spring 2019, SaftLib runs without D-Bus and time (uint_64 t t //nanoseconds since 1970) is replaced by a dedicated 'time' datatype. Please check-out the migration guide from version 1.4 -> 2.0 (see references below).


Documenation on the software API is autogenerated when building SaftLib when in the build process ./configure is called with the --enable-pdf-doc switch. Here is a snapshot from September 2020 (see notes on how-to build saftlib building here).

There exist a couple of useful command line tools based on SaftLib. An overview is given in this How-To.


[1] F-DS-C-06e, Detailed Specification of the FAIR Timing Receiver Nodes

[2] Migration Guide 1.4 -> 2.0; presentation, wiki

[3] documentation, pdf

-- DietrichBeck, MichaelReese - 30 September 2020
Topic attachments
I Attachment Action Size Date Who Comment
saftlib.pdfpdf saftlib.pdf manage 1 MB 13 Jun 2019 - 12:10 DietrichBeck saftlib - 2018-05-25
saftlib2.2.4.pdfpdf saftlib2.2.4.pdf manage 1 MB 30 Sep 2020 - 08:27 MichaelReese autogenerated pdf documentation by saftlib 2.2.4 (merged into a single pdf file)
saftlibAndDbus.jpgjpg saftlibAndDbus.jpg manage 48 K 17 Nov 2018 - 10:49 DietrichBeck saftlib and dbus
saftlibStack.jpgjpg saftlibStack.jpg manage 140 K 17 Nov 2018 - 10:19 DietrichBeck software stack for saftlib
Topic revision: r28 - 16 Mar 2021, DietrichBeck
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback