[v2,1/2] documentation: media: camera_sensor: Document blankings handling

Message ID 20221121181515.34008-2-jacopo@jmondi.org (mailing list archive)
State New
Series Documentation: media: camera_sensor: Document blankings handling |

Commit Message

Jacopo Mondi Nov. 21, 2022, 6:15 p.m. UTC
  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        | 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 c7d4891bd24e..382ea4ecebd4 100644
--- a/Documentation/driver-api/media/camera-sensor.rst
+++ b/Documentation/driver-api/media/camera-sensor.rst
@@ -108,6 +108,39 @@  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 required
+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 limits for the controls should be re-calculated using the newly
+configured size:
+.. code-block:: c
+	#define SENSOR_MAX_VTS          <see sensor documentation>
+	max_vblank = SENSOR_MAX_VTS - (analogue crop height);
+	ret = __v4l2_ctrl_modify_range(sensor->ctrls.vblank,
+				       sensor->ctrls.vblank->minimum,
+				       max_vblank, sensor->ctrls.vblank->step,
+				       sensor->ctrls.vblank->minimum);
+The minimum value could potentially change as well.
+The control default value is reset to the control's minimum and the V4L2
+control framework automatically clamps the control's value in the new limits.
 USB cameras etc. devices