Configure synce4l Service¶

The synce4l service provides Synchronous Ethernet (SyncE) clock distribution using the ESMC protocol. It operates in DPLL netlink mode: the DPLL firmware autonomously selects the best clock source based on pin priorities, and synce4l observes the selection and advertises the corresponding QL to SyncE peers.

StarlingX supports synce4l on the following NIC families:

NIC Family	module_name	Notes
E810 (Columbiaville)	ice	Ports can be detected as active sources directly
E830 (Connorsville)	ice	SyncE source (outgoing) only; no incoming SyncE
E825 (Granite Rapids-D)	zl3073x	Requires external source configuration

Overview ¶

In DPLL netlink mode, synce4l does not control which clock source the hardware locks to. Instead:

The DPLL firmware selects the source with the lowest pin priority number that has a valid signal.
synce4l receives kernel DPLL netlink notifications indicating which pin is active.
synce4l advertises the appropriate QL on all configured ports via ESMC frames.
When received ESMC quality changes, synce4l updates pin priorities via netlink to inform the firmware of relative source quality.

The clock role (T-GM or T-BC) is not configured statically. It emerges at runtime based on which source type is active:

External source active → T-GM behavior (all ports advertise the same QL)
Port source active → T-BC behavior (best port advertises DNU for loop prevention, other ports propagate received QL)

Prerequisites ¶

Before configuring synce4l:

Ensure the host has clock_synchronization=ptp set:

~(keystone_admin)]$ system host-update <hostname> clock_synchronization=ptp

Ensure the target ports are on a supported NIC (E810, E830, or E825).
For E825 (GNR-D) platforms:
- A clock instance with synce_rclka=enabled and pin_state_synce=selectable is required to enable the recovered clock PHY mux and set the DPLL pin to a selectable state.

Configure a synce4l Instance ¶

The clock role is determined by whether an external source is configured on the instance:

T-GM (grand master) advertises a fixed quality level derived from a local GNSS source. On E810, the GNSS receiver is connected to the NIC. On GNR-D platforms, no GNSS receiver is connected to the NIC; the GNSS source feeds a timing module that drives the zl3073x DPLL and disciplines both the E825 and E830 NICs. The timing module is on the mainboard and feeds the built-in E825 and optional add-in E830 card.
T-BC (boundary clock) relays the quality level received from an upstream SyncE source. This does not require GNSS. Receiving and relaying incoming SyncE applies to E810 and E825 NICs only; the E830 supports outgoing (source) SyncE only and cannot receive or relay incoming SyncE.

T-GM Configuration (GNSS Source)¶

This configuration applies to E810 and E825 (GNR-D) platforms. On E810 the GNSS receiver is connected to the NIC; on E825 (GNR-D) it is connected to the mainboard timing module rather than to the NIC. In both cases the recovered GNSS reference is available to the DPLL as a timing source.

E810 Example ¶

On E810 (module_name=ice), the GNSS board label is GNSS-1PPS.

Create the synce4l instance and assign it to the host:

~(keystone_admin)]$ system ptp-instance-add synce1 synce4l
~(keystone_admin)]$ system host-ptp-instance-assign controller-0 synce1

Create an interface and assign a port:

~(keystone_admin)]$ system ptp-interface-add synce1_if1 synce1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 enp1s0f0 synce1_if1

Configure the external source (GNSS):

~(keystone_admin)]$ system ptp-interface-parameter-add synce1_if1 external_source=GNSS-1PPS
~(keystone_admin)]$ system ptp-interface-parameter-add synce1_if1 input_QL=0x02
~(keystone_admin)]$ system ptp-interface-parameter-add synce1_if1 input_ext_QL=0x21

Apply the configuration:

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

E825 Example ¶

On E825 (GNR-D, module_name=zl3073x), the GNSS board label is GNSS_1PPS_IN. This input is provided by the mainboard timing module rather than by the NIC. Timing sources must be configured as external sources, and a clock instance with synce_rclka=enabled and pin_state_synce=selectable is required to enable the recovered clock.

Create the synce4l instance and a clock instance:

~(keystone_admin)]$ system ptp-instance-add synce1 synce4l
~(keystone_admin)]$ system ptp-instance-add clock0 clock

