PTP Servo Tuning Parameters¶

This section describes the clock servo algorithms available in ptp4l and phc2sys, and the tuning parameters that optimize timing performance for different network environments.

Clock Servo Overview ¶

The clock servo is the control algorithm that adjusts the local clock to minimize the offset from the upstream timing source. StarlingX supports two servo algorithms for ptp4l and phc2sys:

linreg (Linear Regression): The default servo in StarlingX. Uses an adaptive algorithm based on linear regression to estimate clock frequency and phase corrections. This servo is self-tuning and requires no manual parameter configuration. It is suitable for most deployments including standard T-GM and T-BC configurations with hardware timestamping.
pi (Proportional-Integral): A classical PI feedback controller that adjusts the clock based on proportional and integral gain constants. This servo provides fine-grained control over convergence behavior and is recommended for Partial Timing Support (PTS) networks or other environments where the default linreg servo does not meet timing accuracy requirements.

For most deployments, the default linreg servo provides good performance without tuning. Consider switching to the pi servo when:

The network uses unicast PTP with non-PTP-aware hops that introduce variable packet delay (common in PTS/telecom networks).
Timing accuracy requirements demand tighter control over convergence speed and steady-state offset.
You need to tune the tradeoff between convergence speed and stability based on observed network behavior.

Configure the Clock Servo ¶

The clock servo is configured as a ptp4l or phc2sys instance parameter.

Switch to the |PI| servo:

~(keystone_admin)]$ system ptp-instance-parameter-add <ptp4l-instance> clock_servo=pi

Switch back to the default linreg servo:

~(keystone_admin)]$ system ptp-instance-parameter-add <ptp4l-instance> clock_servo=linreg

After changing the servo, apply the configuration:

~(keystone_admin)]$ system ptp-instance-apply

When using the pi servo, the following parameters control the behavior of the PI controller. All parameters are configured as ptp4l or phc2sys instance parameters using system ptp-instance-parameter-add.

Core Parameters¶

These are the primary parameters to consider when tuning the PI servo.

Parameter	Default	Description
`pi_proportional_const`	0.0	Proportional gain (Kp) of the PI controller. Controls how aggressively the servo responds to the current offset. Higher values produce faster correction but may cause oscillation in networks with variable delay. When set to 0.0, the system automatically calculates the value from the sync interval.
`pi_integral_const`	0.0	Integral gain (Ki) of the PI controller. Controls how the servo eliminates steady-state offset over time. Higher values correct persistent offset faster but may cause overshoot. When set to 0.0, the value is automatically calculated from the sync interval.
`step_threshold`	0.0	Maximum offset (in seconds) that the servo will correct by adjusting frequency. Offsets larger than this value cause the clock to be stepped (jumped) to the correct time. When set to 0.0, the servo never steps the clock except on start.
`first_step_threshold`	0.00002	Maximum offset (in seconds) that the servo will correct by adjusting frequency on the first update only. Offsets larger than this value cause the clock to be stepped. When set to 0.0, stepping on the first update is disabled.
`max_frequency`	900000000	Maximum allowed frequency adjustment in parts per billion (ppb). This is an additional limit beyond the hardware maximum. When set to 0, the hardware limit is used.
`sanity_freq_limit`	200000000	Maximum allowed frequency offset between the uncorrected clock and the system monotonic clock in ppb. Used as a sanity check. When a larger offset is measured, a warning is logged and the servo is reset.

Auto-Calculation Parameters¶

When pi_proportional_const and pi_integral_const are both set to 0.0 (the default), the PI controller automatically calculates gain values from the sync interval using the following formula parameters. These parameters are intended for advanced use and typically do not need to be changed.

Parameter	Default	Description
`pi_proportional_scale`	0.0	Scale factor for automatic Kp calculation. When set to 0.0, defaults to 0.7 (hardware timestamping) or 0.1 (software timestamping).
`pi_proportional_exponent`	-0.3	Exponent for automatic Kp calculation from the sync interval.
`pi_proportional_norm_max`	0.7	Upper bound for the normalized proportional constant.
`pi_integral_scale`	0.0	Scale factor for automatic Ki calculation. When set to 0.0, defaults to 0.3 (hardware timestamping) or 0.001 (software timestamping).
`pi_integral_exponent`	0.4	Exponent for automatic Ki calculation from the sync interval.
`pi_integral_norm_max`	0.3	Upper bound for the normalized integral constant.

