path: root/Documentation/netlink/specs/dpll.yaml

# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)

name: dpll

doc: DPLL subsystem.

definitions:
  -
    type: enum
    name: mode
    doc: |
      working modes a dpll can support, differentiates if and how dpll selects
      one of its inputs to syntonize with it, valid values for DPLL_A_MODE
      attribute
    entries:
      -
        name: manual
        doc: input can be only selected by sending a request to dpll
        value: 1
      -
        name: automatic
        doc: highest prio input pin auto selected by dpll
    render-max: true
  -
    type: enum
    name: lock-status
    doc: |
      provides information of dpll device lock status, valid values for
      DPLL_A_LOCK_STATUS attribute
    entries:
      -
        name: unlocked
        doc: |
          dpll was not yet locked to any valid input (or forced by setting
          DPLL_A_MODE to DPLL_MODE_DETACHED)
        value: 1
      -
        name: locked
        doc: |
          dpll is locked to a valid signal, but no holdover available
      -
        name: locked-ho-acq
        doc: |
          dpll is locked and holdover acquired
      -
        name: holdover
        doc: |
          dpll is in holdover state - lost a valid lock or was forced
          by disconnecting all the pins (latter possible only
          when dpll lock-state was already DPLL_LOCK_STATUS_LOCKED_HO_ACQ,
          if dpll lock-state was not DPLL_LOCK_STATUS_LOCKED_HO_ACQ, the
          dpll's lock-state shall remain DPLL_LOCK_STATUS_UNLOCKED)
    render-max: true
  -
    type: const
    name: temp-divider
    value: 1000
    doc: |
      temperature divider allowing userspace to calculate the
      temperature as float with three digit decimal precision.
      Value of (DPLL_A_TEMP / DPLL_TEMP_DIVIDER) is integer part of
      temperature value.
      Value of (DPLL_A_TEMP % DPLL_TEMP_DIVIDER) is fractional part of
      temperature value.
  -
    type: enum
    name: type
    doc: type of dpll, valid values for DPLL_A_TYPE attribute
    entries:
      -
        name: pps
        doc: dpll produces Pulse-Per-Second signal
        value: 1
      -
        name: eec
        doc: dpll drives the Ethernet Equipment Clock
    render-max: true
  -
    type: enum
    name: pin-type
    doc: |
      defines possible types of a pin, valid values for DPLL_A_PIN_TYPE
      attribute
    entries:
      -
        name: mux
        doc: aggregates another layer of selectable pins
        value: 1
      -
        name: ext
        doc: external input
      -
        name: synce-eth-port
        doc: ethernet port PHY's recovered clock
      -
        name: int-oscillator
        doc: device internal oscillator
      -
        name: gnss
        doc: GNSS recovered clock
    render-max: true
  -
    type: enum
    name: pin-direction
    doc: |
      defines possible direction of a pin, valid values for
      DPLL_A_PIN_DIRECTION attribute
    entries:
      -
        name: input
        doc: pin used as a input of a signal
        value: 1
      -
        name: output
        doc: pin used to output the signal
    render-max: true
  -
    type: const
    name: pin-frequency-1-hz
    value: 1
  -
    type: const
    name: pin-frequency-10-khz
    value: 10000
  -
    type: const
    name: pin-frequency-77_5-khz
    value: 77500
  -
    type: const
    name: pin-frequency-10-mhz
    value: 10000000
  -
    type: enum
    name: pin-state
    doc: |
      defines possible states of a pin, valid values for
      DPLL_A_PIN_STATE attribute
    entries:
      -
        name: connected
        doc: pin connected, active input of phase locked loop
        value: 1
      -
        name: disconnected
        doc: pin disconnected, not considered as a valid input
      -
        name: selectable
        doc: pin enabled for automatic input selection
    render-max: true
  -
    type: flags
    name: pin-capabilities
    doc: |
      defines possible capabilities of a pin, valid flags on
      DPLL_A_PIN_CAPABILITIES attribute
    entries:
      -
        name: direction-can-change
        doc: pin direction can be changed
      -
        name: priority-can-change
        doc: pin priority can be changed
      -
        name: state-can-change
        doc: pin state can be changed
  -
    type: const
    name: phase-offset-divider
    value: 1000
    doc: |
      phase offset divider allows userspace to calculate a value of
      measured signal phase difference between a pin and dpll device
      as a fractional value with three digit decimal precision.
      Value of (DPLL_A_PHASE_OFFSET / DPLL_PHASE_OFFSET_DIVIDER) is an
      integer part of a measured phase offset value.
      Value of (DPLL_A_PHASE_OFFSET % DPLL_PHASE_OFFSET_DIVIDER) is a
      fractional part of a measured phase offset value.

attribute-sets:
  -
    name: dpll
    enum-name: dpll_a
    attributes:
      -
        name: id
        type: u32
      -
        name: module-name
        type: string
      -
        name: pad
        type: pad
      -
        name: clock-id
        type: u64
      -
        name: mode
        type: u32
        enum: mode
      -
        name: mode-supported
        type: u32
        enum: mode
        multi-attr: true
      -
        name: lock-status
        type: u32
        enum: lock-status
      -
        name: temp
        type: s32
      -
        name: type
        type: u32
        enum: type
  -
    name: pin
    enum-name: dpll_a_pin
    attributes:
      -
        name: id
        type: u32
      -
        name: parent-id
        type: u32
      -
        name: module-name
        type: string
      -
        name: pad
        type: pad
      -
        name: clock-id
        type: u64
      -
        name: board-label
        type: string
      -
        name: panel-label
        type: string
      -
        name: package-label
        type: string
      -
        name: type
        type: u32
        enum: pin-type
      -
        name: direction
        type: u32
        enum: pin-direction
      -
        name: frequency
        type: u64
      -
        name: frequency-supported
        type: nest
        multi-attr: true
        nested-attributes: frequency-range
      -
        name: frequency-min
        type: u64
      -
        name: frequency-max
        type: u64
      -
        name: prio
        type: u32
      -
        name: state
        type: u32
        enum: pin-state
      -
        name: capabilities
        type: u32
      -
        name: parent-device
        type: nest
        multi-attr: true
        nested-attributes: pin-parent-device
      -
        name: parent-pin
        type: nest
        multi-attr: true
        nested-attributes: pin-parent-pin
      -
        name: phase-adjust-min
        type: s32
      -
        name: phase-adjust-max
        type: s32
      -
        name: phase-adjust
        type: s32
      -
        name: phase-offset
        type: s64
      -
        name: fractional-frequency-offset
        type: sint
        doc: |
          The FFO (Fractional Frequency Offset) between the RX and TX
          symbol rate on the media associated with the pin:
          (rx_frequency-tx_frequency)/rx_frequency
          Value is in PPM (parts per million).
          This may be implemented for example for pin of type
          PIN_TYPE_SYNCE_ETH_PORT.
  -
    name: pin-parent-device
    subset-of: pin
    attributes:
      -
        name: parent-id
      -
        name: direction
      -
        name: prio
      -
        name: state
      -
        name: phase-offset
  -
    name: pin-parent-pin
    subset-of: pin
    attributes:
      -
        name: parent-id
      -
        name: state
  -
    name: frequency-range
    subset-of: pin
    attributes:
      -
        name: frequency-min
      -
        name: frequency-max

operations:
  enum-name: dpll_cmd
  list:
    -
      name: device-id-get
      doc: |
        Get id of dpll device that matches given attributes
      attribute-set: dpll
      flags: [ admin-perm ]

      do:
        pre: dpll-lock-doit
        post: dpll-unlock-doit
        request:
          attributes:
            - module-name
            - clock-id
            - type
        reply:
          attributes:
            - id

    -
      name: device-get
      doc: |
        Get list of DPLL devices (dump) or attributes of a single dpll device
      attribute-set: dpll
      flags: [ admin-perm ]

      do:
        pre: dpll-pre-doit
        post: dpll-post-doit
        request:
          attributes:
            - id
        reply: &dev-attrs
          attributes:
            - id
            - module-name
            - mode
            - mode-supported
            - lock-status
            - temp
            - clock-id
            - type

      dump:
        pre: dpll-lock-dumpit
        post: dpll-unlock-dumpit
        reply: *dev-attrs

    -
      name: device-set
      doc: Set attributes for a DPLL device
      attribute-set: dpll
      flags: [ admin-perm ]

      do:
        pre: dpll-pre-doit
        post: dpll-post-doit
        request:
          attributes:
            - id
    -
      name: device-create-ntf
      doc: Notification about device appearing
      notify: device-get
      mcgrp: monitor
    -
      name: device-delete-ntf
      doc: Notification about device disappearing
      notify: device-get
      mcgrp: monitor
    -
      name: device-change-ntf
      doc: Notification about device configuration being changed
      notify: device-get
      mcgrp: monitor
    -
      name: pin-id-get
      doc: |
        Get id of a pin that matches given attributes
      attribute-set: pin
      flags: [ admin-perm ]

      do:
        pre: dpll-lock-doit
        post: dpll-unlock-doit
        request:
          attributes:
            - module-name
            - clock-id
            - board-label
            - panel-label
            - package-label
            - type
        reply:
          attributes:
            - id

    -
      name: pin-get
      doc: |
        Get list of pins and its attributes.
        - dump request without any attributes given - list all the pins in the
          system
        - dump request with target dpll - list all the pins registered with
          a given dpll device
        - do request with target dpll and target pin - single pin attributes
      attribute-set: pin
      flags: [ admin-perm ]

      do:
        pre: dpll-pin-pre-doit
        post: dpll-pin-post-doit
        request:
          attributes:
            - id
        reply: &pin-attrs
          attributes:
            - id
            - board-label
            - panel-label
            - package-label
            - type
            - frequency
            - frequency-supported
            - capabilities
            - parent-device
            - parent-pin
            - phase-adjust-min
            - phase-adjust-max
            - phase-adjust
            - fractional-frequency-offset

      dump:
        pre: dpll-lock-dumpit
        post: dpll-unlock-dumpit
        request:
          attributes:
            - id
        reply: *pin-attrs

    -
      name: pin-set
      doc: Set attributes of a target pin
      attribute-set: pin
      flags: [ admin-perm ]

      do:
        pre: dpll-pin-pre-doit
        post: dpll-pin-post-doit
        request:
          attributes:
            - id
            - frequency
            - direction
            - prio
            - state
            - parent-device
            - parent-pin
            - phase-adjust
    -
      name: pin-create-ntf
      doc: Notification about pin appearing
      notify: pin-get
      mcgrp: monitor
    -
      name: pin-delete-ntf
      doc: Notification about pin disappearing
      notify: pin-get
      mcgrp: monitor
    -
      name: pin-change-ntf
      doc: Notification about pin configuration being changed
      notify: pin-get
      mcgrp: monitor

mcast-groups:
  list:
    -
      name: monitor