1. Patchew
  2. linux
  3. [PATCH v6 00/11] Add strobe duration and hw strobe signal v4l2 ctrl & use it for ov9282
  4. View patch

[PATCH v6 03/11] Documentation: uAPI: media: add V4L2_CID_FLASH_DURATION

Richard Leitner posted 11 patches 2 months, 3 weeks ago
There is a newer version of this series
[PATCH v6 03/11] Documentation: uAPI: media: add V4L2_CID_FLASH_DURATION
Posted by Richard Leitner 2 months, 3 weeks ago 
Add the new strobe_duration control to v4l uAPI documentation.

Signed-off-by: Richard Leitner <richard.leitner@linux.dev>
---
 Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst | 5 +++++
 1 file changed, 5 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..03a58ef94be7c870f55d5a9bb09503995dbfb402 100644
--- a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst
@@ -186,3 +186,8 @@ 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 (integer)``
+    Duration the flash should be on when the flash LED is in flash mode
+    (V4L2_FLASH_LED_MODE_FLASH). The unit should be microseconds (µs)
+    if possible.

-- 
2.47.2
Re: [PATCH v6 03/11] Documentation: uAPI: media: add V4L2_CID_FLASH_DURATION
Posted by Sakari Ailus 1 month, 1 week ago 
Hi Richard,

Thanks for the update (and for the ping!).

On Wed, Jul 16, 2025 at 11:06:53AM +0200, Richard Leitner wrote:
> Add the new strobe_duration control to v4l uAPI documentation.
> 
> Signed-off-by: Richard Leitner <richard.leitner@linux.dev>
> ---
>  Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst | 5 +++++
>  1 file changed, 5 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..03a58ef94be7c870f55d5a9bb09503995dbfb402 100644
> --- a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst
> +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst
> @@ -186,3 +186,8 @@ 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 (integer)``
> +    Duration the flash should be on when the flash LED is in flash mode
> +    (V4L2_FLASH_LED_MODE_FLASH). The unit should be microseconds (µs)
> +    if possible.
> 

I think we should add this is related to the hardware strobe.

How about:

``V4L2_CID_FLASH_DURATION (integer)``

    Duration of the flash strobe from the strobe source, typically a camera
    sensor. Controlling the flash LED strobe length this way requires that the
    flash LED driver's :ref:`flash LED mode <v4l2-cid-flash-led-mode>` is set
    to ``V4L2_FLASH_LED_MODE_FLASH`` and :ref:`strobe source
    <v4l2-cid-strobe-source>` is set to ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``.
    The unit should be microseconds (µs) if possible.

This requires of course the appropriate labels.

I also wonder whether we should use 0,1 µs or even ns for the unit.

-- 
Kind regards,

Sakari Ailus
Re: [PATCH v6 03/11] Documentation: uAPI: media: add V4L2_CID_FLASH_DURATION
Posted by Richard Leitner 1 month ago 
On Mon, Aug 25, 2025 at 08:42:17AM +0300, Sakari Ailus wrote:
> Hi Richard,
> 
> Thanks for the update (and for the ping!).
> 
> On Wed, Jul 16, 2025 at 11:06:53AM +0200, Richard Leitner wrote:
> > Add the new strobe_duration control to v4l uAPI documentation.
> > 
> > Signed-off-by: Richard Leitner <richard.leitner@linux.dev>
> > ---
> >  Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst | 5 +++++
> >  1 file changed, 5 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..03a58ef94be7c870f55d5a9bb09503995dbfb402 100644
> > --- a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst
> > +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst
> > @@ -186,3 +186,8 @@ 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 (integer)``
> > +    Duration the flash should be on when the flash LED is in flash mode
> > +    (V4L2_FLASH_LED_MODE_FLASH). The unit should be microseconds (µs)
> > +    if possible.
> > 
> 
> I think we should add this is related to the hardware strobe.
> 
> How about:
> 
> ``V4L2_CID_FLASH_DURATION (integer)``
> 
>     Duration of the flash strobe from the strobe source, typically a camera
>     sensor. Controlling the flash LED strobe length this way requires that the
>     flash LED driver's :ref:`flash LED mode <v4l2-cid-flash-led-mode>` is set
>     to ``V4L2_FLASH_LED_MODE_FLASH`` and :ref:`strobe source
>     <v4l2-cid-strobe-source>` is set to ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``.
>     The unit should be microseconds (µs) if possible.
> 
> This requires of course the appropriate labels.
> 
> I also wonder whether we should use 0,1 µs or even ns for the unit.

