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