[RFC,v7,3/8] dpll: documentation on DPLL subsystem interface

Commit Message

Vadim Fedorenko April 28, 2023, 12:20 a.m. UTC

From: Vadim Fedorenko <[e-mail]>

Add documentation explaining common netlink interface to configure DPLL
devices and monitoring events. Common way to implement DPLL device in
a driver is also covered.

Signed-off-by: Vadim Fedorenko <[e-mail]>
Signed-off-by: Arkadiusz Kubalewski <[e-mail]>
---
 Documentation/dpll.rst             | 408 +++++++++++++++++++++++++++++
 Documentation/networking/index.rst |   1 +
 2 files changed, 409 insertions(+)
 create mode 100644 Documentation/dpll.rst

Comments

Jakub Kicinski May 4, 2023, 7:04 p.m. UTC | #1

On Thu, 27 Apr 2023 17:20:04 -0700 Vadim Fedorenko wrote:
> From: Vadim Fedorenko <[e-mail]>
> 
> Add documentation explaining common netlink interface to configure DPLL
> devices and monitoring events. Common way to implement DPLL device in
> a driver is also covered.
> 
> Signed-off-by: Vadim Fedorenko <[e-mail]>
> Signed-off-by: Arkadiusz Kubalewski <[e-mail]>

nit: let's put documentation as patch 1, it's more natural for 
a reviewer to start from the docs.

> diff --git a/Documentation/dpll.rst b/Documentation/dpll.rst
> new file mode 100644
> index 000000000000..fba5bc027967
> --- /dev/null
> +++ b/Documentation/dpll.rst
> @@ -0,0 +1,408 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===============================
> +The Linux kernel dpll subsystem
> +===============================
> +
> +

nit: two empty lines here...

> +The main purpose of dpll subsystem is to provide general interface
> +to configure devices that use any kind of Digital PLL and could use
> +different sources of signal to synchronize to as well as different
> +types of outputs.
> +The main interface is NETLINK_GENERIC based protocol with an event
> +monitoring multicast group defined.
> +
> +
> +Device object
> +=============

.. but none after the section start? One nl to separate things, please.

> +Single dpll device object means single Digital PLL circuit and bunch of
> +pins connected with it.

s/bunch of pins connected with it/bunch of connected pins/

> +It provides its supported working modes and current status to the user

"reports the supported modes of operation" ?

> +in response to the `do` request of netlink command
> +``DPLL_CMD_DEVICE_GET`` and list of dplls registered in the subsystem
> +with `dump` netlink request of same command.
> +Requesting configuration of dpll device is done with `do` request of

Changing the configuration ?

> +netlink ``DPLL_CMD_DEVICE_SET`` command.
> +
> +
> +Pin object
> +==========
> +A pin is amorphic object which represents either source or output, it

Is the terminology mixing on purpose?
Source or drain vs input or output ?

> +could be internal component of the device, as well as externaly
> +connected.
> +The number of pins per dpll vary, but usually multiple pins shall be
> +provided for a single dpll device.
> +Pin's properties, capabilities and status is provided to the user in
> +response to `do` request of netlink ``DPLL_CMD_PIN_GET`` command.
> +It is also possible to list all the pins that were registered in the
> +system with `dump` request of ``DPLL_CMD_PIN_GET`` command.
> +Configuration of a pin can be changed by `do` request of netlink
> +``DPLL_CMD_PIN_SET`` command.
> +
> +
> +Pin selection
> +=============
> +In general selected pin (the one which signal is driving the dpll
> +device) can be obtained from ``DPLL_A_PIN_STATE`` attribute, and only
> +one pin shall be in ``DPLL_PIN_STATE_CONNECTED`` state for any dpll
> +device.
> +
> +Pin selection can be done either manualy or automatically, depending on

manually, spellcheck?

> +hardware capabilities and active dpll device work mode
> +(``DPLL_A_MODE`` attribute). The consequence is that, there are
> +differences for each mode in terms of available pin states, as well
> +as for the states the user can request for a dpll device.
> +
> +In manual mode (``DPLL_MODE_MANUAL``) the user can request or receive
> +one of following pin states:
> +- ``DPLL_PIN_STATE_CONNECTED`` - the pin is used to drive dpll device
> +- ``DPLL_PIN_STATE_DISCONNECTED`` - the pin is not used to drive dpll
> +  device
> +
> +In automatic mode (``DPLL_MODE_AUTOMATIC``) the user can request or
> +receive one of following pin states:
> +- ``DPLL_PIN_STATE_SELECTABLE`` - the pin shall be considered as valid
> +  source for automatic selection algorithm
> +- ``DPLL_PIN_STATE_DISCONNECTED`` - the pin shall be not considered as
> +  a valid source for automatic selection algorithm
> +In automatic mode (``DPLL_MODE_AUTOMATIC``) the user can only receive
> +pin state ``DPLL_PIN_STATE_CONNECTED`` once automatic selection
> +algorithm locks a dpll device with one of the sources.

But there's a lot more modes in the mode enum :S

> +Shared pins
> +===========
> +A single pin object can be registered to multiple dpll devices.

s/registered/attached/ ?

