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