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