Thanks for the pointer.

I did a quick internet search and the shortest flash duration of
speedlights/studio strobes I found was Profoto D2 with 1/63000 sec ~> 15.9µs.
So I IMHO we are fine with 1µs resolution here.

regards;rl

> 
> -- 
> Kind regards,
> 
> Sakari Ailus
Re: [PATCH v6 03/11] Documentation: uAPI: media: add V4L2_CID_FLASH_DURATION
Posted by Sakari Ailus 1 month ago 
Hi Richard,

On Mon, Sep 01, 2025 at 12:44:07PM +0200, Richard Leitner wrote:
> On Mon, Aug 25, 2025 at 08:42:17AM +0300, Sakari Ailus wrote:
> > Hi Richard,
> > 
> > Thanks for the update (and for the ping!).
> > 
> > On Wed, Jul 16, 2025 at 11:06:53AM +0200, Richard Leitner wrote:
> > > Add the new strobe_duration control to v4l uAPI documentation.
> > > 
> > > Signed-off-by: Richard Leitner <richard.leitner@linux.dev>
> > > ---
> > >  Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst | 5 +++++
> > >  1 file changed, 5 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..03a58ef94be7c870f55d5a9bb09503995dbfb402 100644
> > > --- a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst
> > > +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst
> > > @@ -186,3 +186,8 @@ 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 (integer)``
> > > +    Duration the flash should be on when the flash LED is in flash mode
> > > +    (V4L2_FLASH_LED_MODE_FLASH). The unit should be microseconds (µs)
> > > +    if possible.
> > > 
> > 
> > I think we should add this is related to the hardware strobe.
> > 
> > How about:
> > 
> > ``V4L2_CID_FLASH_DURATION (integer)``
> > 
> >     Duration of the flash strobe from the strobe source, typically a camera
> >     sensor. Controlling the flash LED strobe length this way requires that the
> >     flash LED driver's :ref:`flash LED mode <v4l2-cid-flash-led-mode>` is set
> >     to ``V4L2_FLASH_LED_MODE_FLASH`` and :ref:`strobe source
> >     <v4l2-cid-strobe-source>` is set to ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``.
> >     The unit should be microseconds (µs) if possible.
> > 
> > This requires of course the appropriate labels.
> > 
> > I also wonder whether we should use 0,1 µs or even ns for the unit.
> 
> Thanks for the pointer.
> 
> I did a quick internet search and the shortest flash duration of
> speedlights/studio strobes I found was Profoto D2 with 1/63000 sec ~> 15.9µs.
> So I IMHO we are fine with 1µs resolution here.

Works for me.

-- 
Sakari Ailus
Re: [PATCH v6 03/11] Documentation: uAPI: media: add V4L2_CID_FLASH_DURATION
Posted by Sakari Ailus 1 month, 1 week ago 
On Mon, Aug 25, 2025 at 08:42:19AM +0300, Sakari Ailus wrote:
> Hi Richard,
> 
> Thanks for the update (and for the ping!).
> 
> On Wed, Jul 16, 2025 at 11:06:53AM +0200, Richard Leitner wrote:
> > Add the new strobe_duration control to v4l uAPI documentation.
> > 
> > Signed-off-by: Richard Leitner <richard.leitner@linux.dev>
> > ---
> >  Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst | 5 +++++
> >  1 file changed, 5 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..03a58ef94be7c870f55d5a9bb09503995dbfb402 100644
> > --- a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst
> > +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst
> > @@ -186,3 +186,8 @@ 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 (integer)``
> > +    Duration the flash should be on when the flash LED is in flash mode
> > +    (V4L2_FLASH_LED_MODE_FLASH). The unit should be microseconds (µs)
> > +    if possible.
> > 
> 
> I think we should add this is related to the hardware strobe.
> 
> How about:
> 
> ``V4L2_CID_FLASH_DURATION (integer)``
> 
>     Duration of the flash strobe from the strobe source, typically a camera
>     sensor. Controlling the flash LED strobe length this way requires that the
>     flash LED driver's :ref:`flash LED mode <v4l2-cid-flash-led-mode>` is set
>     to ``V4L2_FLASH_LED_MODE_FLASH`` and :ref:`strobe source
>     <v4l2-cid-strobe-source>` is set to ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``.
>     The unit should be microseconds (µs) if possible.

