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 244attribute-sets: 245 - 246 name: dpll 247 enum-name: dpll_a 248 attributes: 249 - 250 name: id 251 type: u32 252 - 253 name: module-name 254 type: string 255 - 256 name: pad 257 type: pad 258 - 259 name: clock-id 260 type: u64 261 - 262 name: mode 263 type: u32 264 enum: mode 265 - 266 name: mode-supported 267 type: u32 268 enum: mode 269 multi-attr: true 270 - 271 name: lock-status 272 type: u32 273 enum: lock-status 274 - 275 name: temp 276 type: s32 277 - 278 name: type 279 type: u32 280 enum: type 281 - 282 name: lock-status-error 283 type: u32 284 enum: lock-status-error 285 - 286 name: clock-quality-level 287 type: u32 288 enum: clock-quality-level 289 multi-attr: true 290 doc: | 291 Level of quality of a clock device. This mainly applies when 292 the dpll lock-status is DPLL_LOCK_STATUS_HOLDOVER. This could 293 be put to message multiple times to indicate possible parallel 294 quality levels (e.g. one specified by ITU option 1 and another 295 one specified by option 2). 296 - 297 name: pin 298 enum-name: dpll_a_pin 299 attributes: 300 - 301 name: id 302 type: u32 303 - 304 name: parent-id 305 type: u32 306 - 307 name: module-name 308 type: string 309 - 310 name: pad 311 type: pad 312 - 313 name: clock-id 314 type: u64 315 - 316 name: board-label 317 type: string 318 - 319 name: panel-label 320 type: string 321 - 322 name: package-label 323 type: string 324 - 325 name: type 326 type: u32 327 enum: pin-type 328 - 329 name: direction 330 type: u32 331 enum: pin-direction 332 - 333 name: frequency 334 type: u64 335 - 336 name: frequency-supported 337 type: nest 338 multi-attr: true 339 nested-attributes: frequency-range 340 - 341 name: frequency-min 342 type: u64 343 - 344 name: frequency-max 345 type: u64 346 - 347 name: prio 348 type: u32 349 - 350 name: state 351 type: u32 352 enum: pin-state 353 - 354 name: capabilities 355 type: u32 356 enum: pin-capabilities 357 - 358 name: parent-device 359 type: nest 360 multi-attr: true 361 nested-attributes: pin-parent-device 362 - 363 name: parent-pin 364 type: nest 365 multi-attr: true 366 nested-attributes: pin-parent-pin 367 - 368 name: phase-adjust-min 369 type: s32 370 - 371 name: phase-adjust-max 372 type: s32 373 - 374 name: phase-adjust 375 type: s32 376 - 377 name: phase-offset 378 type: s64 379 - 380 name: fractional-frequency-offset 381 type: sint 382 doc: | 383 The FFO (Fractional Frequency Offset) between the RX and TX 384 symbol rate on the media associated with the pin: 385 (rx_frequency-tx_frequency)/rx_frequency 386 Value is in PPM (parts per million). 387 This may be implemented for example for pin of type 388 PIN_TYPE_SYNCE_ETH_PORT. 389 - 390 name: esync-frequency 391 type: u64 392 doc: | 393 Frequency of Embedded SYNC signal. If provided, the pin is configured 394 with a SYNC signal embedded into its base clock frequency. 395 - 396 name: esync-frequency-supported 397 type: nest 398 multi-attr: true 399 nested-attributes: frequency-range 400 doc: | 401 If provided a pin is capable of embedding a SYNC signal (within given 402 range) into its base frequency signal. 403 - 404 name: esync-pulse 405 type: u32 406 doc: | 407 A ratio of high to low state of a SYNC signal pulse embedded 408 into base clock frequency. Value is in percents. 409 - 410 name: pin-parent-device 411 subset-of: pin 412 attributes: 413 - 414 name: parent-id 415 - 416 name: direction 417 - 418 name: prio 419 - 420 name: state 421 - 422 name: phase-offset 423 - 424 name: pin-parent-pin 425 subset-of: pin 426 attributes: 427 - 428 name: parent-id 429 - 430 name: state 431 - 432 name: frequency-range 433 subset-of: pin 434 attributes: 435 - 436 name: frequency-min 437 - 438 name: frequency-max 439 440operations: 441 enum-name: dpll_cmd 442 list: 443 - 444 name: device-id-get 445 doc: | 446 Get id of dpll device that matches given attributes 447 attribute-set: dpll 448 flags: [ admin-perm ] 449 450 do: 451 pre: dpll-lock-doit 452 post: dpll-unlock-doit 453 request: 454 attributes: 455 - module-name 456 - clock-id 457 - type 458 reply: 459 attributes: 460 - id 461 462 - 463 name: device-get 464 doc: | 465 Get list of DPLL devices (dump) or attributes of a single dpll device 466 attribute-set: dpll 467 flags: [ admin-perm ] 468 469 do: 470 pre: dpll-pre-doit 471 post: dpll-post-doit 472 request: 473 attributes: 474 - id 475 reply: &dev-attrs 476 attributes: 477 - id 478 - module-name 479 - mode 480 - mode-supported 481 - lock-status 482 - lock-status-error 483 - temp 484 - clock-id 485 - type 486 487 dump: 488 reply: *dev-attrs 489 490 - 491 name: device-set 492 doc: Set attributes for a DPLL device 493 attribute-set: dpll 494 flags: [ admin-perm ] 495 496 do: 497 pre: dpll-pre-doit 498 post: dpll-post-doit 499 request: 500 attributes: 501 - id 502 - 503 name: device-create-ntf 504 doc: Notification about device appearing 505 notify: device-get 506 mcgrp: monitor 507 - 508 name: device-delete-ntf 509 doc: Notification about device disappearing 510 notify: device-get 511 mcgrp: monitor 512 - 513 name: device-change-ntf 514 doc: Notification about device configuration being changed 515 notify: device-get 516 mcgrp: monitor 517 - 518 name: pin-id-get 519 doc: | 520 Get id of a pin that matches given attributes 521 attribute-set: pin 522 flags: [ admin-perm ] 523 524 do: 525 pre: dpll-lock-doit 526 post: dpll-unlock-doit 527 request: 528 attributes: 529 - module-name 530 - clock-id 531 - board-label 532 - panel-label 533 - package-label 534 - type 535 reply: 536 attributes: 537 - id 538 539 - 540 name: pin-get 541 doc: | 542 Get list of pins and its attributes. 543 544 - dump request without any attributes given - list all the pins in the 545 system 546 - dump request with target dpll - list all the pins registered with 547 a given dpll device 548 - do request with target dpll and target pin - single pin attributes 549 attribute-set: pin 550 flags: [ admin-perm ] 551 552 do: 553 pre: dpll-pin-pre-doit 554 post: dpll-pin-post-doit 555 request: 556 attributes: 557 - id 558 reply: &pin-attrs 559 attributes: 560 - id 561 - board-label 562 - panel-label 563 - package-label 564 - type 565 - frequency 566 - frequency-supported 567 - capabilities 568 - parent-device 569 - parent-pin 570 - phase-adjust-min 571 - phase-adjust-max 572 - phase-adjust 573 - fractional-frequency-offset 574 - esync-frequency 575 - esync-frequency-supported 576 - esync-pulse 577 578 dump: 579 request: 580 attributes: 581 - id 582 reply: *pin-attrs 583 584 - 585 name: pin-set 586 doc: Set attributes of a target pin 587 attribute-set: pin 588 flags: [ admin-perm ] 589 590 do: 591 pre: dpll-pin-pre-doit 592 post: dpll-pin-post-doit 593 request: 594 attributes: 595 - id 596 - frequency 597 - direction 598 - prio 599 - state 600 - parent-device 601 - parent-pin 602 - phase-adjust 603 - esync-frequency 604 - 605 name: pin-create-ntf 606 doc: Notification about pin appearing 607 notify: pin-get 608 mcgrp: monitor 609 - 610 name: pin-delete-ntf 611 doc: Notification about pin disappearing 612 notify: pin-get 613 mcgrp: monitor 614 - 615 name: pin-change-ntf 616 doc: Notification about pin configuration being changed 617 notify: pin-get 618 mcgrp: monitor 619 620mcast-groups: 621 list: 622 - 623 name: monitor 624