PTP Notification Status Conditions

The PTP status notifications are derived based on the following conditions.

PTP Lock State

The PTP lock state notification describes the synchronization state of a monitored ptp4l instance.

Clock Status

Status

Description

Freerun

Clock is out of sync state

Reported when any of the following conditions are true:

  • portState is not SECONDARY, or clockClass is not in the locked list (default: 6, 7, 135), or timeTraceable flag is FALSE.

  • Holdover time has expired.

  • PMC, ptp4l.conf, or ptp4l are not accessible.

  • Master offset exceeds the configured threshold (default: 1,000,000 ns).

Locked

Clock is in sync state

Reported when all of the following conditions are true:

  • portState is SECONDARY and clockClass is in the locked list and timeTraceable flag is TRUE.

  • PMC, ptp4l.conf, and ptp4l are accessible.

  • Master offset is within the configured threshold.

The locked clockClass values can be changed using the ptp4lClockClassLockedList Helm override. See Install PTP Notifications for instructions.

Holdover

Clock is in holdover state

Reported when the ptp4l instance was previously in Locked state and the current poll detects a loss of sync (any Freerun condition is met), but the holdover timer has not yet expired.

Holdover is only entered from the Locked state. If the instance was never Locked (e.g., initial startup), it remains in Freerun.

The loss of sync is determined by the same criteria as Freerun: clockClass leaves the locked list, portState is no longer SECONDARY, timeTraceable becomes FALSE, master offset exceeds threshold, or PMC/ptp4l become inaccessible.

The holdover duration is configurable per instance. See PTP Instance Monitoring Parameters for details.

PTP Clock Class

The PTP clock class notification reports the clockClass value read from the grandmaster via PMC. This is a separate notification from the PTP lock state.

clockClass

Condition

Description

6

T-GM connected to a PRTC in locked mode (e.g., PRTC traceable to GNSS)

For additional details on clockClass values, refer to ITU-T standard G.8275.1.

7

T-GM in holdover, within holdover specification, traceable to Category 1 frequency source

135

T-BC in holdover, within holdover specification, traceable to Category 1 frequency source

140

T-GM in holdover, out of holdover specification, traceable to Category 1 frequency source

248

T-GM or T-BC in free-run mode

255

Slave only OC (does not send Announce messages)

Note

Only clockClass values in the locked list (default: 6, 7, 135) are considered valid for the Locked PTP Lock State. Other values (140, 248, 255) will cause a transition to Holdover or Freerun. The locked list can be customized via the ptp4lClockClassLockedList Helm override.

Relationship Between Clock Class and Notification State

The clock class notification and the PTP lock state notification are tracked independently. The clock class value is read directly from the grandmaster via PMC and reported as-is. The PTP lock state is determined by the ptp-notification service based on its own holdover timer.

This means that during a holdover event, the clock class may change before the PTP lock state transitions to Freerun. For example:

  1. GNSS signal is lost. The grandmaster transitions to holdover and advertises clockClass 7 (T-GM holdover within specification).

  2. The ptp-notification service detects the loss and enters Holdover state for the configured holdover_seconds duration.

  3. The grandmaster’s own holdover timer expires and it advertises clockClass 140 or 248.

  4. The ptp-notification clock class notification reports 140 or 248 immediately, because it reflects the actual grandmaster state.

  5. The ptp-notification PTP lock state may still report Holdover if its own holdover timer has not yet expired.

Note

A clock class of 248 during a PTP lock state of Holdover is expected behavior when the grandmaster’s holdover expires before the local ptp-notification holdover timer. The clock class reflects the grandmaster’s actual state, while the PTP lock state reflects the local holdover policy.

OS Clock State

The OS clock state notification describes whether the system clock is synchronized to the PTP hardware clock (PHC).

Clock Status

Status

Description

Locked

Clock is in sync state

phc2sys is running and disciplining the OS clock. The OS clock is within the configured tolerance threshold (default: 1000 ns) of the expected offset from the PHC.

Holdover

Clock is in holdover state

The holdover timer has not expired, and one of the following is true:

  • phc2sys is not running and not disciplining the OS clock.

  • The OS clock offset is outside the tolerance range.

Holdover is only entered from the Locked state. The holdover duration is configurable per instance. See PTP Instance Monitoring Parameters for details.

Freerun

Clock is in freerun

Holdover conditions are met but the holdover timer has expired.

GNSS State

The GNSS state notification describes the status of the GNSS timing source monitored by ts2phc.

State

Status

Description

Synchronized

GNSS data is present

