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: const 90 name: temp-divider 91 value: 1000 92 doc: | 93 temperature divider allowing userspace to calculate the 94 temperature as float with three digit decimal precision. 95 Value of (DPLL_A_TEMP / DPLL_TEMP_DIVIDER) is integer part of 96 temperature value. 97 Value of (DPLL_A_TEMP % DPLL_TEMP_DIVIDER) is fractional part of 98 temperature value. 99 - 100 type: enum 101 name: type 102 doc: type of dpll, valid values for DPLL_A_TYPE attribute 103 entries: 104 - 105 name: pps 106 doc: dpll produces Pulse-Per-Second signal 107 value: 1 108 - 109 name: eec 110 doc: dpll drives the Ethernet Equipment Clock 111 render-max: true 112 - 113 type: enum 114 name: pin-type 115 doc: | 116 defines possible types of a pin, valid values for DPLL_A_PIN_TYPE 117 attribute 118 entries: 119 - 120 name: mux 121 doc: aggregates another layer of selectable pins 122 value: 1 123 - 124 name: ext 125 doc: external input 126 - 127 name: synce-eth-port 128 doc: ethernet port PHY's recovered clock 129 - 130 name: int-oscillator 131 doc: device internal oscillator 132 - 133 name: gnss 134 doc: GNSS recovered clock 135 render-max: true 136 - 137 type: enum 138 name: pin-direction 139 doc: | 140 defines possible direction of a pin, valid values for 141 DPLL_A_PIN_DIRECTION attribute 142 entries: 143 - 144 name: input 145 doc: pin used as a input of a signal 146 value: 1 147 - 148 name: output 149 doc: pin used to output the signal 150 render-max: true 151 - 152 type: const 153 name: pin-frequency-1-hz 154 value: 1 155 - 156 type: const 157 name: pin-frequency-10-khz 158 value: 10000 159 - 160 type: const 161 name: pin-frequency-77_5-khz 162 value: 77500 163 - 164 type: const 165 name: pin-frequency-10-mhz 166 value: 10000000 167 - 168 type: enum 169 name: pin-state 170 doc: | 171 defines possible states of a pin, valid values for 172 DPLL_A_PIN_STATE attribute 173 entries: 174 - 175 name: connected 176 doc: pin connected, active input of phase locked loop 177 value: 1 178 - 179 name: disconnected 180 doc: pin disconnected, not considered as a valid input 181 - 182 name: selectable 183 doc: pin enabled for automatic input selection 184 render-max: true 185 - 186 type: flags 187 name: pin-capabilities 188 doc: | 189 defines possible capabilities of a pin, valid flags on 190 DPLL_A_PIN_CAPABILITIES attribute 191 entries: 192 - 193 name: direction-can-change 194 doc: pin direction can be changed 195 - 196 name: priority-can-change 197 doc: pin priority can be changed 198 - 199 name: state-can-change 200 doc: pin state can be changed 201 - 202 type: const 203 name: phase-offset-divider 204 value: 1000 205 doc: | 206 phase offset divider allows userspace to calculate a value of 207 measured signal phase difference between a pin and dpll device 208 as a fractional value with three digit decimal precision. 209 Value of (DPLL_A_PHASE_OFFSET / DPLL_PHASE_OFFSET_DIVIDER) is an 210 integer part of a measured phase offset value. 211 Value of (DPLL_A_PHASE_OFFSET % DPLL_PHASE_OFFSET_DIVIDER) is a 212 fractional part of a measured phase offset value. 213 214attribute-sets: 215 - 216 name: dpll 217 enum-name: dpll_a 218 attributes: 219 - 220 name: id 221 type: u32 222 - 223 name: module-name 224 type: string 225 - 226 name: pad 227 type: pad 228 - 229 name: clock-id 230 type: u64 231 - 232 name: mode 233 type: u32 234 enum: mode 235 - 236 name: mode-supported 237 type: u32 238 enum: mode 239 multi-attr: true 240 - 241 name: lock-status 242 type: u32 243 enum: lock-status 244 - 245 name: temp 246 type: s32 247 - 248 name: type 249 type: u32 250 enum: type 251 - 252 name: lock-status-error 253 type: u32 254 enum: lock-status-error 255 - 256 name: pin 257 enum-name: dpll_a_pin 258 attributes: 259 - 260 name: id 261 type: u32 262 - 263 name: parent-id 264 type: u32 265 - 266 name: module-name 267 type: string 268 - 269 name: pad 270 type: pad 271 - 272 name: clock-id 273 type: u64 274 - 275 name: board-label 276 type: string 277 - 278 name: panel-label 279 type: string 280 - 281 name: package-label 282 type: string 283 - 284 name: type 285 type: u32 286 enum: pin-type 287 - 288 name: direction 289 type: u32 290 enum: pin-direction 291 - 292 name: frequency 293 type: u64 294 - 295 name: frequency-supported 296 type: nest 297 multi-attr: true 298 nested-attributes: frequency-range 299 - 300 name: frequency-min 301 type: u64 302 - 303 name: frequency-max 304 type: u64 305 - 306 name: prio 307 type: u32 308 - 309 name: state 310 type: u32 311 enum: pin-state 312 - 313 name: capabilities 314 type: u32 315 enum: pin-capabilities 316 - 317 name: parent-device 318 type: nest 319 multi-attr: true 320 nested-attributes: pin-parent-device 321 - 322 name: parent-pin 323 type: nest 324 multi-attr: true 325 nested-attributes: pin-parent-pin 326 - 327 name: phase-adjust-min 328 type: s32 329 - 330 name: phase-adjust-max 331 type: s32 332 - 333 name: phase-adjust 334 type: s32 335 - 336 name: phase-offset 337 type: s64 338 - 339 name: fractional-frequency-offset 340 type: sint 341 doc: | 342 The FFO (Fractional Frequency Offset) between the RX and TX 343 symbol rate on the media associated with the pin: 344 (rx_frequency-tx_frequency)/rx_frequency 345 Value is in PPM (parts per million). 346 This may be implemented for example for pin of type 347 PIN_TYPE_SYNCE_ETH_PORT. 348 - 349 name: esync-frequency 350 type: u64 351 doc: | 352 Frequency of Embedded SYNC signal. If provided, the pin is configured 353 with a SYNC signal embedded into its base clock frequency. 354 - 355 name: esync-frequency-supported 356 type: nest 357 multi-attr: true 358 nested-attributes: frequency-range 359 doc: | 360 If provided a pin is capable of embedding a SYNC signal (within given 361 range) into its base frequency signal. 362 - 363 name: esync-pulse 364 type: u32 365 doc: | 366 A ratio of high to low state of a SYNC signal pulse embedded 367 into base clock frequency. Value is in percents. 368 - 369 name: pin-parent-device 370 subset-of: pin 371 attributes: 372 - 373 name: parent-id 374 - 375 name: direction 376 - 377 name: prio 378 - 379 name: state 380 - 381 name: phase-offset 382 - 383 name: pin-parent-pin 384 subset-of: pin 385 attributes: 386 - 387 name: parent-id 388 - 389 name: state 390 - 391 name: frequency-range 392 subset-of: pin 393 attributes: 394 - 395 name: frequency-min 396 - 397 name: frequency-max 398 399operations: 400 enum-name: dpll_cmd 401 list: 402 - 403 name: device-id-get 404 doc: | 405 Get id of dpll device that matches given attributes 406 attribute-set: dpll 407 flags: [ admin-perm ] 408 409 do: 410 pre: dpll-lock-doit 411 post: dpll-unlock-doit 412 request: 413 attributes: 414 - module-name 415 - clock-id 416 - type 417 reply: 418 attributes: 419 - id 420 421 - 422 name: device-get 423 doc: | 424 Get list of DPLL devices (dump) or attributes of a single dpll device 425 attribute-set: dpll 426 flags: [ admin-perm ] 427 428 do: 429 pre: dpll-pre-doit 430 post: dpll-post-doit 431 request: 432 attributes: 433 - id 434 reply: &dev-attrs 435 attributes: 436 - id 437 - module-name 438 - mode 439 - mode-supported 440 - lock-status 441 - lock-status-error 442 - temp 443 - clock-id 444 - type 445 446 dump: 447 reply: *dev-attrs 448 449 - 450 name: device-set 451 doc: Set attributes for a DPLL device 452 attribute-set: dpll 453 flags: [ admin-perm ] 454 455 do: 456 pre: dpll-pre-doit 457 post: dpll-post-doit 458 request: 459 attributes: 460 - id 461 - 462 name: device-create-ntf 463 doc: Notification about device appearing 464 notify: device-get 465 mcgrp: monitor 466 - 467 name: device-delete-ntf 468 doc: Notification about device disappearing 469 notify: device-get 470 mcgrp: monitor 471 - 472 name: device-change-ntf 473 doc: Notification about device configuration being changed 474 notify: device-get 475 mcgrp: monitor 476 - 477 name: pin-id-get 478 doc: | 479 Get id of a pin that matches given attributes 480 attribute-set: pin 481 flags: [ admin-perm ] 482 483 do: 484 pre: dpll-lock-doit 485 post: dpll-unlock-doit 486 request: 487 attributes: 488 - module-name 489 - clock-id 490 - board-label 491 - panel-label 492 - package-label 493 - type 494 reply: 495 attributes: 496 - id 497 498 - 499 name: pin-get 500 doc: | 501 Get list of pins and its attributes. 502 503 - dump request without any attributes given - list all the pins in the 504 system 505 - dump request with target dpll - list all the pins registered with 506 a given dpll device 507 - do request with target dpll and target pin - single pin attributes 508 attribute-set: pin 509 flags: [ admin-perm ] 510 511 do: 512 pre: dpll-pin-pre-doit 513 post: dpll-pin-post-doit 514 request: 515 attributes: 516 - id 517 reply: &pin-attrs 518 attributes: 519 - id 520 - board-label 521 - panel-label 522 - package-label 523 - type 524 - frequency 525 - frequency-supported 526 - capabilities 527 - parent-device 528 - parent-pin 529 - phase-adjust-min 530 - phase-adjust-max 531 - phase-adjust 532 - fractional-frequency-offset 533 - esync-frequency 534 - esync-frequency-supported 535 - esync-pulse 536 537 dump: 538 request: 539 attributes: 540 - id 541 reply: *pin-attrs 542 543 - 544 name: pin-set 545 doc: Set attributes of a target pin 546 attribute-set: pin 547 flags: [ admin-perm ] 548 549 do: 550 pre: dpll-pin-pre-doit 551 post: dpll-pin-post-doit 552 request: 553 attributes: 554 - id 555 - frequency 556 - direction 557 - prio 558 - state 559 - parent-device 560 - parent-pin 561 - phase-adjust 562 - esync-frequency 563 - 564 name: pin-create-ntf 565 doc: Notification about pin appearing 566 notify: pin-get 567 mcgrp: monitor 568 - 569 name: pin-delete-ntf 570 doc: Notification about pin disappearing 571 notify: pin-get 572 mcgrp: monitor 573 - 574 name: pin-change-ntf 575 doc: Notification about pin configuration being changed 576 notify: pin-get 577 mcgrp: monitor 578 579mcast-groups: 580 list: 581 - 582 name: monitor 583