PI Servo Tuning for PTS Networks ¶

In PTS (Partial Timing Support) deployments, PTP packets traverse one or more non-PTP-aware network elements (switches or routers) that do not perform hardware timestamping. These elements introduce PDV variable queuing delays that add jitter to the PTP timing measurements.

The auto-tuned PI servo calculates its gain constants from the sync interval. At typical PTS sync rates (e.g., logSyncInterval=-4, 16 packets/second), the auto-tuned values are approximately:

Kp ≈ 1.6 (proportional)
Ki ≈ 0.1 (integral)

These values are optimized for low-jitter hardware-timestamped paths. In networks with non-PTP-aware hops, the high proportional gain causes the servo to overcorrect frequency in response to jitter-induced offset variations. This produces occasional offset spikes as the servo oscillates before damping.

Recommended PTS Tuning¶

For client ptp4l instances operating through non-PTP-aware hops with jitter, the following conservative PI gains are recommended:

~(keystone_admin)]$ system ptp-instance-parameter-add <ptp4l-instance> \
    clock_servo=pi \
    pi_proportional_const=0.1 \
    pi_integral_const=0.001

~(keystone_admin)]$ system ptp-instance-apply

These values reduce the proportional gain by 16x and the integral gain by 100x compared to the auto-tuned defaults. The effect is:

Steady-state |RMS| tracking is unchanged. The servo tracks the server offset with the same average accuracy.
Frequency deviation is reduced by approximately 95%. The servo makes smaller, smoother frequency adjustments instead of large corrections.
Offset spikes caused by servo overcorrection are eliminated. Only spikes caused by actual network jitter remain.

Note

These values were validated on Intel E825-C and E830-CC NICs with the ice driver under controlled network impairment. Different hardware or network conditions may require adjustment. See Observing Timing Performance for guidance on evaluating timing performance in your environment.

PTS Timing Budget¶

The G.8275.2 timing budget for PTS networks is ±500 µs (0.5 ms) maximum time error. The achievable accuracy depends on the delay and jitter characteristics of the non-PTP-aware hops in the network path.

The following table summarizes the expected performance based on per-hop network characteristics:

Network Condition	Delay/hop	Jitter/hop	Expected Max Offset	Within ±500 µs Budget
Direct connect (hardware timestamps)	—	—	< 10 ns	Yes
Light load (non-PTP-aware switch)	~0.1 ms	~0.02 ms	< 350 µs	Yes
Congested (non-PTP-aware switch)	~0.5 ms	~0.1 ms	~800 µs	No
Adversarial (uncorrelated jitter)	~1.0 ms	~0.3 ms	> 2 ms	No

When the per-hop jitter exceeds approximately 0.02 ms, the raw network jitter dominates the timing error and the servo cannot compensate regardless of tuning. In these environments, consider reducing the number of non-PTP-aware hops or deploying PTP-aware (boundary clock capable) switches in the timing path.

Network Considerations for Tuning ¶

The choice of servo and tuning parameters depends on the characteristics of the network between the timing source and the local node. Consider the following factors when evaluating whether the default linreg servo is sufficient or whether the pi servo with custom tuning is needed.

Packet Delay Variation (PDV)¶

PTP synchronization accuracy is directly affected by the variation in network delay experienced by PTP event messages (Sync and Delay_Resp). In networks with switches, routers, or other forwarding elements that do not support PTP hardware timestamping, packets experience variable queuing delays.

Signs of high PDV in your network:

The ptp4l log shows master offset values that fluctuate widely (e.g., swinging between -500 ns and +500 ns or more).
The rms value reported by ptp4l remains elevated even after the servo has converged.
The freq (frequency adjustment) value changes rapidly between samples, indicating the servo is constantly correcting.

In high-PDV environments, reducing the proportional gain (pi_proportional_const) prevents the servo from overreacting to noisy offset measurements. The integral gain (pi_integral_const) can be reduced proportionally to maintain stability.

Asymmetric Path Delay¶