> +Then there are two groups of configuration knobs:
> +1) Set on a pin - the configuration affects all dpll devices pin is
> +   registered to. (i.e. ``PIN_FREQUENCY``, ``PIN_DIRECTION``),

Why is direction set on a pin? We can't chain DPLLs?

> +2) Set on a pin-dpll tuple - the configuration affects only selected
> +   dpll device. (i.e. PIN_PRIO, PIN_STATE).
> +
> +
> +MUX-type pins
> +=============
> +A pin can be MUX-type, it aggregates child pins and serves as a pin
> +multiplexer. One or more pins are registered with MUX-type instead of
> +being directly registered to a dpll device.
> +Pins registered with a MUX-type provide user with additional nested
> +attribute ``DPLL_A_PIN_PARENT`` for each parent they were registered
> +with.
> +If a pin was registered with multiple parent pins, they behave like a
> +multiple output multiplexer. In this case output of a
> +``DPLL_CMD_PIN_GET`` would contain multiple pin-parent nested
> +attributes with current state related to each parent, like:
> +
> +``'pin': [{
> +        'device': [{'bus-name': 'pci',
> +                    'dev-name': '0000:21:00.0_0', 'id': 0}],
> +        'pin-direction': {'doc': 'pin used as a source of a signal',
> +                          'name': 'source'},
> +        'pin-idx': 13,
> +        'pin-parent': [{'pin-parent-idx': 2,
> +                        'pin-state': {'doc': 'pin disconnected',
> +                                      'name': 'disconnected'}},
> +                       {'pin-parent-idx': 3,
> +                        'pin-state': {'doc': 'pin disconnected',
> +                                      'name': 'disconnected'}}],
> +        }]``
> +
> +Only one child pin can provide it's signal to the parent MUX-type pin at
> +a time, the selection is done with requesting change of child pin state
> +to ``DPLL_PIN_STATE_CONNECTED`` and providing a target MUX-type pin
> +index value in ``DPLL_A_PARENT_PIN_IDX``.
> +
> +Pin priority
> +============
> +Some devices might offer a capability of automatic pin selection mode
> +(enum value ``DPLL_MODE_AUTOMATIC`` of ``DPLL_A_MODE`` attribute).
> +Usually such automatic selection is offloaded to the hardware,

offloaded is a dirty word, s/offloaded to/performed by/

> +which means only pins directly connected to the dpll are capable of
> +automatic source pin selection.

s/are capable of/can be used in the/

> +In automatic selection mode, the user cannot manually select a source
> +pin for the device, instead the user shall provide all directly
> +connected pins with a priority ``DPLL_A_PIN_PRIO``, the device would
> +pick a highest priority valid signal and connect with it.

s/connect with it/use it to control the DPLL device/ ?

> +Child pin of MUX-type is not capable of automatic source pin selection,
> +in order to configure a source of a MUX-type pin, the user needs to
> +request desired pin state of the child pin on the parent - it is done
> +with providing additional attribute for pin set state request - index
> +of parent pin he wish to propagate its signal to
> +(``DPLL_A_PARENT_PIN_IDX``).
> +
> +
> +Configuration commands group
> +============================
> +

oh and the new lines after headers appear ;)

> +Configuration commands are used to get or dump information about

s/or dump//
the netlink ability to query or dump is not something specific to dpll,
I wouldn't mention it so many times.

> +registered dpll devices (and pins), as well as set configuration of
> +device or pins. As dpll device could not be abstract and reflects real

Missing an article before dpll device, maybe "each dpll device", or 'a
dppl device' or 'dpll devices" (plural)

s/could/must/

> +hardware, there is no way to add new dpll device via netlink from user
> +space and each device should be registered by it's driver.
> +
> +All netlink commands require ``GENL_ADMIN_PERM``. This is to prevent
> +any spamming/D.o.S. from unauthorized userspace applications.

no dots in DoS

> +In general it is possible to configure multiple parameters at once.

s/In general//
Should we say that we don't guarantee the change will be atomic in that
case?

> +Device driver implementation
> +============================
> +
> +Device is allocated by ``dpll_device_get`` call. Second call with the
> +same arguments doesn't create new object but provides pointer to
> +previously created device for given arguments, it also increase refcount
> +of that object.
> +Device is deallocated by ``dpll_device_put`` call, which first decreases
> +the refcount, once refcount is cleared the object is destroyed.

You can add () after the function name and render the kdoc at the end
of this doc. The `` marking will then be unnecessary.

Vadim Fedorenko May 5, 2023, 1:16 p.m. UTC | #2

On 04/05/2023 20:04, Jakub Kicinski wrote:
> On Thu, 27 Apr 2023 17:20:04 -0700 Vadim Fedorenko wrote:
>> From: Vadim Fedorenko <[e-mail]>
>>
>> Add documentation explaining common netlink interface to configure DPLL
>> devices and monitoring events. Common way to implement DPLL device in
>> a driver is also covered.
>>
>> Signed-off-by: Vadim Fedorenko <[e-mail]>
>> Signed-off-by: Arkadiusz Kubalewski <[e-mail]>
> 
> nit: let's put documentation as patch 1, it's more natural for
> a reviewer to start from the docs.

Ok, sure, will do it.
And I agree to almost all the comments here, but for some I have, 
questions below.

