583 lines · yaml
1# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)2 3name: dpll4 5doc: DPLL subsystem.6 7definitions:8 -9 type: enum10 name: mode11 doc: |12 working modes a dpll can support, differentiates if and how dpll selects13 one of its inputs to syntonize with it, valid values for DPLL_A_MODE14 attribute15 entries:16 -17 name: manual18 doc: input can be only selected by sending a request to dpll19 value: 120 -21 name: automatic22 doc: highest prio input pin auto selected by dpll23 render-max: true24 -25 type: enum26 name: lock-status27 doc: |28 provides information of dpll device lock status, valid values for29 DPLL_A_LOCK_STATUS attribute30 entries:31 -32 name: unlocked33 doc: |34 dpll was not yet locked to any valid input (or forced by setting35 DPLL_A_MODE to DPLL_MODE_DETACHED)36 value: 137 -38 name: locked39 doc: |40 dpll is locked to a valid signal, but no holdover available41 -42 name: locked-ho-acq43 doc: |44 dpll is locked and holdover acquired45 -46 name: holdover47 doc: |48 dpll is in holdover state - lost a valid lock or was forced49 by disconnecting all the pins (latter possible only50 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, the52 dpll's lock-state shall remain DPLL_LOCK_STATUS_UNLOCKED)53 render-max: true54 -55 type: enum56 name: lock-status-error57 doc: |58 if previous status change was done due to a failure, this provides59 information of dpll device lock status error.60 Valid values for DPLL_A_LOCK_STATUS_ERROR attribute61 entries:62 -63 name: none64 doc: |65 dpll device lock status was changed without any error66 value: 167 -68 name: undefined69 doc: |70 dpll device lock status was changed due to undefined error.71 Driver fills this value up in case it is not able72 to obtain suitable exact error type.73 -74 name: media-down75 doc: |76 dpll device lock status was changed because of associated77 media got down.78 This may happen for example if dpll device was previously79 locked on an input pin of type PIN_TYPE_SYNCE_ETH_PORT.80 -81 name: fractional-frequency-offset-too-high82 doc: |83 the FFO (Fractional Frequency Offset) between the RX and TX84 symbol rate on the media got too high.85 This may happen for example if dpll device was previously86 locked on an input pin of type PIN_TYPE_SYNCE_ETH_PORT.87 render-max: true88 -89 type: const90 name: temp-divider91 value: 100092 doc: |93 temperature divider allowing userspace to calculate the94 temperature as float with three digit decimal precision.95 Value of (DPLL_A_TEMP / DPLL_TEMP_DIVIDER) is integer part of96 temperature value.97 Value of (DPLL_A_TEMP % DPLL_TEMP_DIVIDER) is fractional part of98 temperature value.99 -100 type: enum101 name: type102 doc: type of dpll, valid values for DPLL_A_TYPE attribute103 entries:104 -105 name: pps106 doc: dpll produces Pulse-Per-Second signal107 value: 1108 -109 name: eec110 doc: dpll drives the Ethernet Equipment Clock111 render-max: true112 -113 type: enum114 name: pin-type115 doc: |116 defines possible types of a pin, valid values for DPLL_A_PIN_TYPE117 attribute118 entries:119 -120 name: mux121 doc: aggregates another layer of selectable pins122 value: 1123 -124 name: ext125 doc: external input126 -127 name: synce-eth-port128 doc: ethernet port PHY's recovered clock129 -130 name: int-oscillator131 doc: device internal oscillator132 -133 name: gnss134 doc: GNSS recovered clock135 render-max: true136 -137 type: enum138 name: pin-direction139 doc: |140 defines possible direction of a pin, valid values for141 DPLL_A_PIN_DIRECTION attribute142 entries:143 -144 name: input145 doc: pin used as a input of a signal146 value: 1147 -148 name: output149 doc: pin used to output the signal150 render-max: true151 -152 type: const153 name: pin-frequency-1-hz154 value: 1155 -156 type: const157 name: pin-frequency-10-khz158 value: 10000159 -160 type: const161 name: pin-frequency-77_5-khz162 value: 77500163 -164 type: const165 name: pin-frequency-10-mhz166 value: 10000000167 -168 type: enum169 name: pin-state170 doc: |171 defines possible states of a pin, valid values for172 DPLL_A_PIN_STATE attribute173 entries:174 -175 name: connected176 doc: pin connected, active input of phase locked loop177 value: 1178 -179 name: disconnected180 doc: pin disconnected, not considered as a valid input181 -182 name: selectable183 doc: pin enabled for automatic input selection184 render-max: true185 -186 type: flags187 name: pin-capabilities188 doc: |189 defines possible capabilities of a pin, valid flags on190 DPLL_A_PIN_CAPABILITIES attribute191 entries:192 -193 name: direction-can-change194 doc: pin direction can be changed195 -196 name: priority-can-change197 doc: pin priority can be changed198 -199 name: state-can-change200 doc: pin state can be changed201 -202 type: const203 name: phase-offset-divider204 value: 1000205 doc: |206 phase offset divider allows userspace to calculate a value of207 measured signal phase difference between a pin and dpll device208 as a fractional value with three digit decimal precision.209 Value of (DPLL_A_PHASE_OFFSET / DPLL_PHASE_OFFSET_DIVIDER) is an210 integer part of a measured phase offset value.211 Value of (DPLL_A_PHASE_OFFSET % DPLL_PHASE_OFFSET_DIVIDER) is a212 fractional part of a measured phase offset value.213 214attribute-sets:215 -216 name: dpll217 enum-name: dpll_a218 attributes:219 -220 name: id221 type: u32222 -223 name: module-name224 type: string225 -226 name: pad227 type: pad228 -229 name: clock-id230 type: u64231 -232 name: mode233 type: u32234 enum: mode235 -236 name: mode-supported237 type: u32238 enum: mode239 multi-attr: true240 -241 name: lock-status242 type: u32243 enum: lock-status244 -245 name: temp246 type: s32247 -248 name: type249 type: u32250 enum: type251 -252 name: lock-status-error253 type: u32254 enum: lock-status-error255 -256 name: pin257 enum-name: dpll_a_pin258 attributes:259 -260 name: id261 type: u32262 -263 name: parent-id264 type: u32265 -266 name: module-name267 type: string268 -269 name: pad270 type: pad271 -272 name: clock-id273 type: u64274 -275 name: board-label276 type: string277 -278 name: panel-label279 type: string280 -281 name: package-label282 type: string283 -284 name: type285 type: u32286 enum: pin-type287 -288 name: direction289 type: u32290 enum: pin-direction291 -292 name: frequency293 type: u64294 -295 name: frequency-supported296 type: nest297 multi-attr: true298 nested-attributes: frequency-range299 -300 name: frequency-min301 type: u64302 -303 name: frequency-max304 type: u64305 -306 name: prio307 type: u32308 -309 name: state310 type: u32311 enum: pin-state312 -313 name: capabilities314 type: u32315 enum: pin-capabilities316 -317 name: parent-device318 type: nest319 multi-attr: true320 nested-attributes: pin-parent-device321 -322 name: parent-pin323 type: nest324 multi-attr: true325 nested-attributes: pin-parent-pin326 -327 name: phase-adjust-min328 type: s32329 -330 name: phase-adjust-max331 type: s32332 -333 name: phase-adjust334 type: s32335 -336 name: phase-offset337 type: s64338 -339 name: fractional-frequency-offset340 type: sint341 doc: |342 The FFO (Fractional Frequency Offset) between the RX and TX343 symbol rate on the media associated with the pin:344 (rx_frequency-tx_frequency)/rx_frequency345 Value is in PPM (parts per million).346 This may be implemented for example for pin of type347 PIN_TYPE_SYNCE_ETH_PORT.348 -349 name: esync-frequency350 type: u64351 doc: |352 Frequency of Embedded SYNC signal. If provided, the pin is configured353 with a SYNC signal embedded into its base clock frequency.354 -355 name: esync-frequency-supported356 type: nest357 multi-attr: true358 nested-attributes: frequency-range359 doc: |360 If provided a pin is capable of embedding a SYNC signal (within given361 range) into its base frequency signal.362 -363 name: esync-pulse364 type: u32365 doc: |366 A ratio of high to low state of a SYNC signal pulse embedded367 into base clock frequency. Value is in percents.368 -369 name: pin-parent-device370 subset-of: pin371 attributes:372 -373 name: parent-id374 -375 name: direction376 -377 name: prio378 -379 name: state380 -381 name: phase-offset382 -383 name: pin-parent-pin384 subset-of: pin385 attributes:386 -387 name: parent-id388 -389 name: state390 -391 name: frequency-range392 subset-of: pin393 attributes:394 -395 name: frequency-min396 -397 name: frequency-max398 399operations:400 enum-name: dpll_cmd401 list:402 -403 name: device-id-get404 doc: |405 Get id of dpll device that matches given attributes406 attribute-set: dpll407 flags: [ admin-perm ]408 409 do:410 pre: dpll-lock-doit411 post: dpll-unlock-doit412 request:413 attributes:414 - module-name415 - clock-id416 - type417 reply:418 attributes:419 - id420 421 -422 name: device-get423 doc: |424 Get list of DPLL devices (dump) or attributes of a single dpll device425 attribute-set: dpll426 flags: [ admin-perm ]427 428 do:429 pre: dpll-pre-doit430 post: dpll-post-doit431 request:432 attributes:433 - id434 reply: &dev-attrs435 attributes:436 - id437 - module-name438 - mode439 - mode-supported440 - lock-status441 - lock-status-error442 - temp443 - clock-id444 - type445 446 dump:447 reply: *dev-attrs448 449 -450 name: device-set451 doc: Set attributes for a DPLL device452 attribute-set: dpll453 flags: [ admin-perm ]454 455 do:456 pre: dpll-pre-doit457 post: dpll-post-doit458 request:459 attributes:460 - id461 -462 name: device-create-ntf463 doc: Notification about device appearing464 notify: device-get465 mcgrp: monitor466 -467 name: device-delete-ntf468 doc: Notification about device disappearing469 notify: device-get470 mcgrp: monitor471 -472 name: device-change-ntf473 doc: Notification about device configuration being changed474 notify: device-get475 mcgrp: monitor476 -477 name: pin-id-get478 doc: |479 Get id of a pin that matches given attributes480 attribute-set: pin481 flags: [ admin-perm ]482 483 do:484 pre: dpll-lock-doit485 post: dpll-unlock-doit486 request:487 attributes:488 - module-name489 - clock-id490 - board-label491 - panel-label492 - package-label493 - type494 reply:495 attributes:496 - id497 498 -499 name: pin-get500 doc: |501 Get list of pins and its attributes.502 503 - dump request without any attributes given - list all the pins in the504 system505 - dump request with target dpll - list all the pins registered with506 a given dpll device507 - do request with target dpll and target pin - single pin attributes508 attribute-set: pin509 flags: [ admin-perm ]510 511 do:512 pre: dpll-pin-pre-doit513 post: dpll-pin-post-doit514 request:515 attributes:516 - id517 reply: &pin-attrs518 attributes:519 - id520 - board-label521 - panel-label522 - package-label523 - type524 - frequency525 - frequency-supported526 - capabilities527 - parent-device528 - parent-pin529 - phase-adjust-min530 - phase-adjust-max531 - phase-adjust532 - fractional-frequency-offset533 - esync-frequency534 - esync-frequency-supported535 - esync-pulse536 537 dump:538 request:539 attributes:540 - id541 reply: *pin-attrs542 543 -544 name: pin-set545 doc: Set attributes of a target pin546 attribute-set: pin547 flags: [ admin-perm ]548 549 do:550 pre: dpll-pin-pre-doit551 post: dpll-pin-post-doit552 request:553 attributes:554 - id555 - frequency556 - direction557 - prio558 - state559 - parent-device560 - parent-pin561 - phase-adjust562 - esync-frequency563 -564 name: pin-create-ntf565 doc: Notification about pin appearing566 notify: pin-get567 mcgrp: monitor568 -569 name: pin-delete-ntf570 doc: Notification about pin disappearing571 notify: pin-get572 mcgrp: monitor573 -574 name: pin-change-ntf575 doc: Notification about pin configuration being changed576 notify: pin-get577 mcgrp: monitor578 579mcast-groups:580 list:581 -582 name: monitor583