Linux Precision Time Protocol PTP

Nice picture of the camera you have there, at what time was the picture taken? System time or camera time? Just the timestamp! Precisely please! How precise? As precise as possible!

product owner talking to a developer

So suppose you want to know exact timing, as close as possible to the peripheral attached to your computer as possible, is there a way to achieve that?

Of course that depends a bit on the operating system we use but for linux there is a nice linuxptp package available that can help us out. It supports the Precision Time Protocol which is a synchronization mechanism of hardware clocks according to the international standard IEEE SA 1588-2019

Let’s have a look at an example where we might want to know the exact time, in this case the exact time a picture was taken. A camera is attached to a certain computer board. The computer has an internal clock and so has the camera.

Triggering an image from a camera and receiving the image and time back to the system

The good news is that apart from a System clock on the computer the camera also has its own clock! And with that timestamp we can also record the exact time the image was made given the clock of the camera is synchronized with the clock of the system. That last part is important – usually at startup the camera clock is not aware of the time and the camera clock just starts off at some default time like the unix start date.

How to sync hardware clocks in linux with PTP?

First we need to assure that linux ptp is installed on the system

sudo apt update
sudo apt install linuxptp

This installs several tools like

  • ptp4l (ptp for linux)
  • phc2sys (Ptp Hardware Clock to System) to sync clock to system – only run if necessary
  • pmc (ptp Management Client) can read additional information from ptp4l

The ptp4l program is the tool that ensures a hardware clock is synced. When starting the program we have to specify to what hardware Network Interface Card (NIC) the sync has to take place. Suppose the camera is attached via an UTP cable on eth0 we could start the ptp4l as follows:

ptp4l -q -m -i eth0

This will output information about the synchronization process. Note that hardware synchronization of clocks, which is incredibly more precise than software synchronization is only supported on ports that support the hardware sync. This can be checked via another tool

ethtool -T <device> 

The device must be a name of an existing device on the system, which can be found via ifconfig. An example output of the ethtool could show:

software-system-clock (SOF_TIMESTAMPING_SOFTWARE)
PTP Hardware Clock: none
Hardware Transmit Timestamp Modes: none
Hardware Receive Filter Modes: none

Which means that only software time stamping is supported. This is less precise because the time-packets that are sent between the devices that are synced are interpreted on the packet layer only and there is no additional hardware stamping available.

Hardware time stamping support means that the timestamps are set as close as possible to the physical layer when a packet is sent. Consider the following diagram where a PTP message is sent from a PTP Master to a slave. The PTP message will include a Soft timestamp as well as a Hardware timestamp that can be read at the other (PTP Slave) side. The Slave can use the forwarded hardware timestamp as the timestamp received will be propagated all the way up from the Network Interface Card, the IP, UDP to the PTP layer and can then be synchronized to the Slave Clock.

When a device supports this hardware timestamping, usually on a NIC, the ethtool should provide that information like in the following example.

sudo ethtool -T eth0
Time stamping parameters for eth0:
hardware-transmit     (SOF_TIMESTAMPING_TX_HARDWARE)
        software-transmit     (SOF_TIMESTAMPING_TX_SOFTWARE)
        hardware-receive      (SOF_TIMESTAMPING_RX_HARDWARE)
        software-receive      (SOF_TIMESTAMPING_RX_SOFTWARE)
        software-system-clock (SOF_TIMESTAMPING_SOFTWARE)
        hardware-raw-clock    (SOF_TIMESTAMPING_RAW_HARDWARE)

When the network driver and hardware (Network card) do support the HARDWARE timestamping, the clocks will be synchronized to an enormous precision within nanoseconds.

Pretty amazing!