>> diff --git a/Documentation/dpll.rst b/Documentation/dpll.rst
>> new file mode 100644
>> index 000000000000..fba5bc027967
>> --- /dev/null
>> +++ b/Documentation/dpll.rst
>> @@ -0,0 +1,408 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +===============================
>> +The Linux kernel dpll subsystem
>> +===============================
>> +
>> +
> 
> nit: two empty lines here...
> 
>> +The main purpose of dpll subsystem is to provide general interface
>> +to configure devices that use any kind of Digital PLL and could use
>> +different sources of signal to synchronize to as well as different
>> +types of outputs.
>> +The main interface is NETLINK_GENERIC based protocol with an event
>> +monitoring multicast group defined.
>> +
>> +
>> +Device object
>> +=============
> 
> .. but none after the section start? One nl to separate things, please.
> 
>> +Single dpll device object means single Digital PLL circuit and bunch of
>> +pins connected with it.
> 
> s/bunch of pins connected with it/bunch of connected pins/
> 
>> +It provides its supported working modes and current status to the user
> 
> "reports the supported modes of operation" ?
> 
>> +in response to the `do` request of netlink command
>> +``DPLL_CMD_DEVICE_GET`` and list of dplls registered in the subsystem
>> +with `dump` netlink request of same command.
>> +Requesting configuration of dpll device is done with `do` request of
> 
> Changing the configuration ?
> 
>> +netlink ``DPLL_CMD_DEVICE_SET`` command.
>> +
>> +
>> +Pin object
>> +==========
>> +A pin is amorphic object which represents either source or output, it
> 
> Is the terminology mixing on purpose?
> Source or drain vs input or output ?
> 
>> +could be internal component of the device, as well as externaly
>> +connected.
>> +The number of pins per dpll vary, but usually multiple pins shall be
>> +provided for a single dpll device.
>> +Pin's properties, capabilities and status is provided to the user in
>> +response to `do` request of netlink ``DPLL_CMD_PIN_GET`` command.
>> +It is also possible to list all the pins that were registered in the
>> +system with `dump` request of ``DPLL_CMD_PIN_GET`` command.
>> +Configuration of a pin can be changed by `do` request of netlink
>> +``DPLL_CMD_PIN_SET`` command.
>> +
>> +
>> +Pin selection
>> +=============
>> +In general selected pin (the one which signal is driving the dpll
>> +device) can be obtained from ``DPLL_A_PIN_STATE`` attribute, and only
>> +one pin shall be in ``DPLL_PIN_STATE_CONNECTED`` state for any dpll
>> +device.
>> +
>> +Pin selection can be done either manualy or automatically, depending on
> 
> manually, spellcheck?
> 
>> +hardware capabilities and active dpll device work mode
>> +(``DPLL_A_MODE`` attribute). The consequence is that, there are
>> +differences for each mode in terms of available pin states, as well
>> +as for the states the user can request for a dpll device.
>> +
>> +In manual mode (``DPLL_MODE_MANUAL``) the user can request or receive
>> +one of following pin states:
>> +- ``DPLL_PIN_STATE_CONNECTED`` - the pin is used to drive dpll device
>> +- ``DPLL_PIN_STATE_DISCONNECTED`` - the pin is not used to drive dpll
>> +  device
>> +
>> +In automatic mode (``DPLL_MODE_AUTOMATIC``) the user can request or
>> +receive one of following pin states:
>> +- ``DPLL_PIN_STATE_SELECTABLE`` - the pin shall be considered as valid
>> +  source for automatic selection algorithm
>> +- ``DPLL_PIN_STATE_DISCONNECTED`` - the pin shall be not considered as
>> +  a valid source for automatic selection algorithm
>> +In automatic mode (``DPLL_MODE_AUTOMATIC``) the user can only receive
>> +pin state ``DPLL_PIN_STATE_CONNECTED`` once automatic selection
>> +algorithm locks a dpll device with one of the sources.
> 
> But there's a lot more modes in the mode enum :S
> 
>> +Shared pins
>> +===========
>> +A single pin object can be registered to multiple dpll devices.
> 
> s/registered/attached/ ?
> 
>> +Then there are two groups of configuration knobs:
>> +1) Set on a pin - the configuration affects all dpll devices pin is
>> +   registered to. (i.e. ``PIN_FREQUENCY``, ``PIN_DIRECTION``),
> 
> Why is direction set on a pin? We can't chain DPLLs?

We can chain DPLLs using pins only. We don't have any interface to
configure 2 pins to connect 2 different DPLLs to each other at the same 
time. The configuration should take care of one pin being input and
other one being output. That's why we have direction property attached
to the pin, not the DPLL itself.

