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: const 245 name: pin-measured-frequency-divider 246 value: 1000 247 doc: | 248 pin measured frequency divider allows userspace to calculate 249 a value of measured input frequency as a fractional value with 250 three digit decimal precision (millihertz). 251 Value of (DPLL_A_PIN_MEASURED_FREQUENCY / 252 DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is an integer part of 253 a measured frequency value. 254 Value of (DPLL_A_PIN_MEASURED_FREQUENCY % 255 DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is a fractional part of 256 a measured frequency value. 257 - 258 type: enum 259 name: feature-state 260 doc: | 261 Allow control (enable/disable) and status checking over features. 262 entries: 263 - 264 name: disable 265 doc: | 266 feature shall be disabled 267 - 268 name: enable 269 doc: | 270 feature shall be enabled 271 272attribute-sets: 273 - 274 name: dpll 275 enum-name: dpll_a 276 attributes: 277 - 278 name: id 279 type: u32 280 - 281 name: module-name 282 type: string 283 - 284 name: pad 285 type: pad 286 - 287 name: clock-id 288 type: u64 289 - 290 name: mode 291 type: u32 292 enum: mode 293 - 294 name: mode-supported 295 type: u32 296 enum: mode 297 multi-attr: true 298 - 299 name: lock-status 300 type: u32 301 enum: lock-status 302 - 303 name: temp 304 type: s32 305 - 306 name: type 307 type: u32 308 enum: type 309 - 310 name: lock-status-error 311 type: u32 312 enum: lock-status-error 313 - 314 name: clock-quality-level 315 type: u32 316 enum: clock-quality-level 317 multi-attr: true 318 doc: | 319 Level of quality of a clock device. This mainly applies when 320 the dpll lock-status is DPLL_LOCK_STATUS_HOLDOVER. This could 321 be put to message multiple times to indicate possible parallel 322 quality levels (e.g. one specified by ITU option 1 and another 323 one specified by option 2). 324 - 325 name: phase-offset-monitor 326 type: u32 327 enum: feature-state 328 doc: Receive or request state of phase offset monitor feature. 329 If enabled, dpll device shall monitor and notify all currently 330 available inputs for changes of their phase offset against the 331 dpll device. 332 - 333 name: phase-offset-avg-factor 334 type: u32 335 doc: Averaging factor applied to calculation of reported phase offset. 336 - 337 name: frequency-monitor 338 type: u32 339 enum: feature-state 340 doc: Current or desired state of the frequency monitor feature. 341 If enabled, dpll device shall measure all currently available 342 inputs for their actual input frequency. 343 - 344 name: pin 345 enum-name: dpll_a_pin 346 attributes: 347 - 348 name: id 349 type: u32 350 - 351 name: parent-id 352 type: u32 353 - 354 name: module-name 355 type: string 356 - 357 name: pad 358 type: pad 359 - 360 name: clock-id 361 type: u64 362 - 363 name: board-label 364 type: string 365 - 366 name: panel-label 367 type: string 368 - 369 name: package-label 370 type: string 371 - 372 name: type 373 type: u32 374 enum: pin-type 375 - 376 name: direction 377 type: u32 378 enum: pin-direction 379 - 380 name: frequency 381 type: u64 382 - 383 name: frequency-supported 384 type: nest 385 multi-attr: true 386 nested-attributes: frequency-range 387 - 388 name: frequency-min 389 type: u64 390 - 391 name: frequency-max 392 type: u64 393 - 394 name: prio 395 type: u32 396 - 397 name: state 398 type: u32 399 enum: pin-state 400 - 401 name: capabilities 402 type: u32 403 enum: pin-capabilities 404 - 405 name: parent-device 406 type: nest 407 multi-attr: true 408 nested-attributes: pin-parent-device 409 - 410 name: parent-pin 411 type: nest 412 multi-attr: true 413 nested-attributes: pin-parent-pin 414 - 415 name: phase-adjust-min 416 type: s32 417 - 418 name: phase-adjust-max 419 type: s32 420 - 421 name: phase-adjust 422 type: s32 423 - 424 name: phase-offset 425 type: s64 426 - 427 name: fractional-frequency-offset 428 type: sint 429 doc: | 430 The FFO (Fractional Frequency Offset) between the RX and TX 431 symbol rate on the media associated with the pin: 432 (rx_frequency-tx_frequency)/rx_frequency 433 Value is in PPM (parts per million). 434 This may be implemented for example for pin of type 435 PIN_TYPE_SYNCE_ETH_PORT. 436 - 437 name: esync-frequency 438 type: u64 439 doc: | 440 Frequency of Embedded SYNC signal. If provided, the pin is configured 441 with a SYNC signal embedded into its base clock frequency. 442 - 443 name: esync-frequency-supported 444 type: nest 445 multi-attr: true 446 nested-attributes: frequency-range 447 doc: | 448 If provided a pin is capable of embedding a SYNC signal (within given 449 range) into its base frequency signal. 450 - 451 name: esync-pulse 452 type: u32 453 doc: | 454 A ratio of high to low state of a SYNC signal pulse embedded 455 into base clock frequency. Value is in percents. 456 - 457 name: reference-sync 458 type: nest 459 multi-attr: true 460 nested-attributes: reference-sync 461 doc: | 462 Capable pin provides list of pins that can be bound to create a 463 reference-sync pin pair. 464 - 465 name: phase-adjust-gran 466 type: u32 467 doc: | 468 Granularity of phase adjustment, in picoseconds. The value of 469 phase adjustment must be a multiple of this granularity. 470 - 471 name: fractional-frequency-offset-ppt 472 type: sint 473 doc: | 474 The FFO (Fractional Frequency Offset) of the pin with respect to 475 the nominal frequency. 476 Value = (frequency_measured - frequency_nominal) / frequency_nominal 477 Value is in PPT (parts per trillion, 10^-12). 478 Note: This attribute provides higher resolution than the standard 479 fractional-frequency-offset (which is in PPM). 480 - 481 name: measured-frequency 482 type: u64 483 doc: | 484 The measured frequency of the input pin in millihertz (mHz). 485 Value of (DPLL_A_PIN_MEASURED_FREQUENCY / 486 DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is an integer part (Hz) 487 of a measured frequency value. 488 Value of (DPLL_A_PIN_MEASURED_FREQUENCY % 489 DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is a fractional part 490 of a measured frequency value. 491 492 - 493 name: pin-parent-device 494 subset-of: pin 495 attributes: 496 - 497 name: parent-id 498 - 499 name: direction 500 - 501 name: prio 502 - 503 name: state 504 - 505 name: phase-offset 506 - 507 name: pin-parent-pin 508 subset-of: pin 509 attributes: 510 - 511 name: parent-id 512 - 513 name: state 514 - 515 name: frequency-range 516 subset-of: pin 517 attributes: 518 - 519 name: frequency-min 520 - 521 name: frequency-max 522 - 523 name: reference-sync 524 subset-of: pin 525 attributes: 526 - 527 name: id 528 - 529 name: state 530 531operations: 532 enum-name: dpll_cmd 533 list: 534 - 535 name: device-id-get 536 doc: | 537 Get id of dpll device that matches given attributes 538 attribute-set: dpll 539 flags: [admin-perm] 540 541 do: 542 pre: dpll-lock-doit 543 post: dpll-unlock-doit 544 request: 545 attributes: 546 - module-name 547 - clock-id 548 - type 549 reply: 550 attributes: 551 - id 552 553 - 554 name: device-get 555 doc: | 556 Get list of DPLL devices (dump) or attributes of a single dpll device 557 attribute-set: dpll 558 flags: [admin-perm] 559 560 do: 561 pre: dpll-pre-doit 562 post: dpll-post-doit 563 request: 564 attributes: 565 - id 566 reply: &dev-attrs 567 attributes: 568 - id 569 - module-name 570 - mode 571 - mode-supported 572 - lock-status 573 - lock-status-error 574 - temp 575 - clock-id 576 - type 577 - phase-offset-monitor 578 - phase-offset-avg-factor 579 - frequency-monitor 580 581 dump: 582 reply: *dev-attrs 583 584 - 585 name: device-set 586 doc: Set attributes for a DPLL device 587 attribute-set: dpll 588 flags: [admin-perm] 589 590 do: 591 pre: dpll-pre-doit 592 post: dpll-post-doit 593 request: 594 attributes: 595 - id 596 - mode 597 - phase-offset-monitor 598 - phase-offset-avg-factor 599 - frequency-monitor 600 - 601 name: device-create-ntf 602 doc: Notification about device appearing 603 notify: device-get 604 mcgrp: monitor 605 - 606 name: device-delete-ntf 607 doc: Notification about device disappearing 608 notify: device-get 609 mcgrp: monitor 610 - 611 name: device-change-ntf 612 doc: Notification about device configuration being changed 613 notify: device-get 614 mcgrp: monitor 615 - 616 name: pin-id-get 617 doc: | 618 Get id of a pin that matches given attributes 619 attribute-set: pin 620 flags: [admin-perm] 621 622 do: 623 pre: dpll-lock-doit 624 post: dpll-unlock-doit 625 request: 626 attributes: 627 - module-name 628 - clock-id 629 - board-label 630 - panel-label 631 - package-label 632 - type 633 reply: 634 attributes: 635 - id 636 637 - 638 name: pin-get 639 doc: | 640 Get list of pins and its attributes. 641 642 - dump request without any attributes given - list all the pins in the 643 system 644 - dump request with target dpll - list all the pins registered with 645 a given dpll device 646 - do request with target dpll and target pin - single pin attributes 647 attribute-set: pin 648 flags: [admin-perm] 649 650 do: 651 pre: dpll-pin-pre-doit 652 post: dpll-pin-post-doit 653 request: 654 attributes: 655 - id 656 reply: &pin-attrs 657 attributes: 658 - id 659 - module-name 660 - clock-id 661 - board-label 662 - panel-label 663 - package-label 664 - type 665 - frequency 666 - frequency-supported 667 - capabilities 668 - parent-device 669 - parent-pin 670 - phase-adjust-gran 671 - phase-adjust-min 672 - phase-adjust-max 673 - phase-adjust 674 - fractional-frequency-offset 675 - fractional-frequency-offset-ppt 676 - esync-frequency 677 - esync-frequency-supported 678 - esync-pulse 679 - reference-sync 680 - measured-frequency 681 682 dump: 683 request: 684 attributes: 685 - id 686 reply: *pin-attrs 687 688 - 689 name: pin-set 690 doc: Set attributes of a target pin 691 attribute-set: pin 692 flags: [admin-perm] 693 694 do: 695 pre: dpll-pin-pre-doit 696 post: dpll-pin-post-doit 697 request: 698 attributes: 699 - id 700 - frequency 701 - direction 702 - prio 703 - state 704 - parent-device 705 - parent-pin 706 - phase-adjust 707 - esync-frequency 708 - reference-sync 709 - 710 name: pin-create-ntf 711 doc: Notification about pin appearing 712 notify: pin-get 713 mcgrp: monitor 714 - 715 name: pin-delete-ntf 716 doc: Notification about pin disappearing 717 notify: pin-get 718 mcgrp: monitor 719 - 720 name: pin-change-ntf 721 doc: Notification about pin configuration being changed 722 notify: pin-get 723 mcgrp: monitor 724 725mcast-groups: 726 list: 727 - 728 name: monitor 729