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