Linux PTP Grandmaster with ptp4l and phc2sys

linuxptp is the reference implementation of IEEE 1588 on Linux and includes everything you need to build a PTP grandmaster: ptp4l for the protocol itself, phc2sys to discipline the system clock to the hardware clock, and pmc for management queries. Getting sub-microsecond accuracy requires understanding which clock is being corrected by which daemon — a distinction that a misconfigured deployment usually gets wrong by an order of magnitude. This article covers the daemon roles, a grandmaster configuration, and the verification commands that prove the discipline loop is closed.

Three programs, three jobs

• ptp4l — implements the protocol as an Ordinary Clock, Boundary Clock or Transparent Clock. With hardware timestamping it adjusts the PTP hardware clock (PHC); with software timestamping it adjusts the system clock directly.
• phc2sys — synchronises two clocks, typically the system clock (CLOCK_REALTIME) to the PHC which ptp4l has already disciplined.
• pmc — the PTP management client, for querying and setting attributes on PTP nodes.

The relationship in one line: on a slave, ptp4l corrects the PHC and phc2sys corrects the system clock from the PHC. In software timestamping mode phc2sys is not needed at all, because ptp4l drives the system clock itself.

A slave node

ptp4l -i eth0 -f /etc/ptp4l.conf -s

where -i selects the interface, -f the configuration file, and -s runs the node in slave-only mode so it never announces itself as a master. A healthy slave log looks like:

ptp4l[537896.093]: port 1: UNCALIBRATED to SLAVE on MASTER_CLOCK_SELECTED
ptp4l[537897.093]: master offset -18 s2 freq -9099 path delay 545
ptp4l[537898.093]: master offset 641 s2 freq -8446 path delay 513
ptp4l[537899.093]: master offset 570 s2 freq -8324 path delay 533

The two numbers to watch are master offset (nanoseconds away from the master, which should converge toward zero) and path delay (the measured round-trip, which should be stable). A large, wandering offset with a stable path delay points at timestamping problems; a wildly varying path delay points at the network.

Disciplining the system clock

phc2sys -s eth0 -c CLOCK_REALTIME -w

-w waits for ptp4l to reach a synchronised state before starting, which avoids disciplining the system clock from an unlocked PHC. The automatic form is often preferable on servers with several interfaces:

phc2sys -a -r

-a reads the clock pairs from the running ptp4l process and follows port state changes, adjusting the direction of synchronisation automatically. The system clock is not synchronised unless -r is also given; to allow the system clock itself to act as a time source, specify -r twice. In PPS mode (-d /dev/pps0) the PPS signal only marks the start of a second, so the slave clock must already be close to the correct time before phc2sys starts.

Building a grandmaster

# /etc/ptp4l.conf (grandmaster-relevant settings)
[global]
domainNumber            0
priority1               128
priority2               128
gmCapable               1
time_stamping           hardware
network_transport       UDPv4
clockClass              6
clockAccuracy           0x21

ptp4l -i eth0 -f /etc/ptp4l.conf -m
phc2sys -s eth0 -c CLOCK_REALTIME -w

Key attributes:

• gmCapable — whether the local clock can become grand master. This only applies to 802.1AS clocks; it has no effect on 1588 clocks.
• priority1 / priority2 — used by the best master clock algorithm; lower values take precedence. Setting priority1 low on the intended grandmaster makes the election deterministic instead of depending on clockClass and accuracy attributes.
• time_stamping — hardware, software or legacy. Hardware is the default and the only mode that reaches sub-microsecond accuracy. With more than one interface, all ports must attach to the same PHC, or you must set boundary_clock_jbod 1 and synchronise the separate PHCs externally.
• network_transport — UDPv4 (default), UDPv6 or the raw IEEE 802.3 transport via -2.

When the host is the domain master using hardware timestamping, it is phc2sys that maintains the offset between PTP time and UTC, because PTP time does not apply leap seconds while the system clock does.

Verification and management

pmc -u -b 0 'GET TIME_STATUS_NP'
pmc -u -b 0 'GET PORT_DATA_SET'
journalctl -u ptp4l -n 50
journalctl -u phc2sys -n 50

# confirm hardware timestamping capability on the NIC
ethtool -T eth0
ls /sys/class/ptp/

ethtool -T is the first check on any new host: if the NIC reports only software timestamping, no amount of daemon tuning will produce accurate results. pmc queries require the peer to support management messages, which many PTP devices — and linuxptp itself in some areas — only partially implement, so treat a failed query as a capability question rather than an error.

Deployment notes

• Run both daemons as systemd services with Restart=always, and start phc2sys with -w so the ordering is enforced.
• Keep ptp4l and phc2sys logs — the offset series is the evidence you need when an application complains about timestamp accuracy.
• Do not mix hardware and software timestamping within one domain: the asymmetries will show up as a fixed offset that no amount of tuning removes.
• For a grandmaster fed by GPS, discipline the PHC from the PPS input with phc2sys before advertising the host as a time source.

See also: PTP IEEE 1588 boundary clock configuration, choosing between NTP and PTP, and boundary clock vs transparent clock.

原文链接：https://manpages.debian.org/bullseye/linuxptp/ptp4l.8.en.html