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 reply: *dev-attrs 427 428 - 429 name: device-set 430 doc: Set attributes for a DPLL device 431 attribute-set: dpll 432 flags: [ admin-perm ] 433 434 do: 435 pre: dpll-pre-doit 436 post: dpll-post-doit 437 request: 438 attributes: 439 - id 440 - 441 name: device-create-ntf 442 doc: Notification about device appearing 443 notify: device-get 444 mcgrp: monitor 445 - 446 name: device-delete-ntf 447 doc: Notification about device disappearing 448 notify: device-get 449 mcgrp: monitor 450 - 451 name: device-change-ntf 452 doc: Notification about device configuration being changed 453 notify: device-get 454 mcgrp: monitor 455 - 456 name: pin-id-get 457 doc: | 458 Get id of a pin that matches given attributes 459 attribute-set: pin 460 flags: [ admin-perm ] 461 462 do: 463 pre: dpll-lock-doit 464 post: dpll-unlock-doit 465 request: 466 attributes: 467 - module-name 468 - clock-id 469 - board-label 470 - panel-label 471 - package-label 472 - type 473 reply: 474 attributes: 475 - id 476 477 - 478 name: pin-get 479 doc: | 480 Get list of pins and its attributes. 481 - dump request without any attributes given - list all the pins in the 482 system 483 - dump request with target dpll - list all the pins registered with 484 a given dpll device 485 - do request with target dpll and target pin - single pin attributes 486 attribute-set: pin 487 flags: [ admin-perm ] 488 489 do: 490 pre: dpll-pin-pre-doit 491 post: dpll-pin-post-doit 492 request: 493 attributes: 494 - id 495 reply: &pin-attrs 496 attributes: 497 - id 498 - board-label 499 - panel-label 500 - package-label 501 - type 502 - frequency 503 - frequency-supported 504 - capabilities 505 - parent-device 506 - parent-pin 507 - phase-adjust-min 508 - phase-adjust-max 509 - phase-adjust 510 - fractional-frequency-offset 511 512 dump: 513 request: 514 attributes: 515 - id 516 reply: *pin-attrs 517 518 - 519 name: pin-set 520 doc: Set attributes of a target pin 521 attribute-set: pin 522 flags: [ admin-perm ] 523 524 do: 525 pre: dpll-pin-pre-doit 526 post: dpll-pin-post-doit 527 request: 528 attributes: 529 - id 530 - frequency 531 - direction 532 - prio 533 - state 534 - parent-device 535 - parent-pin 536 - phase-adjust 537 - 538 name: pin-create-ntf 539 doc: Notification about pin appearing 540 notify: pin-get 541 mcgrp: monitor 542 - 543 name: pin-delete-ntf 544 doc: Notification about pin disappearing 545 notify: pin-get 546 mcgrp: monitor 547 - 548 name: pin-change-ntf 549 doc: Notification about pin configuration being changed 550 notify: pin-get 551 mcgrp: monitor 552 553mcast-groups: 554 list: 555 - 556 name: monitor 557