Reported when all of the following are true:

  • ts2phc is running (pid file exists)

  • NIC driver DPLL EEC status reports locked-ho-acq

  • NIC driver DPLL PPS status reports locked-ho-acq

Note

A DPLL status of locked alone (without holdover acquired) does not satisfy this condition.

Failure-Nofix

GNSS data is not detected

ts2phc is not running or the NIC PHC is not being disciplined. The NIC driver DPLL reports a status other than locked. Or the holdover timer has expired.

SyncE Lock State

The SyncE lock state notification describes the EEC DPLL synchronization state for a monitored synce4l instance. The state is derived from the NIC driver DPLL EEC lock status read directly from the kernel, not from the liveness of the synce4l process.

Clock Status

Status

Description

Locked

EEC is in sync state

The EEC DPLL reports locked or locked-ho-acq. The instance is synchronized to its active frequency reference.

Holdover

EEC is in holdover state

The EEC DPLL reports holdover and the holdover timer has not yet expired. Holdover is only entered from the Locked state.

Freerun

EEC is in freerun

The EEC DPLL reports unlocked, or the holdover timer has expired.

The SyncE clock quality notification reports the quality level (QL/SSM) carried in ESMC, as a separate metric notification.

Relationship Between SyncE Lock State and synce4l Service State

The SyncE lock state notification reflects the EEC DPLL hardware state and is tracked independently of the synce4l process state. The ptp-notification service reads the DPLL EEC lock status directly from the kernel each poll; it does not check whether synce4l is running.

This is deliberate: stopping synce4l (for example during a configuration change or a service restart) removes only the ESMC signaling and the quality level query path. It does not by itself change the DPLL lock state. The DPLL continues to discipline to whatever physical reference is present.

The consequence differs by the instance’s role:

  1. A source instance whose EEC is locked to a local physical reference (for example, a GNSS 1PPS input) keeps that reference when synce4l stops. The DPLL stays locked, so the SyncE lock state correctly continues to report Locked. It does not transition to Holdover or Freerun, because the clock has not degraded.

  2. A relay instance whose EEC recovers frequency from a received SyncE line depends on synce4l to qualify and select that reference. When synce4l stops, the qualified reference is lost, so the DPLL genuinely enters holdover and the SyncE lock state transitions Holdover -> Freerun.

Note

When synce4l is stopped or has failed, the SyncE lock state continues to report the DPLL state and does not by itself indicate the daemon is not running. The synce4l service state is reported separately by alarm 100.119 (synce=not-running). See synce4l Monitoring and Alarms. Use the lock state notification for the clock’s synchronization state and alarm 100.119 for synce4l service health.

Note

While synce4l is stopped, the clock quality notification falls back to a value derived from the DPLL lock state rather than the live ESMC quality level, because the synce4l management socket used to read the live quality level is unavailable. For a locked EEC this fallback reports the configured locked quality level (static_ql). The live quality level resumes once synce4l is running again.

Overall Sync State

The overall sync state notification (sync-state) describes the health of the timing chain on the local system. A locked state is reported when the system has reference to an external time source (GNSS or PTP) and the system clock is synchronized to that time source.

State

Status

Description

Locked

Overall state is locked

The components of the local timing chain necessary for accurately synced time on the local host are in a healthy state. This means that a local NIC PHC is locked to an external timing source and the system clock is synchronized to it. The ptp-notification container logs indicate which components are part of the local timing chain and affect this notification.

Holdover

Overall state is in holdover

One or more components in the local timing chain are in a degraded state (holdover or freerun). The overall sync state holdover time has not expired.

The overall holdover time is dynamically calculated as the minimum of the active sync chain component holdover times. See Install PTP Notifications for details. The per-instance holdover durations used in this calculation are configurable. See PTP Instance Monitoring Parameters for configuration details.

Freerun

Overall state is freerun

One or more components in the local timing chain are in a degraded state (holdover or freerun). The overall sync state holdover time has expired.

Overall Sync State Description

This notification helps you to verify that the local system time is being actively synchronized. If a component of the local timing chain enters a degraded state, then a sync-state notification will be produced to indicate that the local timing chain is unhealthy.

The following is an example log output from the ptp-notification container that indicates the components of the local timing chain:

2025-05-01 15:34:48 INFO     Overall sync state chaining info:
os-clock-state = Locked
os-clock's source ptp-device = ptp0
ptp-device's sync-source = PTP
(PTP source) ptp4l-instance-and-state = ('ptp1', 'Locked')
(GNSS source) ts2phc-instance-and-state = NA
Overall sync: previous-state = Freerun, new-state = Locked