PTP functional description

PTP is Precision Time Protocol as described by IEEE standard 1588.

The purpose of this application is to allow to synchronize multiple clocks in the network. This software is based on the open source project linuxptp. On top of which were added patches to add support for Relay as described in 8021.AS 2020. The plan is to have these patches upstream to the linuxptp project. The application that is part of the BSP has these extra patches.

This project can be found here ptp4l

Ptp4l supports the following:

hardware and software timestamping: 1-step and 2-step
implements: ordinary, boundary, transparent clocks and AS bridge
transport over UDP/IPv4, UDP/IPv6, raw Ethernet
supports multiple servos: pi, linreq, ntpshm, nullf

There are multiple executable that are are used:

ptp4l: this is the daemon that adjusted the PHC(Physical Hardware Clock) such offset from master is 0.
pmc: short live application to interact with ptp4l to inspect status and allow certain configurations attributes to be updated without restarting the daemon
phc2sys: this is a daemon which is used to synchronize two or more clocks in the system. Typically is used to synchronize the system clock with a PTP hardware clock which itself is synchronized using ptp4l daemon.
ts2phc: this is a daemon which is used to synchronize a PTP hardware clock to GPS and or 1PPS.

It is possible to pass the following arguments to ptp4l to the command line. The most important arguments are:

-l: to set the log level
-m: to print message to standard output
-i: interface on which to run
-f: to set the configuration file
-p: specify directly the PHC device

When ptp4l is started, it has an option to read the configuration from a file. The most important configurations options are:

delay_mechanism: which can be P2P, Auto or E2E.
network_transport: which can be L2, UDPv4 or UDPv6.
time_stamping: which can be: hardware, software or legacy.
clock_type: which can be OC, BC or Relay
slaveOnly: force the node to behave as a slave only
domainNumber: represents the PTP domain number. Default is 0.
twoStepFlag: a value of 1 uses 2-step timestamping, while a value of 0 uses 1-step timestamping

For more details about ptp4l run: man ptp4l

Ptp4l is works on the physical interfaces and not on the bridge interface, so before starting the daemon, make sure that the interface is up using the command:

ip link set dev eth0 up

1. PTP4L

1.1. Ordinary clock(OC)

To run ptp4l as ordinary clock, the following configuration is needed:

cat > /tmp/linux.cfg
[global]
clock_type              OC
delay_mechanism         E2E
network_transport       L2
time_stamping           hardware
first_step_threshold    0.000001
step_threshold          0.000001

[eth0]

And start ptp4l as:

ptp4l -f /tmp/linux.cfg &

1.2. Boundary clock(BC)

For the boundary clock, it is required at least 2 network interfaces. Because it is required have 1 slave and at least 1 master. Therefore the configuration file can look like this:

cat > /tmp/linux.cfg
[global]
clock_type              BC
delay_mechanism         E2E
network_transport       L2
time_stamping           hardware
first_step_threshold    0.000001
step_threshold          0.000001

[eth0]
[eth1]

And start ptp4l as:

ptp4l -f /tmp/linux.cfg &

1.3. Transparent clock(TC)

For the transparent clock, it is required at least 2 network interfaces. The frames will be forward in SW by the ptp4l application but the timestamps will be do by the HW. The configuration file can look like this:

[global]
priority1               254
free_running            1
freq_est_interval       3
tc_spanning_tree        1
summary_interval        1
clock_type              P2P_TC
network_transport       L2
delay_mechanism         P2P

[eth0]
[eth1]

And start ptp4l as:

ptp4l -f /tmp/linux.cfg &

1.4. AS Bridge(Relay)

The support for this feature is not part of the upstream project. Therefore the implementation and the configuration might changed based on the requests received when this feature will be upstream.

The relay behaves similar to the transparent clock and to boundary clock. The ptp4l configuration for relay can be the following:

cat > /tmp/linux.cfg
[global]
priority1               254
priority2               254
clock_type              RELAY
network_transport       L2
delay_mechanism         P2P
path_trace_enabled      1
transportSpecific       1
follow_up_info          1
ptp_dst_mac             01:80:C2:00:00:0E
gmCapable               1
logAnnounceInterval     0
logSyncInterval         -3
syncReceiptTimeout      3
free_running            1
summary_interval        1

[eth0]
[eth1]
[eth2]

And start ptp4l as:

ptp4l -f /tmp/linux.cfg &

1.5. Multiple PTP instances

It is possible to run multiple ptp4l instances and each of them to control a different PHC. For example, let’s say that we want to control PHC0 and PHC1 and they have the PTP domains 0 and 20.

