.. LINENO 2

.. SPDX-License-Identifier: GPL-2.0
.. NOTE: This document was auto-generated.


.. _netlink-dpll:


=====================================
Family ``dpll`` netlink specification
=====================================


.. contents:: :depth: 3


-------
Summary
-------


DPLL subsystem.

----------
Operations
----------


.. LINENO 573

.. _dpll-operation-device-id-get:

device-id-get
=============
Get id of dpll device that matches given attributes


:attribute-set: :ref:`dpll-attribute-set-dpll`
:flags: [``admin-perm``]
:do:
.. LINENO 580

    **pre**
        dpll-lock-doit

    **post**
        dpll-unlock-doit

    **request**
        :attributes: [``module-name``, ``clock-id``, ``type``]

    **reply**
        :attributes: [``id``]



.. LINENO 592

.. _dpll-operation-device-get:

device-get
==========
Get list of DPLL devices (dump) or attributes of a single dpll device


:attribute-set: :ref:`dpll-attribute-set-dpll`
:flags: [``admin-perm``]
:do:
.. LINENO 599

    **pre**
        dpll-pre-doit

    **post**
        dpll-post-doit

    **request**
        :attributes: [``id``]

    **reply**
        :attributes: [``id``, ``module-name``, ``mode``, ``mode-supported``, ``lock-status``, ``lock-status-error``, ``temp``, ``clock-id``, ``type``, ``phase-offset-monitor``, ``phase-offset-avg-factor``, ``frequency-monitor``]

:dump:
.. LINENO 620

    **reply**
        :attributes: [``id``, ``module-name``, ``mode``, ``mode-supported``, ``lock-status``, ``lock-status-error``, ``temp``, ``clock-id``, ``type``, ``phase-offset-monitor``, ``phase-offset-avg-factor``, ``frequency-monitor``]



.. LINENO 623

.. _dpll-operation-device-set:

device-set
==========
Set attributes for a DPLL device

:attribute-set: :ref:`dpll-attribute-set-dpll`
:flags: [``admin-perm``]
:do:
.. LINENO 629

    **pre**
        dpll-pre-doit

    **post**
        dpll-post-doit

    **request**
        :attributes: [``id``, ``mode``, ``phase-offset-monitor``, ``phase-offset-avg-factor``, ``frequency-monitor``]



.. LINENO 639

.. _dpll-operation-device-create-ntf:

device-create-ntf
=================
Notification about device appearing

:notify: device-get
:mcgrp: monitor


.. LINENO 644

.. _dpll-operation-device-delete-ntf:

device-delete-ntf
=================
Notification about device disappearing

:notify: device-get
:mcgrp: monitor


.. LINENO 649

.. _dpll-operation-device-change-ntf:

device-change-ntf
=================
Notification about device configuration being changed

:notify: device-get
:mcgrp: monitor


.. LINENO 654

.. _dpll-operation-pin-id-get:

pin-id-get
==========
Get id of a pin that matches given attributes


:attribute-set: :ref:`dpll-attribute-set-pin`
:flags: [``admin-perm``]
:do:
.. LINENO 661

    **pre**
        dpll-lock-doit

    **post**
        dpll-unlock-doit

    **request**
        :attributes: [``module-name``, ``clock-id``, ``board-label``, ``panel-label``, ``package-label``, ``type``]

    **reply**
        :attributes: [``id``]



.. LINENO 676

.. _dpll-operation-pin-get:

pin-get
=======
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: :ref:`dpll-attribute-set-pin`
:flags: [``admin-perm``]
:do:
.. LINENO 689

    **pre**
        dpll-pin-pre-doit

    **post**
        dpll-pin-post-doit

    **request**
        :attributes: [``id``]

    **reply**
        :attributes: [``id``, ``module-name``, ``clock-id``, ``board-label``, ``panel-label``, ``package-label``, ``type``, ``frequency``, ``frequency-supported``, ``capabilities``, ``parent-device``, ``parent-pin``, ``phase-adjust-gran``, ``phase-adjust-min``, ``phase-adjust-max``, ``phase-adjust``, ``fractional-frequency-offset``, ``fractional-frequency-offset-ppt``, ``esync-frequency``, ``esync-frequency-supported``, ``esync-pulse``, ``reference-sync``, ``measured-frequency``]

