Re: [PATCH v2 02/48] Documentation: media: camera-sensor: Mention v4l2_devm_sensor_clk_get() for obtaining the clock

[Laurent Pinchart <laurent.pinchart@ideasonboard.com>]

On Thu, Jun 26, 2025 at 03:33:53PM +0200, Mehdi Djait wrote:
> Add the new v4l2 helper devm_v4l2_sensor_clk_get() to Documentation. the
> helper works on both DT- and ACPI-based platforms to retrieve a
> reference to the clock producer from firmware.
> 
> Reviewed-by: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

> Co-developed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> Signed-off-by: Mehdi Djait <mehdi.djait@linux.intel.com>
> ---
>  .../driver-api/media/camera-sensor.rst        | 24 +++++++++++++------
>  1 file changed, 17 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst
> index c290833165e6..94bd1dae82d5 100644
> --- a/Documentation/driver-api/media/camera-sensor.rst
> +++ b/Documentation/driver-api/media/camera-sensor.rst
> @@ -29,21 +29,31 @@ used in the system. Using another frequency may cause harmful effects
>  elsewhere. Therefore only the pre-determined frequencies are configurable by the
>  user.
>  
> +The external clock frequency shall be retrieved by obtaining the external clock
> +using the ``devm_v4l2_sensor_clk_get()`` helper function, and then getting its
> +frequency with ``clk_get_rate()``. Usage of the helper function guarantees
> +correct behaviour regardless of whether the sensor is integrated in a DT-based
> +or ACPI-based system.
> +
>  ACPI
>  ~~~~
>  
> -Read the ``clock-frequency`` _DSD property to denote the frequency. The driver
> -can rely on this frequency being used.
> +ACPI-based systems typically don't register the sensor external clock with the
> +kernel, but specify the external clock frequency in the ``clock-frequency``
> +_DSD property. The ``devm_v4l2_sensor_clk_get()`` helper creates and returns a
> +fixed clock set at that rate.
>  
>  Devicetree
>  ~~~~~~~~~~
>  
> -The preferred way to achieve this is using ``assigned-clocks``,
> -``assigned-clock-parents`` and ``assigned-clock-rates`` properties. See the
> -`clock device tree bindings
> +Devicetree-based systems declare the sensor external clock in the device tree
> +and reference it from the sensor node. The preferred way to select the external
> +clock frequency is to use the ``assigned-clocks``, ``assigned-clock-parents``
> +and ``assigned-clock-rates`` properties in the sensor node to set the clock
> +rate. See the `clock device tree bindings
>  <https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/clock/clock.yaml>`_
> -for more information. The driver then gets the frequency using
> -``clk_get_rate()``.
> +for more information. The ``devm_v4l2_sensor_clk_get()`` helper retrieves and
> +returns that clock.
>  
>  This approach has the drawback that there's no guarantee that the frequency
>  hasn't been modified directly or indirectly by another driver, or supported by

-- 
Regards,

Laurent Pinchart