cat > /tmp/ptp0.cfg
[global]
clock_type              OC
delay_mechanism         E2E
network_transport       L2
time_stamping           hardware
first_step_threshold    0.000001
step_threshold          0.000001

And start the first ptp4l using:

ptp4l -p /dev/ptp0 -f /tmp/ptp0.cfg &

And the second ptp4l will have the configuration:

cat > /tmp/ptp1.cfg
[global]
clock_type              OC
delay_mechanism         E2E
network_transport       L2
time_stamping           hardware
first_step_threshold    0.000001
step_threshold          0.000001
domainNumber            20

And start the second ptp4l using:

ptp4l -p /dev/ptp1 -f /tmp/ptp0.cfg &

If multiple ptp4l instances need to access the same PHC then it is possible and recommended to use the option -i instead of -p.

1.6. DPLL

This feature is still in early stage and is not supported by all the platforms.

DPLL (Digital Phased-Locked Loop) is a device that might exists on the boards. It is possible to expose this device as a HW clock (ptp device) but then it is required to configure this device when using ptp4l and not the other timestamping unit devices. If the HW doesn’t support this or the timestamping units (PHY or switch) doesn’t have 2 signals (1588 REF clock and 1PPS input) from the DPLL then it is not possible to use the DPLL. Before using this make sure that the HW supports this.

The main advantage of the DPLL, is that it has a more stable clock and then it is not required to run phc2sys to synchronize different PTP clocks as the clocks will be synchronized using ts2phc every second.

First it is required to synchronize the DPLL with the timestamping units, to achieve this, it is required to run ts2phc. As all the devices run on the same frequency it is just required to setup the time. To achieve this the following configuration can be used

[global]
clock_servo nullf
first_step_threshold 0.000000001
step_threshold 0.000000001
ts2phc.pulsewidth 100000000

[/dev/ptp1]
ts2phc.pin_index 3

[/dev/ptp2]
ts2phc.pin_index 3

[/dev/ptp3]
ts2phc.pin_index 3

[/dev/ptp10]
ts2phc.master 1
ts2phc.pin_index 0
ts2phc.channel 0

Where:

/dev/ptp10: is the DPLL clock
/dev/ptp1: is the timestamping unit clock
/dev/ptp2: is the timestamping unit clock
/dev/ptp3: is the timestamping unit clock
ts2phc.pin_index: represents the pin on which the event is expected. For master it represents the pin on which to generate the 1PPS and for slave it represents the pin on which to receive the 1PPS.

It is required for this program to run always in the background as all the devices need to always be in sync:

ts2phc -f /tmp/ts2phc.cfg -l 7 &

Once running this program, then all the devices will be in sync and once all of them are in sync then it is possible to start the ptp4l. The ptp4l configuration can be like this:

[global]
clock_type              BC
delay_mechanism         P2P
network_transport       L2
time_stamping           hardware
first_step_threshold    0.0000001
step_threshold          0.0000001
logAnnounceInterval     0
logSyncInterval         0
logMinPdelayReqInterval 0
tx_timestamp_timeout    2000
priority1               254
priority2               254

step_window             3

[eth2]
[eth4]

This is an example of a boundary clock. The main configuration option are:

step_window: represents how many sync frames to ignore after the time was adjusted, so this value needs to be in sync with logSyncInterval. It is recommend that total wait time to be 3 sec.
logSyncInterval: represents the log interval of the sync frames. This needs to be in sync with step_window.

And to start the ptp4l is required to start it option '-p' which needs to point to the DPLL ptp clock, for example:

ptp4l -m -l 7 -f /tmp/ptp4l.cfg -p /dev/ptp10

2. PMC

To be able to see the current status of the ptp4l daemon, it is possible to use the pmc application.

For example to read the offset from master:

pmc -u -b 0 'GET CURRENT_DATA_SET'
sending: GET CURRENT_DATA_SET
        a0369f.fffe.67c4e6-0 seq 0 RESPONSE MANAGEMENT CURRENT_DATA_SET
                stepsRemoved     1
                offsetFromMaster 10.0
                meanPathDelay    252.0

For more details about pmc run: man pmc

3. PHC2SYS

To synchronize the system clock to one of the PHC, the following command can be used:

phc2sys -s /dev/ptp0 -c CLOCK_REALTIME -O 0

Also it is possible to synchronize 2 PHC using the command:

phc2sys -s /dev/ptp0 -c /dev/ptp1 -O 0

Where:

-s: represents the master clock
-c: represents the slave clock
-O: represents the offset between the slave and master times in seconds.

For more details about phc2sys run: man phc2sys

4. TS2PHC

Synchronizes one or more PTP Hardware Clocks using external time stamps. It can synchronize to 1PPS or 1PPS providing TOD information.

