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