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: pin 320 enum-name: dpll_a_pin 321 attributes: 322 - 323 name: id 324 type: u32 325 - 326 name: parent-id 327 type: u32 328 - 329 name: module-name 330 type: string 331 - 332 name: pad 333 type: pad 334 - 335 name: clock-id 336 type: u64 337 - 338 name: board-label 339 type: string 340 - 341 name: panel-label 342 type: string 343 - 344 name: package-label 345 type: string 346 - 347 name: type 348 type: u32 349 enum: pin-type 350 - 351 name: direction 352 type: u32 353 enum: pin-direction 354 - 355 name: frequency 356 type: u64 357 - 358 name: frequency-supported 359 type: nest 360 multi-attr: true 361 nested-attributes: frequency-range 362 - 363 name: frequency-min 364 type: u64 365 - 366 name: frequency-max 367 type: u64 368 - 369 name: prio 370 type: u32 371 - 372 name: state 373 type: u32 374 enum: pin-state 375 - 376 name: capabilities 377 type: u32 378 enum: pin-capabilities 379 - 380 name: parent-device 381 type: nest 382 multi-attr: true 383 nested-attributes: pin-parent-device 384 - 385 name: parent-pin 386 type: nest 387 multi-attr: true 388 nested-attributes: pin-parent-pin 389 - 390 name: phase-adjust-min 391 type: s32 392 - 393 name: phase-adjust-max 394 type: s32 395 - 396 name: phase-adjust 397 type: s32 398 - 399 name: phase-offset 400 type: s64 401 - 402 name: fractional-frequency-offset 403 type: sint 404 doc: | 405 The FFO (Fractional Frequency Offset) between the RX and TX 406 symbol rate on the media associated with the pin: 407 (rx_frequency-tx_frequency)/rx_frequency 408 Value is in PPM (parts per million). 409 This may be implemented for example for pin of type 410 PIN_TYPE_SYNCE_ETH_PORT. 411 - 412 name: esync-frequency 413 type: u64 414 doc: | 415 Frequency of Embedded SYNC signal. If provided, the pin is configured 416 with a SYNC signal embedded into its base clock frequency. 417 - 418 name: esync-frequency-supported 419 type: nest 420 multi-attr: true 421 nested-attributes: frequency-range 422 doc: | 423 If provided a pin is capable of embedding a SYNC signal (within given 424 range) into its base frequency signal. 425 - 426 name: esync-pulse 427 type: u32 428 doc: | 429 A ratio of high to low state of a SYNC signal pulse embedded 430 into base clock frequency. Value is in percents. 431 - 432 name: reference-sync 433 type: nest 434 multi-attr: true 435 nested-attributes: reference-sync 436 doc: | 437 Capable pin provides list of pins that can be bound to create a 438 reference-sync pin pair. 439 440 - 441 name: pin-parent-device 442 subset-of: pin 443 attributes: 444 - 445 name: parent-id 446 - 447 name: direction 448 - 449 name: prio 450 - 451 name: state 452 - 453 name: phase-offset 454 - 455 name: pin-parent-pin 456 subset-of: pin 457 attributes: 458 - 459 name: parent-id 460 - 461 name: state 462 - 463 name: frequency-range 464 subset-of: pin 465 attributes: 466 - 467 name: frequency-min 468 - 469 name: frequency-max 470 - 471 name: reference-sync 472 subset-of: pin 473 attributes: 474 - 475 name: id 476 - 477 name: state 478 479operations: 480 enum-name: dpll_cmd 481 list: 482 - 483 name: device-id-get 484 doc: | 485 Get id of dpll device that matches given attributes 486 attribute-set: dpll 487 flags: [admin-perm] 488 489 do: 490 pre: dpll-lock-doit 491 post: dpll-unlock-doit 492 request: 493 attributes: 494 - module-name 495 - clock-id 496 - type 497 reply: 498 attributes: 499 - id 500 501 - 502 name: device-get 503 doc: | 504 Get list of DPLL devices (dump) or attributes of a single dpll device 505 attribute-set: dpll 506 flags: [admin-perm] 507 508 do: 509 pre: dpll-pre-doit 510 post: dpll-post-doit 511 request: 512 attributes: 513 - id 514 reply: &dev-attrs 515 attributes: 516 - id 517 - module-name 518 - mode 519 - mode-supported 520 - lock-status 521 - lock-status-error 522 - temp 523 - clock-id 524 - type 525 - phase-offset-monitor 526 527 dump: 528 reply: *dev-attrs 529 530 - 531 name: device-set 532 doc: Set attributes for a DPLL device 533 attribute-set: dpll 534 flags: [admin-perm] 535 536 do: 537 pre: dpll-pre-doit 538 post: dpll-post-doit 539 request: 540 attributes: 541 - id 542 - phase-offset-monitor 543 - 544 name: device-create-ntf 545 doc: Notification about device appearing 546 notify: device-get 547 mcgrp: monitor 548 - 549 name: device-delete-ntf 550 doc: Notification about device disappearing 551 notify: device-get 552 mcgrp: monitor 553 - 554 name: device-change-ntf 555 doc: Notification about device configuration being changed 556 notify: device-get 557 mcgrp: monitor 558 - 559 name: pin-id-get 560 doc: | 561 Get id of a pin that matches given attributes 562 attribute-set: pin 563 flags: [admin-perm] 564 565 do: 566 pre: dpll-lock-doit 567 post: dpll-unlock-doit 568 request: 569 attributes: 570 - module-name 571 - clock-id 572 - board-label 573 - panel-label 574 - package-label 575 - type 576 reply: 577 attributes: 578 - id 579 580 - 581 name: pin-get 582 doc: | 583 Get list of pins and its attributes. 584 585 - dump request without any attributes given - list all the pins in the 586 system 587 - dump request with target dpll - list all the pins registered with 588 a given dpll device 589 - do request with target dpll and target pin - single pin attributes 590 attribute-set: pin 591 flags: [admin-perm] 592 593 do: 594 pre: dpll-pin-pre-doit 595 post: dpll-pin-post-doit 596 request: 597 attributes: 598 - id 599 reply: &pin-attrs 600 attributes: 601 - id 602 - board-label 603 - panel-label 604 - package-label 605 - type 606 - frequency 607 - frequency-supported 608 - capabilities 609 - parent-device 610 - parent-pin 611 - phase-adjust-min 612 - phase-adjust-max 613 - phase-adjust 614 - fractional-frequency-offset 615 - esync-frequency 616 - esync-frequency-supported 617 - esync-pulse 618 - reference-sync 619 620 dump: 621 request: 622 attributes: 623 - id 624 reply: *pin-attrs 625 626 - 627 name: pin-set 628 doc: Set attributes of a target pin 629 attribute-set: pin 630 flags: [admin-perm] 631 632 do: 633 pre: dpll-pin-pre-doit 634 post: dpll-pin-post-doit 635 request: 636 attributes: 637 - id 638 - frequency 639 - direction 640 - prio 641 - state 642 - parent-device 643 - parent-pin 644 - phase-adjust 645 - esync-frequency 646 - reference-sync 647 - 648 name: pin-create-ntf 649 doc: Notification about pin appearing 650 notify: pin-get 651 mcgrp: monitor 652 - 653 name: pin-delete-ntf 654 doc: Notification about pin disappearing 655 notify: pin-get 656 mcgrp: monitor 657 - 658 name: pin-change-ntf 659 doc: Notification about pin configuration being changed 660 notify: pin-get 661 mcgrp: monitor 662 663mcast-groups: 664 list: 665 - 666 name: monitor 667