Assign both instances to the host:

~(keystone_admin)]$ system host-ptp-instance-assign controller-0 synce1
~(keystone_admin)]$ system host-ptp-instance-assign controller-0 clock0

Create interfaces and assign ports:

~(keystone_admin)]$ system ptp-interface-add synce1_if1 synce1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 eno8403 synce1_if1

~(keystone_admin)]$ system ptp-interface-add clock0_if1 clock0
~(keystone_admin)]$ system host-if-ptp-assign controller-0 eno8403 clock0_if1

Configure the external source (GNSS):

~(keystone_admin)]$ system ptp-interface-parameter-add synce1_if1 external_source=GNSS_1PPS_IN
~(keystone_admin)]$ system ptp-interface-parameter-add synce1_if1 input_QL=0x02
~(keystone_admin)]$ system ptp-interface-parameter-add synce1_if1 input_ext_QL=0xFF

Enable the recovered clock PHY mux and set the SyncE pin to selectable on the clock instance:
```
~(keystone_admin)]$ system ptp-interface-parameter-add clock0_if1 synce_rclka=enabled
~(keystone_admin)]$ system ptp-instance-parameter-add clock0 pin_state_synce=selectable --section dpll
```
Important

On E825 (GNR-D), both synce_rclka=enabled and pin_state_synce=selectable are required. The first enables the physical recovered clock output from the NIC PHY to the DPLL input; the second sets the DPLL pin state to selectable. Without both, the SyncE pin remains disconnected and the DPLL cannot lock to the recovered clock.

Apply the configuration:

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

T-BC Configuration (Relay)¶

This configuration relays the quality level received from an upstream SyncE source. It applies to E810 and E825 NICs. The E830 supports outgoing SyncE only and cannot be used as a relay.

Important

Relay mode requires the DPLL to lock to the recovered SyncE clock rather than to GNSS. Before configuring relay mode, ensure that no GNSS source is connected or active on the instance. If a valid GNSS signal is present, the DPLL selects GNSS as the active source instead of the recovered SyncE clock. When that happens, synce4l advertises the quality level of the GNSS source rather than relaying the upstream network quality, so downstream ports no longer reflect the received SyncE quality and the relay does not function as intended.

On E825 (GNR-D), disabling GNSS in hardware does not persist: when gnss_enabled is not configured, the platform re-enables the GNSS pin on every ptp-instance-apply. To keep GNSS disabled persistently, set gnss_enabled=0 in the dpll section of the clock instance interface:

~(keystone_admin)]$ system ptp-interface-parameter-add <clock_interface> gnss_enabled=0 --section dpll
~(keystone_admin)]$ system ptp-instance-apply

E810 Example ¶

On E810 (module_name=ice), relay mode is configured by assigning ports without setting external_source. synce4l selects the best quality level received across the assigned ports and relays it on the others. To add more input sources, assign additional interfaces to the instance; no source_ports parameter is used on E810.

Create the instance and assign it to the host:

~(keystone_admin)]$ system ptp-instance-add synce1 synce4l
~(keystone_admin)]$ system host-ptp-instance-assign controller-0 synce1

Create interfaces and assign the ports (no external_source is configured, so the instance operates in relay mode):

~(keystone_admin)]$ system ptp-interface-add synce1_if1 synce1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 enp1s0f0 synce1_if1

~(keystone_admin)]$ system ptp-interface-add synce1_if2 synce1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 enp1s0f1 synce1_if2

Apply the configuration:

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

E825 Example ¶

On E825 (GNR-D), relay mode uses an external source together with the source_ports parameter to read the live quality level from the upstream ports. A clock instance with synce_rclka=enabled and pin_state_synce=selectable is required.

Create the instances and assign them to the host:

~(keystone_admin)]$ system ptp-instance-add synce1 synce4l
~(keystone_admin)]$ system ptp-instance-add clock0 clock
~(keystone_admin)]$ system host-ptp-instance-assign controller-0 synce1
~(keystone_admin)]$ system host-ptp-instance-assign controller-0 clock0

