>From: Bagas Sanjaya <bagasdotme@xxxxxxxxx>
>Sent: Saturday, June 10, 2023 5:23 AM
>
>On Fri, Jun 09, 2023 at 02:18:44PM +0200, Arkadiusz Kubalewski wrote:
>> diff --git a/Documentation/driver-api/dpll.rst b/Documentation/driver-
>api/dpll.rst
>> new file mode 100644
>> index 000000000000..8caa4af022ad
>> --- /dev/null
>> +++ b/Documentation/driver-api/dpll.rst
>> @@ -0,0 +1,458 @@
>> +.. 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
>> +connected pins.
>> +It reports the supported modes of operation 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 the same command.
>> +Changing the configuration of dpll device is done with `do` request of
>> +netlink ``DPLL_CMD_DEVICE_SET`` command.
>> +A device handle is ``DPLL_A_ID``, it shall be provided to get or set
>> +configuration of particular device in the system. It can be obtained
>> +with a ``DPLL_CMD_DEVICE_GET`` `dump` request or
>> +a ``DPLL_CMD_DEVICE_ID_GET`` `do` request, where the one must provide
>> +attributes that result in single device match.
>> +
>> +Pin object
>> +==========
>> +
>> +A pin is amorphic object which represents either input or output, it
>> +could be internal component of the device, as well as externally
>> +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 handle is a ``DPLL_A_PIN_ID``, it shall be provided to get or set
>> +configuration of particular pin in the system. It can be obtained with
>> +``DPLL_CMD_PIN_GET`` `dump` request or ``DPLL_CMD_PIN_ID_GET`` `do`
>> +request, where user provides attributes that result in single pin match.
>> +
>> +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 manually 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
>> + input for automatic selection algorithm
>> +- ``DPLL_PIN_STATE_DISCONNECTED`` - the pin shall be not considered as
>> + a valid input 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 inputs.
>> +
>> +For other dpll device operating modes there is no pin selection
>> +mechanics.
>> +
>> +Shared pins
>> +===========
>> +
>> +A single pin object can be attached 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. ``DPLL_A_PIN_FREQUENCY``),
>> +2) Set on a pin-dpll tuple - the configuration affects only selected
>> + dpll device (i.e. ``DPLL_A_PIN_PRIO``, ``DPLL_A_PIN_STATE``,
>> + ``DPLL_A_PIN_DIRECTION``).
>> +
>> +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': [{
>> + {'clock-id': 282574471561216,
>> + 'module-name': 'ice',
>> + 'pin-dpll-caps': 4,
>> + 'pin-id': 13,
>> + 'pin-parent': [{'pin-id': 2, 'pin-state': 'connected'},
>> + {'pin-id': 3, 'pin-state': 'disconnected'},
>> + {'id': 0, 'pin-direction': 'input'},
>> + {'id': 1, 'pin-direction': 'input'}],
>> + 'pin-type': 'synce-eth-port'}
>> +}]``
>> +
>> +Only one child pin can provide its signal to the parent MUX-type pin at
>> +a time, the selection is done by requesting change of a child pin state
>> +on desired parent, with the use of ``DPLL_A_PIN_PARENT`` nested
>> +attribute. Example of netlink `set state on parent pin` message format:
>> +
>> + ===================== =============================================
>> + ``DPLL_A_PIN_ID`` child pin id
>> + ``DPLL_A_PIN_PARENT`` nested attribute for requesting configuration
>> + related to parent pin
>> + ``DPLL_A_PIN_ID`` parent pin id
>> + ``DPLL_A_PIN_STATE`` requested pin state on parent
>> +
>> +Pin priority
>> +============
>> +
>> +Some devices might offer a capability of automatic pin selection mode
>> +(enum value ``DPLL_MODE_AUTOMATIC`` of ``DPLL_A_MODE`` attribute).
>> +Usually, automatic selection is performed on the hardware level, which
>> +means only pins directly connected to the dpll can be used for automatic
>> +input pin selection.
>> +In automatic selection mode, the user cannot manually select a input
>> +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 use it to control the DPLL
>> +device. Example of netlink `set priority on parent pin` message format:
>> +
>> + ===================== =============================================
>> + ``DPLL_A_PIN_ID`` child pin id
>> + ``DPLL_A_PIN_PARENT`` nested attribute for requesting configuration
>> + related to parent pin
>> + ``DPLL_A_ID`` parent dpll id
>> + ``DPLL_A_PIN_PRIO`` requested pin prio on parent dpll
>> +
>> +Child pin of MUX-type is not capable of automatic input pin selection,
>> +in order to configure a input of a MUX-type pin, the user needs to
>> +request desired pin state of the child pin on the parent pin,
>> +as described in the ``MUX-type pins`` chapter.
>> +
>> +Configuration commands group
>> +============================
>> +
>> +Configuration commands are used to get information about registered
>> +dpll devices (and pins), as well as set configuration of device or pins.
>> +As dpll devices must be abstracted and reflect real hardware,
>> +there is no way to add new dpll device via netlink from user space and
>> +each device should be registered by its driver.
>> +
>> +All netlink commands require ``GENL_ADMIN_PERM``. This is to prevent
>> +any spamming/DoS from unauthorized userspace applications.
>> +
>> +List of netlink commands with possible attributes
>> +=================================================
>> +
>> +All constants identifying command types use a ``DPLL_CMD_`` prefix and
>> +suffix according to command purpose. All attributes use a ``DPLL_A_``
>> +prefix and suffix according to attribute purpose:
>> +
>> + ==================================== =================================
>> + ``DPLL_CMD_DEVICE_ID_GET`` command to get device ID
>> + ``DPLL_A_MODULE_NAME`` attr module name of registerer
>> + ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier
>> + (EUI-64), as defined by the
>> + IEEE 1588 standard
>> + ``DPLL_A_TYPE`` attr type of dpll device
>> + ``DPLL_CMD_DEVICE_GET`` command to get device info or
>> + dump list of available devices
>> + ``DPLL_A_ID`` attr unique dpll device ID
>> + ``DPLL_A_MODULE_NAME`` attr module name of registerer
>> + ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier
>> + (EUI-64), as defined by the
>> + IEEE 1588 standard
>> + ``DPLL_A_MODE`` attr selection mode
>> + ``DPLL_A_MODE_SUPPORTED`` attr available selection modes
>> + ``DPLL_A_LOCK_STATUS`` attr dpll device lock status
>> + ``DPLL_A_TEMP`` attr device temperature info
>> + ``DPLL_A_TYPE`` attr type of dpll device
>> + ``DPLL_CMD_DEVICE_SET`` command to set dpll device config
>> + ``DPLL_A_ID`` attr internal dpll device index
>> + ``DPLL_A_MODE`` attr selection mode to configure
>> + ``DPLL_CMD_PIN_GET`` command to get pin ID
>> + ``DPLL_A_MODULE_NAME`` attr module name of registerer
>> + ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier
>> + (EUI-64), as defined by the
>> + IEEE 1588 standard
>> + ``DPLL_A_PIN_BOARD_LABEL`` attr pin board label provided
>> + by registerer
>> + ``DPLL_A_PIN_PANEL_LABEL`` attr pin panel label provided
>> + by registerer
>> + ``DPLL_A_PIN_PACKAGE_LABEL`` attr pin package label provided
>> + by registerer
>> + ``DPLL_A_PIN_TYPE`` attr type of a pin
>> + ``DPLL_CMD_PIN_GET`` command to get pin info or dump
>> + list of available pins
>> + ``DPLL_A_PIN_ID`` attr unique a pin ID
>> + ``DPLL_A_MODULE_NAME`` attr module name of registerer
>> + ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier
>> + (EUI-64), as defined by the
>> + IEEE 1588 standard
>> + ``DPLL_A_PIN_BOARD_LABEL`` attr pin board label provided
>> + by registerer
>> + ``DPLL_A_PIN_PANEL_LABEL`` attr pin panel label provided
>> + by registerer
>> + ``DPLL_A_PIN_PACKAGE_LABEL`` attr pin package label provided
>> + by registerer
>> + ``DPLL_A_PIN_TYPE`` attr type of a pin
>> + ``DPLL_A_PIN_DIRECTION`` attr direction of a pin
>> + ``DPLL_A_PIN_FREQUENCY`` attr current frequency of a pin
>> + ``DPLL_A_PIN_FREQUENCY_SUPPORTED`` nested attr provides supported
>> + frequencies
>> + ``DPLL_A_PIN_ANY_FREQUENCY_MIN`` attr minimum value of frequency
>> + ``DPLL_A_PIN_ANY_FREQUENCY_MAX`` attr maximum value of frequency
>> + ``DPLL_A_PIN_PARENT`` nested attr for each parent the
>> + pin is connected with
>> + ``DPLL_A_ID`` attr provided if parent is dpll
>> + device
>> + ``DPLL_A_PIN_ID`` attr provided if parent is a pin
>> + ``DPLL_A_PIN_PRIO`` attr priority of pin on the
>> + dpll device
>> + ``DPLL_A_PIN_STATE`` attr state of pin on the dpll
>> + device or on the parent pin
>> + ``DPLL_A_PIN_DPLL_CAPS`` attr bitmask of pin-dpll
>> + capabilities
>> + ``DPLL_CMD_PIN_SET`` command to set pins configuration
>> + ``DPLL_A_PIN_ID`` attr unique a pin ID
>> + ``DPLL_A_PIN_DIRECTION`` attr requested direction of a pin
>> + ``DPLL_A_PIN_FREQUENCY`` attr requested frequency of a pin
>> + ``DPLL_A_PIN_PARENT`` nested attr for each parent
>> + related configuration of a pin
>> + requested
>> + ``DPLL_A_ID`` attr provided if parent is dpll
>> + device
>> + ``DPLL_A_PIN_ID`` attr provided if parent is a pin
>> + ``DPLL_A_PIN_PRIO`` attr requested priority of pin on
>> + the dpll device
>> + ``DPLL_A_PIN_STATE`` attr requested state of pin on
>> + the dpll device or on the parent
>> + pin
>> +
>> +Netlink dump requests
>> +=====================
>> +
>> +The ``DPLL_CMD_DEVICE_GET`` and ``DPLL_CMD_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, but every device or pin
>> +registered in the system is returned.
>> +
>> +SET commands format
>> +===================
>> +
>> +``DPLL_CMD_DEVICE_SET`` - to target a dpll device, the user provides
>> +``DPLL_A_ID``, which is unique identifier of dpll device in the system,
>> +as well as parameter being configured (``DPLL_A_MODE``).
>> +
>> +``DPLL_CMD_PIN_SET`` - to target a pin user has to provide a
>> +``DPLL_A_PIN_ID``, which is unique identifier of a pin in the system.
>> +Also configured pin parameters must be added.
>> +If ``DPLL_A_PIN_DIRECTION`` or ``DPLL_A_PIN_FREQUENCY`` are configured,
>> +this affects all the dpll device they are connected, that is why those
>> +attributes shall not be enclosed in ``DPLL_A_PIN_PARENT``.
>> +Other attributes:
>> +``DPLL_A_PIN_PRIO`` or ``DPLL_A_PIN_STATE`` must be enclosed in
>> +``DPLL_A_PIN_PARENT`` as their configuration relates to only one
>> +parent dpll or parent pin.
>> +Nested attribute of either ``DPLL_A_ID`` or ``DPLL_A_PIN_ID`` determines
>> +if configuration was requested on a dpll device or on a pin
>> +respectively.
>> +In general, it is possible to configure multiple parameters at once, but
>> +internally each parameter change will be invoked separately, where order
>> +of configuration is not guaranteed by any means.
>> +
>> +Device level configuration pre-defined enums
>> +=================================================
>> +
>> +Values for ``DPLL_A_LOCK_STATUS`` attribute:
>> +
>> + ================================== ===================================
>> + ``DPLL_LOCK_STATUS_UNLOCKED`` dpll device is in freerun, not
>> + locked to any input pin
>> + ``DPLL_LOCK_STATUS_LOCKED`` dpll device is locked to the input
>> + but no holdover capability yet
>> + acquired
>> + ``DPLL_LOCK_STATUS_LOCKED_HO_ACQ`` dpll device is locked to the input
>> + pin with holdover capability
>> + acquired
>> + ``DPLL_LOCK_STATUS_HOLDOVER`` dpll device lost a lock, using its
>> + frequency holdover capabilities
>> +
>> +Values for ``DPLL_A_MODE`` attribute:
>> +
>> + ======================= ==============================================
>> + ``DPLL_MODE_MANUAL`` input pin is manually selected by setting pin
>> + state to ``DPLL_PIN_STATE_CONNECTED`` on a
>> + dpll device
>> + ``DPLL_MODE_AUTOMATIC`` input pin is auto selected according to
>> + configured pin priorities and input signal
>> + validity
>> + ``DPLL_MODE_HOLDOVER`` force holdover mode of dpll
>> + ``DPLL_MODE_FREERUN`` dpll device is driven by supplied system clock
>> + without holdover capabilities
>> +
>> +Values for ``DPLL_A_TYPE`` attribute:
>> +
>> + ================= ===================================================
>> + ``DPLL_TYPE_PPS`` dpll device used to provide pulse-per-second output
>> + ``DPLL_TYPE_EEC`` dpll device used to drive ethernet equipment clock
>> +
>> +Pin level configuration pre-defined enums
>> +=========================================
>> +
>> +Values for ``DPLL_A_PIN_STATE`` attribute:
>> +
>> + =============================== ======================================
>> + ``DPLL_PIN_STATE_CONNECTED`` Pin used as active input for a dpll
>> + device or for a parent pin
>> + ``DPLL_PIN_STATE_DISCONNECTED`` Pin disconnected from a dpll device or
>> + from a parent pin
>> + ``DPLL_PIN_STATE_SELECTABLE`` Pin enabled for automatic selection
>> +
>> +Values for ``DPLL_A_PIN_DIRECTION`` attribute:
>> +
>> + ============================= ====================================
>> + ``DPLL_PIN_DIRECTION_INPUT`` used to provide its signal to a dpll
>> + device
>> + ``DPLL_PIN_DIRECTION_OUTPUT`` used to output the signal from a dpll
>> + device
>> +
>> +Values for ``DPLL_A_PIN_TYPE`` attributes:
>> +
>> + ================================ =====================================
>> + ``DPLL_PIN_TYPE_MUX`` MUX type pin, connected pins shall
>> + have their own types
>> + ``DPLL_PIN_TYPE_EXT`` External pin
>> + ``DPLL_PIN_TYPE_SYNCE_ETH_PORT`` SyncE on Ethernet port
>> + ``DPLL_PIN_TYPE_INT_OSCILLATOR`` Internal Oscillator (i.e. Holdover
>> + with Atomic Clock as an input)
>> + ``DPLL_PIN_TYPE_GNSS`` GNSS 1PPS input
>> +
>> +Values for ``DPLL_A_PIN_DPLL_CAPS`` attributes:
>> +
>> + ====================================== ===============================
>> + ``DPLL_PIN_CAPS_DIRECTION_CAN_CHANGE`` Bit present if direction of
>> + pin can change
>> + ``DPLL_PIN_CAPS_PRIORITY_CAN_CHANGE`` Bit present if priority of pin
>> + can change
>> + ``DPLL_PIN_CAPS_STATE_CAN_CHANGE`` Bit present if state of pin can
>> + change
>> +
>> +Notifications
>> +=============
>> +
>> +dpll device can provide notifications regarding status changes of the
>> +device, i.e. lock status changes, input/output changes or other alarms.
>> +There is one multicast group that is used to notify user-space apps via
>> +netlink socket: ``DPLL_MCGRP_MONITOR``
>> +
>> +Notifications messages:
>> +
>> + ============================== =====================================
>> + ``DPLL_CMD_DEVICE_CREATE_NTF`` dpll device was created
>> + ``DPLL_CMD_DEVICE_DELETE_NTF`` dpll device was deleted
>> + ``DPLL_CMD_DEVICE_CHANGE_NTF`` dpll device has changed
>> + ``DPLL_CMD_PIN_CREATE_NTF`` dpll pin was created
>> + ``DPLL_CMD_PIN_DELETE_NTF`` dpll pin was deleted
>> + ``DPLL_CMD_PIN_CHANGE_NTF`` dpll pin has changed
>> +
>> +Events format is the same as for the corresponding get command.
>> +Format of ``DPLL_CMD_DEVICE_`` events is the same as response of
>> +``DPLL_CMD_DEVICE_GET``.
>> +Format of ``DPLL_CMD_PIN_`` events is same as response of
>> +``DPLL_CMD_PIN_GET``.
>> +
>> +Device driver implementation
>> +============================
>> +
>> +Device is allocated by dpll_device_get() call. Second call with the
>> +same arguments will not create new object but provides pointer to
>> +previously created device for given arguments, it also increases
>> +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. Multiple driver instances can obtain reference to it with
>> +dpll_device_get(), as well as register dpll device with their own
>> +ops and priv.
>> +
>> +The pins are allocated separately with dpll_pin_get(), it works
>> +similarly to dpll_device_get(). Function first creates object and then
>> +for each call with the same arguments only the object refcount
>> +increases. Also dpll_pin_put() works similarly to dpll_device_put().
>> +
>> +A pin can be registered with parent dpll device or parent pin, depending
>> +on hardware needs. Each registration requires registerer to provide set
>> +of pin callbacks, and private data pointer for calling them:
>> +- dpll_pin_register() - register pin with a dpll device,
>> +- dpll_pin_on_pin_register() - register pin with another MUX type pin.
>> +
>> +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 are
>> +invoked in two ways:
>> +- after successful change was requested on dpll subsystem, the subsystem
>> + calls corresponding notification,
>> +- requested by device driver with dpll_device_change_ntf() or
>> + dpll_pin_change_ntf() when driver informs about the status change.
>> +
>> +The device driver using dpll interface is not required to implement all
>> +the callback operation. Neverthelessi, 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`` (pins registered with dpll device),
>> +- ``.state_on_pin_get`` (pins registered with parent pin),
>> +- ``.direction_get``.
>> +
>> +Every other operation handler is checked for existence and
>> +``-ENOTSUPP`` is returned in case of absence of specific handler.
>> +
>> +SyncE enablement
>> +================
>> +For SyncE enablement it is required to allow control over dpll device
>> +for a software application which monitors and configures the inputs of
>> +dpll device in response to current state of a dpll device and its
>> +inputs.
>> +In such scenario, dpll device input signal shall be also configurable
>> +to drive dpll with signal recovered from the PHY netdevice.
>> +This is done by exposing a pin to the netdevice - attaching pin to the
>> +netdevice itself with:
>> +netdev_dpll_pin_set(struct net_device *dev, struct dpll_pin *dpll_pin);
>> +Exposed pin id handle ``DPLL_A_PIN_ID`` is then identifiable by the user
>> +as it is attached to rtnetlink respond to get ``RTM_NEWLINK`` command in
>> +nested attribute ``IFLA_DPLL_PIN``.
>
>There are countless htmldocs warnings, so I have to fix them up:
>
>---- >8 ----
>diff --git a/Documentation/driver-api/dpll.rst b/Documentation/driver-
>api/dpll.rst
>index 8caa4af022ad82..5b2d3e3b9f8893 100644
>--- a/Documentation/driver-api/dpll.rst
>+++ b/Documentation/driver-api/dpll.rst
>@@ -63,16 +63,19 @@ 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
> input for automatic selection algorithm
> - ``DPLL_PIN_STATE_DISCONNECTED`` - the pin shall be not considered as
> a valid input 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 inputs.
>@@ -85,6 +88,7 @@ Shared pins
>
> A single pin object can be attached 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. ``DPLL_A_PIN_FREQUENCY``),
> 2) Set on a pin-dpll tuple - the configuration affects only selected
>@@ -103,31 +107,32 @@ 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:
>+attributes with current state related to each parent, like::
>
>-``'pin': [{
>- {'clock-id': 282574471561216,
>- 'module-name': 'ice',
>- 'pin-dpll-caps': 4,
>- 'pin-id': 13,
>- 'pin-parent': [{'pin-id': 2, 'pin-state': 'connected'},
>- {'pin-id': 3, 'pin-state': 'disconnected'},
>- {'id': 0, 'pin-direction': 'input'},
>- {'id': 1, 'pin-direction': 'input'}],
>- 'pin-type': 'synce-eth-port'}
>-}]``
>+ 'pin': [{
>+ {'clock-id': 282574471561216,
>+ 'module-name': 'ice',
>+ 'pin-dpll-caps': 4,
>+ 'pin-id': 13,
>+ 'pin-parent': [{'pin-id': 2, 'pin-state': 'connected'},
>+ {'pin-id': 3, 'pin-state': 'disconnected'},
>+ {'id': 0, 'pin-direction': 'input'},
>+ {'id': 1, 'pin-direction': 'input'}],
>+ 'pin-type': 'synce-eth-port'}
>+ }]
>
> Only one child pin can provide its signal to the parent MUX-type pin at
> a time, the selection is done by requesting change of a child pin state
> on desired parent, with the use of ``DPLL_A_PIN_PARENT`` nested
> attribute. Example of netlink `set state on parent pin` message format:
>
>- ===================== =============================================
>+ ====================== =============================================
> ``DPLL_A_PIN_ID`` child pin id
> ``DPLL_A_PIN_PARENT`` nested attribute for requesting configuration
> related to parent pin
> ``DPLL_A_PIN_ID`` parent pin id
> ``DPLL_A_PIN_STATE`` requested pin state on parent
>+ ====================== =============================================
>
> Pin priority
> ============
>@@ -149,6 +154,7 @@ device. Example of netlink `set priority on parent pin`
>message format:
> related to parent pin
> ``DPLL_A_ID`` parent dpll id
> ``DPLL_A_PIN_PRIO`` requested pin prio on parent dpll
>+ ===================== =============================================
>
> Child pin of MUX-type is not capable of automatic input pin selection,
> in order to configure a input of a MUX-type pin, the user needs to
>@@ -254,6 +260,7 @@ prefix and suffix according to attribute purpose:
> ``DPLL_A_PIN_STATE`` attr requested state of pin on
> the dpll device or on the parent
> pin
>+ ==================================== =================================
>
> Netlink dump requests
> =====================
>@@ -303,6 +310,7 @@ Values for ``DPLL_A_LOCK_STATUS`` attribute:
> acquired
> ``DPLL_LOCK_STATUS_HOLDOVER`` dpll device lost a lock, using its
> frequency holdover capabilities
>+ ================================== ===================================
>
> Values for ``DPLL_A_MODE`` attribute:
>
>@@ -316,12 +324,14 @@ Values for ``DPLL_A_MODE`` attribute:
> ``DPLL_MODE_HOLDOVER`` force holdover mode of dpll
> ``DPLL_MODE_FREERUN`` dpll device is driven by supplied system clock
> without holdover capabilities
>+ ======================= ==============================================
>
> Values for ``DPLL_A_TYPE`` attribute:
>
> ================= ===================================================
> ``DPLL_TYPE_PPS`` dpll device used to provide pulse-per-second output
> ``DPLL_TYPE_EEC`` dpll device used to drive ethernet equipment clock
>+ ================= ===================================================
>
> Pin level configuration pre-defined enums
> =========================================
>@@ -334,6 +344,7 @@ Values for ``DPLL_A_PIN_STATE`` attribute:
> ``DPLL_PIN_STATE_DISCONNECTED`` Pin disconnected from a dpll device or
> from a parent pin
> ``DPLL_PIN_STATE_SELECTABLE`` Pin enabled for automatic selection
>+ =============================== ======================================
>
> Values for ``DPLL_A_PIN_DIRECTION`` attribute:
>
>@@ -342,6 +353,7 @@ Values for ``DPLL_A_PIN_DIRECTION`` attribute:
> device
> ``DPLL_PIN_DIRECTION_OUTPUT`` used to output the signal from a dpll
> device
>+ ============================= ====================================
>
> Values for ``DPLL_A_PIN_TYPE`` attributes:
>
>@@ -353,6 +365,7 @@ Values for ``DPLL_A_PIN_TYPE`` attributes:
> ``DPLL_PIN_TYPE_INT_OSCILLATOR`` Internal Oscillator (i.e. Holdover
> with Atomic Clock as an input)
> ``DPLL_PIN_TYPE_GNSS`` GNSS 1PPS input
>+ ================================ =====================================
>
> Values for ``DPLL_A_PIN_DPLL_CAPS`` attributes:
>
>@@ -363,6 +376,7 @@ Values for ``DPLL_A_PIN_DPLL_CAPS`` attributes:
> can change
> ``DPLL_PIN_CAPS_STATE_CAN_CHANGE`` Bit present if state of pin can
> change
>+ ====================================== ===============================
>
> Notifications
> =============
>@@ -381,6 +395,7 @@ Notifications messages:
> ``DPLL_CMD_PIN_CREATE_NTF`` dpll pin was created
> ``DPLL_CMD_PIN_DELETE_NTF`` dpll pin was deleted
> ``DPLL_CMD_PIN_CHANGE_NTF`` dpll pin has changed
>+ ============================== =====================================
>
> Events format is the same as for the corresponding get command.
> Format of ``DPLL_CMD_DEVICE_`` events is the same as response of
>@@ -413,6 +428,7 @@ increases. Also dpll_pin_put() works similarly to
>dpll_device_put().
> A pin can be registered with parent dpll device or parent pin, depending
> on hardware needs. Each registration requires registerer to provide set
> of pin callbacks, and private data pointer for calling them:
>+
> - dpll_pin_register() - register pin with a dpll device,
> - dpll_pin_on_pin_register() - register pin with another MUX type pin.
>
>@@ -422,6 +438,7 @@ Notifications about registering/deregistering pins are
>also invoked by
> the subsystem.
> Notifications about status changes either of dpll device or a pin are
> invoked in two ways:
>+
> - after successful change was requested on dpll subsystem, the subsystem
> calls corresponding notification,
> - requested by device driver with dpll_device_change_ntf() or
>@@ -431,10 +448,11 @@ The device driver using dpll interface is not
>required to implement all
> the callback operation. Neverthelessi, there are few required to be
> implemented.
> Required dpll device level callback operations:
>+
> - ``.mode_get``,
> - ``.lock_status_get``.
>
>-Required pin level callback operations:
>+oRequired pin level callback operations:
This seems wrong here? I mean the "o" in front of required?
Added new line after the sentences, like:
+ Required pin level callback operations:
+
+ -``.state_get`` (pins registered with dpll device),
> - ``.state_get`` (pins registered with dpll device),
> - ``.state_on_pin_get`` (pins registered with parent pin),
> - ``.direction_get``.
>@@ -451,8 +469,8 @@ inputs.
> In such scenario, dpll device input signal shall be also configurable
> to drive dpll with signal recovered from the PHY netdevice.
> This is done by exposing a pin to the netdevice - attaching pin to the
>-netdevice itself with:
>-netdev_dpll_pin_set(struct net_device *dev, struct dpll_pin *dpll_pin);
>+netdevice itself with
>+``netdev_dpll_pin_set(struct net_device *dev, struct dpll_pin
>*dpll_pin)``.
> Exposed pin id handle ``DPLL_A_PIN_ID`` is then identifiable by the user
> as it is attached to rtnetlink respond to get ``RTM_NEWLINK`` command in
> nested attribute ``IFLA_DPLL_PIN``.
>
>(but because the fix diff above is quite large, Co-developed-by: from
>me may qualify).
>
>Thanks.
Many thanks for pointing this out, will do.
Thank you!
Arkadiusz
>
>--
>An old man doll... just what I always wanted! - Clara