In some networks, the forward and reverse paths between the PTP server and client have different propagation delays. This is common in PTS/telecom networks where PTP traffic traverses different network paths in each direction, or where traffic engineering causes asymmetric queuing.

Asymmetric delay manifests as a constant offset bias in the master offset reported by ptp4l. If the offset is consistently biased in one direction (e.g., always positive or always negative) after the servo has converged, path asymmetry may be present.

StarlingX supports the delayAsymmetry parameter on ptp4l instances to compensate for known asymmetry:

~(keystone_admin)]$ system ptp-instance-parameter-add <ptp4l-instance> \
    delayAsymmetry=<value-in-nanoseconds>

The value is a signed integer in nanoseconds. A positive value indicates that the server-to-client path is longer than the client-to-server path.

Note

Software tools alone cannot directly measure asymmetric delay. It must be inferred from the ptp4l offset behavior or measured using external test equipment. Determine the delayAsymmetry value through testing in the target network environment.

Network Topology Changes¶

In networks where the PTP path can change due to link failures, routing changes, or switchovers, the servo must reconverge after each topology change. The step_threshold and first_step_threshold parameters control whether the servo steps the clock or gradually adjusts the frequency after a large offset is detected.

For environments with frequent topology changes:

Set step_threshold to a value (in seconds) that represents the maximum acceptable offset before stepping. For example, step_threshold=1.0 will step the clock if the offset exceeds 1 second.
Set first_step_threshold=0.0 to disable stepping on the first update, allowing the servo to converge gradually from an unknown initial state.

Temperature and Oscillator Drift¶

The local oscillator on the NIC or system board drifts over time due to temperature changes and aging. In environments with significant temperature variation (e.g., outdoor or edge deployments), the servo must continuously compensate for this drift.

The max_frequency parameter limits how far the servo can adjust the clock frequency. If the oscillator drift exceeds this limit, the servo cannot maintain synchronization. The default value of 900000000 ppb is sufficient for most hardware. Reduce this value only if you need to constrain the servo’s frequency adjustments for specific hardware requirements.

Observing Timing Performance ¶

Before and after tuning, monitor the following data to make informed decisions about servo configuration.

ptp4l Log Output¶

The ptp4l log reports the master offset, frequency adjustment, and path delay at each sync interval. These values are the primary indicators of timing performance.

~(keystone_admin)]$ grep "master offset" /var/log/messages | tail -20

Key values to observe:

master offset: The measured time difference (in nanoseconds) between the local clock and the server. Steady-state values should be as close to 0 as possible.
s0 / s1 / s2: The servo state. s0 indicates the servo is unlocked. s1 indicates the servo is converging (clock is being stepped). s2 indicates the servo is locked and adjusting frequency.
freq: The frequency adjustment being applied in ppb. Large or rapidly changing values indicate the servo is actively correcting. High frequency deviation between samples is a sign of servo overcorrection.
path delay: The estimated one-way delay between server and client. Unstable path delay values indicate PDV in the network.

Diagnosing Servo Overcorrection¶

If the ptp4l log shows occasional large offset spikes (e.g., > 500 µs) that are not correlated with changes in path delay, the servo may be overcorrecting. The following pattern indicates servo overcorrection rather than a network event:

Offset spikes appear suddenly with no corresponding change in path delay or delay dev.
The freq value shows large swings (high frequency deviation) during and around the spike.
Spikes cluster in 2-4 second bursts as the servo oscillates before damping.

If this pattern is observed, reducing the PI gains as described in PI Servo Tuning for PTS Networks should eliminate the servo-induced spikes.

phc2sys Log Output¶

For OS clock synchronization, phc2sys reports similar offset and frequency values:

~(keystone_admin)]$ grep "phc2sys" /var/log/messages | grep "offset" | tail -20

collectd Alarms¶

Out-of-tolerance alarms raised by collectd indicate that the measured offset has exceeded the configured thresholds. See PTP Instance Monitoring Parameters for threshold configuration.

Note

The collectd PTP monitoring plugin polls on a periodic cycle. Short transient offset excursions (lasting less than the polling interval) may not trigger alarms. Direct ptp4l log analysis provides higher resolution visibility into timing performance than the alarm system.