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