Linux PTP Hardware Clocks: PHC Discovery, Synchronization, and Validation

A Precision Time Protocol deployment can expose several clocks that look similar in command output but represent different time bases. A network interface may provide a PTP Hardware Clock (PHC), the system has clocks such as CLOCK_REALTIME and CLOCK_MONOTONIC, and a PTP daemon estimates the relationship between the local and grandmaster clocks. Correct operation requires knowing which port owns each PHC, which clock a measurement uses, and which process is permitted to adjust it.

PTP is not “NTP with smaller numbers.” Hardware timestamps, clock servo state, path asymmetry, grandmaster selection, network topology, and oscillator behavior all matter. A small displayed offset is meaningful only when the timestamp source and time scale are understood.

Map interfaces to PHC devices

The kernel PTP class exposes registered clocks through /dev/ptpN and sysfs. The numeric PHC index is an enumeration result, not a permanent interface identity. A system with multiple NICs, ports, or virtual devices can assign a different number after boot or driver changes.

ls -l /dev/ptp*
ls -l /sys/class/ptp/
ethtool -T eth0
readlink -f /sys/class/net/eth0/device

Replace eth0 with the intended interface. The timestamp capability output reports supported hardware and software timestamping modes, but a requested mode can still be filtered or altered by the driver. Correlate the PHC link under the network device’s sysfs directory when available, and validate with the exact driver and firmware.

Do not assume a PHC belongs to the interface name that happens to share its numeric suffix. Confirm the association after reboot, hotplug, bond changes, or NIC firmware updates. Record PCI path, port, driver, PHC identity, and interface name in monitoring labels.

Separate clock roles

CLOCK_REALTIME is settable wall-clock time and can step. CLOCK_MONOTONIC is intended for elapsed intervals and does not follow wall-clock jumps in the same way. A PHC has its own device clock and can be adjusted independently. Hardware timestamps usually use a PHC time base, while software timestamps are generated in a kernel path related to system clocks.

To compare two clocks, measure or maintain their offset deliberately. LinuxPTP tools such as ptp4l and phc2sys have different responsibilities: one participates in PTP message processing and clock servo behavior, while the other can synchronize a PHC and a system clock according to the configured direction. The exact architecture depends on whether the NIC timestamp clock is selected as master or follows system time.

Never compare raw timestamps from different domains as if they were directly ordered. A wall-clock step can make an event appear to happen in the past, and a PHC adjustment can change the offset without any network packet changing. Store clock identifiers and synchronization state beside captured timing data.

Validate hardware timestamp capability

Hardware timestamp support can exist for transmit, receive, or both, with filters limiting which packets are timestamped. The application requests timestamping through socket options, the networking stack configures the device, and the driver programs the NIC. A successful socket option does not prove that every packet receives a hardware timestamp.

Use ethtool timestamp capability information and the kernel networking timestamping documentation to determine the device path. When collecting a packet trace, distinguish software-generated timestamps from raw hardware timestamps and converted timestamps. The timestamping API reports metadata flags; an application should not relabel the source based on the interface name alone.

For PTP, verify that the configured message type and transport receive the expected timestamp. Check the daemon’s port state, selected grandmaster, delay mechanism, and servo state. A network path can deliver packets while timestamps are absent, stale, or associated with another PHC.

Configure and observe LinuxPTP as one clock system

LinuxPTP configuration includes interface selection, transport, delay mechanism, timestamping mode, domain, priority, and servo options. Defaults may be sensible for a specific deployment but should not be copied across unrelated hardware and network topologies. Confirm configuration against the deployed LinuxPTP release and the network’s profile.

Keep one authority responsible for adjusting each clock. Running multiple daemons that independently discipline the same PHC or system clock can create oscillation or misleading status. On a managed host, inspect service units and processes before starting a second instance. A bond or multi-port NIC can share or separate PHCs in hardware-specific ways.

Monitor more than the current offset. Capture port state, grandmaster identity, mean path delay, offset trajectory, frequency adjustment, packet loss, and timestamp error counters. A stable offset with a constantly saturated frequency correction can signal path asymmetry or oscillator mismatch. A jump may follow a master switch, link reset, host suspend, or PHC driver recovery.

PTP delay mechanisms estimate different parts of the path. End-to-end and peer-to-peer approaches exchange different messages and make different assumptions about transparent or boundary clocks. Mixing configuration across nodes can prevent a port from reaching the expected state or produce a biased delay estimate. Confirm that all participating switches and endpoints use the same supported profile and transport.

Servo output has both transient and steady-state meaning. After startup, a large offset can be expected while the clock converges; repeated steps can disrupt time-sensitive applications. Once synchronized, frequency adjustment reflects oscillator correction and path estimation, not a directly measured crystal defect. Preserve the complete convergence trace and compare it with a known stable grandmaster before changing servo constants.

Asymmetric network paths can bias offset even when packet loss is low. Queueing, traffic shaping, switch timestamp behavior, and different route directions affect measurements. A NIC reporting hardware timestamps does not remove path asymmetry. Test under representative network load, compare ports or paths where possible, and avoid using a single unloaded lab sample as the production accuracy guarantee.

PHC lifecycle and operational changes

NIC reset, driver unload, firmware reload, suspend, or link reconfiguration can reset or disconnect a PHC. A daemon may lose its file descriptor or continue operating against a device whose time base restarted. Re-enumerate the PHC mapping after hardware changes and confirm the daemon reopened the intended clock.

Do not set PHC time or step system time as a first diagnostic. Clock adjustment changes application-visible timestamps and can disrupt logs, leases, authentication, and distributed transactions. Prefer read-only status and offset measurement, then schedule a coordinated change with an explicit time source and rollback plan.

Containerization adds a namespace and device-access boundary. A container that can open /dev/ptpN may still lack network interface access or the required capabilities, while PHC numbering may be host-global. Pass a stable device deliberately and ensure only the intended daemon can adjust it.

Build a measurement and acceptance plan

Establish a baseline with the same network topology, NIC firmware, LinuxPTP version, timestamp mode, and grandmaster. Capture the complete daemon status over a representative interval including link retrain or master selection if relevant. Compare offset distribution, not just one sample; state the sample window and whether values are peak-to-peak, RMS, median, or another defined statistic.

Test a deliberate PHC association change or daemon restart only in a lab. Verify that monitoring detects a missing timestamp, a PHC reset, a master transition, and a stalled servo. For systems that suspend, test whether the PHC continues running and how the daemon re-establishes synchronization after resume.

An acceptance record includes interface-to-PHC mapping, hardware timestamp modes, selected master and port state, clock roles, LinuxPTP configuration, offset and delay distributions, frequency correction, and recovery behavior. Avoid a generic “PTP synchronized” boolean without thresholds and clock identities.

PTP becomes reliable when every timestamp names its clock domain and every clock has one owner. Map the NIC and PHC, verify timestamp provenance, observe the servo and path, and revalidate after device lifecycle changes. That makes precision timing measurable rather than a single offset number with ambiguous meaning.

Related:

Sources: