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: pin-parent-device 350 subset-of: pin 351 attributes: 352 - 353 name: parent-id 354 - 355 name: direction 356 - 357 name: prio 358 - 359 name: state 360 - 361 name: phase-offset 362 - 363 name: pin-parent-pin 364 subset-of: pin 365 attributes: 366 - 367 name: parent-id 368 - 369 name: state 370 - 371 name: frequency-range 372 subset-of: pin 373 attributes: 374 - 375 name: frequency-min 376 - 377 name: frequency-max 378 379operations: 380 enum-name: dpll_cmd 381 list: 382 - 383 name: device-id-get 384 doc: | 385 Get id of dpll device that matches given attributes 386 attribute-set: dpll 387 flags: [ admin-perm ] 388 389 do: 390 pre: dpll-lock-doit 391 post: dpll-unlock-doit 392 request: 393 attributes: 394 - module-name 395 - clock-id 396 - type 397 reply: 398 attributes: 399 - id 400 401 - 402 name: device-get 403 doc: | 404 Get list of DPLL devices (dump) or attributes of a single dpll device 405 attribute-set: dpll 406 flags: [ admin-perm ] 407 408 do: 409 pre: dpll-pre-doit 410 post: dpll-post-doit 411 request: 412 attributes: 413 - id 414 reply: &dev-attrs 415 attributes: 416 - id 417 - module-name 418 - mode 419 - mode-supported 420 - lock-status 421 - lock-status-error 422 - temp 423 - clock-id 424 - type 425 426 dump: 427 reply: *dev-attrs 428 429 - 430 name: device-set 431 doc: Set attributes for a DPLL device 432 attribute-set: dpll 433 flags: [ admin-perm ] 434 435 do: 436 pre: dpll-pre-doit 437 post: dpll-post-doit 438 request: 439 attributes: 440 - id 441 - 442 name: device-create-ntf 443 doc: Notification about device appearing 444 notify: device-get 445 mcgrp: monitor 446 - 447 name: device-delete-ntf 448 doc: Notification about device disappearing 449 notify: device-get 450 mcgrp: monitor 451 - 452 name: device-change-ntf 453 doc: Notification about device configuration being changed 454 notify: device-get 455 mcgrp: monitor 456 - 457 name: pin-id-get 458 doc: | 459 Get id of a pin that matches given attributes 460 attribute-set: pin 461 flags: [ admin-perm ] 462 463 do: 464 pre: dpll-lock-doit 465 post: dpll-unlock-doit 466 request: 467 attributes: 468 - module-name 469 - clock-id 470 - board-label 471 - panel-label 472 - package-label 473 - type 474 reply: 475 attributes: 476 - id 477 478 - 479 name: pin-get 480 doc: | 481 Get list of pins and its attributes. 482 - dump request without any attributes given - list all the pins in the 483 system 484 - dump request with target dpll - list all the pins registered with 485 a given dpll device 486 - do request with target dpll and target pin - single pin attributes 487 attribute-set: pin 488 flags: [ admin-perm ] 489 490 do: 491 pre: dpll-pin-pre-doit 492 post: dpll-pin-post-doit 493 request: 494 attributes: 495 - id 496 reply: &pin-attrs 497 attributes: 498 - id 499 - board-label 500 - panel-label 501 - package-label 502 - type 503 - frequency 504 - frequency-supported 505 - capabilities 506 - parent-device 507 - parent-pin 508 - phase-adjust-min 509 - phase-adjust-max 510 - phase-adjust 511 - fractional-frequency-offset 512 513 dump: 514 request: 515 attributes: 516 - id 517 reply: *pin-attrs 518 519 - 520 name: pin-set 521 doc: Set attributes of a target pin 522 attribute-set: pin 523 flags: [ admin-perm ] 524 525 do: 526 pre: dpll-pin-pre-doit 527 post: dpll-pin-post-doit 528 request: 529 attributes: 530 - id 531 - frequency 532 - direction 533 - prio 534 - state 535 - parent-device 536 - parent-pin 537 - phase-adjust 538 - 539 name: pin-create-ntf 540 doc: Notification about pin appearing 541 notify: pin-get 542 mcgrp: monitor 543 - 544 name: pin-delete-ntf 545 doc: Notification about pin disappearing 546 notify: pin-get 547 mcgrp: monitor 548 - 549 name: pin-change-ntf 550 doc: Notification about pin configuration being changed 551 notify: pin-get 552 mcgrp: monitor 553 554mcast-groups: 555 list: 556 - 557 name: monitor 558