| blob | 8feefeae5376c84430906df0f4e2107bf16bd09c |
1 # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
3 name: dpll
5 doc: DPLL subsystem.
7 definitions:
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.
244 attribute-sets:
245 -
246 name: dpll
247 enum-name: dpll_a
248 attributes:
249 -
250 name: id
251 type: u32
252 -
253 name: module-name
254 type: string
255 -
256 name: pad
257 type: pad
258 -
259 name: clock-id
260 type: u64
261 -
262 name: mode
263 type: u32
264 enum: mode
265 -
266 name: mode-supported
267 type: u32
268 enum: mode
269 multi-attr: true
270 -
271 name: lock-status
272 type: u32
273 enum: lock-status
274 -
275 name: temp
276 type: s32
277 -
278 name: type
279 type: u32
280 enum: type
281 -
282 name: lock-status-error
283 type: u32
284 enum: lock-status-error
285 -
286 name: clock-quality-level
287 type: u32
288 enum: clock-quality-level
289 multi-attr: true
290 doc: |
291 Level of quality of a clock device. This mainly applies when
292 the dpll lock-status is DPLL_LOCK_STATUS_HOLDOVER. This could
293 be put to message multiple times to indicate possible parallel
294 quality levels (e.g. one specified by ITU option 1 and another
295 one specified by option 2).
296 -
297 name: pin
298 enum-name: dpll_a_pin
299 attributes:
300 -
301 name: id
302 type: u32
303 -
304 name: parent-id
305 type: u32
306 -
307 name: module-name
308 type: string
309 -
310 name: pad
311 type: pad
312 -
313 name: clock-id
314 type: u64
315 -
316 name: board-label
317 type: string
318 -
319 name: panel-label
320 type: string
321 -
322 name: package-label
323 type: string
324 -
325 name: type
326 type: u32
327 enum: pin-type
328 -
329 name: direction
330 type: u32
331 enum: pin-direction
332 -
333 name: frequency
334 type: u64
335 -
336 name: frequency-supported
337 type: nest
338 multi-attr: true
339 nested-attributes: frequency-range
340 -
341 name: frequency-min
342 type: u64
343 -
344 name: frequency-max
345 type: u64
346 -
347 name: prio
348 type: u32
349 -
350 name: state
351 type: u32
352 enum: pin-state
353 -
354 name: capabilities
355 type: u32
356 enum: pin-capabilities
357 -
358 name: parent-device
359 type: nest
360 multi-attr: true
361 nested-attributes: pin-parent-device
362 -
363 name: parent-pin
364 type: nest
365 multi-attr: true
366 nested-attributes: pin-parent-pin
367 -
368 name: phase-adjust-min
369 type: s32
370 -
371 name: phase-adjust-max
372 type: s32
373 -
374 name: phase-adjust
375 type: s32
376 -
377 name: phase-offset
378 type: s64
379 -
380 name: fractional-frequency-offset
381 type: sint
382 doc: |
383 The FFO (Fractional Frequency Offset) between the RX and TX
384 symbol rate on the media associated with the pin:
385 (rx_frequency-tx_frequency)/rx_frequency
386 Value is in PPM (parts per million).
387 This may be implemented for example for pin of type
388 PIN_TYPE_SYNCE_ETH_PORT.
389 -
390 name: esync-frequency
391 type: u64
392 doc: |
393 Frequency of Embedded SYNC signal. If provided, the pin is configured
394 with a SYNC signal embedded into its base clock frequency.
395 -
396 name: esync-frequency-supported
397 type: nest
398 multi-attr: true
399 nested-attributes: frequency-range
400 doc: |
401 If provided a pin is capable of embedding a SYNC signal (within given
402 range) into its base frequency signal.
403 -
404 name: esync-pulse
405 type: u32
406 doc: |
407 A ratio of high to low state of a SYNC signal pulse embedded
408 into base clock frequency. Value is in percents.
409 -
410 name: pin-parent-device
411 subset-of: pin
412 attributes:
413 -
414 name: parent-id
415 -
416 name: direction
417 -
418 name: prio
419 -
420 name: state
421 -
422 name: phase-offset
423 -
424 name: pin-parent-pin
425 subset-of: pin
426 attributes:
427 -
428 name: parent-id
429 -
430 name: state
431 -
432 name: frequency-range
433 subset-of: pin
434 attributes:
435 -
436 name: frequency-min
437 -
438 name: frequency-max
440 operations:
441 enum-name: dpll_cmd
442 list:
443 -
444 name: device-id-get
445 doc: |
446 Get id of dpll device that matches given attributes
447 attribute-set: dpll
448 flags: [ admin-perm ]
450 do:
451 pre: dpll-lock-doit
452 post: dpll-unlock-doit
453 request:
454 attributes:
455 - module-name
456 - clock-id
457 - type
458 reply:
459 attributes:
460 - id
462 -
463 name: device-get
464 doc: |
465 Get list of DPLL devices (dump) or attributes of a single dpll device
466 attribute-set: dpll
467 flags: [ admin-perm ]
469 do:
470 pre: dpll-pre-doit
471 post: dpll-post-doit
472 request:
473 attributes:
474 - id
475 reply: &dev-attrs
476 attributes:
477 - id
478 - module-name
479 - mode
480 - mode-supported
481 - lock-status
482 - lock-status-error
483 - temp
484 - clock-id
485 - type
487 dump:
488 reply: *dev-attrs
490 -
491 name: device-set
492 doc: Set attributes for a DPLL device
493 attribute-set: dpll
494 flags: [ admin-perm ]
496 do:
497 pre: dpll-pre-doit
498 post: dpll-post-doit
499 request:
500 attributes:
501 - id
502 -
503 name: device-create-ntf
504 doc: Notification about device appearing
505 notify: device-get
506 mcgrp: monitor
507 -
508 name: device-delete-ntf
509 doc: Notification about device disappearing
510 notify: device-get
511 mcgrp: monitor
512 -
513 name: device-change-ntf
514 doc: Notification about device configuration being changed
515 notify: device-get
516 mcgrp: monitor
517 -
518 name: pin-id-get
519 doc: |
520 Get id of a pin that matches given attributes
521 attribute-set: pin
522 flags: [ admin-perm ]
524 do:
525 pre: dpll-lock-doit
526 post: dpll-unlock-doit
527 request:
528 attributes:
529 - module-name
530 - clock-id
531 - board-label
532 - panel-label
533 - package-label
534 - type
535 reply:
536 attributes:
537 - id
539 -
540 name: pin-get
541 doc: |
542 Get list of pins and its attributes.
544 - dump request without any attributes given - list all the pins in the
545 system
546 - dump request with target dpll - list all the pins registered with
547 a given dpll device
548 - do request with target dpll and target pin - single pin attributes
549 attribute-set: pin
550 flags: [ admin-perm ]
552 do:
553 pre: dpll-pin-pre-doit
554 post: dpll-pin-post-doit
555 request:
556 attributes:
557 - id
558 reply: &pin-attrs
559 attributes:
560 - id
561 - board-label
562 - panel-label
563 - package-label
564 - type
565 - frequency
566 - frequency-supported
567 - capabilities
568 - parent-device
569 - parent-pin
570 - phase-adjust-min
571 - phase-adjust-max
572 - phase-adjust
573 - fractional-frequency-offset
574 - esync-frequency
575 - esync-frequency-supported
576 - esync-pulse
578 dump:
579 request:
580 attributes:
581 - id
582 reply: *pin-attrs
584 -
585 name: pin-set
586 doc: Set attributes of a target pin
587 attribute-set: pin
588 flags: [ admin-perm ]
590 do:
591 pre: dpll-pin-pre-doit
592 post: dpll-pin-post-doit
593 request:
594 attributes:
595 - id
596 - frequency
597 - direction
598 - prio
599 - state
600 - parent-device
601 - parent-pin
602 - phase-adjust
603 - esync-frequency
604 -
605 name: pin-create-ntf
606 doc: Notification about pin appearing
607 notify: pin-get
608 mcgrp: monitor
609 -
610 name: pin-delete-ntf
611 doc: Notification about pin disappearing
612 notify: pin-get
613 mcgrp: monitor
614 -
615 name: pin-change-ntf
616 doc: Notification about pin configuration being changed
617 notify: pin-get
618 mcgrp: monitor
620 mcast-groups:
621 list:
622 -
623 name: monitor