@@ -189,3 +189,30 @@ the ``V4L2_CID_VFLIP`` and ``V4L2_CID_HFLIP`` controls with the
a flip can potentially change the output buffer content layout. Flips should
also be taken into account when enumerating and handling media bus formats
on the camera sensor source pads.
+
+Exposure and Gain Control
+-------------------------
+
+Camera sensor drivers that allow applications to control the image exposure
+and gain should do so by exposing dedicated controls to applications.
+
+Exposure time is controlled by registering the ``V4L2_CID_EXPOSURE`` control.
+The control definition does not specify a unit to allow maximum flexibility
+for multiple device types, but when used for camera sensor drivers it should be
+expressed in unit of lines whenever possible.
+
+To convert lines into units of time, the total line length (visible and
+not visible pixels) has to be divided by the pixel rate::
+
+ line duration = total line length / pixel rate
+ = (image width + horizontal blanking) / pixel rate
+
+Camera sensor driver should try whenever possible to distinguish between the
+analogue and digital gain control functions. Analogue gain is a multiplier
+factor applied to all color channels on the pixel array before they get
+converted in the digital domain. It should be made controllable by
+registering the ``V4L2_CID_ANALOGUE_GAIN`` control, expressed as a device
+specific gain code. Digital gain control is optional and should be exposed to
+applications by registering ``V4L2_CID_DIGITAL_GAIN``. Camera sensor drivers are
+discouraged from using ``V4L2_CID_GAIN`` as it doesn't allow differentiation of
+analogue vs digital gain.
Document the suggested way to exposure controls for exposure and gain for camera sensor drivers. Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com> --- .../driver-api/media/camera-sensor.rst | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+)