synce4l Instance Parameters

This section provides a complete reference of all synce4l configuration parameters. Parameters are organized by configuration section and indicate which DPLL mode they apply to.

For upstream reference, see the official synce4l project.

Global Parameters

Global parameters are set using system ptp-instance-parameter-add and are written to the [global] section of the generated configuration file. The following parameters are routed to the global section by name: logging_level, use_syslog, verbose, message_tag, smc_socket_path.

Parameter	Default	Range	Description
logging_level	6	0–7	Minimum syslog severity level to log, following the standard syslog levels.
message_tag	(auto-generated)	string	Tag prepended to log messages. Auto-generated from the instance name if not specified; can be overridden.
poll_interval_msec	20	1–500	Sleep time between subsequent SyncE clock polls, in milliseconds.
smc_socket_path	/var/run/synce4l-<instance>.smc	string	Path to the socket file used for external application communication, including live status queries from the collectd SyncE monitoring plugin. Set this explicitly to a path under /var/run (for example, /var/run/synce4l-synce1.smc). This directory is mounted into the monitoring pod. A socket created outside this directory is not visible to the monitoring plugin, which then silently falls back and cannot query synce4l.
use_syslog	1	0–1	Enable syslog output.
verbose	0	0–1	Enable verbose logging to stdout.

Device Parameters

Device parameters are set using system ptp-instance-parameter-add and are written to the [<device>] section. Any parameter not recognized as a global parameter name is routed to the device section.

Parameter	Default	Range	Description
clock_id	(auto-detected)	0–MAX(u64)	The clock ID of the EEC-type DPLL in the system. Auto-detected by the platform. On E825 it is read from the zl3073x kernel module; on E810 and E830 it is derived from the base port MAC as an EUI-64 value.
module_name	(auto-detected)	string	Name of the kernel module that registered the DPLL device. Auto-detected by the platform: zl3073x on E825, ice on E810 and E830.
extended_tlv	0	0, 1	Set to 1 to enable extended QL (enhanced ESMC TLV).
network_option	1	1, 2	Network option according to ITU-T G.8264. All devices in a SyncE domain must use the same option. Option 1 is used in Europe and most international deployments; option 2 in Japan and North America.
recover_time	300	10–720	Minimum time in seconds to recover from the QL-failed state on a port.
dnu_prio	0xf	0xf–0xffff	Pin priority value assigned to a source marked “Do Not Use”. Required for DPLL netlink mode.
holdover_tx	0	0, 1	Set to 1 to advertise a configured quality level while the EEC is in holdover, instead of DNU. Effective only in DPLL netlink mode.
holdover_tx_ql	0	0x0–0xF	SSM code advertised during holdover when holdover_tx=1. The value is sent verbatim, including 0 (STU).
holdover_tx_ext_ql	0xFF	0x0–0xFF	Extended SSM code advertised during holdover when holdover_tx=1 and extended_tlv=1.

Note

By default, synce4l advertises DNU (0x0F) on all ports while the EEC is in holdover. Setting holdover_tx=1 advertises holdover_tx_ql instead, which is permitted by ITU-T G.781 because a DPLL in holdover remains frequency-traceable. This applies only to genuine holdover in DPLL netlink mode; freerun and unlocked states still advertise DNU. There is no built-in default holdover QL because the valid value is network-option specific — the operator must choose an appropriate value.

Note

The input_mode parameter is deprecated and has no effect in synce4l 1.1.0. It is not required in the configuration.

Note

The eec_get_state_cmd and eec_*_value parameters are legacy mode parameters and are ignored in DPLL netlink mode. They should not be configured.

Port Parameters

Port parameters are set using system ptp-interface-parameter-add on interfaces that do not have external_source configured. They are written to the [<port_name>] section.

Parameter	Default	Range	Description
tx_heartbeat_msec	1000	100–3000	Interval between consecutive ESMC frame transmissions, in milliseconds.
rx_heartbeat_msec	50	10–500	Interval between consecutive ESMC socket polls, in milliseconds. The platform sets this to 500 by default.
allowed_qls	(none)	comma-separated	List of hex QL values to accept from received ESMC. Values not in the list are discarded. If not set, all QLs are accepted. Format: 0x02,0x04,0x08
allowed_ext_qls	(none)	comma-separated	List of hex extended QL values to accept. Same filtering as allowed_qls. If not set, all extended QLs are accepted.

