[2/3] documentation: media: camera_sensor: Document blankings handling

When a new image format is applied on the sensor it is necessary to
update the vertical and horizontal blanking limits, to comply with the
new visibile sizes.

Add that part to the documentation of camera sensor subdevices.

Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
---
 .../driver-api/media/camera-sensor.rst        | 29 +++++++++++++++++++
 1 file changed, 29 insertions(+)

Hi Jacopo

Thanks for the patch.

On Mon, 7 Nov 2022 at 20:50, Jacopo Mondi <jacopo@jmondi.org> wrote:
>
> When a new image format is applied on the sensor it is necessary to
> update the vertical and horizontal blanking limits, to comply with the
> new visibile sizes.
>
> Add that part to the documentation of camera sensor subdevices.
>
> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
> ---
>  .../driver-api/media/camera-sensor.rst        | 29 +++++++++++++++++++
>  1 file changed, 29 insertions(+)
>
> diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst
> index bb7d62db4cd1..31f74f85ebc5 100644
> --- a/Documentation/driver-api/media/camera-sensor.rst
> +++ b/Documentation/driver-api/media/camera-sensor.rst
> @@ -107,6 +107,35 @@ The first entity in the linear pipeline is the pixel array. The pixel array may
>  be followed by other entities that are there to allow configuring binning,
>  skipping, scaling or digital crop :ref:`v4l2-subdev-selections`.
>
> +Blankings initialization and reconfiguration
> +""""""""""""""""""""""""""""""""""""""""""""
> +
> +The value used to initialize the vertical and horizontal blanking controls
> +should be selected in order to realize, in association with the driver default
> +format and default pixel rate, a reasonable frame rate output, usually one of
> +the standard 15, 30 or 60 frame per second.
> +
> +When a new frame size is applied on the subdevice sensor drivers are requested

s/requested/required. There's no option about it - if the ranges
change then the limits must be updated.

> +to update the limits of their blankings controls.
> +
> +The V4L2 control framework provides the ``v4l2_ctrl_modify_range()`` function
> +(and the unlocked ``__v4l2_ctrl_modify_range()`` counterpart) to assist drivers
> +in re-computing the controls limits.
> +
> +The new maximum limit for the controls should be re-calculated using the
> +newly applied visibile width and height

s/visibile/visible

However that depends on whether patch 1 is correct or not.

> +
> +.. code-block:: c
> +
> +       max_vblank = MAX_VTS - sensor->fmt.height;
> +       ret = __v4l2_ctrl_modify_range(sensor->ctrls.vblank,
> +                                      sensor->ctrls.vblank->minimum,
> +                                      max_vblank, sensor->ctrls.vblank->step,
> +                                      sensor->ctrls.vblank->minimum);
> +
> +The blankings default value is reset to the control minimum and the V4L2
> +control framework automatically clamps the control's value in the new limits.

So this raises the question we debated previously - what should the
default signify, and does it need to change?

  Dave

> +
>  USB cameras etc. devices
>  ~~~~~~~~~~~~~~~~~~~~~~~~
>
> --
> 2.38.1
>