Precision Timing
The precision timing subsystem provides a small set of reusable mechanisms for
PTP, gPTP, and other users that control high-resolution clocks. Enable it with
CONFIG_PRECISION_TIMING.
Note
The API is at experimental maturity and may still change. A protocol does not change maturity by using this subsystem.
The subsystem deliberately does not implement synchronization policy. PTP and gPTP continue to own their protocol state machines, clock selection, step thresholds, sample acceptance, lock detection, source-loss handling, and diagnostics.
Precision time
precision_time_t is a signed 64-bit nanosecond value. Checked
addition and subtraction helpers report overflow. The type does not identify a
time domain or timescale; modelling TAI, UTC, PHCs, monotonic time, and protocol
relationships is outside this API.
Precision clock
precision_clock dispatches four mandatory clock operations:
read the current time;
set an absolute time;
apply a phase adjustment; and
set a rate offset from the nominal frequency as parts per million with a 16-bit binary fractional field.
All operations must be implemented by a clock adapter. Adjustment ranges and other hardware constraints remain the responsibility of the underlying clock implementation.
precision_clock_ptp_adapter exposes an existing Zephyr PTP clock
device through this interface. It performs the required conversion between
net_ptp_time and precision_time_t; it does not add
capability discovery or synchronization state.
PI controller
precision_pi is an instance-based proportional-integral controller.
Each instance stores its own gains and integral term. For every error sample,
the update is equivalent to:
integral += ki * error;
output = kp * error + integral;
The controller does not decide whether an error should be stepped, rejected, or used for rate adjustment. It also does not track synchronization, acquisition, lock, holdover, source timeout, or clock faults. Callers own those decisions and reset the accumulated integral term when their policy requires it.
The PTP and gPTP integrations initialize their controllers from
CONFIG_PRECISION_TIMING_PI_KP and
CONFIG_PRECISION_TIMING_PI_KI. The integer values express the
gains in thousandths. Direct users of precision_pi_init() may provide
different gains for each controller instance.
Protocol integration
PTP and the gPTP default clock-update path each keep their existing policy and
use a precision_pi for the shared calculation. They initialize a
PTP-clock adapter once and use precision_clock operations to access
the PHC.
Sample
The Precision timing sample demonstrates checked time arithmetic, a software-backed precision clock, and PI-driven rate adjustment.