Re: [PATCH net-next 1/4] dpll: docs: add support for pin signal phase offset/adjust

[Jiri Pirko <jiri@resnulli.us>]

Wed, Sep 27, 2023 at 11:24:32AM CEST, arkadiusz.kubalewski@intel.com wrote:
>Add dpll documentation on new pin's attributes:
>- phase-offset - measured difference between phase of signals on pin
>  and dpll
>- phase-adjust - adjustable value of pin's signal phase
>- phase-adjust-min / phase-adjust-max - values for determining limits
>  for phase-adjust
>
>Signed-off-by: Arkadiusz Kubalewski <arkadiusz.kubalewski@intel.com>
>---
> Documentation/driver-api/dpll.rst | 53 ++++++++++++++++++++++++++++++-
> 1 file changed, 52 insertions(+), 1 deletion(-)
>
>diff --git a/Documentation/driver-api/dpll.rst b/Documentation/driver-api/dpll.rst
>index bb52f1b8c0be..59634a3513bd 100644
>--- a/Documentation/driver-api/dpll.rst
>+++ b/Documentation/driver-api/dpll.rst
>@@ -173,6 +173,47 @@ in order to configure active 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.
> 
>+Phase offset measurement and adjustment
>+========================================
>+
>+Device may provide ability to measure a phase difference between signals
>+on a pin and its parent dpll device. If pin-dpll phase offset measurement
>+is supported, it shall be provided with ``DPLL_A_PIN_PHASE_OFFSET``
>+attribute for each parent dpll device.
>+
>+Device may also provide ability to adjust a signal phase on a pin.
>+If pin phase adjustment is supported, minimal and maximal values that pin
>+handle shall be provide to the user on ``DPLL_CMD_PIN_GET`` respond
>+with ``DPLL_A_PIN_PHASE_ADJUST_MIN`` and ``DPLL_A_PIN_PHASE_ADJUST_MAX``
>+attributes. Configured phase adjust value is provided with
>+``DPLL_A_PIN_PHASE_ADJUST`` attribute of a pin, and value change can be
>+requested with the same attribute with ``DPLL_CMD_PIN_SET`` command.
>+
>+  =============================== ======================================
>+  ``DPLL_A_PIN_ID``               configured pin id
>+  ``DPLL_A_PIN_PHASE_ADJUST_MIN`` attr minimum value of phase adjustment
>+  ``DPLL_A_PIN_PHASE_ADJUST_MAX`` attr maximum value of phase adjustment
>+  ``DPLL_A_PIN_PHASE_ADJUST``     attr configured value of phase
>+                                  adjustment on parent dpll device
>+  ``DPLL_A_PIN_PARENT_DEVICE``    nested attribute for requesting
>+                                  configuration on given parent dpll
>+                                  device
>+    ``DPLL_A_PIN_PARENT_ID``      parent dpll device id
>+    ``DPLL_A_PIN_PHASE_OFFSET``   attr measured phase difference
>+                                  between a pin and parent dpll device
>+  =============================== ======================================
>+
>+All phase related values are provided in pico seconds, which represents
>+time differnece between signals phase. The negative value means that
>+phase of signal on pin is earlier in time than dpll's signal. Positive
>+value means that phase of signal on pin is later in time than signal of
>+a dpll.
>+
>+Phase adjust (also min and max) values are integers, but measured phase
>+offset values are fractional with 3-digit decimal places and shell be
>+divided with ``DPLL_PIN_PHASE_OFFSET_DIVIDER`` to get integer part and
>+modulo divided to get fractional part.
>+
> Configuration commands group
> ============================
> 
>@@ -263,6 +304,12 @@ according to attribute purpose.
>                                        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_PHASE_ADJUST_MIN``    attr minimum value of phase
>+                                       adjustment
>+    ``DPLL_A_PIN_PHASE_ADJUST_MAX``    attr maximum value of phase
>+                                       adjustment
>+    ``DPLL_A_PIN_PHASE_ADJUST``        attr configured value of phase
>+                                       adjustment on parent device
>     ``DPLL_A_PIN_PARENT_DEVICE``       nested attr for each parent device
>                                        the pin is connected with
>       ``DPLL_A_PIN_PARENT_ID``         attr parent dpll device id
>@@ -270,8 +317,10 @@ according to attribute purpose.
>                                        dpll device
>       ``DPLL_A_PIN_STATE``             attr state of pin on the parent
>                                        dpll device
>-     ``DPLL_A_PIN_DIRECTION``          attr direction of a pin on the
>+      ``DPLL_A_PIN_DIRECTION``         attr direction of a pin on the

Could be in a separate patch, it's not related to this one.


>                                        parent dpll device
>+      ``DPLL_A_PIN_PHASE_OFFSET``      attr measured phase difference
>+                                       between a pin and parent dpll
>     ``DPLL_A_PIN_PARENT_PIN``          nested attr for each parent pin
>                                        the pin is connected with
>       ``DPLL_A_PIN_PARENT_ID``         attr parent pin id
>@@ -284,6 +333,8 @@ according to attribute purpose.
>   ``DPLL_CMD_PIN_SET``                 command to set pins configuration
>     ``DPLL_A_PIN_ID``                  attr unique a pin ID
>     ``DPLL_A_PIN_FREQUENCY``           attr requested frequency of a pin
>+    ``DPLL_A_PIN_PHASE_ADJUST``        attr requested value of phase
>+                                       adjustment on parent device
>     ``DPLL_A_PIN_PARENT_DEVICE``       nested attr for each parent dpll
>                                        device configuration request
>       ``DPLL_A_PIN_PARENT_ID``         attr parent dpll device id
>-- 
>2.38.1
>