Also adding a reference to V4L2_CID_FLASH_HW_STROBE_SIGNAL:

``V4L2_CID_FLASH_DURATION (integer)``
    Duration of the flash strobe from the strobe source, typically a camera
    sensor. Controlling the flash LED strobe length this way requires that the
    strobe source's :ref:`V4L2_CID_FLASH_HW_STROBE_SIGNAL
    <v4l2-cid-flash-hw-strobe>` is enabled and flash LED driver's :ref:`flash
    LED mode <v4l2-cid-flash-led-mode>` is set to ``V4L2_FLASH_LED_MODE_FLASH``
    and :ref:`strobe source <v4l2-cid-strobe-source>` is set to
    ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``. The unit should be microseconds (µs)
    if possible.

Similarly, the documentation for V4L2_CID_FLASH_HW_STROBE_SIGNAL should be
amended with a reference, but the label needs to exist first. I think you
could merge the two documentation patches to make this easier.

-- 
Sakari Ailus
Re: [PATCH v6 03/11] Documentation: uAPI: media: add V4L2_CID_FLASH_DURATION
Posted by Richard Leitner 1 month, 1 week ago 
Hi Sakari,

On Mon, Aug 25, 2025 at 08:48:31AM +0300, Sakari Ailus wrote:
> On Mon, Aug 25, 2025 at 08:42:19AM +0300, Sakari Ailus wrote:
> > Hi Richard,
> > 
> > Thanks for the update (and for the ping!).
> > 
> > On Wed, Jul 16, 2025 at 11:06:53AM +0200, Richard Leitner wrote:
> > > Add the new strobe_duration control to v4l uAPI documentation.
> > > 
> > > Signed-off-by: Richard Leitner <richard.leitner@linux.dev>
> > > ---
> > >  Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst | 5 +++++
> > >  1 file changed, 5 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..03a58ef94be7c870f55d5a9bb09503995dbfb402 100644
> > > --- a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst
> > > +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst
> > > @@ -186,3 +186,8 @@ 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 (integer)``
> > > +    Duration the flash should be on when the flash LED is in flash mode
> > > +    (V4L2_FLASH_LED_MODE_FLASH). The unit should be microseconds (µs)
> > > +    if possible.
> > > 
> > 
> > I think we should add this is related to the hardware strobe.
> > 
> > How about:
> > 
> > ``V4L2_CID_FLASH_DURATION (integer)``
> > 
> >     Duration of the flash strobe from the strobe source, typically a camera
> >     sensor. Controlling the flash LED strobe length this way requires that the
> >     flash LED driver's :ref:`flash LED mode <v4l2-cid-flash-led-mode>` is set
> >     to ``V4L2_FLASH_LED_MODE_FLASH`` and :ref:`strobe source
> >     <v4l2-cid-strobe-source>` is set to ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``.
> >     The unit should be microseconds (µs) if possible.
> 
> Also adding a reference to V4L2_CID_FLASH_HW_STROBE_SIGNAL:
> 
> ``V4L2_CID_FLASH_DURATION (integer)``
>     Duration of the flash strobe from the strobe source, typically a camera
>     sensor. Controlling the flash LED strobe length this way requires that the
>     strobe source's :ref:`V4L2_CID_FLASH_HW_STROBE_SIGNAL
>     <v4l2-cid-flash-hw-strobe>` is enabled and flash LED driver's :ref:`flash
>     LED mode <v4l2-cid-flash-led-mode>` is set to ``V4L2_FLASH_LED_MODE_FLASH``
>     and :ref:`strobe source <v4l2-cid-strobe-source>` is set to
>     ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``. The unit should be microseconds (µs)
>     if possible.
> 
> Similarly, the documentation for V4L2_CID_FLASH_HW_STROBE_SIGNAL should be
> amended with a reference, but the label needs to exist first. I think you
> could merge the two documentation patches to make this easier.

Thanks for the review. Extending the documentation as you suggested
defintely makes sense. Thank you also for your suggestion. That makes things
even easier.

I will send a v7 end of this week. If anything else pops up or causes
questions on this series please feel free to give feedback :)
I have my fingers crossed for v7 to be the last ;-)

Thanks again for your great feedback!

regards;rl

> 
> -- 
> Sakari Ailus

Patchew 2.1-devel-b67e4c2

© 2016 - 2025 Red Hat, Inc.