diff options
Diffstat (limited to 'Documentation/sensor_driver_requirements.rst')
| -rw-r--r-- | Documentation/sensor_driver_requirements.rst | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/Documentation/sensor_driver_requirements.rst b/Documentation/sensor_driver_requirements.rst new file mode 100644 index 00000000..fb4269d0 --- /dev/null +++ b/Documentation/sensor_driver_requirements.rst @@ -0,0 +1,95 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. include:: documentation-contents.rst + +.. _sensor-driver-requirements: + +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`_ + +.. _V4L2_CID_ANALOGUE_GAIN: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/ext-ctrls-image-source.html +.. _V4L2_CID_EXPOSURE: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/control.html +.. _V4L2_CID_HBLANK: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/ext-ctrls-image-source.html +.. _V4L2_CID_PIXEL_RATE: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/ext-ctrls-image-process.html +.. _V4L2_CID_VBLANK: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/ext-ctrls-image-source.html + +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`_ + +.. _V4L2_CID_CAMERA_ORIENTATION: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/ext-ctrls-camera.html +.. _V4L2_CID_CAMERA_SENSOR_ROTATION: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/ext-ctrls-camera.html + +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`_ + +.. _V4L2_CID_HFLIP: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/control.html +.. _V4L2_CID_VFLIP: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/control.html + +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: + +.. _VIDIOC_SUBDEV_G_SELECTION: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/vidioc-subdev-g-selection.html#c.V4L.VIDIOC_SUBDEV_G_SELECTION + +* `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. + +.. _V4L2_SEL_TGT_CROP_BOUNDS: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/v4l2-selection-targets.html +.. _V4L2_SEL_TGT_CROP_DEFAULT: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/v4l2-selection-targets.html +.. _V4L2_SEL_TGT_CROP: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/v4l2-selection-targets.html |