[PATCH v2 0/2] Documentation: media: camera_sensor: Document blankings handling

[PATCH v2 0/2] Documentation: media: camera_sensor: Document blankings handling

[Jacopo Mondi]

Document update of blankings and exposure on camera sensor mode change.

V1 -> v2, thanks Dave:
- Use analogue crop sizes
- Drop 1/3
- Correct language

Thanks
  j

Jacopo Mondi (2):
  documentation: media: camera_sensor: Document blankings handling
  documentation: media: camera_sensor: Update exposure on blanking
    change

 .../driver-api/media/camera-sensor.rst        | 69 +++++++++++++++++++
 1 file changed, 69 insertions(+)

--
2.38.1

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

[Jacopo Mondi]

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
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.38.1

[PATCH v2 2/2] documentation: media: camera_sensor: Update exposure on blanking change

[Jacopo Mondi]

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        | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst
index 382ea4ecebd4..675f55ad54b5 100644
--- a/Documentation/driver-api/media/camera-sensor.rst
+++ b/Documentation/driver-api/media/camera-sensor.rst
@@ -184,3 +184,39 @@ 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 limits on vertical blanking update
+"""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+The sensor exposure time, specified by the ``V4L2_CID_EXPOSURE`` control, is
+usually 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 = (analogue crop height) + ctrl->val - SENSOR_EXPOSURE_OFFSET;
+			__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