>> +2) Set on a pin-dpll tuple - the configuration affects only selected
>> +   dpll device. (i.e. PIN_PRIO, PIN_STATE).
>> +
>> +
>> +MUX-type pins
>> +=============
>> +A pin can be MUX-type, it aggregates child pins and serves as a pin
>> +multiplexer. One or more pins are registered with MUX-type instead of
>> +being directly registered to a dpll device.
>> +Pins registered with a MUX-type provide user with additional nested
>> +attribute ``DPLL_A_PIN_PARENT`` for each parent they were registered
>> +with.
>> +If a pin was registered with multiple parent pins, they behave like a
>> +multiple output multiplexer. In this case output of a
>> +``DPLL_CMD_PIN_GET`` would contain multiple pin-parent nested
>> +attributes with current state related to each parent, like:
>> +
>> +``'pin': [{
>> +        'device': [{'bus-name': 'pci',
>> +                    'dev-name': '0000:21:00.0_0', 'id': 0}],
>> +        'pin-direction': {'doc': 'pin used as a source of a signal',
>> +                          'name': 'source'},
>> +        'pin-idx': 13,
>> +        'pin-parent': [{'pin-parent-idx': 2,
>> +                        'pin-state': {'doc': 'pin disconnected',
>> +                                      'name': 'disconnected'}},
>> +                       {'pin-parent-idx': 3,
>> +                        'pin-state': {'doc': 'pin disconnected',
>> +                                      'name': 'disconnected'}}],
>> +        }]``
>> +
>> +Only one child pin can provide it's signal to the parent MUX-type pin at
>> +a time, the selection is done with requesting change of child pin state
>> +to ``DPLL_PIN_STATE_CONNECTED`` and providing a target MUX-type pin
>> +index value in ``DPLL_A_PARENT_PIN_IDX``.
>> +
>> +Pin priority
>> +============
>> +Some devices might offer a capability of automatic pin selection mode
>> +(enum value ``DPLL_MODE_AUTOMATIC`` of ``DPLL_A_MODE`` attribute).
>> +Usually such automatic selection is offloaded to the hardware,
> 
> offloaded is a dirty word, s/offloaded to/performed by/
> 
>> +which means only pins directly connected to the dpll are capable of
>> +automatic source pin selection.
> 
> s/are capable of/can be used in the/
> 
>> +In automatic selection mode, the user cannot manually select a source
>> +pin for the device, instead the user shall provide all directly
>> +connected pins with a priority ``DPLL_A_PIN_PRIO``, the device would
>> +pick a highest priority valid signal and connect with it.
> 
> s/connect with it/use it to control the DPLL device/ ?
> 
>> +Child pin of MUX-type is not capable of automatic source pin selection,
>> +in order to configure a source of a MUX-type pin, the user needs to
>> +request desired pin state of the child pin on the parent - it is done
>> +with providing additional attribute for pin set state request - index
>> +of parent pin he wish to propagate its signal to
>> +(``DPLL_A_PARENT_PIN_IDX``).
>> +
>> +
>> +Configuration commands group
>> +============================
>> +
> 
> oh and the new lines after headers appear ;)
> 
>> +Configuration commands are used to get or dump information about
> 
> s/or dump//
> the netlink ability to query or dump is not something specific to dpll,
> I wouldn't mention it so many times.
> 
>> +registered dpll devices (and pins), as well as set configuration of
>> +device or pins. As dpll device could not be abstract and reflects real
> 
> Missing an article before dpll device, maybe "each dpll device", or 'a
> dppl device' or 'dpll devices" (plural)
> 
> s/could/must/
> 
>> +hardware, there is no way to add new dpll device via netlink from user
>> +space and each device should be registered by it's driver.
>> +
>> +All netlink commands require ``GENL_ADMIN_PERM``. This is to prevent
>> +any spamming/D.o.S. from unauthorized userspace applications.
> 
> no dots in DoS
> 
>> +In general it is possible to configure multiple parameters at once.
> 
> s/In general//
> Should we say that we don't guarantee the change will be atomic in that
> case?

I agree, I'll add this explicitly in the next version.

>> +Device driver implementation
>> +============================
>> +
>> +Device is allocated by ``dpll_device_get`` call. Second call with the
>> +same arguments doesn't create new object but provides pointer to
>> +previously created device for given arguments, it also increase refcount
>> +of that object.
>> +Device is deallocated by ``dpll_device_put`` call, which first decreases
>> +the refcount, once refcount is cleared the object is destroyed.
> 
> You can add () after the function name and render the kdoc at the end
> of this doc. The `` marking will then be unnecessary.
> 
Mmm... any examples of such a way of creating documentation? I was
following tls*.rst style, but without copying code-blocks.

Jakub Kicinski May 5, 2023, 3:29 p.m. UTC | #3

On Fri, 5 May 2023 14:16:53 +0100 Vadim Fedorenko wrote:
> >> +Then there are two groups of configuration knobs:
> >> +1) Set on a pin - the configuration affects all dpll devices pin is
> >> +   registered to. (i.e. ``PIN_FREQUENCY``, ``PIN_DIRECTION``),  
> > 
> > Why is direction set on a pin? We can't chain DPLLs?  
> 
> We can chain DPLLs using pins only. We don't have any interface to
> configure 2 pins to connect 2 different DPLLs to each other at the same 
> time. The configuration should take care of one pin being input and
> other one being output. That's why we have direction property attached
> to the pin, not the DPLL itself.

Makes sense.

> >> +Device driver implementation
> >> +============================
> >> +
> >> +Device is allocated by ``dpll_device_get`` call. Second call with the
> >> +same arguments doesn't create new object but provides pointer to
> >> +previously created device for given arguments, it also increase refcount
> >> +of that object.
> >> +Device is deallocated by ``dpll_device_put`` call, which first decreases
> >> +the refcount, once refcount is cleared the object is destroyed.  
> > 
> > You can add () after the function name and render the kdoc at the end
> > of this doc. The `` marking will then be unnecessary.
> >   
> Mmm... any examples of such a way of creating documentation? I was
> following tls*.rst style, but without copying code-blocks.

