Hi Jacopo, On Mon, Jul 10, 2023 at 03:22:40PM +0200, Jacopo Mondi wrote: > Document the suggested way to exposure controls for exposure and gain > for camera sensor drivers. > > Signed-off-by: Jacopo Mondi <jacopo.mondi@xxxxxxxxxxxxxxxx> > Reviewed-by: Dave Stevenson <dave.stevenson@xxxxxxxxxxxxxxx> > --- > .../driver-api/media/camera-sensor.rst | 27 +++++++++++++++++++ > 1 file changed, 27 insertions(+) > > diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst > index cd915ca119ea..67fe77b1edb9 100644 > --- a/Documentation/driver-api/media/camera-sensor.rst > +++ b/Documentation/driver-api/media/camera-sensor.rst > @@ -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. This part of the documentation applies to both raw and SoC cameras. Should the exposure unit be something more user-friendly for SoC cameras? We have two exposure controls now, V4L2_CID_EXPOSURE and V4L2_CID_EXPOSURE_ABSOLUTE. The former doesn't specity a unit whereas the latter suggests the unit of 100 µs. As exposure is specific to cameras, I think at least a part of this should make it to the controls documentation. The UVC, for instance, uses EXPOSURE_ABSOLUTE. Could we document V4L2_CID_EXPOSURE is in lines (if 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 multiplication > +factor applied to all color channels on the pixel array before they get > +converted into the digital domain. It should be made controllable by The analogue gain may not be linear. This depends on the sensor. I'd thus drop the wording related to multiplication factor. > +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. -- Kind regards, Sakari Ailus
