Skip to content

ntpstats.hwclocks

Live samples from hardware clocks and clock-error-bound services.

  • PHC (any PTP hardware clock, /dev/ptpN): the system clock against the PHC with the kernel's PTP_SYS_OFFSET_EXTENDED ioctl (include/uapi/linux/ptp_clock.h), as linuxptp's phc2sys reads it (sysoff.c): of n readings [system, PHC, system] the one with the shortest system window is kept, and the PHC is compared with the window's midpoint. A PHC usually runs on TAI; the whole seconds between it and the system clock (TAI - UTC) are removed and reported as whole_seconds unless tai_utc is given. Offset = PHC - system (reference - local). Reading /dev/ptpN needs read permission on the device.
  • OCP Time Card (/sys/class/timecard/ocpN, Linux ptp_ocp driver, Documentation/ABI/testing/sysfs-timecard): the PHC above, through the card's ptp link, plus gnss_sync (1 when it reads SYNC, 0 when LOST @ ...), clock_source, utc_tai_offset and the firmware's clock_status_offset and clock_status_drift (in the firmware's own units, kept as they are).
  • AWS ClockBound: clockbound_now() of the ClockBound client library (libclockbound, clock-bound-ffi/include/clockbound.h), called in process. The sample is the window's centre minus the system clock read around the call, the half-width as bound and the clock status.
  • Meta fbclock: ptpcheck fbclock --utc (facebook/time), whose text output is Earliest/Latest in ns. The command runs as a subprocess, so the system clock is read before and after it and the window's centre is compared with the midpoint; read_window is that interval, which bounds the error of the comparison.

The samples of the two bound services also record earliest and latest, so their watch log is a bounds file that ntpstats bounds checks against a reference.

sys_offset_request(n_samples=9)

The ptp_sys_offset_extended request: n samples against CLOCK_REALTIME.

parse_sys_offset(buf)

(system_ns, phc_minus_system_ns, window_ns) from a filled ptp_sys_offset_extended: the reading with the shortest system window (linuxptp sysoff_estimate).

read_phc(device='/dev/ptp0', n_samples=9)

Read a PHC against the system clock (see :func:parse_sys_offset).

phc_sample(sys_ns, phc_minus_sys_ns, window_ns, tai_utc=None)

A watch sample from one PHC reading; removes TAI - UTC (given, or the whole seconds).

sample_phc(cmd=('/dev/ptp0',))

cmd is [device] or [device, tai_utc_seconds].

timecard_status(path='/sys/class/timecard/ocp0')

The status attributes of an OCP Time Card (ptp_ocp sysfs).

sample_timecard(cmd=('/sys/class/timecard/ocp0',))

cmd is [sysfs directory]; the PHC comes from its ptp link.

clockbound_sample(before_ns, after_ns, earliest_ns, latest_ns, status)

A watch sample from one clockbound_now() result and the system clock read around it.

sample_clockbound(cmd=())

cmd may name the library file (default: found on the library path).

parse_fbclock(text)

(earliest_ns, latest_ns) from ptpcheck fbclock text output.

parse_port_states(text)

[(port number, state)] from pmc PORT_DATA_SET responses (one per port).