Create one interface for the upstream (source-facing) ports and assign every upstream port to it. Create a separate interface for the downstream (distribution-facing) port:

~(keystone_admin)]$ system ptp-interface-add synce1_upstream synce1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 eno8403 synce1_upstream
~(keystone_admin)]$ system host-if-ptp-assign controller-0 eno8503 synce1_upstream

~(keystone_admin)]$ system ptp-interface-add synce1_downstream synce1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 eno8603 synce1_downstream

~(keystone_admin)]$ system ptp-interface-add clock0_if1 clock0
~(keystone_admin)]$ system host-if-ptp-assign controller-0 eno8403 clock0_if1

Determine the SyncE board label for an upstream port by reading its dev_port value:
```
~(keystone_admin)]$ cat /sys/class/net/<port_name>/dev_port
```
A value of 0 corresponds to board label CLK_78M125_NAC0_SYNCE0; a value of 1 corresponds to CLK_78M125_NAC0_SYNCE1.
Configure the external source on the upstream interface with dynamic QL from the upstream ports:
```
~(keystone_admin)]$ system ptp-interface-parameter-add synce1_upstream external_source=CLK_78M125_NAC0_SYNCE0
~(keystone_admin)]$ system ptp-interface-parameter-add synce1_upstream input_QL=0x02
~(keystone_admin)]$ system ptp-interface-parameter-add synce1_upstream source_ports=eno8403,eno8503
```
The source_ports parameter enables dynamic QL relay: synce4l reads the received quality level from the listed upstream ports and relays the best one on the downstream ports, rather than advertising the static input_QL. List every port to be used as a relay input in source_ports, separated by commas.

Note

A single synce4l instance can use more than one external source. To configure additional sources, set external_source on additional interfaces of the same instance — each interface contributes one external source. This is useful for T-BC configurations that accept clock quality from multiple upstream ports. If two interfaces are assigned the same port, their parameters are merged into a single port section.

Enable the recovered clock PHY mux and set the SyncE pin to selectable:

~(keystone_admin)]$ system ptp-interface-parameter-add clock0_if1 synce_rclka=enabled
~(keystone_admin)]$ system ptp-instance-parameter-add clock0 pin_state_synce=selectable --section dpll

Apply the configuration:

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

External Source Board Labels ¶

The external_source parameter value must match the board label registered by the kernel DPLL driver for the target pin. The valid input board labels depend on the NIC family.

E810 (module_name=ice):

The SMA and U.FL connectors are bidirectional. The platform assigns a default direction to each pin: SMA1 and U.FL1 default to input, while SMA2 and U.FL2 default to output. Use the external_source_direction parameter to override the default where the hardware supports it.

Board Label	Default Direction
`GNSS-1PPS`	input
`SMA1`	input
`SMA2`	output
`U.FL1`	input
`U.FL2`	output

E825 (|GNR-D|, module_name=zl3073x):

On E825 (GNR-D), the GNSS_1PPS_IN and GNSS_10M_IN inputs are provided by the mainboard timing module rather than by the NIC. They are still referenced by board label in the external_source parameter.

Board Label	Description
`GNSS_1PPS_IN`	GNSS 1PPS input (from mainboard timing module)
`GNSS_10M_IN`	GNSS 10 MHz input (from mainboard timing module)
`1EPPS_IN`	External 1PPS input
`CLK_78M125_NAC0_SYNCE0`	SyncE recovered clock 0
`CLK_78M125_NAC0_SYNCE1`	SyncE recovered clock 1

Note

Board labels must match exactly what the NIC’s kernel DPLL driver registers for the target pin. Using an incorrect board label causes silent pin resolution failure: synce4l never finds the pin and the external source appears permanently inactive.

Note

On GNR-D platforms, the GNSS source is not connected to the NIC; it feeds a timing module that disciplines both the E825 and E830 NICs. The E830 supports outgoing (source) SyncE only; it cannot receive or relay incoming SyncE.

Enable Extended QL ¶

To advertise the extended SSM code (enhanced ESMC TLV), enable extended_tlv on the instance and set the extended QL value on the external source:

