summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJacopo Mondi <jacopo@jmondi.org>2020-12-30 18:02:48 +0100
committerJacopo Mondi <jacopo@jmondi.org>2021-01-18 10:39:13 +0100
commit1b4997ef08a04bcad205d6708cdb25a88740301c (patch)
treee141dd4fbf6b8770237f7ba6d51521e945a78e8b
parent7415c139cd1cab73fdd91785a7816eab51e7a567 (diff)
libcamera: Document sensor driver requirements
Document the feature an image sensor driver has to provide to be fully libcamera-compliant. Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
-rw-r--r--Documentation/index.rst1
-rw-r--r--Documentation/meson.build1
-rw-r--r--Documentation/sensor_driver_requirements.rst64
3 files changed, 66 insertions, 0 deletions
diff --git a/Documentation/index.rst b/Documentation/index.rst
index c49db18d..285ca7c3 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -18,3 +18,4 @@
Pipeline Handler Writer's Guide <guides/pipeline-handler>
Tracing guide <guides/tracing>
Environment variables <environment_variables>
+ Sensor driver requirements <sensor_driver_requirements>
diff --git a/Documentation/meson.build b/Documentation/meson.build
index b1f5bb52..9950465d 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -57,6 +57,7 @@ if sphinx.found()
'guides/pipeline-handler.rst',
'guides/tracing.rst',
'index.rst',
+ 'sensor_driver_requirements.rst',
'../README.rst',
]
diff --git a/Documentation/sensor_driver_requirements.rst b/Documentation/sensor_driver_requirements.rst
new file mode 100644
index 00000000..0e658aaa
--- /dev/null
+++ b/Documentation/sensor_driver_requirements.rst
@@ -0,0 +1,64 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. _sensor-driver-requirements:
+
+Sensor Driver Requirements
+==========================
+
+libcamera handles imaging devices in the CameraSensor class and defines
+through its API a consistent interface 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 to applications and
+pipeline handlers all the required information to interface with the camera
+sensor, 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.
+
+The sensor driver shall support the following V4L2 controls:
+
+* `V4L2_CID_HBLANK`_
+* `V4L2_CID_PIXEL_RATE`_
+
+.. _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
+
+Both 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-image-process.html
+
+The controls are used to register the camera location and orientation.
+
+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?highlight=g_selection#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