:dump:
.. LINENO 721

    **request**
        :attributes: [``id``]

    **reply**
        :attributes: [``id``, ``module-name``, ``clock-id``, ``board-label``, ``panel-label``, ``package-label``, ``type``, ``frequency``, ``frequency-supported``, ``capabilities``, ``parent-device``, ``parent-pin``, ``phase-adjust-gran``, ``phase-adjust-min``, ``phase-adjust-max``, ``phase-adjust``, ``fractional-frequency-offset``, ``fractional-frequency-offset-ppt``, ``esync-frequency``, ``esync-frequency-supported``, ``esync-pulse``, ``reference-sync``, ``measured-frequency``]



.. LINENO 727

.. _dpll-operation-pin-set:

pin-set
=======
Set attributes of a target pin

:attribute-set: :ref:`dpll-attribute-set-pin`
:flags: [``admin-perm``]
:do:
.. LINENO 733

    **pre**
        dpll-pin-pre-doit

    **post**
        dpll-pin-post-doit

    **request**
        :attributes: [``id``, ``frequency``, ``direction``, ``prio``, ``state``, ``parent-device``, ``parent-pin``, ``phase-adjust``, ``esync-frequency``, ``reference-sync``]



.. LINENO 748

.. _dpll-operation-pin-create-ntf:

pin-create-ntf
==============
Notification about pin appearing

:notify: pin-get
:mcgrp: monitor


.. LINENO 753

.. _dpll-operation-pin-delete-ntf:

pin-delete-ntf
==============
Notification about pin disappearing

:notify: pin-get
:mcgrp: monitor


.. LINENO 758

.. _dpll-operation-pin-change-ntf:

pin-change-ntf
==============
Notification about pin configuration being changed

:notify: pin-get
:mcgrp: monitor



----------------
Multicast groups
----------------


- monitor

-----------
Definitions
-----------


.. LINENO 8

.. _dpll-definition-mode:

mode
====
:type: enum
: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:
    :manual: input can be only selected by sending a request to dpll
    :automatic: highest prio input pin auto selected by dpll


.. LINENO 24

.. _dpll-definition-lock-status:

lock-status
===========
:type: enum
:doc: provides information of dpll device lock status, valid values for DPLL_A_LOCK_STATUS attribute


:entries:
    :unlocked: dpll was not yet locked to any valid input (or forced by setting DPLL_A_MODE to DPLL_MODE_DETACHED)
    :locked: dpll is locked to a valid signal, but no holdover available
    :locked-ho-acq: dpll is locked and holdover acquired
    :holdover: 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)


.. LINENO 54

.. _dpll-definition-lock-status-error:

lock-status-error
=================
:type: enum
:doc: if previous status change was done due to a failure, this provides information of dpll device lock status error. Valid values for DPLL_A_LOCK_STATUS_ERROR attribute


:entries:
    :none: dpll device lock status was changed without any error
    :undefined: dpll device lock status was changed due to undefined error. Driver fills this value up in case it is not able to obtain suitable exact error type.
    :media-down: dpll device lock status was changed because of associated media got down. This may happen for example if dpll device was previously locked on an input pin of type PIN_TYPE_SYNCE_ETH_PORT.
    :fractional-frequency-offset-too-high: the FFO (Fractional Frequency Offset) between the RX and TX symbol rate on the media got too high. This may happen for example if dpll device was previously locked on an input pin of type PIN_TYPE_SYNCE_ETH_PORT.


.. LINENO 88

.. _dpll-definition-clock-quality-level:

clock-quality-level
===================
:type: enum
:doc: level of quality of a clock device. This mainly applies when the dpll lock-status is DPLL_LOCK_STATUS_HOLDOVER. The current list is defined according to the table 11-7 contained in ITU-T G.8264/Y.1364 document. One may extend this list freely by other ITU-T defined clock qualities, or different ones defined by another standardization body (for those, please use different prefix).


:entries:
    :itu-opt1-prc: 
    :itu-opt1-ssu-a: 
    :itu-opt1-ssu-b: 
    :itu-opt1-eec1: 
    :itu-opt1-prtc: 
    :itu-opt1-eprtc: 
    :itu-opt1-eeec: 
    :itu-opt1-eprc: 