net_dim.rst, maybe?  driver.rst ? Feel free to ping me 1:1 if you're
struggling, it should be fairly straightforward.

Arkadiusz Kubalewski May 11, 2023, 10:23 a.m. UTC | #4

>From: Jakub Kicinski <[e-mail]>
>Sent: Friday, May 5, 2023 5:30 PM
>
>On Fri, 5 May 2023 14:16:53 +0100 Vadim Fedorenko wrote:
>> >> +Then there are two groups of configuration knobs:
>> >> +1) Set on a pin - the configuration affects all dpll devices pin is
>> >> +   registered to. (i.e. ``PIN_FREQUENCY``, ``PIN_DIRECTION``),
>> >
>> > Why is direction set on a pin? We can't chain DPLLs?
>>
>> We can chain DPLLs using pins only. We don't have any interface to
>> configure 2 pins to connect 2 different DPLLs to each other at the same
>> time. The configuration should take care of one pin being input and
>> other one being output. That's why we have direction property attached
>> to the pin, not the DPLL itself.
>
>Makes sense.

Hmmm, actually we already can register the same pin with 2 dplls, and it could
identify itself as an input for one dpll and as an output for the other. It
makes sense as change on one pin would again inform both dplls.

The dpll_pin_direction_get/set callbacks are already called with dpll, so
we are good, only one change would be needed is to move PIN_DIRECTION to the
pin-dpll configuration tuples on `pin-get`.

Thus, actually it looks like a bug now:
- pin-dpll tuple may report different direction for each dpll pin was
registered with
- userspace see this as pin specific property, but it would return different
values depending on which dpll was given as arg for pin-get command.

I will fix it, as it relates to the modifying spec in first place.

>
>> >> +Device driver implementation
>> >> +============================
>> >> +
>> >> +Device is allocated by ``dpll_device_get`` call. Second call with the
>> >> +same arguments doesn't create new object but provides pointer to
>> >> +previously created device for given arguments, it also increase refcount
>> >> +of that object.
>> >> +Device is deallocated by ``dpll_device_put`` call, which first decreases
>> >> +the refcount, once refcount is cleared the object is destroyed.
>> >
>> > You can add () after the function name and render the kdoc at the end
>> > of this doc. The `` marking will then be unnecessary.
>> >
>> Mmm... any examples of such a way of creating documentation? I was
>> following tls*.rst style, but without copying code-blocks.
>
>net_dim.rst, maybe?  driver.rst ? Feel free to ping me 1:1 if you're
>struggling, it should be fairly straightforward.

Patch

