mirror of
https://git.kernel.org/pub/scm/network/iproute2/iproute2.git
synced 2026-01-26 06:07:54 +00:00
dpll: Add dpll command
Add a new userspace tool for managing and monitoring DPLL devices via the
Linux kernel DPLL subsystem. The tool uses libmnl for netlink communication
and provides a complete interface for device and pin configuration.
The tool supports:
- Device management: enumerate devices, query capabilities (lock status,
temperature, supported modes, clock quality levels), configure phase-offset
monitoring and averaging
- Pin management: enumerate pins with hierarchical relationships, configure
frequencies (including esync), phase adjustments, priorities, states, and
directions
- Complex topologies: handle parent-device and parent-pin relationships,
reference synchronization tracking, multi-attribute queries (frequency
ranges, capabilities)
- ID resolution: query device/pin IDs by various attributes (module-name,
clock-id, board-label, type)
- Monitoring: real-time display of device and pin state changes via netlink
multicast notifications
- Output formats: both human-readable and JSON output (with pretty-print
support)
The tool belongs in iproute2 as DPLL devices are tightly integrated with
network interfaces - modern NICs provide hardware clock synchronization
support. The DPLL subsystem uses the same netlink infrastructure as other
networking subsystems, and the tool follows established iproute2 patterns
for command structure, output formatting, and error handling.
Example usage:
# dpll device show
# dpll device id-get module-name ice
# dpll device set id 0 phase-offset-monitor enable
# dpll pin show
# dpll pin set id 0 frequency 10000000
# dpll pin set id 13 parent-device 0 state connected prio 10
# dpll pin set id 0 reference-sync 1 state connected
# dpll monitor
# dpll -j -p device show
Testing notes:
Tested on real hardware with ice and zl3073x drivers. All commands work
(device show/set/id-get, pin show/set/id-get, monitor). JSON output was
carefully compared with cli.py - the tools are interchangeable.
v2:
- Added testing notes
- Added MAINTAINERS entry
- Removed unused -n parameter from man page
v3:
- Use shared mnlg and str_to_bool helpers from lib
- Use str_num_map for bidirectional string/enum mapping
- Remove unnecessary else after return
- Remove misleading "legacy" comments
- Simplify DPLL_PR_MULTI_ENUM_STR macro
- Convert json_output to global json variable
- Use appropriate mnl helpers with proper type casting to respect signed integer data types
- Use DPLL_PR_INT_FMT for phase-adjust-gran to respect signed integer type
- Remove dpll_link from Makefile (mistake in v2)
v4:
- Replace DPLL_PR_MULTI_ENUM_STR macro with dpll_pr_multi_enum_str() function
- Replace pr_out("\n") with print_nl() for one-line mode support
- Remove all is_json_context() code splitting, use PRINT_FP/PRINT_JSON/PRINT_ANY appropriately
- Add dpll_pr_freq_range() helper function to reduce code duplication
v5
- Fix checkpatch warnings
- Use structure initialization instead of memset
- Use sigemptyset() for proper signal mask initialization
- Remove redundant if (json) checks around JSON functions
- Use signalfd for signal handling in monitor
- Set netlink socket to non-blocking in monitor
Reviewed-by: Jiri Pirko <jiri@nvidia.com>
Co-developed-by: Ivan Vecera <ivecera@redhat.com>
Signed-off-by: Petr Oros <poros@redhat.com>
Signed-off-by: Ivan Vecera <ivecera@redhat.com>
Signed-off-by: David Ahern <dsahern@kernel.org>
This commit is contained in:
Petr Oros
David Ahern
parent
9771095a3b
commit
656cfc3ce0
@ -42,6 +42,11 @@ devlink
|
||||
M: Jiri Pirko <jiri@resnulli.us>
|
||||
F: devlink/*
|
||||
|
||||
dpll
|
||||
M: Petr Oros <poros@redhat.com>
|
||||
M: Ivan Vecera <ivecera@redhat.com>
|
||||
F: dpll/*
|
||||
|
||||
netkit
|
||||
M: Daniel Borkmann <daniel@iogearbox.net>
|
||||
M: Nikolay Aleksandrov <razor@blackwall.org>
|
||||
|
||||
3
Makefile
3
Makefile
@ -71,7 +71,7 @@ YACCFLAGS = -d -t -v
|
||||
|
||||
SUBDIRS=lib ip tc bridge misc netem genl man
|
||||
ifeq ($(HAVE_MNL),y)
|
||||
SUBDIRS += tipc devlink rdma dcb vdpa netshaper
|
||||
SUBDIRS += tipc devlink rdma dcb vdpa netshaper dpll
|
||||
endif
|
||||
|
||||
LIBNETLINK=../lib/libutil.a ../lib/libnetlink.a
|
||||
@ -111,6 +111,7 @@ install: all
|
||||
install -m 0755 -d $(DESTDIR)$(BASH_COMPDIR)
|
||||
install -m 0644 bash-completion/tc $(DESTDIR)$(BASH_COMPDIR)
|
||||
install -m 0644 bash-completion/devlink $(DESTDIR)$(BASH_COMPDIR)
|
||||
install -m 0644 bash-completion/dpll $(DESTDIR)$(BASH_COMPDIR)
|
||||
install -m 0644 include/bpf_elf.h $(DESTDIR)$(HDRDIR)
|
||||
|
||||
version:
|
||||
|
||||
316
bash-completion/dpll
Normal file
316
bash-completion/dpll
Normal file
@ -0,0 +1,316 @@
|
||||
# bash completion for dpll(8) -*- shell-script -*-
|
||||
|
||||
# Get all the optional commands for dpll
|
||||
_dpll_get_optional_commands()
|
||||
{
|
||||
local object=$1; shift
|
||||
|
||||
local filter_options=""
|
||||
local options="$(dpll $object help 2>&1 \
|
||||
| command sed -n -e "s/^.*dpll $object //p" \
|
||||
| cut -d " " -f 1)"
|
||||
|
||||
# Remove duplicate options from "dpll $OBJECT help" command
|
||||
local opt
|
||||
for opt in $options; do
|
||||
if [[ $filter_options =~ $opt ]]; then
|
||||
continue
|
||||
else
|
||||
filter_options="$filter_options $opt"
|
||||
fi
|
||||
done
|
||||
|
||||
echo $filter_options
|
||||
}
|
||||
|
||||
# Complete based on given word
|
||||
_dpll_direct_complete()
|
||||
{
|
||||
local device_id pin_id value
|
||||
|
||||
case $1 in
|
||||
device_id)
|
||||
value=$(dpll -j device show 2>/dev/null \
|
||||
| jq '.device[].id' 2>/dev/null)
|
||||
;;
|
||||
pin_id)
|
||||
value=$(dpll -j pin show 2>/dev/null \
|
||||
| jq '.pin[].id' 2>/dev/null)
|
||||
;;
|
||||
module_name)
|
||||
value=$(dpll -j device show 2>/dev/null \
|
||||
| jq -r '.device[]."module-name"' 2>/dev/null \
|
||||
| sort -u)
|
||||
;;
|
||||
esac
|
||||
|
||||
echo $value
|
||||
}
|
||||
|
||||
# Handle device subcommands
|
||||
_dpll_device()
|
||||
{
|
||||
local command=$1
|
||||
|
||||
case $command in
|
||||
show)
|
||||
case $prev in
|
||||
id)
|
||||
COMPREPLY=( $( compgen -W \
|
||||
"$(_dpll_direct_complete device_id)" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
*)
|
||||
COMPREPLY=( $( compgen -W "id" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
;;
|
||||
set)
|
||||
case $prev in
|
||||
id)
|
||||
COMPREPLY=( $( compgen -W \
|
||||
"$(_dpll_direct_complete device_id)" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
phase-offset-monitor)
|
||||
COMPREPLY=( $( compgen -W "enable disable true false 0 1" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
phase-offset-avg-factor)
|
||||
# numeric value, no completion
|
||||
return 0
|
||||
;;
|
||||
*)
|
||||
COMPREPLY=( $( compgen -W "id phase-offset-monitor \
|
||||
phase-offset-avg-factor" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
;;
|
||||
id-get)
|
||||
case $prev in
|
||||
module-name)
|
||||
COMPREPLY=( $( compgen -W \
|
||||
"$(_dpll_direct_complete module_name)" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
clock-id)
|
||||
# numeric value, no completion
|
||||
return 0
|
||||
;;
|
||||
type)
|
||||
COMPREPLY=( $( compgen -W "pps eec" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
*)
|
||||
COMPREPLY=( $( compgen -W "module-name clock-id type" \
|
||||
-- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
# Handle pin subcommands
|
||||
_dpll_pin()
|
||||
{
|
||||
local command=$1
|
||||
|
||||
case $command in
|
||||
show)
|
||||
case $prev in
|
||||
id)
|
||||
COMPREPLY=( $( compgen -W \
|
||||
"$(_dpll_direct_complete pin_id)" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
device)
|
||||
COMPREPLY=( $( compgen -W \
|
||||
"$(_dpll_direct_complete device_id)" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
*)
|
||||
COMPREPLY=( $( compgen -W "id device" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
;;
|
||||
set)
|
||||
case $prev in
|
||||
id|parent-device)
|
||||
COMPREPLY=( $( compgen -W \
|
||||
"$(_dpll_direct_complete device_id)" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
parent-pin|reference-sync)
|
||||
COMPREPLY=( $( compgen -W \
|
||||
"$(_dpll_direct_complete pin_id)" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
frequency|phase-adjust|esync-frequency|prio)
|
||||
# numeric value, no completion
|
||||
return 0
|
||||
;;
|
||||
direction)
|
||||
COMPREPLY=( $( compgen -W "input output" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
state)
|
||||
COMPREPLY=( $( compgen -W \
|
||||
"connected disconnected selectable" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
*)
|
||||
# Check if we are in nested context (after parent-device/parent-pin/reference-sync)
|
||||
local i nested_keyword=""
|
||||
for (( i=cword-1; i>0; i-- )); do
|
||||
case "${words[i]}" in
|
||||
parent-device)
|
||||
nested_keyword="parent-device"
|
||||
break
|
||||
;;
|
||||
parent-pin|reference-sync)
|
||||
nested_keyword="parent-pin"
|
||||
break
|
||||
;;
|
||||
id|frequency|phase-adjust|esync-frequency)
|
||||
# Hit a top-level keyword, not in nested context
|
||||
break
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
if [[ "$nested_keyword" == "parent-device" ]]; then
|
||||
COMPREPLY=( $( compgen -W "direction prio state" -- "$cur" ) )
|
||||
elif [[ "$nested_keyword" == "parent-pin" ]]; then
|
||||
COMPREPLY=( $( compgen -W "state" -- "$cur" ) )
|
||||
else
|
||||
COMPREPLY=( $( compgen -W "id frequency phase-adjust \
|
||||
esync-frequency parent-device parent-pin reference-sync" \
|
||||
-- "$cur" ) )
|
||||
fi
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
;;
|
||||
id-get)
|
||||
case $prev in
|
||||
module-name)
|
||||
COMPREPLY=( $( compgen -W \
|
||||
"$(_dpll_direct_complete module_name)" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
clock-id)
|
||||
# numeric value, no completion
|
||||
return 0
|
||||
;;
|
||||
board-label|panel-label|package-label)
|
||||
# string value, no completion
|
||||
return 0
|
||||
;;
|
||||
type)
|
||||
COMPREPLY=( $( compgen -W "mux ext synce-eth-port \
|
||||
int-oscillator gnss" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
*)
|
||||
COMPREPLY=( $( compgen -W "module-name clock-id \
|
||||
board-label panel-label package-label type" \
|
||||
-- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
# Handle monitor subcommand
|
||||
_dpll_monitor()
|
||||
{
|
||||
# monitor has no additional arguments
|
||||
return 0
|
||||
}
|
||||
|
||||
# Complete any dpll command
|
||||
_dpll()
|
||||
{
|
||||
local cur prev words cword
|
||||
local opt='--Version --json --pretty'
|
||||
local objects="device pin monitor"
|
||||
|
||||
_init_completion || return
|
||||
# Gets the word-to-complete without considering the colon as word breaks
|
||||
_get_comp_words_by_ref -n : cur prev words cword
|
||||
|
||||
if [[ $cword -eq 1 ]]; then
|
||||
case $cur in
|
||||
-*)
|
||||
COMPREPLY=( $( compgen -W "$opt" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
*)
|
||||
COMPREPLY=( $( compgen -W "$objects help" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
|
||||
# Deal with options
|
||||
if [[ $prev == -* ]]; then
|
||||
case $prev in
|
||||
-V|--Version)
|
||||
return 0
|
||||
;;
|
||||
-j|--json)
|
||||
COMPREPLY=( $( compgen -W "--pretty $objects" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
*)
|
||||
COMPREPLY=( $( compgen -W "$objects" -- "$cur" ) )
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
|
||||
# Remove all options so completions don't have to deal with them.
|
||||
local i
|
||||
for (( i=1; i < ${#words[@]}; )); do
|
||||
if [[ ${words[i]::1} == - ]]; then
|
||||
words=( "${words[@]:0:i}" "${words[@]:i+1}" )
|
||||
[[ $i -le $cword ]] && cword=$(( cword - 1 ))
|
||||
else
|
||||
i=$(( ++i ))
|
||||
fi
|
||||
done
|
||||
|
||||
local object=${words[1]}
|
||||
local command=${words[2]}
|
||||
local pprev=${words[cword - 2]}
|
||||
local prev=${words[cword - 1]}
|
||||
|
||||
case $object in
|
||||
device|pin|monitor)
|
||||
if [[ $cword -eq 2 ]]; then
|
||||
COMPREPLY=( $( compgen -W "help" -- "$cur") )
|
||||
if [[ $object != "monitor" ]]; then
|
||||
COMPREPLY+=( $( compgen -W \
|
||||
"$(_dpll_get_optional_commands $object)" -- "$cur" ) )
|
||||
fi
|
||||
else
|
||||
"_dpll_$object" $command
|
||||
fi
|
||||
;;
|
||||
help)
|
||||
return 0
|
||||
;;
|
||||
*)
|
||||
COMPREPLY=( $( compgen -W "$objects help" -- "$cur" ) )
|
||||
;;
|
||||
esac
|
||||
|
||||
} &&
|
||||
complete -F _dpll dpll
|
||||
|
||||
# ex: ts=4 sw=4 et filetype=sh
|
||||
1
dpll/.gitignore
vendored
Normal file
1
dpll/.gitignore
vendored
Normal file
@ -0,0 +1 @@
|
||||
dpll
|
||||
38
dpll/Makefile
Normal file
38
dpll/Makefile
Normal file
@ -0,0 +1,38 @@
|
||||
# SPDX-License-Identifier: GPL-2.0
|
||||
include ../config.mk
|
||||
|
||||
# iproute2 libraries
|
||||
LIBNETLINK=../lib/libutil.a ../lib/libnetlink.a
|
||||
|
||||
TARGETS :=
|
||||
ALLOBJS :=
|
||||
|
||||
# Check if libmnl is available
|
||||
ifeq ($(HAVE_MNL),y)
|
||||
|
||||
DPLLOBJ = dpll.o
|
||||
TARGETS += dpll
|
||||
ALLOBJS += dpll.o
|
||||
|
||||
# libmnl flags
|
||||
dpll.o: CFLAGS += -I../include -I../include/uapi
|
||||
|
||||
else
|
||||
$(warning "libmnl not found, skipping dpll tool build")
|
||||
endif
|
||||
|
||||
# Default CFLAGS for all objects
|
||||
CFLAGS += -I../include -I../include/uapi
|
||||
|
||||
all: $(TARGETS) $(LIBS)
|
||||
|
||||
dpll: $(DPLLOBJ) $(LIBNETLINK)
|
||||
$(QUIET_LINK)$(CC) $^ $(LDFLAGS) $(LDLIBS) -o $@
|
||||
|
||||
install: all
|
||||
for i in $(TARGETS); \
|
||||
do install -m 0755 $$i $(DESTDIR)$(SBINDIR); \
|
||||
done
|
||||
|
||||
clean:
|
||||
rm -f $(ALLOBJS) $(TARGETS)
|
||||
1951
dpll/dpll.c
Normal file
1951
dpll/dpll.c
Normal file
File diff suppressed because it is too large
Load Diff
428
man/man8/dpll.8
Normal file
428
man/man8/dpll.8
Normal file
@ -0,0 +1,428 @@
|
||||
.TH DPLL 8 "23 October 2025" "iproute2" "Linux"
|
||||
.SH NAME
|
||||
dpll \- Digital Phase Locked Loop (DPLL) subsystem management
|
||||
.SH SYNOPSIS
|
||||
.ad l
|
||||
.in +8
|
||||
.ti -8
|
||||
.B dpll
|
||||
.RI "[ " OPTIONS " ]"
|
||||
.B device
|
||||
.RI "{ " COMMAND " | "
|
||||
.BR help " }"
|
||||
.sp
|
||||
|
||||
.ti -8
|
||||
.B dpll
|
||||
.RI "[ " OPTIONS " ]"
|
||||
.B pin
|
||||
.RI "{ " COMMAND " | "
|
||||
.BR help " }"
|
||||
.sp
|
||||
|
||||
.ti -8
|
||||
.B dpll
|
||||
.RI "[ " OPTIONS " ]"
|
||||
.B monitor
|
||||
|
||||
.ti -8
|
||||
.IR OPTIONS " := { "
|
||||
\fB\-V\fR[\fIersion\fR] |
|
||||
\fB\-j\fR[\fIson\fR] |
|
||||
\fB\-p\fR[\fIretty\fR] }
|
||||
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.B 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.
|
||||
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
.BR "\-V" , " \-Version"
|
||||
Print the version of the
|
||||
.B dpll
|
||||
utility and exit.
|
||||
|
||||
.TP
|
||||
.BR "\-j" , " \-json"
|
||||
Output results in JavaScript Object Notation (JSON).
|
||||
|
||||
.TP
|
||||
.BR "\-p" , " \-pretty"
|
||||
When combined with \-j, generates a pretty JSON output with indentation
|
||||
and newlines for better human readability.
|
||||
|
||||
.SH DEVICE COMMANDS
|
||||
|
||||
.SS dpll device show [ id ID ]
|
||||
|
||||
Display information about DPLL devices. If no arguments are specified,
|
||||
shows all devices in the system.
|
||||
|
||||
.TP
|
||||
.BI id " ID"
|
||||
Show only the device with the specified numeric identifier.
|
||||
|
||||
.PP
|
||||
Output includes:
|
||||
.RS
|
||||
.IP \[bu] 2
|
||||
Device ID
|
||||
.IP \[bu]
|
||||
Module name providing the device
|
||||
.IP \[bu]
|
||||
Clock ID (unique identifier)
|
||||
.IP \[bu]
|
||||
Operating mode (manual, automatic, holdover, freerun)
|
||||
.IP \[bu]
|
||||
Lock status (locked-ho-ack, locked, unlocked, holdover)
|
||||
.IP \[bu]
|
||||
Temperature (if supported)
|
||||
.IP \[bu]
|
||||
Type (PPS or EEC)
|
||||
.RE
|
||||
|
||||
.SS dpll device set id ID [ phase-offset-monitor { enable | disable } ] [ phase-offset-avg-factor FACTOR ]
|
||||
|
||||
Configure DPLL device parameters.
|
||||
|
||||
.TP
|
||||
.BI id " ID"
|
||||
Specifies which device to configure (required).
|
||||
|
||||
.TP
|
||||
.BI phase-offset-monitor " { enable | disable | true | false | 0 | 1 }"
|
||||
Enable or disable phase offset monitoring between the device and its pins.
|
||||
When enabled, the kernel continuously measures and reports phase differences.
|
||||
|
||||
.TP
|
||||
.BI phase-offset-avg-factor " FACTOR"
|
||||
Set the averaging factor (1-255) applied to phase offset calculations.
|
||||
Higher values provide smoother but slower-responding measurements.
|
||||
|
||||
.SS 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.
|
||||
|
||||
.TP
|
||||
.BI module-name " NAME"
|
||||
Kernel module name.
|
||||
|
||||
.TP
|
||||
.BI clock-id " ID"
|
||||
64-bit clock identifier in decimal or hex (0x prefix).
|
||||
|
||||
.TP
|
||||
.BI type " TYPE"
|
||||
Device type:
|
||||
.BR pps " or " eec .
|
||||
|
||||
.SH PIN COMMANDS
|
||||
|
||||
.SS dpll pin show [ id ID ] [ device ID ]
|
||||
|
||||
Display information about DPLL pins. If no arguments are specified,
|
||||
shows all pins in the system.
|
||||
|
||||
.TP
|
||||
.BI id " ID"
|
||||
Show only the pin with the specified numeric identifier.
|
||||
|
||||
.TP
|
||||
.BI device " ID"
|
||||
Show only pins associated with the specified device ID.
|
||||
|
||||
.PP
|
||||
Output includes:
|
||||
.RS
|
||||
.IP \[bu] 2
|
||||
Pin ID
|
||||
.IP \[bu]
|
||||
Module name
|
||||
.IP \[bu]
|
||||
Clock ID
|
||||
.IP \[bu]
|
||||
Board label (hardware label from device tree or ACPI)
|
||||
.IP \[bu]
|
||||
Pin type (mux, ext, synce-eth-port, int-oscillator, gnss)
|
||||
.IP \[bu]
|
||||
Frequency and supported frequency ranges
|
||||
.IP \[bu]
|
||||
Capabilities (state-can-change, priority-can-change, direction-can-change)
|
||||
.IP \[bu]
|
||||
Phase adjustment range, granularity, and current value
|
||||
.IP \[bu]
|
||||
Parent device relationships (direction, priority, state, phase offset)
|
||||
.IP \[bu]
|
||||
Parent pin relationships
|
||||
.IP \[bu]
|
||||
Reference sync information
|
||||
.IP \[bu]
|
||||
Esync frequency support (if applicable)
|
||||
.RE
|
||||
|
||||
.SS dpll pin set id ID [ PARAMETER VALUE ] ...
|
||||
|
||||
Configure DPLL pin parameters. Multiple parameters can be specified
|
||||
in a single command.
|
||||
|
||||
.TP
|
||||
.BI id " ID"
|
||||
Specifies which pin to configure (required).
|
||||
|
||||
.TP
|
||||
.BI frequency " FREQ"
|
||||
Set pin frequency in Hz. The pin must support the specified frequency
|
||||
(check frequency-supported ranges in pin show output).
|
||||
|
||||
.TP
|
||||
.BI phase-adjust " ADJUSTMENT"
|
||||
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.
|
||||
|
||||
.TP
|
||||
.BI esync-frequency " FREQUENCY"
|
||||
Set enhanced SyncE (Synchronous Ethernet) frequency in Hz for capable pins.
|
||||
|
||||
.TP
|
||||
.BI parent-device " DEVICE_ID " "[ " "direction DIR" " ] [ " "prio PRIO" " ] [ " "state STATE" " ]"
|
||||
Configure the relationship between this pin and a parent DPLL device.
|
||||
.RS
|
||||
.TP
|
||||
.BI direction " { input | output }"
|
||||
Set the pin's direction relative to the parent device.
|
||||
.TP
|
||||
.BI prio " PRIORITY"
|
||||
Set priority (0-255) for this pin on the parent device.
|
||||
.TP
|
||||
.BI state " { connected | disconnected | selectable }"
|
||||
Set the pin's state on the parent device.
|
||||
.RE
|
||||
|
||||
.TP
|
||||
.BI parent-pin " PIN_ID " "[ " "state STATE" " ]"
|
||||
Configure the relationship to a parent pin.
|
||||
|
||||
.TP
|
||||
.BI reference-sync " PIN_ID " "[ " "state STATE" " ]"
|
||||
Configure reference sync relationship with another pin.
|
||||
|
||||
.SS dpll pin id-get [ SELECTOR ] ...
|
||||
|
||||
Retrieve a pin ID based on identifying attributes.
|
||||
|
||||
.TP
|
||||
.BI module-name " NAME"
|
||||
Filter by kernel module name.
|
||||
|
||||
.TP
|
||||
.BI clock-id " ID"
|
||||
Filter by 64-bit clock identifier.
|
||||
|
||||
.TP
|
||||
.BI board-label " LABEL"
|
||||
Filter by board label (hardware identifier).
|
||||
|
||||
.TP
|
||||
.BI panel-label " LABEL"
|
||||
Filter by panel label.
|
||||
|
||||
.TP
|
||||
.BI package-label " LABEL"
|
||||
Filter by package label.
|
||||
|
||||
.TP
|
||||
.BI type " TYPE"
|
||||
Filter by pin type:
|
||||
.BR mux ", " ext ", " synce-eth-port ", " int-oscillator ", " gnss .
|
||||
|
||||
.SH MONITOR COMMAND
|
||||
|
||||
.SS dpll monitor
|
||||
|
||||
Monitor DPLL subsystem events in real-time. Displays notifications about:
|
||||
.RS
|
||||
.IP \[bu] 2
|
||||
Device creation, deletion, and configuration changes
|
||||
.IP \[bu]
|
||||
Pin creation, deletion, and configuration changes
|
||||
.IP \[bu]
|
||||
Lock status changes
|
||||
.IP \[bu]
|
||||
Phase offset updates
|
||||
.IP \[bu]
|
||||
Frequency changes
|
||||
.RE
|
||||
|
||||
.PP
|
||||
Events are prefixed with their type: [DEVICE_CREATE], [DEVICE_CHANGE],
|
||||
[DEVICE_DELETE], [PIN_CREATE], [PIN_CHANGE], [PIN_DELETE].
|
||||
|
||||
.PP
|
||||
Press Ctrl+C to stop monitoring.
|
||||
|
||||
.SH EXAMPLES
|
||||
|
||||
.SS Show all DPLL devices
|
||||
.nf
|
||||
.B dpll device show
|
||||
.fi
|
||||
|
||||
.SS Show specific device in JSON format
|
||||
.nf
|
||||
.B dpll -j device show id 0
|
||||
.fi
|
||||
|
||||
.SS Enable phase offset monitoring on device 0
|
||||
.nf
|
||||
.B dpll device set id 0 phase-offset-monitor enable
|
||||
.fi
|
||||
|
||||
.SS Show all pins
|
||||
.nf
|
||||
.B dpll pin show
|
||||
.fi
|
||||
|
||||
.SS Show pin with pretty JSON output
|
||||
.nf
|
||||
.B dpll -jp pin show id 5
|
||||
.fi
|
||||
|
||||
.SS Set pin frequency to 10 MHz
|
||||
.nf
|
||||
.B dpll pin set id 0 frequency 10000000
|
||||
.fi
|
||||
|
||||
.SS Configure pin relationship to parent device
|
||||
.nf
|
||||
.B dpll pin set id 1 parent-device 0 prio 10 direction input state connected
|
||||
.fi
|
||||
|
||||
.SS Adjust phase by -1000 picoseconds
|
||||
.nf
|
||||
.B dpll pin set id 2 phase-adjust -1000
|
||||
.fi
|
||||
|
||||
.SS Set multiple pin parameters at once
|
||||
.nf
|
||||
.B dpll pin set id 3 frequency 10000000 phase-adjust -1000
|
||||
.fi
|
||||
|
||||
.SS Monitor DPLL events
|
||||
.nf
|
||||
.B dpll monitor
|
||||
.fi
|
||||
|
||||
.SS Monitor events in JSON format
|
||||
.nf
|
||||
.B dpll -jp monitor
|
||||
.fi
|
||||
|
||||
.SS Get device ID by module name
|
||||
.nf
|
||||
.B dpll device id-get module-name ice
|
||||
.fi
|
||||
|
||||
.SS Get pin ID by board label
|
||||
.nf
|
||||
.B dpll pin id-get board-label "GNSS-1PPS"
|
||||
.fi
|
||||
|
||||
.SH 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.
|
||||
|
||||
.PP
|
||||
Important considerations:
|
||||
.RS
|
||||
.IP \[bu] 2
|
||||
Check phase-adjust-min and phase-adjust-max before setting values
|
||||
.IP \[bu]
|
||||
Some hardware requires values to be multiples of phase-adjust-gran
|
||||
.IP \[bu]
|
||||
Negative values shift phase backwards (earlier in time)
|
||||
.IP \[bu]
|
||||
Positive values shift phase forwards (later in time)
|
||||
.IP \[bu]
|
||||
The kernel validates all phase adjustment requests
|
||||
.RE
|
||||
|
||||
.SH CAPABILITIES
|
||||
Pins may have various capabilities that determine which operations are allowed:
|
||||
|
||||
.TP
|
||||
.B state-can-change
|
||||
The pin's state (connected/disconnected/selectable) can be modified.
|
||||
|
||||
.TP
|
||||
.B priority-can-change
|
||||
The pin's priority can be modified. This may apply to top-level priority
|
||||
or priority within parent-device relationships.
|
||||
|
||||
.TP
|
||||
.B direction-can-change
|
||||
The pin's direction (input/output) can be modified.
|
||||
|
||||
.PP
|
||||
Use
|
||||
.B dpll pin show
|
||||
to check which capabilities a pin supports before attempting configuration
|
||||
changes.
|
||||
|
||||
.SH EXIT STATUS
|
||||
.TP
|
||||
.B 0
|
||||
Success
|
||||
.TP
|
||||
.B 1
|
||||
General failure
|
||||
.TP
|
||||
.B 2
|
||||
Invalid arguments or usage
|
||||
.TP
|
||||
.B 255
|
||||
Netlink communication error
|
||||
|
||||
.SH NOTES
|
||||
.IP \[bu] 2
|
||||
The DPLL subsystem requires kernel support (CONFIG_DPLL=y or m)
|
||||
.IP \[bu]
|
||||
Hardware support varies by device and driver
|
||||
.IP \[bu]
|
||||
Some operations require specific hardware capabilities
|
||||
.IP \[bu]
|
||||
Phase offset values are measured by hardware and cannot be set directly
|
||||
.IP \[bu]
|
||||
Changes to device/pin configuration may affect system clock synchronization
|
||||
|
||||
.SH SEE ALSO
|
||||
.BR ip (8),
|
||||
.BR devlink (8),
|
||||
.BR ethtool (8)
|
||||
|
||||
.PP
|
||||
Linux kernel documentation:
|
||||
.I Documentation/driver-api/dpll.rst
|
||||
|
||||
.PP
|
||||
Netlink specification:
|
||||
.I Documentation/netlink/specs/dpll.yaml
|
||||
|
||||
.SH AUTHOR
|
||||
dpll was written by Arkadiusz Kubalewski, Vadim Fedorenko, and others.
|
||||
|
||||
This manual page was written by Petr Oros.
|
||||
|
||||
.SH REPORTING BUGS
|
||||
Report bugs to <netdev@vger.kernel.org>
|
||||
Loading…
x
Reference in New Issue
Block a user