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) between the RX and TX 452 symbol rate on the media associated with the pin: 453 (rx_frequency-tx_frequency)/rx_frequency 454 Value is in PPM (parts per million). 455 This may be implemented for example for pin of type 456 PIN_TYPE_SYNCE_ETH_PORT. 457 - 458 name: esync-frequency 459 type: u64 460 doc: | 461 Frequency of Embedded SYNC signal. If provided, the pin is configured 462 with a SYNC signal embedded into its base clock frequency. 463 - 464 name: esync-frequency-supported 465 type: nest 466 multi-attr: true 467 nested-attributes: frequency-range 468 doc: | 469 If provided a pin is capable of embedding a SYNC signal (within given 470 range) into its base frequency signal. 471 - 472 name: esync-pulse 473 type: u32 474 doc: | 475 A ratio of high to low state of a SYNC signal pulse embedded 476 into base clock frequency. Value is in percents. 477 - 478 name: reference-sync 479 type: nest 480 multi-attr: true 481 nested-attributes: reference-sync 482 doc: | 483 Capable pin provides list of pins that can be bound to create a 484 reference-sync pin pair. 485 - 486 name: phase-adjust-gran 487 type: u32 488 doc: | 489 Granularity of phase adjustment, in picoseconds. The value of 490 phase adjustment must be a multiple of this granularity. 491 - 492 name: fractional-frequency-offset-ppt 493 type: sint 494 doc: | 495 The FFO (Fractional Frequency Offset) of the pin with respect to 496 the nominal frequency. 497 Value = (frequency_measured - frequency_nominal) / frequency_nominal 498 Value is in PPT (parts per trillion, 10^-12). 499 Note: This attribute provides higher resolution than the standard 500 fractional-frequency-offset (which is in PPM). 501 - 502 name: measured-frequency 503 type: u64 504 doc: | 505 The measured frequency of the input pin in millihertz (mHz). 506 Value of (DPLL_A_PIN_MEASURED_FREQUENCY / 507 DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is an integer part (Hz) 508 of a measured frequency value. 509 Value of (DPLL_A_PIN_MEASURED_FREQUENCY % 510 DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is a fractional part 511 of a measured frequency value. 512 - 513 name: operstate 514 type: u32 515 enum: pin-operstate 516 doc: | 517 Operational state of the pin with respect to its parent DPLL 518 device. Unlike state (which reflects the administrative intent), 519 operstate reflects the actual hardware status. 520 521 - 522 name: pin-parent-device 523 subset-of: pin 524 attributes: 525 - 526 name: parent-id 527 - 528 name: direction 529 - 530 name: prio 531 - 532 name: state 533 - 534 name: operstate 535 - 536 name: phase-offset 537 - 538 name: pin-parent-pin 539 subset-of: pin 540 attributes: 541 - 542 name: parent-id 543 - 544 name: state 545 - 546 name: frequency-range 547 subset-of: pin 548 attributes: 549 - 550 name: frequency-min 551 - 552 name: frequency-max 553 - 554 name: reference-sync 555 subset-of: pin 556 attributes: 557 - 558 name: id 559 - 560 name: state 561 562operations: 563 enum-name: dpll_cmd 564 list: 565 - 566 name: device-id-get 567 doc: | 568 Get id of dpll device that matches given attributes 569 attribute-set: dpll 570 flags: [admin-perm] 571 572 do: 573 pre: dpll-lock-doit 574 post: dpll-unlock-doit 575 request: 576 attributes: 577 - module-name 578 - clock-id 579 - type 580 reply: 581 attributes: 582 - id 583 584 - 585 name: device-get 586 doc: | 587 Get list of DPLL devices (dump) or attributes of a single dpll device 588 attribute-set: dpll 589 flags: [admin-perm] 590 591 do: 592 pre: dpll-pre-doit 593 post: dpll-post-doit 594 request: 595 attributes: 596 - id 597 reply: &dev-attrs 598 attributes: 599 - id 600 - module-name 601 - mode 602 - mode-supported 603 - lock-status 604 - lock-status-error 605 - temp 606 - clock-id 607 - type 608 - phase-offset-monitor 609 - phase-offset-avg-factor 610 - frequency-monitor 611 612 dump: 613 reply: *dev-attrs 614 615 - 616 name: device-set 617 doc: Set attributes for a 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 - mode 628 - phase-offset-monitor 629 - phase-offset-avg-factor 630 - frequency-monitor 631 - 632 name: device-create-ntf 633 doc: Notification about device appearing 634 notify: device-get 635 mcgrp: monitor 636 - 637 name: device-delete-ntf 638 doc: Notification about device disappearing 639 notify: device-get 640 mcgrp: monitor 641 - 642 name: device-change-ntf 643 doc: Notification about device configuration being changed 644 notify: device-get 645 mcgrp: monitor 646 - 647 name: pin-id-get 648 doc: | 649 Get id of a pin that matches given attributes 650 attribute-set: pin 651 flags: [admin-perm] 652 653 do: 654 pre: dpll-lock-doit 655 post: dpll-unlock-doit 656 request: 657 attributes: 658 - module-name 659 - clock-id 660 - board-label 661 - panel-label 662 - package-label 663 - type 664 reply: 665 attributes: 666 - id 667 668 - 669 name: pin-get 670 doc: | 671 Get list of pins and its attributes. 672 673 - dump request without any attributes given - list all the pins in the 674 system 675 - dump request with target dpll - list all the pins registered with 676 a given dpll device 677 - do request with target dpll and target pin - single pin attributes 678 attribute-set: pin 679 flags: [admin-perm] 680 681 do: 682 pre: dpll-pin-pre-doit 683 post: dpll-pin-post-doit 684 request: 685 attributes: 686 - id 687 reply: &pin-attrs 688 attributes: 689 - id 690 - module-name 691 - clock-id 692 - board-label 693 - panel-label 694 - package-label 695 - type 696 - frequency 697 - frequency-supported 698 - capabilities 699 - parent-device 700 - parent-pin 701 - phase-adjust-gran 702 - phase-adjust-min 703 - phase-adjust-max 704 - phase-adjust 705 - fractional-frequency-offset 706 - fractional-frequency-offset-ppt 707 - esync-frequency 708 - esync-frequency-supported 709 - esync-pulse 710 - reference-sync 711 - measured-frequency 712 713 dump: 714 request: 715 attributes: 716 - id 717 reply: *pin-attrs 718 719 - 720 name: pin-set 721 doc: Set attributes of a target pin 722 attribute-set: pin 723 flags: [admin-perm] 724 725 do: 726 pre: dpll-pin-pre-doit 727 post: dpll-pin-post-doit 728 request: 729 attributes: 730 - id 731 - frequency 732 - direction 733 - prio 734 - state 735 - parent-device 736 - parent-pin 737 - phase-adjust 738 - esync-frequency 739 - reference-sync 740 - 741 name: pin-create-ntf 742 doc: Notification about pin appearing 743 notify: pin-get 744 mcgrp: monitor 745 - 746 name: pin-delete-ntf 747 doc: Notification about pin disappearing 748 notify: pin-get 749 mcgrp: monitor 750 - 751 name: pin-change-ntf 752 doc: Notification about pin configuration being changed 753 notify: pin-get 754 mcgrp: monitor 755 756mcast-groups: 757 list: 758 - 759 name: monitor 760