DPLL(8) Linux DPLL(8) # [NAME](#NAME) dpll - Digital Phase Locked Loop (DPLL) subsystem management # [SYNOPSIS](#SYNOPSIS) **dpll** \[ *OPTIONS* ] **device** { *COMMAND* | **help** } **dpll** \[ *OPTIONS* ] **pin** { *COMMAND* | **help** } **dpll** \[ *OPTIONS* ] **monitor** *OPTIONS* := { **-V** | **--Version** | **-j** | **--json** | **-p** | **--pretty** | **-t** | **--timestamp** | **--tshort** } # [DESCRIPTION](#DESCRIPTION) The **dpll** utility is used to configure and monitor Digital Phase Locked Loop (DPLL) devices and pins. DPLLs are used for clock synchronization in various hardware, particularly in telecommunications and networking equipment. A DPLL device can lock to one or more input pins and provide synchronized output. Pins can be physical external signals (like GNSS 1PPS, SyncE), or internal oscillators. # [OPTIONS](#OPTIONS) [**-V**, **--Version**](#V) Print the version of the **dpll** utility and exit. [**-j**, **--json**](#j) Output results in JavaScript Object Notation (JSON). [**-p**, **--pretty**](#p) When combined with -j, generates a pretty JSON output with indentation and newlines for better human readability. [**-t**, **--timestamp**](#t) When used with the **monitor** object, print a **Timestamp:** line before each received notification, in the same format used by **ip monitor**. [**--tshort**](#tshort) Like **-t**, but emits a more compact, ISO 8601 inline prefix “**\[**YYYY-MM-DD**T**HH:MM:SS**.**uuuuuu**]**” in front of each notification instead of a separate **Timestamp:** line. # [DEVICE COMMANDS](#DEVICE_COMMANDS) ## [dpll device show \[ id ID \] \[ module-name NAME \] \[ clock-id ID \] \[ type TYPE \] \[ mode MODE \] \[ lock-status STATUS \]](#dpll_device_show___id_ID_____module-name_NAME_____clock-id_ID_____type_TYPE_____mode_MODE_____lock-status_STATUS__) Display information about DPLL devices. If no arguments are specified, shows all devices in the system. [**id ID**](#id) Show only the device with the specified numeric identifier. [**module-name NAME**](#module-name) Show only devices provided by the specified kernel module. [**clock-id ID**](#clock-id) Show only devices with the specified 64-bit clock identifier. [**type TYPE**](#type) Show only devices of the specified type: **pps** or **eec**. [**mode MODE**](#mode) Show only devices in the specified operating mode: **manual** or **automatic**. [**lock-status STATUS**](#lock-status) Show only devices with the specified lock status: **unlocked**, **locked**, **locked-ho-acq**, **holdover**. Output includes: • Device ID • Module name providing the device • Clock ID (unique identifier) • Operating mode (manual, automatic) • Lock status (unlocked, locked, locked-ho-acq, holdover) • Lock status error (if present) • Clock quality level (if supported) • Temperature (if supported) • Type (PPS or EEC) • Supported modes • Phase offset monitor status (enable/disable) • Phase offset averaging factor • Frequency monitor status (enable/disable) ## [dpll device set id ID \[ PARAMETER VALUE \] ...](#dpll_device_set_id_ID___PARAMETER_VALUE___...) Configure DPLL device parameters. [**id ID**](#id~2) Specifies which device to configure (required). [**mode { automatic | manual }**](#mode~2) Set the operating mode of the DPLL device. In **automatic** mode, the DPLL autonomously selects the best available input source based on priority and quality. In **manual** mode, the input source must be explicitly configured and the DPLL will not automatically switch sources. [**phase-offset-monitor { enable | disable }**](#phase-offset-monitor) Enable or disable phase offset monitoring between the device and its pins. When enabled, the kernel continuously measures and reports phase differences. [**phase-offset-avg-factor FACTOR**](#phase-offset-avg-factor) Set the averaging factor (1-255) applied to phase offset calculations. Higher values provide smoother but slower-responding measurements. [**frequency-monitor { enable | disable }**](#frequency-monitor) Enable or disable frequency monitoring on the device. When enabled, the kernel continuously measures and reports actual pin frequencies, which can be read via the **measured-frequency** field in pin show output. ## [dpll device id-get \[ module-name NAME \] \[ clock-id ID \] \[ type TYPE \]](#dpll_device_id-get___module-name_NAME_____clock-id_ID_____type_TYPE__) Retrieve the device ID based on identifying attributes. Useful for scripting when you need to find a device's numeric ID. At least one attribute should be specified to identify the device. [**module-name NAME**](#module-name~2) Kernel module name. [**clock-id ID**](#clock-id~2) 64-bit clock identifier in decimal or hex (0x prefix). [**type TYPE**](#type~2) Device type: **pps** or **eec**. # [PIN COMMANDS](#PIN_COMMANDS) ## [dpll pin show \[ id ID \] \[ parent-device DEVICE\_ID \] \[ parent-pin PIN\_ID \] \[ module-name NAME \] \[ clock-id ID \] \[ board-label LABEL \] \[ panel-label LABEL \] \[ package-label LABEL \] \[ type TYPE \] \[ direction DIR \] \[ state STATE \] \[ operstate OPERSTATE \]](#dpll_pin_show___id_ID_____parent-device_DEVICE_ID_____parent-pin_PIN_ID_____module-name_NAME_____clock-id_ID_____board-label_LABEL_____panel-label_LABEL_____package-label_LABEL_____type_TYPE_____direction_DIR_____state_STATE_____operstate_OPERSTATE__) Display information about DPLL pins. If no arguments are specified, shows all pins in the system. [**id ID**](#id~3) Show only the pin with the specified numeric identifier. [**parent-device DEVICE\_ID**](#parent-device) Show only pins that have the specified DPLL device as a parent. [**parent-pin PIN\_ID**](#parent-pin) Show only pins that have the specified pin as a parent (mux pins). [**module-name NAME**](#module-name~3) Show only pins provided by the specified kernel module. [**clock-id ID**](#clock-id~3) Show only pins with the specified 64-bit clock identifier. [**board-label LABEL**](#board-label) Show only pins with the specified board label. [**panel-label LABEL**](#panel-label) Show only pins with the specified panel label. [**package-label LABEL**](#package-label) Show only pins with the specified package label. [**type TYPE**](#type~3) Show only pins of the specified type: **mux**, **ext**, **synce-eth-port**, **int-oscillator**, **gnss**. [**direction DIR**](#direction) Show only pins that have a parent-device relationship with the specified direction: **input**, **output**. When combined with **parent-device**, only the specified parent-device relationship is checked. [**state STATE**](#state) Show only pins that have a parent-device relationship with the specified state: **connected**, **disconnected**, **selectable**. When combined with **parent-device**, only the specified parent-device relationship is checked. [**operstate OPERSTATE**](#operstate) Show only pins that have a parent-device relationship with the specified operational state: **active**, **standby**, **no-signal**, **qual-failed**. When combined with **parent-device**, only the specified parent-device relationship is checked. Output includes: • Pin ID • Module name • Clock ID • Board label (hardware label from device tree or ACPI) • Panel label • Package label • Pin type (mux, ext, synce-eth-port, int-oscillator, gnss) • Configured frequency and supported frequency ranges • Measured frequency in Hz (when frequency monitoring is enabled) • Capabilities (state-can-change, priority-can-change, direction-can-change) • Phase adjustment range, granularity, and current value • Fractional frequency offset • Parent device relationships (direction, priority, state, phase offset) • Parent pin relationships • Reference sync information • Esync frequency and pulse support (if applicable) ## [dpll pin set id ID \[ PARAMETER VALUE \] ...](#dpll_pin_set_id_ID___PARAMETER_VALUE___...) Configure DPLL pin parameters. Multiple parameters can be specified in a single command. [**id ID**](#id~4) Specifies which pin to configure (required). [**frequency FREQ**](#frequency) Set pin frequency in Hz. The pin must support the specified frequency (check frequency-supported ranges in pin show output). [**phase-adjust ADJUSTMENT**](#phase-adjust) Set phase adjustment in picoseconds. This value fine-tunes the phase of the output signal. Negative values shift the phase backwards, positive values shift it forwards. The value must be within the phase-adjust-min and phase-adjust-max range. [**esync-frequency FREQUENCY**](#esync-frequency) Set enhanced SyncE (Synchronous Ethernet) frequency in Hz for capable pins. [**parent-device DEVICE\_ID \[ direction DIR \] \[ prio PRIO \] \[ state STATE \]**](#parent-device~2) Configure the relationship between this pin and a parent DPLL device. [**direction { input | output }**](#direction~2) Set the pin's direction relative to the parent device. [**prio PRIORITY**](#prio) Set priority (0-255) for this pin on the parent device. [**state { connected | disconnected | selectable }**](#state~2) Set the pin's state on the parent device. [**parent-pin PIN\_ID \[ state STATE \]**](#parent-pin~2) Configure the relationship to a parent pin. [**reference-sync PIN\_ID \[ state STATE \]**](#reference-sync) Configure reference sync relationship with another pin. ## [dpll pin id-get \[ SELECTOR \] ...](#dpll_pin_id-get___SELECTOR___...) Retrieve a pin ID based on identifying attributes. [**module-name NAME**](#module-name~4) Filter by kernel module name. [**clock-id ID**](#clock-id~4) Filter by 64-bit clock identifier. [**board-label LABEL**](#board-label~2) Filter by board label (hardware identifier). [**panel-label LABEL**](#panel-label~2) Filter by panel label. [**package-label LABEL**](#package-label~2) Filter by package label. [**type TYPE**](#type~4) Filter by pin type: **mux**, **ext**, **synce-eth-port**, **int-oscillator**, **gnss**. # [MONITOR COMMAND](#MONITOR_COMMAND) ## [dpll monitor](#dpll_monitor) Monitor DPLL subsystem events in real-time. Displays notifications about: • Device creation, deletion, and configuration changes • Pin creation, deletion, and configuration changes • Lock status changes • Phase offset updates • Frequency changes Events are prefixed with their type: \[DEVICE\_CREATE], \[DEVICE\_CHANGE], \[DEVICE\_DELETE], \[PIN\_CREATE], \[PIN\_CHANGE], \[PIN\_DELETE]. Press Ctrl+C to stop monitoring. # [EXAMPLES](#EXAMPLES) ## [Show all DPLL devices](#Show_all_DPLL_devices) ``` dpll device show ``` ## [Show specific device in JSON format](#Show_specific_device_in_JSON_format) ``` dpll -j device show id 0 ``` ## [Set device 0 to manual mode](#Set_device_0_to_manual_mode) ``` dpll device set id 0 mode manual ``` ## [Enable phase offset monitoring on device 0](#Enable_phase_offset_monitoring_on_device_0) ``` dpll device set id 0 phase-offset-monitor enable ``` ## [Enable frequency monitoring on device 0](#Enable_frequency_monitoring_on_device_0) ``` dpll device set id 0 frequency-monitor enable ``` ## [Show all EEC devices](#Show_all_EEC_devices) ``` dpll device show type eec ``` ## [Show devices from specific module in JSON](#Show_devices_from_specific_module_in_JSON) ``` dpll -jp device show module-name ice ``` ## [Show all pins](#Show_all_pins) ``` dpll pin show ``` ## [Show all GNSS pins](#Show_all_GNSS_pins) ``` dpll pin show type gnss ``` ## [Show GNSS pins from specific module](#Show_GNSS_pins_from_specific_module) ``` dpll pin show type gnss module-name ice ``` ## [Show pin with pretty JSON output](#Show_pin_with_pretty_JSON_output) ``` dpll -jp pin show id 5 ``` ## [Show connected input pins on device 0](#Show_connected_input_pins_on_device_0) ``` dpll pin show parent-device 0 direction input state connected ``` ## [Set pin frequency to 10 MHz](#Set_pin_frequency_to_10_MHz) ``` dpll pin set id 0 frequency 10000000 ``` ## [Configure pin relationship to parent device](#Configure_pin_relationship_to_parent_device) ``` dpll pin set id 1 parent-device 0 prio 10 direction input state connected ``` ## [Adjust phase by -1000 picoseconds](#Adjust_phase_by_-1000_picoseconds) ``` dpll pin set id 2 phase-adjust -1000 ``` ## [Set multiple pin parameters at once](#Set_multiple_pin_parameters_at_once) ``` dpll pin set id 3 frequency 10000000 phase-adjust -1000 ``` ## [Monitor DPLL events](#Monitor_DPLL_events) ``` dpll monitor ``` ## [Monitor events in JSON format](#Monitor_events_in_JSON_format) ``` dpll -jp monitor ``` ## [Get device ID by module name](#Get_device_ID_by_module_name) ``` dpll device id-get module-name ice ``` ## [Get pin ID by board label](#Get_pin_ID_by_board_label) ``` dpll pin id-get board-label GNSS-1PPS ``` # [PHASE ADJUSTMENT](#PHASE_ADJUSTMENT) Phase adjustment is specified in picoseconds (1e-12 seconds) and allows fine-tuning of signal phase. This is crucial for precise time synchronization applications like 5G networks and high-frequency trading. Important considerations: • Check phase-adjust-min and phase-adjust-max before setting values • Some hardware requires values to be multiples of phase-adjust-gran • Negative values shift phase backwards (earlier in time) • Positive values shift phase forwards (later in time) • The kernel validates all phase adjustment requests # [CAPABILITIES](#CAPABILITIES) Pins may have various capabilities that determine which operations are allowed: [**state-can-change**](#state-can-change) The pin's state (connected/disconnected/selectable) can be modified. [**priority-can-change**](#priority-can-change) The pin's priority can be modified. This may apply to top-level priority or priority within parent-device relationships. [**direction-can-change**](#direction-can-change) The pin's direction (input/output) can be modified. Use **dpll pin show** to check which capabilities a pin supports before attempting configuration changes. # [EXIT STATUS](#EXIT_STATUS) **0** Success **1** Failure # [NOTES](#NOTES) • The DPLL subsystem requires kernel support (CONFIG\_DPLL=y or m) • Hardware support varies by device and driver • Some operations require specific hardware capabilities • Phase offset values are measured by hardware and cannot be set directly • Changes to device/pin configuration may affect system clock synchronization # [SEE ALSO](#SEE_ALSO) [**ip**(8)](/man/os/iproute2/ip.8), [**devlink**(8)](/man/os/iproute2/devlink.8), [**ethtool**(8)](/man/os/iproute2/ethtool.8) Linux kernel documentation: *Documentation/driver-api/dpll.rst* Netlink specification: *Documentation/netlink/specs/dpll.yaml* # [AUTHOR](#AUTHOR) dpll was written by Arkadiusz Kubalewski, Vadim Fedorenko, and others. This manual page was written by Petr Oros. # [REPORTING BUGS](#REPORTING_BUGS) Report bugs to <netdev@vger.kernel.org> 23 October 2025 iproute2 --- Document: dpll(8) from iproute2 7.2.0-r0 (Chainguard OS) Source: https://kernel.googlesource.com/pub/scm/network/iproute2/iproute2