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