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 reply: *dev-attrs 388 389 - 390 name: device-set 391 doc: Set attributes for a DPLL device 392 attribute-set: dpll 393 flags: [ admin-perm ] 394 395 do: 396 pre: dpll-pre-doit 397 post: dpll-post-doit 398 request: 399 attributes: 400 - id 401 - 402 name: device-create-ntf 403 doc: Notification about device appearing 404 notify: device-get 405 mcgrp: monitor 406 - 407 name: device-delete-ntf 408 doc: Notification about device disappearing 409 notify: device-get 410 mcgrp: monitor 411 - 412 name: device-change-ntf 413 doc: Notification about device configuration being changed 414 notify: device-get 415 mcgrp: monitor 416 - 417 name: pin-id-get 418 doc: | 419 Get id of a pin that matches given attributes 420 attribute-set: pin 421 flags: [ admin-perm ] 422 423 do: 424 pre: dpll-lock-doit 425 post: dpll-unlock-doit 426 request: 427 attributes: 428 - module-name 429 - clock-id 430 - board-label 431 - panel-label 432 - package-label 433 - type 434 reply: 435 attributes: 436 - id 437 438 - 439 name: pin-get 440 doc: | 441 Get list of pins and its attributes. 442 - dump request without any attributes given - list all the pins in the 443 system 444 - dump request with target dpll - list all the pins registered with 445 a given dpll device 446 - do request with target dpll and target pin - single pin attributes 447 attribute-set: pin 448 flags: [ admin-perm ] 449 450 do: 451 pre: dpll-pin-pre-doit 452 post: dpll-pin-post-doit 453 request: 454 attributes: 455 - id 456 reply: &pin-attrs 457 attributes: 458 - id 459 - board-label 460 - panel-label 461 - package-label 462 - type 463 - frequency 464 - frequency-supported 465 - capabilities 466 - parent-device 467 - parent-pin 468 - phase-adjust-min 469 - phase-adjust-max 470 - phase-adjust 471 - fractional-frequency-offset 472 473 dump: 474 request: 475 attributes: 476 - id 477 reply: *pin-attrs 478 479 - 480 name: pin-set 481 doc: Set attributes of a target pin 482 attribute-set: pin 483 flags: [ admin-perm ] 484 485 do: 486 pre: dpll-pin-pre-doit 487 post: dpll-pin-post-doit 488 request: 489 attributes: 490 - id 491 - frequency 492 - direction 493 - prio 494 - state 495 - parent-device 496 - parent-pin 497 - phase-adjust 498 - 499 name: pin-create-ntf 500 doc: Notification about pin appearing 501 notify: pin-get 502 mcgrp: monitor 503 - 504 name: pin-delete-ntf 505 doc: Notification about pin disappearing 506 notify: pin-get 507 mcgrp: monitor 508 - 509 name: pin-change-ntf 510 doc: Notification about pin configuration being changed 511 notify: pin-get 512 mcgrp: monitor 513 514mcast-groups: 515 list: 516 - 517 name: monitor 518