Debian Codegraph @

upstream/debian-unstable/man8/dpll.8

raw
1 .TH DPLL 8 "23 October 2025" "iproute2" "Linux"
2 .SH NAME
3 dpll \- Digital Phase Locked Loop (DPLL) subsystem management
4 .SH SYNOPSIS
5 .ad l
6 .in +8
7 .ti -8
8 .B dpll
9 .RI "[ " OPTIONS " ]"
10 .B device
11 .RI "{ " COMMAND " | "
12 .BR help " }"
13 .sp
14
15 .ti -8
16 .B dpll
17 .RI "[ " OPTIONS " ]"
18 .B pin
19 .RI "{ " COMMAND " | "
20 .BR help " }"
21 .sp
22
23 .ti -8
24 .B dpll
25 .RI "[ " OPTIONS " ]"
26 .B monitor
27
28 .ti -8
29 .IR OPTIONS " := { "
30 \fB\-V\fR[\fIersion\fR] |
31 \fB\-j\fR[\fIson\fR] |
32 \fB\-p\fR[\fIretty\fR] }
33
34 .SH DESCRIPTION
35 The
36 .B dpll
37 utility is used to configure and monitor Digital Phase Locked Loop (DPLL)
38 devices and pins. DPLLs are used for clock synchronization in various
39 hardware, particularly in telecommunications and networking equipment.
40
41 A DPLL device can lock to one or more input pins and provide synchronized
42 output. Pins can be physical external signals (like GNSS 1PPS, SyncE), or
43 internal oscillators.
44
45 .SH OPTIONS
46 .TP
47 .BR "\-V" , " \-Version"
48 Print the version of the
49 .B dpll
50 utility and exit.
51
52 .TP
53 .BR "\-j" , " \-json"
54 Output results in JavaScript Object Notation (JSON).
55
56 .TP
57 .BR "\-p" , " \-pretty"
58 When combined with \-j, generates a pretty JSON output with indentation
59 and newlines for better human readability.
60
61 .SH DEVICE COMMANDS
62
63 .SS dpll device show [ id ID ]
64
65 Display information about DPLL devices. If no arguments are specified,
66 shows all devices in the system.
67
68 .TP
69 .BI id " ID"
70 Show only the device with the specified numeric identifier.
71
72 .PP
73 Output includes:
74 .RS
75 .IP \[bu] 2
76 Device ID
77 .IP \[bu]
78 Module name providing the device
79 .IP \[bu]
80 Clock ID (unique identifier)
81 .IP \[bu]
82 Operating mode (manual, automatic, holdover, freerun)
83 .IP \[bu]
84 Lock status (locked-ho-ack, locked, unlocked, holdover)
85 .IP \[bu]
86 Temperature (if supported)
87 .IP \[bu]
88 Type (PPS or EEC)
89 .RE
90
91 .SS dpll device set id ID [ mode { automatic | manual } ] [ phase-offset-monitor { enable | disable } ] [ phase-offset-avg-factor FACTOR ]
92
93 Configure DPLL device parameters.
94
95 .TP
96 .BI id " ID"
97 Specifies which device to configure (required).
98
99 .TP
100 .BI mode " { automatic | manual }"
101 Set the operating mode of the DPLL device.
102 In
103 .B automatic
104 mode, the DPLL autonomously selects the best available input source
105 based on priority and quality. In
106 .B manual
107 mode, the input source must be explicitly configured and the DPLL
108 will not automatically switch sources.
109
110 .TP
111 .BI phase-offset-monitor " { enable | disable | true | false | 0 | 1 }"
112 Enable or disable phase offset monitoring between the device and its pins.
113 When enabled, the kernel continuously measures and reports phase differences.
114
115 .TP
116 .BI phase-offset-avg-factor " FACTOR"
117 Set the averaging factor (1-255) applied to phase offset calculations.
118 Higher values provide smoother but slower-responding measurements.
119
120 .SS dpll device id-get [ module-name NAME ] [ clock-id ID ] [ type TYPE ]
121
122 Retrieve the device ID based on identifying attributes. Useful for scripting
123 when you need to find a device's numeric ID. At least one attribute should
124 be specified to identify the device.
125
126 .TP
127 .BI module-name " NAME"
128 Kernel module name.
129
130 .TP
131 .BI clock-id " ID"
132 64-bit clock identifier in decimal or hex (0x prefix).
133
134 .TP
135 .BI type " TYPE"
136 Device type:
137 .BR pps " or " eec .
138
139 .SH PIN COMMANDS
140
141 .SS dpll pin show [ id ID ] [ device ID ]
142
143 Display information about DPLL pins. If no arguments are specified,
144 shows all pins in the system.
145
146 .TP
147 .BI id " ID"
148 Show only the pin with the specified numeric identifier.
149
150 .TP
151 .BI device " ID"
152 Show only pins associated with the specified device ID.
153
154 .PP
155 Output includes:
156 .RS
157 .IP \[bu] 2
158 Pin ID
159 .IP \[bu]
160 Module name
161 .IP \[bu]
162 Clock ID
163 .IP \[bu]
164 Board label (hardware label from device tree or ACPI)
165 .IP \[bu]
166 Pin type (mux, ext, synce-eth-port, int-oscillator, gnss)
167 .IP \[bu]
168 Frequency and supported frequency ranges
169 .IP \[bu]
170 Capabilities (state-can-change, priority-can-change, direction-can-change)
171 .IP \[bu]
172 Phase adjustment range, granularity, and current value
173 .IP \[bu]
174 Parent device relationships (direction, priority, state, phase offset)
175 .IP \[bu]
176 Parent pin relationships
177 .IP \[bu]
178 Reference sync information
179 .IP \[bu]
180 Esync frequency support (if applicable)
181 .RE
182
183 .SS dpll pin set id ID [ PARAMETER VALUE ] ...
184
185 Configure DPLL pin parameters. Multiple parameters can be specified
186 in a single command.
187
188 .TP
189 .BI id " ID"
190 Specifies which pin to configure (required).
191
192 .TP
193 .BI frequency " FREQ"
194 Set pin frequency in Hz. The pin must support the specified frequency
195 (check frequency-supported ranges in pin show output).
196
197 .TP
198 .BI phase-adjust " ADJUSTMENT"
199 Set phase adjustment in picoseconds. This value fine-tunes the phase
200 of the output signal. Negative values shift the phase backwards,
201 positive values shift it forwards. The value must be within the
202 phase-adjust-min and phase-adjust-max range.
203
204 .TP
205 .BI esync-frequency " FREQUENCY"
206 Set enhanced SyncE (Synchronous Ethernet) frequency in Hz for capable pins.
207
208 .TP
209 .BI parent-device " DEVICE_ID " "[ " "direction DIR" " ] [ " "prio PRIO" " ] [ " "state STATE" " ]"
210 Configure the relationship between this pin and a parent DPLL device.
211 .RS
212 .TP
213 .BI direction " { input | output }"
214 Set the pin's direction relative to the parent device.
215 .TP
216 .BI prio " PRIORITY"
217 Set priority (0-255) for this pin on the parent device.
218 .TP
219 .BI state " { connected | disconnected | selectable }"
220 Set the pin's state on the parent device.
221 .RE
222
223 .TP
224 .BI parent-pin " PIN_ID " "[ " "state STATE" " ]"
225 Configure the relationship to a parent pin.
226
227 .TP
228 .BI reference-sync " PIN_ID " "[ " "state STATE" " ]"
229 Configure reference sync relationship with another pin.
230
231 .SS dpll pin id-get [ SELECTOR ] ...
232
233 Retrieve a pin ID based on identifying attributes.
234
235 .TP
236 .BI module-name " NAME"
237 Filter by kernel module name.
238
239 .TP
240 .BI clock-id " ID"
241 Filter by 64-bit clock identifier.
242
243 .TP
244 .BI board-label " LABEL"
245 Filter by board label (hardware identifier).
246
247 .TP
248 .BI panel-label " LABEL"
249 Filter by panel label.
250
251 .TP
252 .BI package-label " LABEL"
253 Filter by package label.
254
255 .TP
256 .BI type " TYPE"
257 Filter by pin type:
258 .BR mux ", " ext ", " synce-eth-port ", " int-oscillator ", " gnss .
259
260 .SH MONITOR COMMAND
261
262 .SS dpll monitor
263
264 Monitor DPLL subsystem events in real-time. Displays notifications about:
265 .RS
266 .IP \[bu] 2
267 Device creation, deletion, and configuration changes
268 .IP \[bu]
269 Pin creation, deletion, and configuration changes
270 .IP \[bu]
271 Lock status changes
272 .IP \[bu]
273 Phase offset updates
274 .IP \[bu]
275 Frequency changes
276 .RE
277
278 .PP
279 Events are prefixed with their type: [DEVICE_CREATE], [DEVICE_CHANGE],
280 [DEVICE_DELETE], [PIN_CREATE], [PIN_CHANGE], [PIN_DELETE].
281
282 .PP
283 Press Ctrl+C to stop monitoring.
284
285 .SH EXAMPLES
286
287 .SS Show all DPLL devices
288 .nf
289 .B dpll device show
290 .fi
291
292 .SS Show specific device in JSON format
293 .nf
294 .B dpll -j device show id 0
295 .fi
296
297 .SS Set device 0 to manual mode
298 .nf
299 .B dpll device set id 0 mode manual
300 .fi
301
302 .SS Enable phase offset monitoring on device 0
303 .nf
304 .B dpll device set id 0 phase-offset-monitor enable
305 .fi
306
307 .SS Show all pins
308 .nf
309 .B dpll pin show
310 .fi
311
312 .SS Show pin with pretty JSON output
313 .nf
314 .B dpll -jp pin show id 5
315 .fi
316
317 .SS Set pin frequency to 10 MHz
318 .nf
319 .B dpll pin set id 0 frequency 10000000
320 .fi
321
322 .SS Configure pin relationship to parent device
323 .nf
324 .B dpll pin set id 1 parent-device 0 prio 10 direction input state connected
325 .fi
326
327 .SS Adjust phase by -1000 picoseconds
328 .nf
329 .B dpll pin set id 2 phase-adjust -1000
330 .fi
331
332 .SS Set multiple pin parameters at once
333 .nf
334 .B dpll pin set id 3 frequency 10000000 phase-adjust -1000
335 .fi
336
337 .SS Monitor DPLL events
338 .nf
339 .B dpll monitor
340 .fi
341
342 .SS Monitor events in JSON format
343 .nf
344 .B dpll -jp monitor
345 .fi
346
347 .SS Get device ID by module name
348 .nf
349 .B dpll device id-get module-name ice
350 .fi
351
352 .SS Get pin ID by board label
353 .nf
354 .B dpll pin id-get board-label "GNSS-1PPS"
355 .fi
356
357 .SH PHASE ADJUSTMENT
358 Phase adjustment is specified in picoseconds (1e-12 seconds) and allows
359 fine-tuning of signal phase. This is crucial for precise time synchronization
360 applications like 5G networks and high-frequency trading.
361
362 .PP
363 Important considerations:
364 .RS
365 .IP \[bu] 2
366 Check phase-adjust-min and phase-adjust-max before setting values
367 .IP \[bu]
368 Some hardware requires values to be multiples of phase-adjust-gran
369 .IP \[bu]
370 Negative values shift phase backwards (earlier in time)
371 .IP \[bu]
372 Positive values shift phase forwards (later in time)
373 .IP \[bu]
374 The kernel validates all phase adjustment requests
375 .RE
376
377 .SH CAPABILITIES
378 Pins may have various capabilities that determine which operations are allowed:
379
380 .TP
381 .B state-can-change
382 The pin's state (connected/disconnected/selectable) can be modified.
383
384 .TP
385 .B priority-can-change
386 The pin's priority can be modified. This may apply to top-level priority
387 or priority within parent-device relationships.
388
389 .TP
390 .B direction-can-change
391 The pin's direction (input/output) can be modified.
392
393 .PP
394 Use
395 .B dpll pin show
396 to check which capabilities a pin supports before attempting configuration
397 changes.
398
399 .SH EXIT STATUS
400 .TP
401 .B 0
402 Success
403 .TP
404 .B 1
405 General failure
406 .TP
407 .B 2
408 Invalid arguments or usage
409 .TP
410 .B 255
411 Netlink communication error
412
413 .SH NOTES
414 .IP \[bu] 2
415 The DPLL subsystem requires kernel support (CONFIG_DPLL=y or m)
416 .IP \[bu]
417 Hardware support varies by device and driver
418 .IP \[bu]
419 Some operations require specific hardware capabilities
420 .IP \[bu]
421 Phase offset values are measured by hardware and cannot be set directly
422 .IP \[bu]
423 Changes to device/pin configuration may affect system clock synchronization
424
425 .SH SEE ALSO
426 .BR ip (8),
427 .BR devlink (8),
428 .BR ethtool (8)
429
430 .PP
431 Linux kernel documentation:
432 .I Documentation/driver-api/dpll.rst
433
434 .PP
435 Netlink specification:
436 .I Documentation/netlink/specs/dpll.yaml
437
438 .SH AUTHOR
439 dpll was written by Arkadiusz Kubalewski, Vadim Fedorenko, and others.
440
441 This manual page was written by Petr Oros.
442
443 .SH REPORTING BUGS
444 Report bugs to <[email protected]>