182bdadd0f
Add a new .rst file referencing the documentation contents. This file is then included in each documentation page so that we can enhance the Documentation pages on the libcamera website using it. As we do not want the appearance of the libcamera in-tree Documentation to change just yet, disable the new class using the sphinx theme's CSS. To facilitate easier distinguishing between "normal" and documentation pages on the website we want to add a "documentation" class to the content of all such pages. Since this new file will be included on each documentation page it is convenient to add the new directive here - do so. As the website uses different CSS to libcamera, move the contents on docs.rst a little so that the directive at the end of the contents block applies correctly. Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
95 lines
4.2 KiB
ReStructuredText
95 lines
4.2 KiB
ReStructuredText
.. 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
|