[PATCH v7 04/10] Documentation: uAPI: media: add V4L2_CID_FLASH_{DURATION,HW_STROBE_SIGNAL}

[Richard Leitner <richard.leitner@linux.dev>]

Add the new strobe duration and hardware strobe signal control to v4l
uAPI documentation. Additionally add labels for cross-referencing v4l
controls.

Signed-off-by: Richard Leitner <richard.leitner@linux.dev>
---
 .../userspace-api/media/v4l/ext-ctrls-flash.rst    | 29 ++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst
index d22c5efb806a183a3ad67ec3e6550b002a51659a..6254420a8ca95929d23ffdc65f40a6e53e30a635 100644
--- a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst
@@ -57,6 +57,8 @@ Flash Control IDs
 ``V4L2_CID_FLASH_CLASS (class)``
     The FLASH class descriptor.
 
+.. _v4l2-cid-flash-led-mode:
+
 ``V4L2_CID_FLASH_LED_MODE (menu)``
     Defines the mode of the flash LED, the high-power white LED attached
     to the flash controller. Setting this control may not be possible in
@@ -80,6 +82,8 @@ Flash Control IDs
 
 
 
+.. _v4l2-cid-flash-strobe-source:
+
 ``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
     Defines the source of the flash LED strobe.
 
@@ -186,3 +190,28 @@ Flash Control IDs
     charged before strobing. LED flashes often require a cooldown period
     after strobe during which another strobe will not be possible. This
     is a read-only control.
+
+.. _v4l2-cid-flash-duration:
+
+``V4L2_CID_FLASH_DURATION (integer)``
+    Duration of the flash strobe pulse generated by the strobe source,
+    typically a camera sensor. This method of controlling flash LED strobe
+    duration has three prerequisites: the strobe source's
+    :ref:`hardware strobe signal <v4l2-cid-flash-hw-strobe-signal>` must be
+    enabled, the flash LED driver's :ref:`flash LED mode <v4l2-cid-flash-led-mode>`
+    must be set to ``V4L2_FLASH_LED_MODE_FLASH``, and the
+    :ref:`strobe source <v4l2-cid-flash-strobe-source>` must be configured to
+    ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``. The unit should be microseconds (µs)
+    if possible.
+
+.. _v4l2-cid-flash-hw-strobe-signal:
+
+``V4L2_CID_FLASH_HW_STROBE_SIGNAL (boolean)``
+    Enables the output of a hardware strobe signal from the strobe source,
+    typically a camera sensor. To control a flash LED driver connected to this
+    hardware signal, the :ref:`flash LED mode <v4l2-cid-flash-led-mode>`
+    must be set to ``V4L2_FLASH_LED_MODE_FLASH`` and the
+    :ref:`strobe source <v4l2-cid-flash-strobe-source>` must be set to
+    ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``. Provided the flash LED driver
+    supports it, the length of the strobe signal can be configured by
+    adjusting its :ref:`flash duration <v4l2-cid-flash-duration>`.

-- 
2.47.2