From 1b4997ef08a04bcad205d6708cdb25a88740301c Mon Sep 17 00:00:00 2001 From: Jacopo Mondi Date: Wed, 30 Dec 2020 18:02:48 +0100 Subject: libcamera: Document sensor driver requirements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the feature an image sensor driver has to provide to be fully libcamera-compliant. Reviewed-by: Laurent Pinchart Reviewed-by: Niklas Söderlund Signed-off-by: Jacopo Mondi --- Documentation/index.rst | 1 + Documentation/meson.build | 1 + Documentation/sensor_driver_requirements.rst | 64 ++++++++++++++++++++++++++++ 3 files changed, 66 insertions(+) create mode 100644 Documentation/sensor_driver_requirements.rst (limited to 'Documentation') 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 Tracing guide Environment variables + 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 -- cgit v1.2.1