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

On 14/03/2025 09:49, 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.
> 

If this control is present, does that mean that the flash duration always have
to be set manually? Or can there be an 'Auto' mode as well? And if so, how is
that set?

Regards,

	Hans

Hi Hans,

thanks for your quick feedback!

On Fri, Mar 14, 2025 at 10:41:04AM +0100, Hans Verkuil wrote:
> On 14/03/2025 09:49, 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.
> > 
> 
> If this control is present, does that mean that the flash duration always have
> to be set manually? Or can there be an 'Auto' mode as well? And if so, how is
> that set?

To be honest I haven't thought about automatic flash duration. Is this
something which is required?

At least for the ov9282 sensor (which I've implemented this control for
in this series) there is no "auto" mode AFAIK.

If it's required: What would be the best solution?
Extending V4L2_CID_FLASH_LED_MODE with a new menu option? E.g.
V4L2_FLASH_LED_MODE_FLASH_{MANUAL,AUTO}?

> 
> Regards,
> 
> 	Hans

Thanks!
Richard

On 14/03/2025 11:28, Richard Leitner wrote:
> Hi Hans,
> 
> thanks for your quick feedback!
> 
> On Fri, Mar 14, 2025 at 10:41:04AM +0100, Hans Verkuil wrote:
>> On 14/03/2025 09:49, 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.
>>>
>>
>> If this control is present, does that mean that the flash duration always have
>> to be set manually? Or can there be an 'Auto' mode as well? And if so, how is
>> that set?
> 
> To be honest I haven't thought about automatic flash duration. Is this
> something which is required?

No idea, it was just something I was wondering about. Sakari probably knows a lot
more about this.

Regards,

	Hans

> 
> At least for the ov9282 sensor (which I've implemented this control for
> in this series) there is no "auto" mode AFAIK.
> 
> If it's required: What would be the best solution?
> Extending V4L2_CID_FLASH_LED_MODE with a new menu option? E.g.
> V4L2_FLASH_LED_MODE_FLASH_{MANUAL,AUTO}?
> 
>>
>> Regards,
>>
>> 	Hans
> 
> Thanks!
> Richard

Hi Hans, Hi Sakari,

On Fri, Mar 14, 2025 at 11:36:12AM +0100, Hans Verkuil wrote:
> On 14/03/2025 11:28, Richard Leitner wrote:
> > Hi Hans,
> > 
> > thanks for your quick feedback!
> > 
> > On Fri, Mar 14, 2025 at 10:41:04AM +0100, Hans Verkuil wrote:
> >> On 14/03/2025 09:49, 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.
> >>>
> >>
> >> If this control is present, does that mean that the flash duration always have
> >> to be set manually? Or can there be an 'Auto' mode as well? And if so, how is
> >> that set?
> > 
> > To be honest I haven't thought about automatic flash duration. Is this
> > something which is required?
> 
> No idea, it was just something I was wondering about. Sakari probably knows a lot
> more about this.

Sakari, should I add something like an auto/manual flash duration
control to this series?

Personally I think as long as we have no user of such an "auto" control
it's not really necessary. Or are there any drivers doing "auto"
flash/strobe duration already?

Thanks!

regards;rl

> 
> Regards,
> 
> 	Hans
> 
> > 
> > At least for the ov9282 sensor (which I've implemented this control for
> > in this series) there is no "auto" mode AFAIK.
> > 
> > If it's required: What would be the best solution?
> > Extending V4L2_CID_FLASH_LED_MODE with a new menu option? E.g.
> > V4L2_FLASH_LED_MODE_FLASH_{MANUAL,AUTO}?
> > 
> >>
> >> Regards,
> >>
> >> 	Hans
> > 
> > Thanks!
> > Richard
> 

Hi Richard,

On Tue, Mar 25, 2025 at 09:24:18AM +0100, Richard Leitner wrote:
> Hi Hans, Hi Sakari,
> 
> On Fri, Mar 14, 2025 at 11:36:12AM +0100, Hans Verkuil wrote:
> > On 14/03/2025 11:28, Richard Leitner wrote:
> > > Hi Hans,
> > > 
> > > thanks for your quick feedback!
> > > 
> > > On Fri, Mar 14, 2025 at 10:41:04AM +0100, Hans Verkuil wrote:
> > >> On 14/03/2025 09:49, 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.
> > >>>
> > >>
> > >> If this control is present, does that mean that the flash duration always have
> > >> to be set manually? Or can there be an 'Auto' mode as well? And if so, how is
> > >> that set?
> > > 
> > > To be honest I haven't thought about automatic flash duration. Is this
> > > something which is required?
> > 
> > No idea, it was just something I was wondering about. Sakari probably knows a lot
> > more about this.
> 
> Sakari, should I add something like an auto/manual flash duration
> control to this series?
> 
> Personally I think as long as we have no user of such an "auto" control
> it's not really necessary. Or are there any drivers doing "auto"
> flash/strobe duration already?

I think the only other drivers that support controlling the flash currently
are CCS and vgxy61. The CCS calculates the timing in the driver and the
vgxy61 appears to be doing that all in firmware.

I'd add a control to select between auto / manual if there's a need to
support both. CCS could be a case for this as the user space might know
better what it wants from the flash.

-- 
Regards,

Sakari Ailus