Tools

The driver is distributed with a few tools living in the tools/ subdirectory, most of these tools use the fmc-tdc library. The programs are meant to provide examples about the use of the driver and library interface.

List TDC boards

The tool fmc-tdc-list is capable of listing the available boards in the system. Below is the output from the command on an example system with 3 SPEC boards, each populated with a TDC mezzanine.

$ fmc-tdc-list
FMC-TDC Device ID 0019
FMC-TDC Device ID 0018
FMC-TDC Device ID 0017

Termination Configuration

The tool fmc-tdc-term enables or disables the 50 Ohm termination of a given input channel. The listing below shows the run of fmc-tdc-term tool to get the current status of the 50 Ohm termination on the TDC board with an ID assigned to 4:

$ fmc-tdc-term 0x4
channel 0: 50 Ohm termination is off
channel 1: 50 Ohm termination is off
channel 2: 50 Ohm termination is off
channel 3: 50 Ohm termination is off
channel 4: 50 Ohm termination is off

To set the 50 Ohm termination e.g. on channel 0 on the TDC board with an ID assigned to 4 please execute the following command:

$ fmc-tdc-term 0x4 0 on
channel 0: 50 Ohm termination is on

Reading Temperature

The tool fmc-tdc-temperature allows to read the current temperature of the TDC board. The command below reads the temperature of the TDC board with an ID assigned to 4:

$ fmc-tdc-temperature 0x4
31.4 deg C

Getting And Setting Board Time

The tool fmc-tdc-time allows to read and switch the time source to White-Rabbit or local oscillator. The command below gets the information about the current time source:

$ fmc-tdc-time 0x4 get
WR Status: synchronized.
Current TAI time is 1647471357.000000000 s

In the example above, the time source has been set to White-Rabbit. To set the time source to the local oscillator:

$ fmc-tdc-time 0x4 local
# no output after the command is executed

To set the time source to the White-Rabbit:

$ fmc-tdc-time 0x4 wr
Locking the card to WR: ... locked!

Read Timestamps

The tool fmc-tdc-tstamp can print acquired timestamps. In the example below the tool prints 5 samples (-s parameter) from the channel 2 (-c parameter) on the board with the ID 0x19 (-D parameter).

fmc-tdc-tstamp -D 0x19 -c 2 -s 5
channel 2 | channel seq 0
    ts   0000041028s  590492339195ps
    diff 0000041028s  590492339195ps [0.000024 Hz]
channel 2 | channel seq 1
    ts   0000041028s  591492339023ps
    diff 0000000000s  000999999828ps [1000.001000 Hz]
channel 2 | channel seq 2
    ts   0000041028s  592492338931ps
    diff 0000000000s  000999999908ps [1000.001000 Hz]
channel 2 | channel seq 3
    ts   0000041028s  593492338597ps
    diff 0000000000s  000999999666ps [1000.001000 Hz]
channel 2 | channel seq 4
    ts   0000041028s  594492338425ps
    diff 0000000000s  000999999828ps [1000.001000 Hz]

User Offset Configuration

The tool fmc-tdc-offset sets or gets the user-offset applied to the incoming timestamps. The example below show that all offsets are set to 0 in an example setup.

$ fmc-tdc-offset 0x19
channel 0: 0 ps
channel 1: 0 ps
channel 2: 0 ps
channel 3: 0 ps
channel 4: 0 ps

Calibration Data

The tool fmc-tdc-calibration reads calibration data from a file that contains it in binary form and shows it on STDOUT in binary form or in human readable one (default). This could be used to change the TDC calibration data at runtime by redirecting the binary output of this program to the proper sysfs binary attribute. This tool expects all values to be little endian. Please note that the TDC driver supports only ps precision, but calibration data is typically stored with sub-picosecond precision. For this reason, according to your source, calibration values may disagree on the fs part.

The example below shows the read of calibration data:

$ fmc-tdc-calibration -f /sys/bus/zio/devices/tdc-1n5c-0004/calibration_data
Temperature: 47 C
White Rabbit Offset: 229460000 fs
Zero Offset
  ch1-ch2: -109000 fs
  ch2-ch3: 493000 fs
  ch3-ch4: 499000 fs
  ch4-ch5: 336000 fs