.. LINENO 118

.. _dpll-definition-temp-divider:

temp-divider
============
:type: const
: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.


.. LINENO 129

.. _dpll-definition-type:

type
====
:type: enum
:doc: type of dpll, valid values for DPLL_A_TYPE attribute


:entries:
    :pps: dpll produces Pulse-Per-Second signal
    :eec: dpll drives the Ethernet Equipment Clock


.. LINENO 142

.. _dpll-definition-pin-type:

pin-type
========
:type: enum
:doc: defines possible types of a pin, valid values for DPLL_A_PIN_TYPE attribute


:entries:
    :mux: aggregates another layer of selectable pins
    :ext: external input
    :synce-eth-port: ethernet port PHY's recovered clock
    :int-oscillator: device internal oscillator
    :gnss: GNSS recovered clock


.. LINENO 166

.. _dpll-definition-pin-direction:

pin-direction
=============
:type: enum
:doc: defines possible direction of a pin, valid values for DPLL_A_PIN_DIRECTION attribute


:entries:
    :input: pin used as a input of a signal
    :output: pin used to output the signal


.. LINENO 181

.. _dpll-definition-pin-frequency-1-hz:

pin-frequency-1-hz
==================
:type: const
:value: 1


.. LINENO 185

.. _dpll-definition-pin-frequency-10-khz:

pin-frequency-10-khz
====================
:type: const
:value: 10000


.. LINENO 189

.. _dpll-definition-pin-frequency-77-5-khz:

pin-frequency-77-5-khz
======================
:type: const
:value: 77500


.. LINENO 193

.. _dpll-definition-pin-frequency-10-mhz:

pin-frequency-10-mhz
====================
:type: const
:value: 10000000


.. LINENO 197

.. _dpll-definition-pin-state:

pin-state
=========
:type: enum
:doc: defines possible states of a pin, valid values for DPLL_A_PIN_STATE attribute


:entries:
    :connected: pin connected, active input of phase locked loop
    :disconnected: pin disconnected, not considered as a valid input
    :selectable: pin enabled for automatic input selection


.. LINENO 215

.. _dpll-definition-pin-operstate:

pin-operstate
=============
:type: enum
:doc: defines possible operational states of a pin with respect to its parent DPLL device, valid values for DPLL_A_PIN_OPERSTATE attribute


:entries:
    :active: pin is qualified and actively used by the DPLL
    :standby: pin is qualified but not actively used by the DPLL
    :no-signal: pin does not have a valid signal
    :qual-failed: pin signal failed qualification (e.g. frequency or phase monitor)


.. LINENO 236

.. _dpll-definition-pin-capabilities:

pin-capabilities
================
:type: flags
:doc: defines possible capabilities of a pin, valid flags on DPLL_A_PIN_CAPABILITIES attribute


:entries:
    :direction-can-change: pin direction can be changed
    :priority-can-change: pin priority can be changed
    :state-can-change: pin state can be changed


.. LINENO 252

.. _dpll-definition-phase-offset-divider:

phase-offset-divider
====================
:type: const
: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.


.. LINENO 264

.. _dpll-definition-pin-measured-frequency-divider:

pin-measured-frequency-divider
==============================
:type: const
:value: 1000
:doc: pin measured frequency divider allows userspace to calculate a value of measured input frequency as a fractional value with three digit decimal precision (millihertz). Value of (DPLL_A_PIN_MEASURED_FREQUENCY / DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is an integer part of a measured frequency value. Value of (DPLL_A_PIN_MEASURED_FREQUENCY % DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is a fractional part of a measured frequency value.


.. LINENO 278

.. _dpll-definition-feature-state:

feature-state
=============
:type: enum
:doc: Allow control (enable/disable) and status checking over features.


:entries:
    :disable: feature shall be disabled
    :enable: feature shall be enabled



--------------
Attribute sets
--------------


.. _dpll-attribute-set-dpll:

dpll
====
.. LINENO 298

id (``u32``)
~~~~~~~~~~~~


.. LINENO 301

module-name (``string``)
~~~~~~~~~~~~~~~~~~~~~~~~


.. LINENO 304

pad (``pad``)
~~~~~~~~~~~~~


.. LINENO 307

clock-id (``u64``)
~~~~~~~~~~~~~~~~~~


.. LINENO 310

mode (``u32``)
~~~~~~~~~~~~~~
:enum: :ref:`dpll-definition-mode`


.. LINENO 314

mode-supported (``u32``)
~~~~~~~~~~~~~~~~~~~~~~~~
:enum: :ref:`dpll-definition-mode`
:multi-attr: True


.. LINENO 319

lock-status (``u32``)
~~~~~~~~~~~~~~~~~~~~~
:enum: :ref:`dpll-definition-lock-status`


.. LINENO 323

temp (``s32``)
~~~~~~~~~~~~~~


.. LINENO 326

type (``u32``)
~~~~~~~~~~~~~~
:enum: :ref:`dpll-definition-type`


.. LINENO 330

lock-status-error (``u32``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
:enum: :ref:`dpll-definition-lock-status-error`


.. LINENO 334

clock-quality-level (``u32``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:enum: :ref:`dpll-definition-clock-quality-level`
:multi-attr: True
:doc: Level of quality of a clock device. This mainly applies when the dpll lock-status is DPLL_LOCK_STATUS_HOLDOVER. This could be put to message multiple times to indicate possible parallel quality levels (e.g. one specified by ITU option 1 and another one specified by option 2).


.. LINENO 345

phase-offset-monitor (``u32``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:enum: :ref:`dpll-definition-feature-state`
:doc: Receive or request state of phase offset monitor feature. If enabled, dpll device shall monitor and notify all currently available inputs for changes of their phase offset against the dpll device.


.. LINENO 353

phase-offset-avg-factor (``u32``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Averaging factor applied to calculation of reported phase offset.


.. LINENO 357

frequency-monitor (``u32``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
:enum: :ref:`dpll-definition-feature-state`
:doc: Current or desired state of the frequency monitor feature. If enabled, dpll device shall measure all currently available inputs for their actual input frequency.


.. _dpll-attribute-set-pin:

pin
===
.. LINENO 368

id (``u32``)
~~~~~~~~~~~~


.. LINENO 371

parent-id (``u32``)
~~~~~~~~~~~~~~~~~~~


.. LINENO 374

module-name (``string``)
~~~~~~~~~~~~~~~~~~~~~~~~


.. LINENO 377

pad (``pad``)
~~~~~~~~~~~~~


.. LINENO 380

clock-id (``u64``)
~~~~~~~~~~~~~~~~~~


.. LINENO 383

board-label (``string``)
~~~~~~~~~~~~~~~~~~~~~~~~


.. LINENO 386

panel-label (``string``)
~~~~~~~~~~~~~~~~~~~~~~~~


.. LINENO 389

package-label (``string``)
~~~~~~~~~~~~~~~~~~~~~~~~~~


.. LINENO 392

type (``u32``)
~~~~~~~~~~~~~~
:enum: :ref:`dpll-definition-pin-type`


.. LINENO 396

direction (``u32``)
~~~~~~~~~~~~~~~~~~~
:enum: :ref:`dpll-definition-pin-direction`


.. LINENO 400

frequency (``u64``)
~~~~~~~~~~~~~~~~~~~


.. LINENO 403

frequency-supported (``nest``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:multi-attr: True
:nested-attributes: :ref:`dpll-attribute-set-frequency-range`


.. LINENO 408

frequency-min (``u64``)
~~~~~~~~~~~~~~~~~~~~~~~


.. LINENO 411

frequency-max (``u64``)
~~~~~~~~~~~~~~~~~~~~~~~


.. LINENO 414

prio (``u32``)
~~~~~~~~~~~~~~


.. LINENO 417

state (``u32``)
~~~~~~~~~~~~~~~
:enum: :ref:`dpll-definition-pin-state`


.. LINENO 421

capabilities (``u32``)
~~~~~~~~~~~~~~~~~~~~~~
:enum: :ref:`dpll-definition-pin-capabilities`


.. LINENO 425

parent-device (``nest``)
~~~~~~~~~~~~~~~~~~~~~~~~
:multi-attr: True
:nested-attributes: :ref:`dpll-attribute-set-pin-parent-device`


.. LINENO 430

parent-pin (``nest``)
~~~~~~~~~~~~~~~~~~~~~
:multi-attr: True
:nested-attributes: :ref:`dpll-attribute-set-pin-parent-pin`


.. LINENO 435

phase-adjust-min (``s32``)
~~~~~~~~~~~~~~~~~~~~~~~~~~


.. LINENO 438

phase-adjust-max (``s32``)
~~~~~~~~~~~~~~~~~~~~~~~~~~


.. LINENO 441

phase-adjust (``s32``)
~~~~~~~~~~~~~~~~~~~~~~


.. LINENO 444

phase-offset (``s64``)
~~~~~~~~~~~~~~~~~~~~~~


.. LINENO 447

fractional-frequency-offset (``sint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The FFO (Fractional Frequency Offset) of the pin. At top level this represents the RX vs TX symbol rate offset on the media associated with the pin. Inside the pin-parent-device nest it represents the frequency offset between the pin and its parent DPLL device. Value is in PPM (parts per million). This is a lower-precision version of fractional-frequency-offset-ppt.


.. LINENO 459

esync-frequency (``u64``)
~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Frequency of Embedded SYNC signal. If provided, the pin is configured with a SYNC signal embedded into its base clock frequency.


.. LINENO 465

esync-frequency-supported (``nest``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:multi-attr: True
:nested-attributes: :ref:`dpll-attribute-set-frequency-range`
:doc: If provided a pin is capable of embedding a SYNC signal (within given range) into its base frequency signal.


.. LINENO 473

esync-pulse (``u32``)
~~~~~~~~~~~~~~~~~~~~~
:doc: A ratio of high to low state of a SYNC signal pulse embedded into base clock frequency. Value is in percents.


.. LINENO 479

reference-sync (``nest``)
~~~~~~~~~~~~~~~~~~~~~~~~~
:multi-attr: True
:nested-attributes: :ref:`dpll-attribute-set-reference-sync`
:doc: Capable pin provides list of pins that can be bound to create a reference-sync pin pair.


.. LINENO 487

phase-adjust-gran (``u32``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Granularity of phase adjustment, in picoseconds. The value of phase adjustment must be a multiple of this granularity.


.. LINENO 493

fractional-frequency-offset-ppt (``sint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The FFO (Fractional Frequency Offset) of the pin. At top level this represents the RX vs TX symbol rate offset on the media associated with the pin. Inside the pin-parent-device nest it represents the frequency offset between the pin and its parent DPLL device. Value is in PPT (parts per trillion, 10^-12). This is a higher-precision version of fractional-frequency-offset.


.. LINENO 505

measured-frequency (``u64``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The measured frequency of the input pin in millihertz (mHz). Value of (DPLL_A_PIN_MEASURED_FREQUENCY / DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is an integer part (Hz) of a measured frequency value. Value of (DPLL_A_PIN_MEASURED_FREQUENCY % DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is a fractional part of a measured frequency value.


.. LINENO 516

operstate (``u32``)
~~~~~~~~~~~~~~~~~~~
:enum: :ref:`dpll-definition-pin-operstate`
:doc: Operational state of the pin with respect to its parent DPLL device. Unlike state (which reflects the administrative intent), operstate reflects the actual hardware status.


.. _dpll-attribute-set-pin-parent-device:

pin-parent-device
=================
.. LINENO 529

parent-id
~~~~~~~~~


.. LINENO 531

direction
~~~~~~~~~


.. LINENO 533

prio
~~~~


.. LINENO 535

state
~~~~~


.. LINENO 537

operstate
~~~~~~~~~


.. LINENO 539

phase-offset
~~~~~~~~~~~~


.. LINENO 541

fractional-frequency-offset
~~~~~~~~~~~~~~~~~~~~~~~~~~~


.. LINENO 543

fractional-frequency-offset-ppt
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


.. _dpll-attribute-set-pin-parent-pin:

pin-parent-pin
==============
.. LINENO 549

parent-id
~~~~~~~~~


.. LINENO 551

state
~~~~~


.. _dpll-attribute-set-frequency-range:

frequency-range
===============
.. LINENO 557

frequency-min
~~~~~~~~~~~~~


.. LINENO 559

frequency-max
~~~~~~~~~~~~~


.. _dpll-attribute-set-reference-sync:

reference-sync
==============
.. LINENO 565

id
~~


.. LINENO 567

state
~~~~~