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