Skip to main content
`Ctrl`+`K`

# Sensor Driver Requirements

libcamera handles imaging devices in the CameraSensor class and defines a consistent interface through its API towards other library components.

The CameraSensor class uses the V4L2 subdev kernel API to interface with the camera sensor through one or multiple sub-devices exposed in userspace by the sensor driver.

In order for libcamera to be fully operational and provide all the required information to interface with the camera sensor to applications and pipeline handlers, a set of mandatory and optional features the driver has to support has been defined.

## Mandatory Requirements

The sensor driver is assumed to be fully compliant with the V4L2 specification.

For RAW sensors, the sensor driver shall support the following V4L2 controls:

- V4L2_CID_ANALOGUE_GAIN

- V4L2_CID_EXPOSURE

- V4L2_CID_HBLANK

- V4L2_CID_PIXEL_RATE

- V4L2_CID_VBLANK

The `ANALOGUE_GAIN` control units are sensor-specific. libcamera requires a sensor-specific CameraSensorHelper implementation to translate between the sensor specific `gain code` and the analogue `gain value` expressed as an absolute number as defined by `controls::AnalogueGain`.

While V4L2 doesn’t specify a unit for the `EXPOSURE` control, libcamera requires it to be expressed as a number of image lines. Camera sensor drivers that do not comply with this requirement will need to be adapted or will produce incorrect results.

The `HBLANK`, `PIXEL_RATE` and `VBLANK` controls are used to compute the sensor output timings.

## Optional Requirements

The sensor driver should support the following V4L2 controls:

- V4L2_CID_CAMERA_ORIENTATION

- V4L2_CID_CAMERA_SENSOR_ROTATION

The controls are used to register the camera location and rotation.

In order to support rotating the image the sensor driver should support

- V4L2_CID_HFLIP

- V4L2_CID_VFLIP

The controls must be writable from userspace. In case of a RAW Bayer sensors, drivers should correctly report if vertical/horizontal flips modify the Bayer pattern ordering by reporting the V4L2_CTRL_FLAG_MODIFY_LAYOUT control flag.

The sensor driver should implement support for the V4L2 Selection API, specifically it should implement support for the VIDIOC_SUBDEV_G_SELECTION ioctl with support for the following selection targets:

- V4L2_SEL_TGT_CROP_BOUNDS to report the readable pixel array area size

- V4L2_SEL_TGT_CROP_DEFAULT to report the active pixel array area size

- V4L2_SEL_TGT_CROP to report the analogue selection rectangle

Support for the selection API is scheduled to become a mandatory feature in the near future.