For more details about ts2phc run: man ts2phc

5. TESTPTP

Allows to test different features of the PHC. But it also allows to configure different pins of the PHC to have different functions like generating 1PPS or detect rising or falling edges of a signal that comes to the pin.

For example to configure pin 3 to generate 1 PPS with the pulse witdh of 200ms.

testptp -L 3,2;
testptp -p 1000000000 -w 200000000 -H 0

For example to configure pin 2 to store the timestamp when seeing a rising or failling edge

testptp -L 2,1

For more details about testptp run: testptp --help

6. Default configurations

IEEE1588 over Ethernet boundary clock:

[global]
delay_mechanism         E2E
network_transport       L2
time_stamping           hardware
first_step_threshold    0.000001
step_threshold          0.000001
clock_type              BC
logAnnounceInterval     0
logSyncInterval         -4
logMinDelayReqInterval  -2

[eth0]
[eth1]

IEEE1588 over Ethernet transparent clock:

[global]
delay_mechanism         E2E
network_transport       L2
time_stamping           hardware
first_step_threshold    0.000001
step_threshold          0.000001
clock_type              E2E_TC
free_running            1
logAnnounceInterval     0
logSyncInterval         -4
logMinDelayReqInterval  -2

[eth0]
[eth1]

IEEE1588 over Ethernet ordinary clock:

[global]
delay_mechanism         E2E
network_transport       L2
time_stamping           hardware
first_step_threshold    0.000001
step_threshold          0.000001
logAnnounceInterval     0
logSyncInterval         -4
logMinDelayReqInterval  -2

[eth0]

IEEE1588 over IPv4 boundary clock:

[global]
delay_mechanism         E2E
network_transport       UDPv4
time_stamping           hardware
first_step_threshold    0.000001
step_threshold          0.000001
clock_type              BC
logAnnounceInterval     0
logSyncInterval         -4
logMinDelayReqInterval  -2

[eth0]
[eth1]

IEEE1588 over IPv4 transparent clock:

[global]
delay_mechanism         E2E
network_transport       UDPv4
time_stamping           hardware
first_step_threshold    0.000001
step_threshold          0.000001
clock_type              E2E_TC
free_running            1
logAnnounceInterval     0
logSyncInterval         -4
logMinDelayReqInterval  -2

[eth0]
[eth1]

IEEE1588 over IPv4 ordinary clock:

[global]
delay_mechanism         E2E
network_transport       UDPv4
time_stamping           hardware
first_step_threshold    0.000001
step_threshold          0.000001
logAnnounceInterval     0
logSyncInterval         -4
logMinDelayReqInterval  -2

[eth0]

IEEE1588 over IPv6 boundary clock:

[global]
delay_mechanism         E2E
network_transport       UDPv6
time_stamping           hardware
first_step_threshold    0.000001
step_threshold          0.000001
clock_type              BC
logAnnounceInterval     0
logSyncInterval         -4
logMinDelayReqInterval  -2

[eth0]
[eth1]

IEEE1588 over IPv6 transparent clock:

[global]
delay_mechanism         E2E
network_transport       UDPv6
time_stamping           hardware
first_step_threshold    0.000001
step_threshold          0.000001
clock_type              E2E_TC
free_running            1
logAnnounceInterval     0
logSyncInterval         -4
logMinDelayReqInterval  -2

[eth0]
[eth1]

IEEE1588 over IPv6 ordinary clock:

[global]
delay_mechanism         E2E
network_transport       UDPv6
time_stamping           hardware
first_step_threshold    0.000001
step_threshold          0.000001
logAnnounceInterval     0
logSyncInterval         -4
logMinDelayReqInterval  -2

[eth0]

IEEE802.1AS Relay

[global]
priority1               254
priority2               254
clock_type              RELAY
network_transport       L2
delay_mechanism         P2P
path_trace_enabled      1
transportSpecific       1
follow_up_info          1
ptp_dst_mac             01:80:C2:00:00:0E
gmCapable               1
logAnnounceInterval     0
logSyncInterval         -3
syncReceiptTimeout      3
free_running            1
summary_interval        1
tc_spanning_tree        1

[eth0]
[eth1]

IEEE802.1AS End-node

[global]
gmCapable               1
priority1               248
priority2               248
logAnnounceInterval     0
logSyncInterval         -3
syncReceiptTimeout      3
neighborPropDelayThresh 800
min_neighbor_prop_delay -20000000
assume_two_step         1
path_trace_enabled      1
follow_up_info          1
transportSpecific       0x1
ptp_dst_mac             01:80:C2:00:00:0E
network_transport       L2
delay_mechanism         P2P

[eth0]