1 # SPDX-License-Identifier: ((GPL-2.0 WITH Linu 1 # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
2 2
3 name: dpll 3 name: dpll
4 4
5 doc: DPLL subsystem. 5 doc: DPLL subsystem.
6 6
7 definitions: 7 definitions:
8 - 8 -
9 type: enum 9 type: enum
10 name: mode 10 name: mode
11 doc: | 11 doc: |
12 working modes a dpll can support, differ 12 working modes a dpll can support, differentiates if and how dpll selects
13 one of its inputs to syntonize with it, 13 one of its inputs to syntonize with it, valid values for DPLL_A_MODE
14 attribute 14 attribute
15 entries: 15 entries:
16 - 16 -
17 name: manual 17 name: manual
18 doc: input can be only selected by sen 18 doc: input can be only selected by sending a request to dpll
19 value: 1 19 value: 1
20 - 20 -
21 name: automatic 21 name: automatic
22 doc: highest prio input pin auto selec 22 doc: highest prio input pin auto selected by dpll
23 render-max: true 23 render-max: true
24 - 24 -
25 type: enum 25 type: enum
26 name: lock-status 26 name: lock-status
27 doc: | 27 doc: |
28 provides information of dpll device lock 28 provides information of dpll device lock status, valid values for
29 DPLL_A_LOCK_STATUS attribute 29 DPLL_A_LOCK_STATUS attribute
30 entries: 30 entries:
31 - 31 -
32 name: unlocked 32 name: unlocked
33 doc: | 33 doc: |
34 dpll was not yet locked to any valid 34 dpll was not yet locked to any valid input (or forced by setting
35 DPLL_A_MODE to DPLL_MODE_DETACHED) 35 DPLL_A_MODE to DPLL_MODE_DETACHED)
36 value: 1 36 value: 1
37 - 37 -
38 name: locked 38 name: locked
39 doc: | 39 doc: |
40 dpll is locked to a valid signal, bu 40 dpll is locked to a valid signal, but no holdover available
41 - 41 -
42 name: locked-ho-acq 42 name: locked-ho-acq
43 doc: | 43 doc: |
44 dpll is locked and holdover acquired 44 dpll is locked and holdover acquired
45 - 45 -
46 name: holdover 46 name: holdover
47 doc: | 47 doc: |
48 dpll is in holdover state - lost a v 48 dpll is in holdover state - lost a valid lock or was forced
49 by disconnecting all the pins (latte 49 by disconnecting all the pins (latter possible only
50 when dpll lock-state was already DPL 50 when dpll lock-state was already DPLL_LOCK_STATUS_LOCKED_HO_ACQ,
51 if dpll lock-state was not DPLL_LOCK 51 if dpll lock-state was not DPLL_LOCK_STATUS_LOCKED_HO_ACQ, the
52 dpll's lock-state shall remain DPLL_ 52 dpll's lock-state shall remain DPLL_LOCK_STATUS_UNLOCKED)
53 render-max: true 53 render-max: true
54 - 54 -
55 type: enum <<
56 name: lock-status-error <<
57 doc: | <<
58 if previous status change was done due t <<
59 information of dpll device lock status e <<
60 Valid values for DPLL_A_LOCK_STATUS_ERRO <<
61 entries: <<
62 - <<
63 name: none <<
64 doc: | <<
65 dpll device lock status was changed <<
66 value: 1 <<
67 - <<
68 name: undefined <<
69 doc: | <<
70 dpll device lock status was changed <<
71 Driver fills this value up in case i <<
72 to obtain suitable exact error type. <<
73 - <<
74 name: media-down <<
75 doc: | <<
76 dpll device lock status was changed <<
77 media got down. <<
78 This may happen for example if dpll <<
79 locked on an input pin of type PIN_T <<
80 - <<
81 name: fractional-frequency-offset-too- <<
82 doc: | <<
83 the FFO (Fractional Frequency Offset <<
84 symbol rate on the media got too hig <<
85 This may happen for example if dpll <<
86 locked on an input pin of type PIN_T <<
87 render-max: true <<
88 - <<
89 type: const 55 type: const
90 name: temp-divider 56 name: temp-divider
91 value: 1000 57 value: 1000
92 doc: | 58 doc: |
93 temperature divider allowing userspace t 59 temperature divider allowing userspace to calculate the
94 temperature as float with three digit de 60 temperature as float with three digit decimal precision.
95 Value of (DPLL_A_TEMP / DPLL_TEMP_DIVIDE 61 Value of (DPLL_A_TEMP / DPLL_TEMP_DIVIDER) is integer part of
96 temperature value. 62 temperature value.
97 Value of (DPLL_A_TEMP % DPLL_TEMP_DIVIDE 63 Value of (DPLL_A_TEMP % DPLL_TEMP_DIVIDER) is fractional part of
98 temperature value. 64 temperature value.
99 - 65 -
100 type: enum 66 type: enum
101 name: type 67 name: type
102 doc: type of dpll, valid values for DPLL_A 68 doc: type of dpll, valid values for DPLL_A_TYPE attribute
103 entries: 69 entries:
104 - 70 -
105 name: pps 71 name: pps
106 doc: dpll produces Pulse-Per-Second si 72 doc: dpll produces Pulse-Per-Second signal
107 value: 1 73 value: 1
108 - 74 -
109 name: eec 75 name: eec
110 doc: dpll drives the Ethernet Equipmen 76 doc: dpll drives the Ethernet Equipment Clock
111 render-max: true 77 render-max: true
112 - 78 -
113 type: enum 79 type: enum
114 name: pin-type 80 name: pin-type
115 doc: | 81 doc: |
116 defines possible types of a pin, valid v 82 defines possible types of a pin, valid values for DPLL_A_PIN_TYPE
117 attribute 83 attribute
118 entries: 84 entries:
119 - 85 -
120 name: mux 86 name: mux
121 doc: aggregates another layer of selec 87 doc: aggregates another layer of selectable pins
122 value: 1 88 value: 1
123 - 89 -
124 name: ext 90 name: ext
125 doc: external input 91 doc: external input
126 - 92 -
127 name: synce-eth-port 93 name: synce-eth-port
128 doc: ethernet port PHY's recovered clo 94 doc: ethernet port PHY's recovered clock
129 - 95 -
130 name: int-oscillator 96 name: int-oscillator
131 doc: device internal oscillator 97 doc: device internal oscillator
132 - 98 -
133 name: gnss 99 name: gnss
134 doc: GNSS recovered clock 100 doc: GNSS recovered clock
135 render-max: true 101 render-max: true
136 - 102 -
137 type: enum 103 type: enum
138 name: pin-direction 104 name: pin-direction
139 doc: | 105 doc: |
140 defines possible direction of a pin, val 106 defines possible direction of a pin, valid values for
141 DPLL_A_PIN_DIRECTION attribute 107 DPLL_A_PIN_DIRECTION attribute
142 entries: 108 entries:
143 - 109 -
144 name: input 110 name: input
145 doc: pin used as a input of a signal 111 doc: pin used as a input of a signal
146 value: 1 112 value: 1
147 - 113 -
148 name: output 114 name: output
149 doc: pin used to output the signal 115 doc: pin used to output the signal
150 render-max: true 116 render-max: true
151 - 117 -
152 type: const 118 type: const
153 name: pin-frequency-1-hz 119 name: pin-frequency-1-hz
154 value: 1 120 value: 1
155 - 121 -
156 type: const 122 type: const
157 name: pin-frequency-10-khz 123 name: pin-frequency-10-khz
158 value: 10000 124 value: 10000
159 - 125 -
160 type: const 126 type: const
161 name: pin-frequency-77_5-khz 127 name: pin-frequency-77_5-khz
162 value: 77500 128 value: 77500
163 - 129 -
164 type: const 130 type: const
165 name: pin-frequency-10-mhz 131 name: pin-frequency-10-mhz
166 value: 10000000 132 value: 10000000
167 - 133 -
168 type: enum 134 type: enum
169 name: pin-state 135 name: pin-state
170 doc: | 136 doc: |
171 defines possible states of a pin, valid 137 defines possible states of a pin, valid values for
172 DPLL_A_PIN_STATE attribute 138 DPLL_A_PIN_STATE attribute
173 entries: 139 entries:
174 - 140 -
175 name: connected 141 name: connected
176 doc: pin connected, active input of ph 142 doc: pin connected, active input of phase locked loop
177 value: 1 143 value: 1
178 - 144 -
179 name: disconnected 145 name: disconnected
180 doc: pin disconnected, not considered 146 doc: pin disconnected, not considered as a valid input
181 - 147 -
182 name: selectable 148 name: selectable
183 doc: pin enabled for automatic input s 149 doc: pin enabled for automatic input selection
184 render-max: true 150 render-max: true
185 - 151 -
186 type: flags 152 type: flags
187 name: pin-capabilities 153 name: pin-capabilities
188 doc: | 154 doc: |
189 defines possible capabilities of a pin, 155 defines possible capabilities of a pin, valid flags on
190 DPLL_A_PIN_CAPABILITIES attribute 156 DPLL_A_PIN_CAPABILITIES attribute
191 entries: 157 entries:
192 - 158 -
193 name: direction-can-change 159 name: direction-can-change
194 doc: pin direction can be changed 160 doc: pin direction can be changed
195 - 161 -
196 name: priority-can-change 162 name: priority-can-change
197 doc: pin priority can be changed 163 doc: pin priority can be changed
198 - 164 -
199 name: state-can-change 165 name: state-can-change
200 doc: pin state can be changed 166 doc: pin state can be changed
201 - 167 -
202 type: const 168 type: const
203 name: phase-offset-divider 169 name: phase-offset-divider
204 value: 1000 170 value: 1000
205 doc: | 171 doc: |
206 phase offset divider allows userspace to 172 phase offset divider allows userspace to calculate a value of
207 measured signal phase difference between 173 measured signal phase difference between a pin and dpll device
208 as a fractional value with three digit d 174 as a fractional value with three digit decimal precision.
209 Value of (DPLL_A_PHASE_OFFSET / DPLL_PHA 175 Value of (DPLL_A_PHASE_OFFSET / DPLL_PHASE_OFFSET_DIVIDER) is an
210 integer part of a measured phase offset 176 integer part of a measured phase offset value.
211 Value of (DPLL_A_PHASE_OFFSET % DPLL_PHA 177 Value of (DPLL_A_PHASE_OFFSET % DPLL_PHASE_OFFSET_DIVIDER) is a
212 fractional part of a measured phase offs 178 fractional part of a measured phase offset value.
213 179
214 attribute-sets: 180 attribute-sets:
215 - 181 -
216 name: dpll 182 name: dpll
217 enum-name: dpll_a 183 enum-name: dpll_a
218 attributes: 184 attributes:
219 - 185 -
220 name: id 186 name: id
221 type: u32 187 type: u32
222 - 188 -
223 name: module-name 189 name: module-name
224 type: string 190 type: string
225 - 191 -
226 name: pad 192 name: pad
227 type: pad 193 type: pad
228 - 194 -
229 name: clock-id 195 name: clock-id
230 type: u64 196 type: u64
231 - 197 -
232 name: mode 198 name: mode
233 type: u32 199 type: u32
234 enum: mode 200 enum: mode
235 - 201 -
236 name: mode-supported 202 name: mode-supported
237 type: u32 203 type: u32
238 enum: mode 204 enum: mode
239 multi-attr: true 205 multi-attr: true
240 - 206 -
241 name: lock-status 207 name: lock-status
242 type: u32 208 type: u32
243 enum: lock-status 209 enum: lock-status
244 - 210 -
245 name: temp 211 name: temp
246 type: s32 212 type: s32
247 - 213 -
248 name: type 214 name: type
249 type: u32 215 type: u32
250 enum: type 216 enum: type
251 - <<
252 name: lock-status-error <<
253 type: u32 <<
254 enum: lock-status-error <<
255 - 217 -
256 name: pin 218 name: pin
257 enum-name: dpll_a_pin 219 enum-name: dpll_a_pin
258 attributes: 220 attributes:
259 - 221 -
260 name: id 222 name: id
261 type: u32 223 type: u32
262 - 224 -
263 name: parent-id 225 name: parent-id
264 type: u32 226 type: u32
265 - 227 -
266 name: module-name 228 name: module-name
267 type: string 229 type: string
268 - 230 -
269 name: pad 231 name: pad
270 type: pad 232 type: pad
271 - 233 -
272 name: clock-id 234 name: clock-id
273 type: u64 235 type: u64
274 - 236 -
275 name: board-label 237 name: board-label
276 type: string 238 type: string
277 - 239 -
278 name: panel-label 240 name: panel-label
279 type: string 241 type: string
280 - 242 -
281 name: package-label 243 name: package-label
282 type: string 244 type: string
283 - 245 -
284 name: type 246 name: type
285 type: u32 247 type: u32
286 enum: pin-type 248 enum: pin-type
287 - 249 -
288 name: direction 250 name: direction
289 type: u32 251 type: u32
290 enum: pin-direction 252 enum: pin-direction
291 - 253 -
292 name: frequency 254 name: frequency
293 type: u64 255 type: u64
294 - 256 -
295 name: frequency-supported 257 name: frequency-supported
296 type: nest 258 type: nest
297 multi-attr: true 259 multi-attr: true
298 nested-attributes: frequency-range 260 nested-attributes: frequency-range
299 - 261 -
300 name: frequency-min 262 name: frequency-min
301 type: u64 263 type: u64
302 - 264 -
303 name: frequency-max 265 name: frequency-max
304 type: u64 266 type: u64
305 - 267 -
306 name: prio 268 name: prio
307 type: u32 269 type: u32
308 - 270 -
309 name: state 271 name: state
310 type: u32 272 type: u32
311 enum: pin-state 273 enum: pin-state
312 - 274 -
313 name: capabilities 275 name: capabilities
314 type: u32 276 type: u32
315 enum: pin-capabilities 277 enum: pin-capabilities
316 - 278 -
317 name: parent-device 279 name: parent-device
318 type: nest 280 type: nest
319 multi-attr: true 281 multi-attr: true
320 nested-attributes: pin-parent-device 282 nested-attributes: pin-parent-device
321 - 283 -
322 name: parent-pin 284 name: parent-pin
323 type: nest 285 type: nest
324 multi-attr: true 286 multi-attr: true
325 nested-attributes: pin-parent-pin 287 nested-attributes: pin-parent-pin
326 - 288 -
327 name: phase-adjust-min 289 name: phase-adjust-min
328 type: s32 290 type: s32
329 - 291 -
330 name: phase-adjust-max 292 name: phase-adjust-max
331 type: s32 293 type: s32
332 - 294 -
333 name: phase-adjust 295 name: phase-adjust
334 type: s32 296 type: s32
335 - 297 -
336 name: phase-offset 298 name: phase-offset
337 type: s64 299 type: s64
338 - <<
339 name: fractional-frequency-offset <<
340 type: sint <<
341 doc: | <<
342 The FFO (Fractional Frequency Offset <<
343 symbol rate on the media associated <<
344 (rx_frequency-tx_frequency)/rx_frequ <<
345 Value is in PPM (parts per million). <<
346 This may be implemented for example <<
347 PIN_TYPE_SYNCE_ETH_PORT. <<
348 - 300 -
349 name: pin-parent-device 301 name: pin-parent-device
350 subset-of: pin 302 subset-of: pin
351 attributes: 303 attributes:
352 - 304 -
353 name: parent-id 305 name: parent-id
354 - 306 -
355 name: direction 307 name: direction
356 - 308 -
357 name: prio 309 name: prio
358 - 310 -
359 name: state 311 name: state
360 - 312 -
361 name: phase-offset 313 name: phase-offset
362 - 314 -
363 name: pin-parent-pin 315 name: pin-parent-pin
364 subset-of: pin 316 subset-of: pin
365 attributes: 317 attributes:
366 - 318 -
367 name: parent-id 319 name: parent-id
368 - 320 -
369 name: state 321 name: state
370 - 322 -
371 name: frequency-range 323 name: frequency-range
372 subset-of: pin 324 subset-of: pin
373 attributes: 325 attributes:
374 - 326 -
375 name: frequency-min 327 name: frequency-min
376 - 328 -
377 name: frequency-max 329 name: frequency-max
378 330
379 operations: 331 operations:
380 enum-name: dpll_cmd 332 enum-name: dpll_cmd
381 list: 333 list:
382 - 334 -
383 name: device-id-get 335 name: device-id-get
384 doc: | 336 doc: |
385 Get id of dpll device that matches giv 337 Get id of dpll device that matches given attributes
386 attribute-set: dpll 338 attribute-set: dpll
387 flags: [ admin-perm ] 339 flags: [ admin-perm ]
388 340
389 do: 341 do:
390 pre: dpll-lock-doit 342 pre: dpll-lock-doit
391 post: dpll-unlock-doit 343 post: dpll-unlock-doit
392 request: 344 request:
393 attributes: 345 attributes:
394 - module-name 346 - module-name
395 - clock-id 347 - clock-id
396 - type 348 - type
397 reply: 349 reply:
398 attributes: 350 attributes:
399 - id 351 - id
400 352
401 - 353 -
402 name: device-get 354 name: device-get
403 doc: | 355 doc: |
404 Get list of DPLL devices (dump) or att 356 Get list of DPLL devices (dump) or attributes of a single dpll device
405 attribute-set: dpll 357 attribute-set: dpll
406 flags: [ admin-perm ] 358 flags: [ admin-perm ]
407 359
408 do: 360 do:
409 pre: dpll-pre-doit 361 pre: dpll-pre-doit
410 post: dpll-post-doit 362 post: dpll-post-doit
411 request: 363 request:
412 attributes: 364 attributes:
413 - id 365 - id
414 reply: &dev-attrs 366 reply: &dev-attrs
415 attributes: 367 attributes:
416 - id 368 - id
417 - module-name 369 - module-name
418 - mode 370 - mode
419 - mode-supported 371 - mode-supported
420 - lock-status 372 - lock-status
421 - lock-status-error <<
422 - temp 373 - temp
423 - clock-id 374 - clock-id
424 - type 375 - type
425 376
426 dump: 377 dump:
427 reply: *dev-attrs 378 reply: *dev-attrs
428 379
429 - 380 -
430 name: device-set 381 name: device-set
431 doc: Set attributes for a DPLL device 382 doc: Set attributes for a DPLL device
432 attribute-set: dpll 383 attribute-set: dpll
433 flags: [ admin-perm ] 384 flags: [ admin-perm ]
434 385
435 do: 386 do:
436 pre: dpll-pre-doit 387 pre: dpll-pre-doit
437 post: dpll-post-doit 388 post: dpll-post-doit
438 request: 389 request:
439 attributes: 390 attributes:
440 - id 391 - id
441 - 392 -
442 name: device-create-ntf 393 name: device-create-ntf
443 doc: Notification about device appearing 394 doc: Notification about device appearing
444 notify: device-get 395 notify: device-get
445 mcgrp: monitor 396 mcgrp: monitor
446 - 397 -
447 name: device-delete-ntf 398 name: device-delete-ntf
448 doc: Notification about device disappear 399 doc: Notification about device disappearing
449 notify: device-get 400 notify: device-get
450 mcgrp: monitor 401 mcgrp: monitor
451 - 402 -
452 name: device-change-ntf 403 name: device-change-ntf
453 doc: Notification about device configura 404 doc: Notification about device configuration being changed
454 notify: device-get 405 notify: device-get
455 mcgrp: monitor 406 mcgrp: monitor
456 - 407 -
457 name: pin-id-get 408 name: pin-id-get
458 doc: | 409 doc: |
459 Get id of a pin that matches given att 410 Get id of a pin that matches given attributes
460 attribute-set: pin 411 attribute-set: pin
461 flags: [ admin-perm ] 412 flags: [ admin-perm ]
462 413
463 do: 414 do:
464 pre: dpll-lock-doit 415 pre: dpll-lock-doit
465 post: dpll-unlock-doit 416 post: dpll-unlock-doit
466 request: 417 request:
467 attributes: 418 attributes:
468 - module-name 419 - module-name
469 - clock-id 420 - clock-id
470 - board-label 421 - board-label
471 - panel-label 422 - panel-label
472 - package-label 423 - package-label
473 - type 424 - type
474 reply: 425 reply:
475 attributes: 426 attributes:
476 - id 427 - id
477 428
478 - 429 -
479 name: pin-get 430 name: pin-get
480 doc: | 431 doc: |
481 Get list of pins and its attributes. 432 Get list of pins and its attributes.
482 <<
483 - dump request without any attributes 433 - dump request without any attributes given - list all the pins in the
484 system 434 system
485 - dump request with target dpll - list 435 - dump request with target dpll - list all the pins registered with
486 a given dpll device 436 a given dpll device
487 - do request with target dpll and targ 437 - do request with target dpll and target pin - single pin attributes
488 attribute-set: pin 438 attribute-set: pin
489 flags: [ admin-perm ] 439 flags: [ admin-perm ]
490 440
491 do: 441 do:
492 pre: dpll-pin-pre-doit 442 pre: dpll-pin-pre-doit
493 post: dpll-pin-post-doit 443 post: dpll-pin-post-doit
494 request: 444 request:
495 attributes: 445 attributes:
496 - id 446 - id
497 reply: &pin-attrs 447 reply: &pin-attrs
498 attributes: 448 attributes:
499 - id 449 - id
500 - board-label 450 - board-label
501 - panel-label 451 - panel-label
502 - package-label 452 - package-label
503 - type 453 - type
504 - frequency 454 - frequency
505 - frequency-supported 455 - frequency-supported
506 - capabilities 456 - capabilities
507 - parent-device 457 - parent-device
508 - parent-pin 458 - parent-pin
509 - phase-adjust-min 459 - phase-adjust-min
510 - phase-adjust-max 460 - phase-adjust-max
511 - phase-adjust 461 - phase-adjust
512 - fractional-frequency-offset <<
513 462
514 dump: 463 dump:
515 request: 464 request:
516 attributes: 465 attributes:
517 - id 466 - id
518 reply: *pin-attrs 467 reply: *pin-attrs
519 468
520 - 469 -
521 name: pin-set 470 name: pin-set
522 doc: Set attributes of a target pin 471 doc: Set attributes of a target pin
523 attribute-set: pin 472 attribute-set: pin
524 flags: [ admin-perm ] 473 flags: [ admin-perm ]
525 474
526 do: 475 do:
527 pre: dpll-pin-pre-doit 476 pre: dpll-pin-pre-doit
528 post: dpll-pin-post-doit 477 post: dpll-pin-post-doit
529 request: 478 request:
530 attributes: 479 attributes:
531 - id 480 - id
532 - frequency 481 - frequency
533 - direction 482 - direction
534 - prio 483 - prio
535 - state 484 - state
536 - parent-device 485 - parent-device
537 - parent-pin 486 - parent-pin
538 - phase-adjust 487 - phase-adjust
539 - 488 -
540 name: pin-create-ntf 489 name: pin-create-ntf
541 doc: Notification about pin appearing 490 doc: Notification about pin appearing
542 notify: pin-get 491 notify: pin-get
543 mcgrp: monitor 492 mcgrp: monitor
544 - 493 -
545 name: pin-delete-ntf 494 name: pin-delete-ntf
546 doc: Notification about pin disappearing 495 doc: Notification about pin disappearing
547 notify: pin-get 496 notify: pin-get
548 mcgrp: monitor 497 mcgrp: monitor
549 - 498 -
550 name: pin-change-ntf 499 name: pin-change-ntf
551 doc: Notification about pin configuratio 500 doc: Notification about pin configuration being changed
552 notify: pin-get 501 notify: pin-get
553 mcgrp: monitor 502 mcgrp: monitor
554 503
555 mcast-groups: 504 mcast-groups:
556 list: 505 list:
557 - 506 -
558 name: monitor 507 name: monitor
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.