[3/3] documentation: media: camera_sensor: Update exposure on blanking change

The maximum achieable exposure time in a camera sensor is usually
bound by the total frame height (visible + blankings) minus a fixed
sensor-speific offset.

When the vertical blanking control value is changed, the exposure
control limits should be updated as well.

Add this to the camera sensor documentation.

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

Hi Jacopo

On Mon, 7 Nov 2022 at 20:50, Jacopo Mondi <jacopo@jmondi.org> wrote:
>
> The maximum achieable exposure time in a camera sensor is usually

s/achieable/achievable

> bound by the total frame height (visible + blankings) minus a fixed
> sensor-speific offset.

s/speific/specific

visible, or analogue crop?

> When the vertical blanking control value is changed, the exposure
> control limits should be updated as well.
>
> Add this to the camera sensor documentation.
>
> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
> ---
>  .../driver-api/media/camera-sensor.rst        | 33 +++++++++++++++++++
>  1 file changed, 33 insertions(+)
>
> diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst
> index 31f74f85ebc5..76206c7647d6 100644
> --- a/Documentation/driver-api/media/camera-sensor.rst
> +++ b/Documentation/driver-api/media/camera-sensor.rst
> @@ -179,3 +179,36 @@ used to obtain device's power state after the power state transition:
>  The function returns a non-zero value if it succeeded getting the power count or
>  runtime PM was disabled, in either of which cases the driver may proceed to
>  access the device.
> +
> +Resetting exposure on vertical blanking update

Resetting exposure limits on vertical blanking update
You don't want to update the value (unless it is now outside the
permissible range).

> +""""""""""""""""""""""""""""""""""""""""""""""
> +
> +The sensor exposure time, specified by the ``V4L2_CID_EXPOSURE`` control, is
> +usually limited by a maximum value which is equal to maximum vertical blankings
> +minus a known offset usually specified in the chip programming manual.

limited to a maximum value related to the frame interval. Frequently
it is a number of lines less than the frame length that will be
specified in the sensor documentation.

> +When a new ``V4L2_CID_VBLANK`` value is applied, regardless of it being actually
> +programmed to the hardware or not, the limits of the ``V4L2_CID_EXPOSURE``
> +control should be updated as well.
> +
> +The typical coding pattern that realizes that in the ``.s_ctrl`` callback
> +handler is:
> +
> +.. code-block:: c
> +

#define SENSOR_EXPOSURE_OFFSET   <see sensor documentation>

> +       static int s_ctrl(struct v4l2_ctrl *ctrl)
> +       {
> +               int exp_max;
> +
> +               switch (ctrl->id) {
> +               case V4L2_CID_VBLANK:
> +                       exp_max = sensor->fmt.height + ctrl->val - 4;

sensor->fmt.height + ctrl->val - SENSOR_EXPOSURE_OFFSET.

Discussion on patch 1 over the use of sensor->fmt.height.

  Dave

> +                       __v4l2_ctrl_modify_range(sensor->ctrls.exposure,
> +                       sensor->ctrls.exposure->minimum,
> +                       exp_max, sensor->ctrls.exposure->step,
> +                       sensor->ctrls.exposure->default_value);
> +                       break;
> +               }
> +
> +               if (!pm_runtime_get_if_in_use(&sensor->i2c_client->dev))
> +                       return 0;
> --
> 2.38.1
>