~(keystone_admin)]$ system ptp-instance-parameter-add synce1 extended_tlv=1
~(keystone_admin)]$ system ptp-interface-parameter-add synce1_if1 input_QL=0x02
~(keystone_admin)]$ system ptp-interface-parameter-add synce1_if1 input_ext_QL=0x21
~(keystone_admin)]$ system ptp-instance-apply

With extended_tlv=1, each transmitted ESMC frame carries both the base QL TLV (from input_QL) and the extended QL TLV (from input_ext_QL). Peers that support the extended TLV read the extended SSM code; peers that do not ignore the unknown TLV and use the base SSM code. Use the Extended SSM values from the QL reference table for the configured network_option. See synce4l Instance Parameters.

Filter Received Quality Levels ¶

The allowed_qls port parameter acts as a per-port whitelist of acceptable incoming quality levels. If a port receives an ESMC quality level that is not in the list, the frame is discarded; if this persists, the port enters the QL-failed state and is not selected as a clock source. Use it to reject upstream sources that advertise a quality level below an acceptable threshold.

For example, to accept only PRC, SSU-A, and SSU-B on a port (network_option=1):

~(keystone_admin)]$ system ptp-interface-parameter-add synce1_if1 allowed_qls=0x02,0x04,0x08
~(keystone_admin)]$ system ptp-instance-apply

A port receiving EEC1 (0x0B) or DNU (0x0F) would then be treated as having no valid source. allowed_ext_qls applies the same filtering to the extended SSM code when extended_tlv=1.

Advertise a Quality Level in Holdover ¶

By default, synce4l advertises DNU (0x0F) on all ports while the EEC is in holdover. To advertise a specific quality level instead (permitted by ITU-T G.781 because the DPLL remains frequency-traceable), enable holdover_tx on the instance and set the holdover quality level:

~(keystone_admin)]$ system ptp-instance-parameter-add synce1 holdover_tx=1
~(keystone_admin)]$ system ptp-instance-parameter-add synce1 holdover_tx_ql=0x0B
~(keystone_admin)]$ system ptp-instance-apply

This example advertises EEC1 (0x0B, network_option=1) during holdover. Choose a value appropriate to the configured network_option; there is no built-in default. If extended_tlv=1, also set holdover_tx_ext_ql. The configured value is advertised only for genuine holdover in DPLL netlink mode; freerun and unlocked states still advertise DNU.

Monitoring and Notification Parameters ¶

The platform generates a monitoring configuration for each synce4l instance in /etc/linuxptp/ptpinstance/instance-monitoring.conf. Both the collectd PTP plugin (for alarming) and the ptp-notification service (for O-RAN notifications) read this file to report the correct quality level during each DPLL state.

These parameters are set using the --section monitoring option of the system ptp-instance-parameter-add command.

Parameter	Default	Description
`static_ql`	0x02	Quality level advertised when the DPLL is locked to a non-SyncE source. Plugin default; not written by the platform unless set.
`holdover_ql`	0x04	Quality level advertised when the DPLL is in holdover.
`freerun_ql`	0x0F	Quality level advertised when the DPLL is in freerun.
`holdover_seconds`	300	Seconds the DPLL may remain in holdover before the alarm escalates from major to critical (freerun).
`interface`	(none)	The NIC interface the instance monitors.
`source`	(none)	Clock source type context (for example, `GNSS` or `SYNCE`).
`smc_socket_path`	`/var/run/synce4l-<instance>.smc`	Path to the `synce4l` SMC socket used to query live status. Set this explicitly to a path under `/var/run` and use the same value as the instance’s global `smc_socket_path` parameter, so that the socket `synce4l` creates is the socket the monitoring plugin reads. The effective value for an instance can be found in its generated configuration file, `/etc/linuxptp/ptpinstance/synce4l-<instance>.conf`.

Example: Configure monitoring parameters

~(keystone_admin)]$ system ptp-instance-parameter-add synce1 smc_socket_path=/var/run/synce4l-synce1.smc
~(keystone_admin)]$ system ptp-instance-parameter-add synce1 --section monitoring interface=<port_name>
~(keystone_admin)]$ system ptp-instance-parameter-add synce1 --section monitoring source=GNSS
~(keystone_admin)]$ system ptp-instance-parameter-add synce1 --section monitoring smc_socket_path=/var/run/synce4l-synce1.smc
~(keystone_admin)]$ system ptp-instance-parameter-add synce1 --section monitoring holdover_ql=0x04
~(keystone_admin)]$ system ptp-instance-parameter-add synce1 --section monitoring freerun_ql=0x0f