diff --git a/Documentation/dpll.rst b/Documentation/dpll.rst
new file mode 100644
index 000000000000..fba5bc027967
--- /dev/null
+++ b/Documentation/dpll.rst
@@ -0,0 +1,408 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+===============================
+The Linux kernel dpll subsystem
+===============================
+
+
+The main purpose of dpll subsystem is to provide general interface
+to configure devices that use any kind of Digital PLL and could use
+different sources of signal to synchronize to as well as different
+types of outputs.
+The main interface is NETLINK_GENERIC based protocol with an event
+monitoring multicast group defined.
+
+
+Device object
+=============
+Single dpll device object means single Digital PLL circuit and bunch of
+pins connected with it.
+It provides its supported working modes and current status to the user
+in response to the `do` request of netlink command
+``DPLL_CMD_DEVICE_GET`` and list of dplls registered in the subsystem
+with `dump` netlink request of same command.
+Requesting configuration of dpll device is done with `do` request of
+netlink ``DPLL_CMD_DEVICE_SET`` command.
+
+
+Pin object
+==========
+A pin is amorphic object which represents either source or output, it
+could be internal component of the device, as well as externaly
+connected.
+The number of pins per dpll vary, but usually multiple pins shall be
+provided for a single dpll device.
+Pin's properties, capabilities and status is provided to the user in
+response to `do` request of netlink ``DPLL_CMD_PIN_GET`` command.
+It is also possible to list all the pins that were registered in the
+system with `dump` request of ``DPLL_CMD_PIN_GET`` command.
+Configuration of a pin can be changed by `do` request of netlink
+``DPLL_CMD_PIN_SET`` command.
+
+
+Pin selection
+=============
+In general selected pin (the one which signal is driving the dpll
+device) can be obtained from ``DPLL_A_PIN_STATE`` attribute, and only
+one pin shall be in ``DPLL_PIN_STATE_CONNECTED`` state for any dpll
+device.
+
+Pin selection can be done either manualy or automatically, depending on
+hardware capabilities and active dpll device work mode
+(``DPLL_A_MODE`` attribute). The consequence is that, there are
+differences for each mode in terms of available pin states, as well
+as for the states the user can request for a dpll device.
+
+In manual mode (``DPLL_MODE_MANUAL``) the user can request or receive
+one of following pin states:
+- ``DPLL_PIN_STATE_CONNECTED`` - the pin is used to drive dpll device
+- ``DPLL_PIN_STATE_DISCONNECTED`` - the pin is not used to drive dpll
+  device
+
+In automatic mode (``DPLL_MODE_AUTOMATIC``) the user can request or
+receive one of following pin states:
+- ``DPLL_PIN_STATE_SELECTABLE`` - the pin shall be considered as valid
+  source for automatic selection algorithm
+- ``DPLL_PIN_STATE_DISCONNECTED`` - the pin shall be not considered as
+  a valid source for automatic selection algorithm
+In automatic mode (``DPLL_MODE_AUTOMATIC``) the user can only receive
+pin state ``DPLL_PIN_STATE_CONNECTED`` once automatic selection
+algorithm locks a dpll device with one of the sources.
+
+
+Shared pins
+===========
+A single pin object can be registered to multiple dpll devices.
+Then there are two groups of configuration knobs:
+1) Set on a pin - the configuration affects all dpll devices pin is
+   registered to. (i.e. ``PIN_FREQUENCY``, ``PIN_DIRECTION``),
+2) Set on a pin-dpll tuple - the configuration affects only selected
+   dpll device. (i.e. PIN_PRIO, PIN_STATE).
+
+
+MUX-type pins
+=============
+A pin can be MUX-type, it aggregates child pins and serves as a pin
+multiplexer. One or more pins are registered with MUX-type instead of
+being directly registered to a dpll device.
+Pins registered with a MUX-type provide user with additional nested
+attribute ``DPLL_A_PIN_PARENT`` for each parent they were registered
+with.
+If a pin was registered with multiple parent pins, they behave like a
+multiple output multiplexer. In this case output of a
+``DPLL_CMD_PIN_GET`` would contain multiple pin-parent nested
+attributes with current state related to each parent, like:
+
+``'pin': [{
+        'device': [{'bus-name': 'pci',
+                    'dev-name': '0000:21:00.0_0', 'id': 0}],
+        'pin-direction': {'doc': 'pin used as a source of a signal',
+                          'name': 'source'},
+        'pin-idx': 13,
+        'pin-parent': [{'pin-parent-idx': 2,
+                        'pin-state': {'doc': 'pin disconnected',
+                                      'name': 'disconnected'}},
+                       {'pin-parent-idx': 3,
+                        'pin-state': {'doc': 'pin disconnected',
+                                      'name': 'disconnected'}}],
+        }]``
+
+Only one child pin can provide it's signal to the parent MUX-type pin at
+a time, the selection is done with requesting change of child pin state
+to ``DPLL_PIN_STATE_CONNECTED`` and providing a target MUX-type pin
+index value in ``DPLL_A_PARENT_PIN_IDX``.
+
+Pin priority
+============
+Some devices might offer a capability of automatic pin selection mode
+(enum value ``DPLL_MODE_AUTOMATIC`` of ``DPLL_A_MODE`` attribute).
+Usually such automatic selection is offloaded to the hardware,
+which means only pins directly connected to the dpll are capable of
+automatic source pin selection.
+In automatic selection mode, the user cannot manually select a source
+pin for the device, instead the user shall provide all directly
+connected pins with a priority ``DPLL_A_PIN_PRIO``, the device would
+pick a highest priority valid signal and connect with it.
+Child pin of MUX-type is not capable of automatic source pin selection,
+in order to configure a source of a MUX-type pin, the user needs to
+request desired pin state of the child pin on the parent - it is done
+with providing additional attribute for pin set state request - index
+of parent pin he wish to propagate its signal to
+(``DPLL_A_PARENT_PIN_IDX``).
+
+
+Configuration commands group
+============================
+
+Configuration commands are used to get or dump information about
+registered dpll devices (and pins), as well as set configuration of
+device or pins. As dpll device could not be abstract and reflects real
+hardware, there is no way to add new dpll device via netlink from user
+space and each device should be registered by it's driver.
+
+All netlink commands require ``GENL_ADMIN_PERM``. This is to prevent
+any spamming/D.o.S. from unauthorized userspace applications.
+
+List of netlink commands with possible attributes
+=================================================
+
+All constants identifying command types use ``DPLL_CMD_`` prefix and
+suffix according to command purpose. All attributes use ``DPLL_A_``
+prefix and suffix according to attribute purpose:
+
+  ============================  =======================================
+  ``DEVICE_GET``                command to get device info or dump list
+                                of available devices
+    ``ID``                      attr internal dpll device ID
+    ``DEV_NAME``                attr dpll device name
+    ``BUS_NAME``                attr dpll device bus name
+    ``MODE``                    attr selection mode
+    ``MODE_SUPPORTED``          attr available selection modes
+    ``LOCK_STATUS``             attr internal frequency-lock status
+    ``TEMP``                    attr device temperature information
+    ``CLOCK_ID``                attr Unique Clock Identifier (EUI-64),
+                                as defined by the IEEE 1588 standard
+    ``TYPE``                    attr type or purpose of dpll device
+  ``DEVICE_SET``                command to set dpll device configuration
+    ``ID``                      attr internal dpll device index
+    ``NAME``                    attr dpll device name (not required if
+                                dpll device index was provided)
+    ``MODE``                    attr selection mode to configure
+  ``PIN_GET``                   command to get pin info or dump list of
+                                available pins
+    ``DEVICE``                  nest attr for each dpll device pin is
+                                connected with
+      ``ID``                    attr internal dpll device ID
+      ``DEV_NAME``              attr dpll device name
+      ``BUS_NAME``              attr dpll device bus name
+      ``PIN_PRIO``              attr priority of pin on the dpll device
+      ``PIN_STATE``             attr state of pin on the dpll device
+    ``PIN_IDX``                 attr index of a pin on the dpll device
+    ``PIN_DESCRIPTION``         attr description provided by driver
+    ``PIN_TYPE``                attr type of a pin
+    ``PIN_DIRECTION``           attr direction of a pin
+    ``PIN_FREQUENCY``           attr current frequency of a pin
+    ``PIN_FREQUENCY_SUPPORTED`` attr provides supported frequencies
+    ``PIN_ANY_FREQUENCY_MIN``   attr minimum value of frequency in case
+                                pin/dpll supports any frequency
+    ``PIN_ANY_FREQUENCY_MAX``   attr maximum value of frequency in case
+                                pin/dpll supports any frequency
+    ``PIN_PARENT``              nest attr for each MUX-type parent, that
+                                pin is connected with
+      ``PIN_PARENT_IDX``        attr index of a parent pin on the dpll
+                                device
+      ``PIN_STATE``             attr state of a pin on parent pin
+    ``PIN_RCLK_DEVICE``         attr name of a device, where pin
+                                recovers clock signal from
+    ``PIN_DPLL_CAPS``           attr bitmask of pin-dpll capabilities
+
+  ``PIN_SET``                   command to set pins configuration
+    ``ID``                      attr internal dpll device index
+    ``BUS_NAME``                attr dpll device name (not required if
+                                dpll device ID was provided)
+    ``DEV_NAME``                attr dpll device name (not required if
+                                dpll device ID was provided)
+    ``PIN_IDX``                 attr index of a pin on the dpll device
+    ``PIN_DIRECTION``           attr direction to be set
+    ``PIN_FREQUENCY``           attr frequency to be set
+    ``PIN_PRIO``                attr pin priority to be set
+    ``PIN_STATE``               attr pin state to be set
+    ``PIN_PARENT_IDX``          attr if provided state is to be set with
+                                parent pin instead of with dpll device
+
+Netlink dump requests
+=====================
+
+The ``DEVICE_GET`` and ``PIN_GET`` commands are capable of dump type
+netlink requests, in which case the response is in the same format as
+for their ``do`` request.
+
+
+SET commands format
+===================
+
+``DEVICE_SET`` - to target a dpll device, the user provides either a
+``ID`` or both ``BUS_NAME`` and ``DEV_NAME``, as well as parameter being
+configured (``DPLL_A_MODE``).
+
+``PIN_SET`` - to target a pin user has to provide a ``PIN_IDX``, but
+pin does not exist on its own, thus a dpll device must be also targeted
+with either a ``ID`` or both ``BUS_NAME`` and ``DEV_NAME`` to which
+pin being configured was registered with. Also configured pin parameters
+must be added.
+If ``PIN_DIRECTION`` or ``PIN_FREQUENCY`` are configured, this affects
+all the dpll device they are connected.
+If ``PIN_PRIO`` or ``PIN_STATE`` are configured, this affects only
+the dpll device being targeted.
+If valid ``PIN_PARENT_IDX`` is provided, the set command shall affect
+the configuration between a pin and it's parent, which is a
+``PIN_STATE``.
+In general it is possible to configure multiple parameters at once.
+
+
+Device level configuration pre-defined enums
+=================================================
+
+For all below enum names used for configuration of dpll device use
+the ``DPLL_`` prefix.
+
+Values for ``DPLL_A_LOCK_STATUS`` attribute:
+
+  ============================= ======================================
+  ``LOCK_STATUS_UNLOCKED``      dpll device is in freerun, not locked
+                                to any source pin
+  ``LOCK_STATUS_CALIBRATING``   dpll device calibrates to lock to the
+                                source pin signal
+  ``LOCK_STATUS_LOCKED``        dpll device is locked to the source
+                                pin frequency
+  ``LOCK_STATUS_HOLDOVER``      dpll device lost a lock, using its
+                                frequency holdover capabilities
+
+Values for ``DPLL_A_MODE`` attribute:
+
+  =================== ================================================
+  ``MODE_FORCED``     source pin is force-selected by setting pin
+                      state to ``DPLL_PIN_STATE_CONNECTED`` on a dpll
+  ``MODE_AUTOMATIC``  source pin is auto selected according to
+                      configured pin priorities and source signal
+                      validity
+  ``MODE_HOLDOVER``   force holdover mode of dpll
+  ``MODE_FREERUN``    dpll device is driven by supplied system clock
+                      without holdover capabilities
+  ``MODE_NCO``        similar to FREERUN, with possibility to
+                      numerically control frequency offset
+
+Values for ``DPLL_A_TYPE`` attribute:
+
+  ============= ===================================================
+  ``TYPE_PPS``  dpll device used to provide pulse-per-second output
+  ``TYPE_EEC``  dpll device used to drive ethernet equipment clock
+
+
+
+Pin level configuration pre-defined enums
+=========================================
+
+For all below enum names used for configuration of pin use the
+``DPLL_PIN_`` prefix.
+
+Values for ``DPLL_A_PIN_STATE`` attribute:
+
+  ======================= ========================================
+  ``STATE_CONNECTED``     Pin used as active source for a dpll
+                          device or for a parent pin
+  ``STATE_DISCONNECTED``  Pin disconnected from a dpll device or
+                          from a parent pin
+  ``STATE_SELECTABLE``    Pin enabled for automatic selection
+
+Values for ``DPLL_A_PIN_DIRECTION`` attribute:
+
+  ======================= ==============================
+  ``DIRECTION_SOURCE``    Pin used as a source of signal
+  ``DIRECTION_OUTPUT``    Pin used to output signal
+
+Values for ``DPLL_A_PIN_TYPE`` attributes:
+
+  ======================== ========================================
+  ``TYPE_MUX``             MUX type pin, connected pins shall have
+                           their own types
+  ``TYPE_EXT``             External pin
+  ``TYPE_SYNCE_ETH_PORT``  SyncE on Ethernet port
+  ``TYPE_INT_OSCILLATOR``  Internal Oscillator (i.e. Holdover with
+                           Atomic Clock as a Source)
+  ``TYPE_GNSS``            GNSS 1PPS source
+
+Values for ``DPLL_A_PIN_DPLL_CAPS`` attributes:
+
+  ============================= ================================
+  ``CAPS_DIRECTION_CAN_CHANGE`` Bit present if direction can change
+  ``CAPS_PRIORITY_CAN_CHANGE``  Bit present if priority can change
+  ``CAPS_STATE_CAN_CHANGE``     Bit present if state can change
+
+
+Notifications
+=============
+
+dpll device can provide notifications regarding status changes of the
+device, i.e. lock status changes, source/output type changes or alarms.
+This is the multicast group that is used to notify user-space apps via
+netlink socket: ``DPLL_MCGRP_MONITOR``
+
+Notifications messages (attrbiutes use ``DPLL_A`` prefix):
+
+  ========================= ==========================================
+  ``EVENT_DEVICE_CREATE``   event value new dpll device was created
+    ``ID``                  attr internal dpll device ID
+    ``DEV_NAME``            attr dpll device name
+    ``BUS_NAME``            attr dpll device bus name
+  ``EVENT_DEVICE_DELETE``   event value dpll device was deleted
+    ``ID``                  attr dpll device index
+  ``EVENT_DEVICE_CHANGE``   event value dpll device attribute has
+                            changed
+    ``ID``                  attr modified dpll device ID
+    ``PIN_IDX``             attr the modified pin index
+
+Device change event shall consiste of the attribute and the value that
+has changed.
+
+
+Device driver implementation
+============================
+
+Device is allocated by ``dpll_device_get`` call. Second call with the
+same arguments doesn't create new object but provides pointer to
+previously created device for given arguments, it also increase refcount
+of that object.
+Device is deallocated by ``dpll_device_put`` call, which first decreases
+the refcount, once refcount is cleared the object is destroyed.
+
+Device should implement set of operations and register device via
+``dpll_device_register`` at which point it becomes available to the
+users. Only one driver instance can register a dpll device within dpll
+subsytem. Multiple driver instances can obtain reference to it with
+``dpll_device_get``.
+
+The pins are allocated separately with ``dpll_pin_get``, it works
+similarly to ``dpll_device_get``. Creates object and the for each call
+with the same arguments the object refcount increases.
+
+Once dpll device is created, allocated pin can be registered with it
+with 2 different methods, always providing implemented pin callbacks,
+and private data pointer for calling them:
+``dpll_pin_register`` - simple registration with a dpll device.
+``dpll_pin_on_pin_register`` - register pin with another MUX type pin.
+
+For different instances of a device driver requiring to find already
+registered dpll (i.e. to connect its pins to it) use ``dpll_device_get``
+to obtain proper dpll device pointer.
+
+The name of dpll device is generated based on registerer provided module
+struct pointer, clock_id and device_idx values.
+Name is in format: ``%s/%llx/%d`` where arguments are as follows:
+``module_name(dpll->module)`` - syscall on parent module struct pointer
+``dpll->clock_id``            - registerer given clock id
+``dpll->device_idx``          - registerer given device id
+
+Notifications of adding or removing dpll devices are created within
+subsystem itself.
+Notifications about registering/deregistering pins are also invoked by
+the subsystem.
+Notifications about status changes either of dpll device or a pin shall
+be requested by device driver with ``dpll_device_notify`` or
+``dpll_pin_notify``.
+
+The device driver using dpll interface is not required to implement all
+the callback operation. Nevertheless there are few required to be
+implemented.
+Required dpll device level callback operations:
+- ``.mode_get``
+- ``.lock_status_get``
+
+Required pin level callback operations:
+- ``.state_get``
+- ``.direction_get``
+
+There is no strict requirement to implement all the operations for
+each device, every operation handler is checked for existence and
+ENOTSUPP is returned in case of absence of specific handler.
+
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index a164ff074356..4828d6f6daf1 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -17,6 +17,7 @@  Contents:
    dsa/index
    devlink/index
    caif/index
+   dpll
    ethtool-netlink
    ieee802154
    j1939