[3/5] Documentation: Add flash driver requirements
diff mbox series

Message ID 20250828-flash-support-v1-3-4c5dc674a05b@emfend.at
State New
Headers show
Series
  • Support for v4l2 flash devices
Related show

Commit Message

Matthias Fend Aug. 28, 2025, 1:09 p.m. UTC 
Document the requirements for the v4l2 flash device drivers required by
libcamera.

Signed-off-by: Matthias Fend <matthias.fend@emfend.at>
---
 Documentation/documentation-contents.rst    |  1 +
 Documentation/flash_driver_requirements.rst | 40 +++++++++++++++++++++++++++++
 Documentation/index.rst                     |  1 +
 Documentation/meson.build                   |  1 +
 4 files changed, 43 insertions(+)

Patch
diff mbox series 

diff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst
index 5c1118493745692f2521bced9dab48098585c39e..be7415cde42f55ae5f9da20bc9211227b8f8658c 100644
--- a/Documentation/documentation-contents.rst
+++ b/Documentation/documentation-contents.rst
@@ -22,6 +22,7 @@ 
    * :doc:`/internal-api-html/index`
    * |
    * **Documentation for System Integrators**
+   * :doc:`/flash_driver_requirements`
    * :doc:`/lens_driver_requirements`
    * :doc:`/sensor_driver_requirements`
 
diff --git a/Documentation/flash_driver_requirements.rst b/Documentation/flash_driver_requirements.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b4a1b4866e651c506203af7089b5634808de5ab7
--- /dev/null
+++ b/Documentation/flash_driver_requirements.rst
@@ -0,0 +1,40 @@ 
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. include:: documentation-contents.rst
+
+.. _flash-driver-requirements:
+
+Flash Driver Requirements
+=========================
+
+libcamera handles V4L2 flash devices in the CameraFlash class and defines
+a consistent interface through its API towards other library components.
+
+The CameraFlash class uses the V4L2 subdev kernel API to interface with the
+camera flash through a sub-device exposed to userspace by the V4L2 flash driver.
+
+In order for libcamera to be fully operational and provide all the required
+information to interface with the camera flash to applications and pipeline
+handlers, the driver must support a set of mandatory features.
+
+Mandatory Requirements
+----------------------
+
+The flash driver is assumed to be fully compliant with the V4L2 specification.
+
+The flash driver shall support the following V4L2 controls:
+
+* `V4L2_CID_FLASH_LED_MODE`_
+* `V4L2_CID_FLASH_STROBE_SOURCE`_
+* `V4L2_CID_FLASH_STROBE`_
+* `V4L2_CID_FLASH_TIMEOUT`_
+* `V4L2_CID_FLASH_INTENSITY`_
+* `V4L2_CID_FLASH_TORCH_INTENSITY`_
+
+.. _V4L2_CID_FLASH_LED_MODE: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/ext-ctrls-flash.html
+.. _V4L2_CID_FLASH_STROBE_SOURCE: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/ext-ctrls-flash.html
+.. _V4L2_CID_FLASH_STROBE: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/ext-ctrls-flash.html
+.. _V4L2_CID_FLASH_TIMEOUT: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/ext-ctrls-flash.html
+.. _V4L2_CID_FLASH_INTENSITY: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/ext-ctrls-flash.html
+.. _V4L2_CID_FLASH_TORCH_INTENSITY: https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/ext-ctrls-flash.html
+
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 251112fbdf5f075b3e5c064d7230b9ad2c23b587..7ed56c17787fc643ef74cc35ef5b5db7d29eb18d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -14,6 +14,7 @@ 
    Camera Sensor Model <camera-sensor-model>
    Environment variables <environment_variables>
    Feature Requirements <feature_requirements>
+   Flash driver requirements <flash_driver_requirements>
    IPA Writer's guide <guides/ipa>
    Lens driver requirements <lens_driver_requirements>
    libcamera Architecture <libcamera_architecture>
diff --git a/Documentation/meson.build b/Documentation/meson.build
index a8d4afc01dd154546d107b49bc322a993e4d78bd..965b33c60b031610251efbe59abb1682cb714d4a 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -159,6 +159,7 @@  if sphinx.found()
         'documentation-contents.rst',
         'environment_variables.rst',
         'feature_requirements.rst',
+        'flash_driver_requirements.rst',
         'guides/application-developer.rst',
         'guides/ipa.rst',
         'guides/pipeline-handler.rst',