man(8)

🌸 NAME 🌸

okay so bestie, welcome to the man(8) page for synce4l — the Synchronous Ethernet (SyncE) controller application 💅✨

like yes it's a section-8 system administration manual, but it's also the moment. buckle up 🎀

---

✨ SYNOPSIS ✨

synce4l -f [file] [-l <num>] [-m] [-q] [-v] [-h]

---

🦋 DESCRIPTION 🦋

so synce4l is an implementation of the Synchronous Ethernet (SyncE) protocol, according to ITU-T Rec. G.8264 — no cap, that's literally what it is 📜

the design goal? it's giving "provide logic to supported hardware" by processing Ethernet Synchronization Messaging Channel (ESMC) and controlling the Ethernet Equipment Clock (EEC) on a Network Card Interface (NIC) 🔥

and here's the tea: the application can operate in two mutually exclusive modes — line or external. you pick one. you cannot have both. the universe said no 🫶

🌈 External input mode

if synce4l is configured to run in external input mode, then the EEC needs to have an external 1PPS source attached (GPS or other generator) 📡

in this scenario, synce4l always broadcasts the clock quality level (QL) defined in the configuration file. and additionally — for external input mode — incoming SyncE frames do not participate in the best source selection algorithm for the EEC. like, they're just not in the running, bestie 🙈

💜 Line input mode

in line input mode, incoming SyncE frames are processed and the best clock source is extracted from the link having the best quality level 👑

synce4l configures such a "best quality" port as a source to recover clock for the EEC. the recovered QL is broadcasted to all other interfaces then. and nope — an external clock source cannot be used in this mode. periodt 🚫

---

💅 OPTIONS 💅

• -f [file] — read configuration from file (heads up: the config file takes precedence over command line arguments, so the file wins every argument, iykyk) 📂
• -l [num] — set the logging level to num (0: least detailed, 7: most detailed) 🔍
• -m — print messages to stdout 🖨️
• -q — do not print messages to the syslog 🤫
• -v — print synce4l version and exit 👋
• -h — print this message and exit 🆘

---

🎀 CONFIGURATION FILE 🎀

the configuration file contains three sections:

• global,
• device,
• port.

⭐ Global section

this section starts with the [global] keyword. it sets the logging options, that's its whole vibe.

available options:

• logging_level — minimum log level required to appear in a log. defaults to 6, valid values are 0 - 7 📊
• message_tag — tag reported in a log 🏷️
• use_syslog — set to 1 if syslog should be used. defaults to 1, valid values are 0 or 1 💻
• verbose — set to 1 to log extra information. defaults to 0, valid values are 0 or 1 🗣️

🧚 Device section

this section specifies the configuration of one logical device, e.g. 'synce1'. the name is defined by the user. the name has no impact for any functionality except traces — it's purely for the aesthetic 🎨

the name must be enclosed in extra angle bracket when defining a new device section, e.g. [<synce1>] 🫶

all ports defined by port sections after the device section will create one SyncE device (until the next device section). so order matters, bestie 📌

available options:

• input_mode — set to "line" to enable line input mode, set "external" for external input mode. defaults to "line", valid values are "line" or "external" 🔀
• external_input_QL — Quality Level (QL) for "external input" mode. valid values specified in ITU-T Recommendations 📖
• external_input_ext_QL — Extended Quality Level for "external input" mode. valid values specified in ITU-T Recommendations 📖
• extended_tlv — set to 1 to enable extended QL. defaults to 0, valid values are 0 or 1 🔛
• network_option — network option according to T-REC-G.8264. all devices in the SyncE domain should have the same option configured. no rogue settings, okay? 🤝 defaults to 1, valid values are 1 or 2 🌐
• recover_time — seconds indicating the minimum time to recover from the QL-failed state on the port. defaults to 60, valid values are 10 - 720 ⏱️
• get_eec_state_cmd — defines a shell command which will be executed by synce4l to acquire current state of a SyncE EEC on the device. a separated command must be provided by the user for each device configured for frequency synchronization. the command shall output current state of EEC to stdout, and the expected values are defined (also by the user) with the following configuration items: eec_holdover_value, eec_locked_ho_value, eec_locked_value, eec_freerun_value, eec_invalid_value 🐚
• eec_holdover_value — defines a string value expected on the stdout stream when the EEC is in HOLDOVER state 🧊
• eec_locked_ho_value — defines a string value expected on the stdout stream when the EEC is in LOCKED HOLDOVER state 🔒
• eec_locked_value — defines a string value expected on the stdout stream when the EEC is in LOCKED state 🔐
• eec_freerun_value — defines a string value expected on the stdout stream when the EEC is in FREERUN state 🏃
• eec_invalid_value — defines a string value expected on the stdout stream when the EEC is in INVALID state ❌

🍓 Port section

any other section not starting with < (e.g. [eth0]) is the port section. multiple port sections are allowed. each port participates in SyncE communication 🌉

available options:

• tx_heartbeat_msec — interval between consecutive SyncE frame transmissions (1000ms recommended). defaults to 1000, valid values are 100 - 3000 📤
• rx_heartbeat_msec — interval between consecutive SyncE socket polls (frame receive). defaults to 50, valid values are 10 - 500 📥
• recover_clock_enable_cmd — a shell command which enables the PHY port pointed by this Port section as a source of frequency for the SyncE EEC on this device (required only in "internal input" mode) ✅
• recover_clock_disable_cmd — a shell command which disables the PHY port pointed by this Port section as a source of frequency for the SyncE EEC on this device (required only in "internal input" mode) 🚫
• allowed_qls — list of integers containing allowed SSM QLs separated by comma (,), other received ones would be discarded. if the parameter is not provided, all QLs will be accepted 🎯
• allowed_ext_qls — list of integers containing allowed extended SSM QLs separated by comma (,), other received ones would be discarded. if the parameter is not provided, all QLs will be accepted 🎯

---

💀 BUGS 💀

no known bugs. she's flawless, she's perfect, she ate and left no crumbs 👑

---

👑 AUTHOR 👑

• Arkadiusz Kubalewski <arkadiusz.kubalewski@intel.com>
• Michal Michalik <michal.michalik@intel.com>

---

okay that's the whole page bestie, go forth and synchronize those Ethernet clocks 🌸✨

version 1.0 · dated 27 Oct 2022 · mwah 💋 🫶