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       -
 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
 340 operations:
 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
 514 mcast-groups:
 515   list:
 516     -
 517       name: monitor