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 - 142 name: generic 143 doc: generic dpll type for devices outside PPS/EEC classes 144 render-max: true 145 - 146 type: enum 147 name: pin-type 148 doc: | 149 defines possible types of a pin, valid values for DPLL_A_PIN_TYPE 150 attribute 151 entries: 152 - 153 name: mux 154 doc: aggregates another layer of selectable pins 155 value: 1 156 - 157 name: ext 158 doc: external input 159 - 160 name: synce-eth-port 161 doc: ethernet port PHY's recovered clock 162 - 163 name: int-oscillator 164 doc: device internal oscillator 165 - 166 name: gnss 167 doc: GNSS recovered clock 168 - 169 name: int-nco 170 doc: | 171 Device internal numerically controlled oscillator. 172 When connected as a DPLL input, the DPLL enters NCO mode 173 where the output frequency is adjusted by the host via 174 the PTP clock interface. 175 render-max: true 176 - 177 type: enum 178 name: pin-direction 179 doc: | 180 defines possible direction of a pin, valid values for 181 DPLL_A_PIN_DIRECTION attribute 182 entries: 183 - 184 name: input 185 doc: pin used as a input of a signal 186 value: 1 187 - 188 name: output 189 doc: pin used to output the signal 190 render-max: true 191 - 192 type: const 193 name: pin-frequency-1-hz 194 value: 1 195 - 196 type: const 197 name: pin-frequency-10-khz 198 value: 10000 199 - 200 type: const 201 name: pin-frequency-77-5-khz 202 value: 77500 203 - 204 type: const 205 name: pin-frequency-10-mhz 206 value: 10000000 207 - 208 type: enum 209 name: pin-state 210 doc: | 211 defines possible states of a pin, valid values for 212 DPLL_A_PIN_STATE attribute 213 entries: 214 - 215 name: connected 216 doc: pin connected, active input of phase locked loop 217 value: 1 218 - 219 name: disconnected 220 doc: pin disconnected, not considered as a valid input 221 - 222 name: selectable 223 doc: pin enabled for automatic input selection 224 render-max: true 225 - 226 type: enum 227 name: pin-operstate 228 doc: | 229 defines possible operational states of a pin with respect to its 230 parent DPLL device, valid values for DPLL_A_PIN_OPERSTATE attribute 231 entries: 232 - 233 name: active 234 doc: pin is qualified and actively used by the DPLL 235 value: 1 236 - 237 name: standby 238 doc: pin is qualified but not actively used by the DPLL 239 - 240 name: no-signal 241 doc: pin does not have a valid signal 242 - 243 name: qual-failed 244 doc: pin signal failed qualification (e.g. frequency or phase monitor) 245 render-max: true 246 - 247 type: flags 248 name: pin-capabilities 249 doc: | 250 defines possible capabilities of a pin, valid flags on 251 DPLL_A_PIN_CAPABILITIES attribute 252 entries: 253 - 254 name: direction-can-change 255 doc: pin direction can be changed 256 - 257 name: priority-can-change 258 doc: pin priority can be changed 259 - 260 name: state-can-change 261 doc: pin state can be changed 262 - 263 name: state-connected-override 264 doc: | 265 pin state can be set to connected regardless of current 266 DPLL device mode, overriding the active input selection. 267 Requires state-can-change to be set as well. 268 - 269 type: const 270 name: phase-offset-divider 271 value: 1000 272 doc: | 273 phase offset divider allows userspace to calculate a value of 274 measured signal phase difference between a pin and dpll device 275 as a fractional value with three digit decimal precision. 276 Value of (DPLL_A_PHASE_OFFSET / DPLL_PHASE_OFFSET_DIVIDER) is an 277 integer part of a measured phase offset value. 278 Value of (DPLL_A_PHASE_OFFSET % DPLL_PHASE_OFFSET_DIVIDER) is a 279 fractional part of a measured phase offset value. 280 - 281 type: const 282 name: pin-measured-frequency-divider 283 value: 1000 284 doc: | 285 pin measured frequency divider allows userspace to calculate 286 a value of measured input frequency as a fractional value with 287 three digit decimal precision (millihertz). 288 Value of (DPLL_A_PIN_MEASURED_FREQUENCY / 289 DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is an integer part of 290 a measured frequency value. 291 Value of (DPLL_A_PIN_MEASURED_FREQUENCY % 292 DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is a fractional part of 293 a measured frequency value. 294 - 295 type: enum 296 name: feature-state 297 doc: | 298 Allow control (enable/disable) and status checking over features. 299 entries: 300 - 301 name: disable 302 doc: | 303 feature shall be disabled 304 - 305 name: enable 306 doc: | 307 feature shall be enabled 308 309attribute-sets: 310 - 311 name: dpll 312 enum-name: dpll_a 313 attributes: 314 - 315 name: id 316 type: u32 317 - 318 name: module-name 319 type: string 320 - 321 name: pad 322 type: pad 323 - 324 name: clock-id 325 type: u64 326 - 327 name: mode 328 type: u32 329 enum: mode 330 - 331 name: mode-supported 332 type: u32 333 enum: mode 334 multi-attr: true 335 - 336 name: lock-status 337 type: u32 338 enum: lock-status 339 - 340 name: temp 341 type: s32 342 - 343 name: type 344 type: u32 345 enum: type 346 - 347 name: lock-status-error 348 type: u32 349 enum: lock-status-error 350 - 351 name: clock-quality-level 352 type: u32 353 enum: clock-quality-level 354 multi-attr: true 355 doc: | 356 Level of quality of a clock device. This mainly applies when 357 the dpll lock-status is DPLL_LOCK_STATUS_HOLDOVER. This could 358 be put to message multiple times to indicate possible parallel 359 quality levels (e.g. one specified by ITU option 1 and another 360 one specified by option 2). 361 - 362 name: phase-offset-monitor 363 type: u32 364 enum: feature-state 365 doc: Receive or request state of phase offset monitor feature. 366 If enabled, dpll device shall monitor and notify all currently 367 available inputs for changes of their phase offset against the 368 dpll device. 369 - 370 name: phase-offset-avg-factor 371 type: u32 372 doc: Averaging factor applied to calculation of reported phase offset. 373 - 374 name: frequency-monitor 375 type: u32 376 enum: feature-state 377 doc: Current or desired state of the frequency monitor feature. 378 If enabled, dpll device shall measure all currently available 379 inputs for their actual input frequency. 380 - 381 name: pin 382 enum-name: dpll_a_pin 383 attributes: 384 - 385 name: id 386 type: u32 387 - 388 name: parent-id 389 type: u32 390 - 391 name: module-name 392 type: string 393 - 394 name: pad 395 type: pad 396 - 397 name: clock-id 398 type: u64 399 - 400 name: board-label 401 type: string 402 - 403 name: panel-label 404 type: string 405 - 406 name: package-label 407 type: string 408 - 409 name: type 410 type: u32 411 enum: pin-type 412 - 413 name: direction 414 type: u32 415 enum: pin-direction 416 - 417 name: frequency 418 type: u64 419 - 420 name: frequency-supported 421 type: nest 422 multi-attr: true 423 nested-attributes: frequency-range 424 - 425 name: frequency-min 426 type: u64 427 - 428 name: frequency-max 429 type: u64 430 - 431 name: prio 432 type: u32 433 - 434 name: state 435 type: u32 436 enum: pin-state 437 - 438 name: capabilities 439 type: u32 440 enum: pin-capabilities 441 - 442 name: parent-device 443 type: nest 444 multi-attr: true 445 nested-attributes: pin-parent-device 446 - 447 name: parent-pin 448 type: nest 449 multi-attr: true 450 nested-attributes: pin-parent-pin 451 - 452 name: phase-adjust-min 453 type: s32 454 - 455 name: phase-adjust-max 456 type: s32 457 - 458 name: phase-adjust 459 type: s32 460 - 461 name: phase-offset 462 type: s64 463 - 464 name: fractional-frequency-offset 465 type: sint 466 doc: | 467 The FFO (Fractional Frequency Offset) of the pin. 468 At top level this represents the RX vs TX symbol rate 469 offset on the media associated with the pin. Inside 470 the pin-parent-device nest it represents the frequency 471 offset between the pin and its parent DPLL device. 472 For pins of type PIN_TYPE_INT_NCO this represents 473 the DPLL's current output frequency offset from its 474 nominal frequency. 475 Value is in PPM (parts per million). 476 This is a lower-precision version of 477 fractional-frequency-offset-ppt. 478 - 479 name: esync-frequency 480 type: u64 481 doc: | 482 Frequency of Embedded SYNC signal. If provided, the pin is configured 483 with a SYNC signal embedded into its base clock frequency. 484 - 485 name: esync-frequency-supported 486 type: nest 487 multi-attr: true 488 nested-attributes: frequency-range 489 doc: | 490 If provided a pin is capable of embedding a SYNC signal (within given 491 range) into its base frequency signal. 492 - 493 name: esync-pulse 494 type: u32 495 doc: | 496 A ratio of high to low state of a SYNC signal pulse embedded 497 into base clock frequency. Value is in percents. 498 - 499 name: reference-sync 500 type: nest 501 multi-attr: true 502 nested-attributes: reference-sync 503 doc: | 504 Capable pin provides list of pins that can be bound to create a 505 reference-sync pin pair. 506 - 507 name: phase-adjust-gran 508 type: u32 509 doc: | 510 Granularity of phase adjustment, in picoseconds. The value of 511 phase adjustment must be a multiple of this granularity. 512 - 513 name: fractional-frequency-offset-ppt 514 type: sint 515 doc: | 516 The FFO (Fractional Frequency Offset) of the pin. 517 At top level this represents the RX vs TX symbol rate 518 offset on the media associated with the pin. Inside 519 the pin-parent-device nest it represents the frequency 520 offset between the pin and its parent DPLL device. 521 For pins of type PIN_TYPE_INT_NCO this represents 522 the DPLL's current output frequency offset from its 523 nominal frequency. 524 Value is in PPT (parts per trillion, 10^-12). 525 This is a higher-precision version of 526 fractional-frequency-offset. 527 - 528 name: measured-frequency 529 type: u64 530 doc: | 531 The measured frequency of the input pin in millihertz (mHz). 532 Value of (DPLL_A_PIN_MEASURED_FREQUENCY / 533 DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is an integer part (Hz) 534 of a measured frequency value. 535 Value of (DPLL_A_PIN_MEASURED_FREQUENCY % 536 DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is a fractional part 537 of a measured frequency value. 538 - 539 name: operstate 540 type: u32 541 enum: pin-operstate 542 doc: | 543 Operational state of the pin with respect to its parent DPLL 544 device. Unlike state (which reflects the administrative intent), 545 operstate reflects the actual hardware status. 546 547 - 548 name: pin-parent-device 549 subset-of: pin 550 attributes: 551 - 552 name: parent-id 553 - 554 name: direction 555 - 556 name: prio 557 - 558 name: state 559 - 560 name: operstate 561 - 562 name: phase-offset 563 - 564 name: fractional-frequency-offset 565 - 566 name: fractional-frequency-offset-ppt 567 - 568 name: pin-parent-pin 569 subset-of: pin 570 attributes: 571 - 572 name: parent-id 573 - 574 name: state 575 - 576 name: frequency-range 577 subset-of: pin 578 attributes: 579 - 580 name: frequency-min 581 - 582 name: frequency-max 583 - 584 name: reference-sync 585 subset-of: pin 586 attributes: 587 - 588 name: id 589 - 590 name: state 591 592operations: 593 enum-name: dpll_cmd 594 list: 595 - 596 name: device-id-get 597 doc: | 598 Get id of dpll device that matches given attributes 599 attribute-set: dpll 600 flags: [admin-perm] 601 602 do: 603 pre: dpll-lock-doit 604 post: dpll-unlock-doit 605 request: 606 attributes: 607 - module-name 608 - clock-id 609 - type 610 reply: 611 attributes: 612 - id 613 614 - 615 name: device-get 616 doc: | 617 Get list of DPLL devices (dump) or attributes of a single dpll device 618 attribute-set: dpll 619 flags: [admin-perm] 620 621 do: 622 pre: dpll-pre-doit 623 post: dpll-post-doit 624 request: 625 attributes: 626 - id 627 reply: &dev-attrs 628 attributes: 629 - id 630 - module-name 631 - mode 632 - mode-supported 633 - lock-status 634 - lock-status-error 635 - temp 636 - clock-id 637 - type 638 - phase-offset-monitor 639 - phase-offset-avg-factor 640 - frequency-monitor 641 642 dump: 643 reply: *dev-attrs 644 645 - 646 name: device-set 647 doc: Set attributes for a DPLL device 648 attribute-set: dpll 649 flags: [admin-perm] 650 651 do: 652 pre: dpll-pre-doit 653 post: dpll-post-doit 654 request: 655 attributes: 656 - id 657 - mode 658 - phase-offset-monitor 659 - phase-offset-avg-factor 660 - frequency-monitor 661 - 662 name: device-create-ntf 663 doc: Notification about device appearing 664 notify: device-get 665 mcgrp: monitor 666 - 667 name: device-delete-ntf 668 doc: Notification about device disappearing 669 notify: device-get 670 mcgrp: monitor 671 - 672 name: device-change-ntf 673 doc: Notification about device configuration being changed 674 notify: device-get 675 mcgrp: monitor 676 - 677 name: pin-id-get 678 doc: | 679 Get id of a pin that matches given attributes 680 attribute-set: pin 681 flags: [admin-perm] 682 683 do: 684 pre: dpll-lock-doit 685 post: dpll-unlock-doit 686 request: 687 attributes: 688 - module-name 689 - clock-id 690 - board-label 691 - panel-label 692 - package-label 693 - type 694 reply: 695 attributes: 696 - id 697 698 - 699 name: pin-get 700 doc: | 701 Get list of pins and its attributes. 702 703 - dump request without any attributes given - list all the pins in the 704 system 705 - dump request with target dpll - list all the pins registered with 706 a given dpll device 707 - do request with target dpll and target pin - single pin attributes 708 attribute-set: pin 709 flags: [admin-perm] 710 711 do: 712 pre: dpll-pin-pre-doit 713 post: dpll-pin-post-doit 714 request: 715 attributes: 716 - id 717 reply: &pin-attrs 718 attributes: 719 - id 720 - module-name 721 - clock-id 722 - board-label 723 - panel-label 724 - package-label 725 - type 726 - frequency 727 - frequency-supported 728 - capabilities 729 - parent-device 730 - parent-pin 731 - phase-adjust-gran 732 - phase-adjust-min 733 - phase-adjust-max 734 - phase-adjust 735 - fractional-frequency-offset 736 - fractional-frequency-offset-ppt 737 - esync-frequency 738 - esync-frequency-supported 739 - esync-pulse 740 - reference-sync 741 - measured-frequency 742 743 dump: 744 request: 745 attributes: 746 - id 747 reply: *pin-attrs 748 749 - 750 name: pin-set 751 doc: Set attributes of a target pin 752 attribute-set: pin 753 flags: [admin-perm] 754 755 do: 756 pre: dpll-pin-pre-doit 757 post: dpll-pin-post-doit 758 request: 759 attributes: 760 - id 761 - frequency 762 - direction 763 - prio 764 - state 765 - parent-device 766 - parent-pin 767 - phase-adjust 768 - esync-frequency 769 - reference-sync 770 - 771 name: pin-create-ntf 772 doc: Notification about pin appearing 773 notify: pin-get 774 mcgrp: monitor 775 - 776 name: pin-delete-ntf 777 doc: Notification about pin disappearing 778 notify: pin-get 779 mcgrp: monitor 780 - 781 name: pin-change-ntf 782 doc: Notification about pin configuration being changed 783 notify: pin-get 784 mcgrp: monitor 785 786mcast-groups: 787 list: 788 - 789 name: monitor 790