Documentation/netlink/specs/dpll.yaml

   1 # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
   2
   3 name: dpll
   4
   5 doc: DPLL subsystem.
   6
   7 definitions:
   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
 214 attribute-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
 379 operations:
 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
 554 mcast-groups:
 555   list:
 556     -
 557       name: monitor