tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
2---
3name: dpll
4
5doc: DPLL subsystem.
6
7definitions:
8 -
9 type: enum
10 name: mode
11 doc: |
12 working modes a dpll can support, differentiates if and how dpll selects
13 one of its inputs to syntonize with it, valid values for DPLL_A_MODE
14 attribute
15 entries:
16 -
17 name: manual
18 doc: input can be only selected by sending a request to dpll
19 value: 1
20 -
21 name: automatic
22 doc: highest prio input pin auto selected by dpll
23 render-max: true
24 -
25 type: enum
26 name: lock-status
27 doc: |
28 provides information of dpll device lock status, valid values for
29 DPLL_A_LOCK_STATUS attribute
30 entries:
31 -
32 name: unlocked
33 doc: |
34 dpll was not yet locked to any valid input (or forced by setting
35 DPLL_A_MODE to DPLL_MODE_DETACHED)
36 value: 1
37 -
38 name: locked
39 doc: |
40 dpll is locked to a valid signal, but no holdover available
41 -
42 name: locked-ho-acq
43 doc: |
44 dpll is locked and holdover acquired
45 -
46 name: holdover
47 doc: |
48 dpll is in holdover state - lost a valid lock or was forced
49 by disconnecting all the pins (latter possible only
50 when dpll lock-state was already DPLL_LOCK_STATUS_LOCKED_HO_ACQ,
51 if dpll lock-state was not DPLL_LOCK_STATUS_LOCKED_HO_ACQ, the
52 dpll's lock-state shall remain DPLL_LOCK_STATUS_UNLOCKED)
53 render-max: true
54 -
55 type: enum
56 name: lock-status-error
57 doc: |
58 if previous status change was done due to a failure, this provides
59 information of dpll device lock status error.
60 Valid values for DPLL_A_LOCK_STATUS_ERROR attribute
61 entries:
62 -
63 name: none
64 doc: |
65 dpll device lock status was changed without any error
66 value: 1
67 -
68 name: undefined
69 doc: |
70 dpll device lock status was changed due to undefined error.
71 Driver fills this value up in case it is not able
72 to obtain suitable exact error type.
73 -
74 name: media-down
75 doc: |
76 dpll device lock status was changed because of associated
77 media got down.
78 This may happen for example if dpll device was previously
79 locked on an input pin of type PIN_TYPE_SYNCE_ETH_PORT.
80 -
81 name: fractional-frequency-offset-too-high
82 doc: |
83 the FFO (Fractional Frequency Offset) between the RX and TX
84 symbol rate on the media got too high.
85 This may happen for example if dpll device was previously
86 locked on an input pin of type PIN_TYPE_SYNCE_ETH_PORT.
87 render-max: true
88 -
89 type: enum
90 name: clock-quality-level
91 doc: |
92 level of quality of a clock device. This mainly applies when
93 the dpll lock-status is DPLL_LOCK_STATUS_HOLDOVER.
94 The current list is defined according to the table 11-7 contained
95 in ITU-T G.8264/Y.1364 document. One may extend this list freely
96 by other ITU-T defined clock qualities, or different ones defined
97 by another standardization body (for those, please use
98 different prefix).
99 entries:
100 -
101 name: itu-opt1-prc
102 value: 1
103 -
104 name: itu-opt1-ssu-a
105 -
106 name: itu-opt1-ssu-b
107 -
108 name: itu-opt1-eec1
109 -
110 name: itu-opt1-prtc
111 -
112 name: itu-opt1-eprtc
113 -
114 name: itu-opt1-eeec
115 -
116 name: itu-opt1-eprc
117 render-max: true
118 -
119 type: const
120 name: temp-divider
121 value: 1000
122 doc: |
123 temperature divider allowing userspace to calculate the
124 temperature as float with three digit decimal precision.
125 Value of (DPLL_A_TEMP / DPLL_TEMP_DIVIDER) is integer part of
126 temperature value.
127 Value of (DPLL_A_TEMP % DPLL_TEMP_DIVIDER) is fractional part of
128 temperature value.
129 -
130 type: enum
131 name: type
132 doc: type of dpll, valid values for DPLL_A_TYPE attribute
133 entries:
134 -
135 name: pps
136 doc: dpll produces Pulse-Per-Second signal
137 value: 1
138 -
139 name: eec
140 doc: dpll drives the Ethernet Equipment Clock
141 render-max: true
142 -
143 type: enum
144 name: pin-type
145 doc: |
146 defines possible types of a pin, valid values for DPLL_A_PIN_TYPE
147 attribute
148 entries:
149 -
150 name: mux
151 doc: aggregates another layer of selectable pins
152 value: 1
153 -
154 name: ext
155 doc: external input
156 -
157 name: synce-eth-port
158 doc: ethernet port PHY's recovered clock
159 -
160 name: int-oscillator
161 doc: device internal oscillator
162 -
163 name: gnss
164 doc: GNSS recovered clock
165 render-max: true
166 -
167 type: enum
168 name: pin-direction
169 doc: |
170 defines possible direction of a pin, valid values for
171 DPLL_A_PIN_DIRECTION attribute
172 entries:
173 -
174 name: input
175 doc: pin used as a input of a signal
176 value: 1
177 -
178 name: output
179 doc: pin used to output the signal
180 render-max: true
181 -
182 type: const
183 name: pin-frequency-1-hz
184 value: 1
185 -
186 type: const
187 name: pin-frequency-10-khz
188 value: 10000
189 -
190 type: const
191 name: pin-frequency-77-5-khz
192 value: 77500
193 -
194 type: const
195 name: pin-frequency-10-mhz
196 value: 10000000
197 -
198 type: enum
199 name: pin-state
200 doc: |
201 defines possible states of a pin, valid values for
202 DPLL_A_PIN_STATE attribute
203 entries:
204 -
205 name: connected
206 doc: pin connected, active input of phase locked loop
207 value: 1
208 -
209 name: disconnected
210 doc: pin disconnected, not considered as a valid input
211 -
212 name: selectable
213 doc: pin enabled for automatic input selection
214 render-max: true
215 -
216 type: flags
217 name: pin-capabilities
218 doc: |
219 defines possible capabilities of a pin, valid flags on
220 DPLL_A_PIN_CAPABILITIES attribute
221 entries:
222 -
223 name: direction-can-change
224 doc: pin direction can be changed
225 -
226 name: priority-can-change
227 doc: pin priority can be changed
228 -
229 name: state-can-change
230 doc: pin state can be changed
231 -
232 type: const
233 name: phase-offset-divider
234 value: 1000
235 doc: |
236 phase offset divider allows userspace to calculate a value of
237 measured signal phase difference between a pin and dpll device
238 as a fractional value with three digit decimal precision.
239 Value of (DPLL_A_PHASE_OFFSET / DPLL_PHASE_OFFSET_DIVIDER) is an
240 integer part of a measured phase offset value.
241 Value of (DPLL_A_PHASE_OFFSET % DPLL_PHASE_OFFSET_DIVIDER) is a
242 fractional part of a measured phase offset value.
243 -
244 type: enum
245 name: feature-state
246 doc: |
247 Allow control (enable/disable) and status checking over features.
248 entries:
249 -
250 name: disable
251 doc: |
252 feature shall be disabled
253 -
254 name: enable
255 doc: |
256 feature shall be enabled
257
258attribute-sets:
259 -
260 name: dpll
261 enum-name: dpll_a
262 attributes:
263 -
264 name: id
265 type: u32
266 -
267 name: module-name
268 type: string
269 -
270 name: pad
271 type: pad
272 -
273 name: clock-id
274 type: u64
275 -
276 name: mode
277 type: u32
278 enum: mode
279 -
280 name: mode-supported
281 type: u32
282 enum: mode
283 multi-attr: true
284 -
285 name: lock-status
286 type: u32
287 enum: lock-status
288 -
289 name: temp
290 type: s32
291 -
292 name: type
293 type: u32
294 enum: type
295 -
296 name: lock-status-error
297 type: u32
298 enum: lock-status-error
299 -
300 name: clock-quality-level
301 type: u32
302 enum: clock-quality-level
303 multi-attr: true
304 doc: |
305 Level of quality of a clock device. This mainly applies when
306 the dpll lock-status is DPLL_LOCK_STATUS_HOLDOVER. This could
307 be put to message multiple times to indicate possible parallel
308 quality levels (e.g. one specified by ITU option 1 and another
309 one specified by option 2).
310 -
311 name: phase-offset-monitor
312 type: u32
313 enum: feature-state
314 doc: Receive or request state of phase offset monitor feature.
315 If enabled, dpll device shall monitor and notify all currently
316 available inputs for changes of their phase offset against the
317 dpll device.
318 -
319 name: phase-offset-avg-factor
320 type: u32
321 doc: Averaging factor applied to calculation of reported phase offset.
322 -
323 name: pin
324 enum-name: dpll_a_pin
325 attributes:
326 -
327 name: id
328 type: u32
329 -
330 name: parent-id
331 type: u32
332 -
333 name: module-name
334 type: string
335 -
336 name: pad
337 type: pad
338 -
339 name: clock-id
340 type: u64
341 -
342 name: board-label
343 type: string
344 -
345 name: panel-label
346 type: string
347 -
348 name: package-label
349 type: string
350 -
351 name: type
352 type: u32
353 enum: pin-type
354 -
355 name: direction
356 type: u32
357 enum: pin-direction
358 -
359 name: frequency
360 type: u64
361 -
362 name: frequency-supported
363 type: nest
364 multi-attr: true
365 nested-attributes: frequency-range
366 -
367 name: frequency-min
368 type: u64
369 -
370 name: frequency-max
371 type: u64
372 -
373 name: prio
374 type: u32
375 -
376 name: state
377 type: u32
378 enum: pin-state
379 -
380 name: capabilities
381 type: u32
382 enum: pin-capabilities
383 -
384 name: parent-device
385 type: nest
386 multi-attr: true
387 nested-attributes: pin-parent-device
388 -
389 name: parent-pin
390 type: nest
391 multi-attr: true
392 nested-attributes: pin-parent-pin
393 -
394 name: phase-adjust-min
395 type: s32
396 -
397 name: phase-adjust-max
398 type: s32
399 -
400 name: phase-adjust
401 type: s32
402 -
403 name: phase-offset
404 type: s64
405 -
406 name: fractional-frequency-offset
407 type: sint
408 doc: |
409 The FFO (Fractional Frequency Offset) between the RX and TX
410 symbol rate on the media associated with the pin:
411 (rx_frequency-tx_frequency)/rx_frequency
412 Value is in PPM (parts per million).
413 This may be implemented for example for pin of type
414 PIN_TYPE_SYNCE_ETH_PORT.
415 -
416 name: esync-frequency
417 type: u64
418 doc: |
419 Frequency of Embedded SYNC signal. If provided, the pin is configured
420 with a SYNC signal embedded into its base clock frequency.
421 -
422 name: esync-frequency-supported
423 type: nest
424 multi-attr: true
425 nested-attributes: frequency-range
426 doc: |
427 If provided a pin is capable of embedding a SYNC signal (within given
428 range) into its base frequency signal.
429 -
430 name: esync-pulse
431 type: u32
432 doc: |
433 A ratio of high to low state of a SYNC signal pulse embedded
434 into base clock frequency. Value is in percents.
435 -
436 name: reference-sync
437 type: nest
438 multi-attr: true
439 nested-attributes: reference-sync
440 doc: |
441 Capable pin provides list of pins that can be bound to create a
442 reference-sync pin pair.
443 -
444 name: phase-adjust-gran
445 type: u32
446 doc: |
447 Granularity of phase adjustment, in picoseconds. The value of
448 phase adjustment must be a multiple of this granularity.
449
450 -
451 name: pin-parent-device
452 subset-of: pin
453 attributes:
454 -
455 name: parent-id
456 -
457 name: direction
458 -
459 name: prio
460 -
461 name: state
462 -
463 name: phase-offset
464 -
465 name: pin-parent-pin
466 subset-of: pin
467 attributes:
468 -
469 name: parent-id
470 -
471 name: state
472 -
473 name: frequency-range
474 subset-of: pin
475 attributes:
476 -
477 name: frequency-min
478 -
479 name: frequency-max
480 -
481 name: reference-sync
482 subset-of: pin
483 attributes:
484 -
485 name: id
486 -
487 name: state
488
489operations:
490 enum-name: dpll_cmd
491 list:
492 -
493 name: device-id-get
494 doc: |
495 Get id of dpll device that matches given attributes
496 attribute-set: dpll
497 flags: [admin-perm]
498
499 do:
500 pre: dpll-lock-doit
501 post: dpll-unlock-doit
502 request:
503 attributes:
504 - module-name
505 - clock-id
506 - type
507 reply:
508 attributes:
509 - id
510
511 -
512 name: device-get
513 doc: |
514 Get list of DPLL devices (dump) or attributes of a single dpll device
515 attribute-set: dpll
516 flags: [admin-perm]
517
518 do:
519 pre: dpll-pre-doit
520 post: dpll-post-doit
521 request:
522 attributes:
523 - id
524 reply: &dev-attrs
525 attributes:
526 - id
527 - module-name
528 - mode
529 - mode-supported
530 - lock-status
531 - lock-status-error
532 - temp
533 - clock-id
534 - type
535 - phase-offset-monitor
536 - phase-offset-avg-factor
537
538 dump:
539 reply: *dev-attrs
540
541 -
542 name: device-set
543 doc: Set attributes for a DPLL device
544 attribute-set: dpll
545 flags: [admin-perm]
546
547 do:
548 pre: dpll-pre-doit
549 post: dpll-post-doit
550 request:
551 attributes:
552 - id
553 - phase-offset-monitor
554 - phase-offset-avg-factor
555 -
556 name: device-create-ntf
557 doc: Notification about device appearing
558 notify: device-get
559 mcgrp: monitor
560 -
561 name: device-delete-ntf
562 doc: Notification about device disappearing
563 notify: device-get
564 mcgrp: monitor
565 -
566 name: device-change-ntf
567 doc: Notification about device configuration being changed
568 notify: device-get
569 mcgrp: monitor
570 -
571 name: pin-id-get
572 doc: |
573 Get id of a pin that matches given attributes
574 attribute-set: pin
575 flags: [admin-perm]
576
577 do:
578 pre: dpll-lock-doit
579 post: dpll-unlock-doit
580 request:
581 attributes:
582 - module-name
583 - clock-id
584 - board-label
585 - panel-label
586 - package-label
587 - type
588 reply:
589 attributes:
590 - id
591
592 -
593 name: pin-get
594 doc: |
595 Get list of pins and its attributes.
596
597 - dump request without any attributes given - list all the pins in the
598 system
599 - dump request with target dpll - list all the pins registered with
600 a given dpll device
601 - do request with target dpll and target pin - single pin attributes
602 attribute-set: pin
603 flags: [admin-perm]
604
605 do:
606 pre: dpll-pin-pre-doit
607 post: dpll-pin-post-doit
608 request:
609 attributes:
610 - id
611 reply: &pin-attrs
612 attributes:
613 - id
614 - module-name
615 - clock-id
616 - board-label
617 - panel-label
618 - package-label
619 - type
620 - frequency
621 - frequency-supported
622 - capabilities
623 - parent-device
624 - parent-pin
625 - phase-adjust-gran
626 - phase-adjust-min
627 - phase-adjust-max
628 - phase-adjust
629 - fractional-frequency-offset
630 - esync-frequency
631 - esync-frequency-supported
632 - esync-pulse
633 - reference-sync
634
635 dump:
636 request:
637 attributes:
638 - id
639 reply: *pin-attrs
640
641 -
642 name: pin-set
643 doc: Set attributes of a target pin
644 attribute-set: pin
645 flags: [admin-perm]
646
647 do:
648 pre: dpll-pin-pre-doit
649 post: dpll-pin-post-doit
650 request:
651 attributes:
652 - id
653 - frequency
654 - direction
655 - prio
656 - state
657 - parent-device
658 - parent-pin
659 - phase-adjust
660 - esync-frequency
661 - reference-sync
662 -
663 name: pin-create-ntf
664 doc: Notification about pin appearing
665 notify: pin-get
666 mcgrp: monitor
667 -
668 name: pin-delete-ntf
669 doc: Notification about pin disappearing
670 notify: pin-get
671 mcgrp: monitor
672 -
673 name: pin-change-ntf
674 doc: Notification about pin configuration being changed
675 notify: pin-get
676 mcgrp: monitor
677
678mcast-groups:
679 list:
680 -
681 name: monitor