Note

The recover_clock_enable_cmd and recover_clock_disable_cmd parameters are legacy mode parameters and are ignored in DPLL netlink mode.

External Source Parameters

External source parameters are set using system ptp-interface-parameter-add on interfaces that have external_source=<board_label> configured. They are written to the [{<ext_src_name>}] section.

The external_source parameter itself is a meta-parameter consumed by the platform to trigger external source section generation. It is not written directly to the configuration file.

An instance may have multiple external sources. Each is configured by setting external_source on a separate interface of the same instance; the platform generates a distinct [{<ext_src_name>}] section for each.

Parameter	Default	Range	Description
board_label	(from external_source)	string	DPLL pin board label for pin identification. Must exactly match the label registered by the kernel driver. See Configure synce4l Service for valid labels per NIC family.
input_QL	0	0x0–0xF	Quality level advertised when this external source is active. A value of 0 makes the source unusable for selection. See the QL reference below for values per network option.
input_ext_QL	0	0x0–0xFF	Extended quality level, used when extended_tlv=1.
internal_prio	128	0–255	Internal source priority. Higher priority (lower value) selects a source as better quality when two sources are considered equal. The platform sets this to 0 for generated external sources.
source_ports	(none)	comma-separated	Port names for dynamic QL relay. When configured, synce4l reads ESMC from the specified ports and uses the received QL instead of the static input_QL. Use for T-BC configurations where the external source QL should reflect upstream network quality.

Note

The source_ports parameter is a StarlingX addition and is not part of the upstream synce4l project.

Note

To bias selection between sources of equal quality level, use the internal_prio external-source parameter (lower value = higher priority). Do not rely on pin_priority_* clock-instance parameters (--section dpll) to order SyncE sources in this release: synce4l manages pin priorities autonomously in DPLL netlink mode and re-asserts them at runtime, so pin_priority_* values are not retained. pin_state_synce=selectable is required on E825 and is unaffected by this; only the pin_priority_* values are.

Note

The external_enable_cmd and external_disable_cmd parameters are legacy mode parameters and are ignored in DPLL netlink mode.

QL Values Quick Reference

The valid QL values depend on the configured network_option. Option 1 (network_option=1) is used in Europe and most international deployments. Option 2 (network_option=2) is used in Japan and North America. A lower priority number indicates a higher-quality clock. If extended SSM is not enabled, the extended SSM value is implicitly 0xFF.

Option 1 QL values (network_option=1):

Quality Level	Priority	SSM	Extended SSM
ePRTC	0	0x2	0x21
PRTC	1	0x2	0x20
PRC	2	0x2	0xFF
SSU-A	3	0x4	0xFF
SSU-B	4	0x8	0xFF
EEC1	5	0xB	0xFF

Option 2 QL values (network_option=2):

Quality Level	Priority	SSM	Extended SSM
ePRTC	0	0x1	0x21
PRTC	1	0x1	0x20
PRS	2	0x1	0xFF
STU	3	0x0	0xFF
ST2	4	0x7	0xFF
TNC	5	0x4	0xFF
ST3E	6	0xD	0xFF
EEC2	7	0xA	0xFF
PROV	8	0xE	0xFF

Parameter Routing Summary

The following table summarizes how parameters set via CLI are routed to the generated synce4l configuration file:

CLI Command	Condition	Config Section
ptp-instance-parameter-add	Parameter name is logging_level, use_syslog, verbose, message_tag, or smc_socket_path	[global]
ptp-instance-parameter-add	Any other parameter name	[<device>]
ptp-interface-parameter-add	Interface has external_source set; parameter is input_QL, input_ext_QL, internal_prio, board_label, source_ports, external_enable_cmd, or external_disable_cmd	[{<ext_src>}]
ptp-interface-parameter-add	Interface does not have external_source, or parameter is not in the external source list	[<port>]