Important

You must set smc_socket_path to a path under /var/run and use the same value for both the global parameter (which tells synce4l where to create its SMC socket) and the monitoring section parameter (which tells the collectd SyncE plugin where to read it). The /var/run directory is mounted into the monitoring pod. If the socket is created outside this directory, the monitoring plugin cannot reach it, silently falls back, and reports stale or default quality levels while synce4l continues to run normally.

Note

The collectd SyncE plugin drives the advertised quality level based on the DPLL lock state by sending SET_QL to synce4l over its SMC socket. These values therefore change what is transmitted on the wire:

Locked to a non-SyncE source (for example GNSS or PTP): advertises static_ql (default 0x02, PRC).
Locked to an incoming SyncE source: pass-through — the received quality level is relayed unchanged.
Holdover (timer not expired): advertises holdover_ql (default 0x04, SSU-A).
Holdover timer expired, or freerun/unlocked: advertises freerun_ql (default 0x0F, DNU).

SyncE Notifications (O-RAN)¶

The ptp-notification service publishes O-RAN compliant SyncE status events that applications can subscribe to. The events are derived from the same instance-monitoring.conf state that drives alarm 100.119, so the reported values track the DPLL lock state and advertised quality level.

Two SyncE resources are published, addressed per instance as /./<node>/<instance>/sync/synce-status/<resource>:

Resource	Event Type	Values
`sync/synce-status/lock-state`	`event.sync.synce-status.synce-state-change`	`LOCKED`, `HOLDOVER`, `FREERUN`
`sync/synce-status/clock-quality`	`event.sync.synce-status.synce-clock-quality-change`	ITU-T G.8264 SSM/QL value (for example 2 = QL-PRC, 4 = QL-SSU-A, 15 = QL-DNU)

The lock-state value reflects the DPLL lock state (the same state that determines the alarm severity), and the clock-quality value is the SSM code currently advertised, which follows the monitoring quality-level parameters (static_ql, holdover_ql, freerun_ql, or a pass-through SyncE value).

For the subscription mechanism, see Integrate the Application with Notification Client Sidecar. For the complete resource-path reference, subscription requests, and CloudEvent payload examples, see the PTP notifications API reference.

Override Auto-Detected Values ¶

The platform auto-detects clock_id and module_name for synce4l instances. To override these values:

~(keystone_admin)]$ system ptp-instance-parameter-add synce1 clock_id=<clock_id>
~(keystone_admin)]$ system ptp-instance-parameter-add synce1 module_name=zl3073x

User-specified parameters always take precedence over auto-detected values.

All synce4l parameters are passed through without validation. Any name=value pair set via system ptp-instance-parameter-add or system ptp-interface-parameter-add is written to the generated configuration file. If synce4l does not recognize a parameter, it silently ignores it.

For the complete list of supported parameters, see synce4l Instance Parameters.

Remove a Synce4l Configuration ¶

Configuration can be removed at the parameter, interface, or instance level. Apply the change with system ptp-instance-apply after any removal.

To remove a single parameter (the full name=value must be given):

~(keystone_admin)]$ system ptp-interface-parameter-delete synce1_if1 input_QL=0x02
~(keystone_admin)]$ system ptp-instance-parameter-delete synce1 --section monitoring holdover_ql=0x04

To remove a port from an interface, then delete the interface:

~(keystone_admin)]$ system host-if-ptp-remove controller-0 enp1s0f0 synce1_if1
~(keystone_admin)]$ system ptp-interface-delete synce1_if1

To unassign the instance from the host, then delete it:

~(keystone_admin)]$ system host-ptp-instance-remove controller-0 synce1
~(keystone_admin)]$ system ptp-instance-delete synce1

Apply the configuration:

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

Configure synce4l Service

Configure synce4l Service¶

StarlingX

Page Contents