Re: [PATCH v7 01/10] media: v4l: ctrls: add a control for flash/strobe duration

[Laurent Pinchart <laurent.pinchart@ideasonboard.com>]

Hi Richard,

Thank you for the patch.

On Mon, Sep 01, 2025 at 05:05:06PM +0200, Richard Leitner wrote:
> Add a control V4L2_CID_FLASH_DURATION to set the duration of a
> flash/strobe pulse. This is different to the V4L2_CID_FLASH_TIMEOUT
> control, as the timeout defines a limit after which the flash is
> "forcefully" turned off again.
> 
> On the other hand the new V4L2_CID_FLASH_DURATION is the desired length
> of the flash/strobe pulse.

It took me a while to understand the difference between the
V4L2_CID_FLASH_TIMEOUT and V4L2_CID_FLASH_DURATION controls, as I
wondered how a device could implement different duration and timeout
values. Then I realized that the timeout control is meant for flash
controllers, while the duration control is meant for the source of the
flash controller's external hardware strobe signal, typically the camera
sensor. I'd like this to be more explicit, here and in the
documentation. Here's a proposal for an updated commit message:

----
Add a V4L2_CID_FLASH_DURATION control to set the duration of a
flash/strobe pulse. This controls the length of the flash/strobe pulse
output by device (typically a camera sensor) and connected to the flash
controller. This is different to the V4L2_CID_FLASH_TIMEOUT control,
which is implemented by the flash controller and defines a limit after
which the flash is "forcefully" turned off again.
----

This could probably be improved, but it's good enough for me for the
commit message.

On a side note, I think we could have reused the V4L2_CID_FLASH_TIMEOUT
control for this purpose, even if the name isn't the best match, as the
two usages are implemented on different devices (flash controller vs.
camera sensor). We have no shortage of control ID space, so a separate
control ID is fine too, and probably clearer (as long as we document it
clearly).

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

> Signed-off-by: Richard Leitner <richard.leitner@linux.dev>
> ---
>  drivers/media/v4l2-core/v4l2-ctrls-defs.c | 1 +
>  include/uapi/linux/v4l2-controls.h        | 1 +
>  2 files changed, 2 insertions(+)
> 
> diff --git a/drivers/media/v4l2-core/v4l2-ctrls-defs.c b/drivers/media/v4l2-core/v4l2-ctrls-defs.c
> index 1ea52011247accc51d0261f56eab1cf13c0624a0..f9ed7273a9f3eafe01c31b638e1c8d9fcf5424af 100644
> --- a/drivers/media/v4l2-core/v4l2-ctrls-defs.c
> +++ b/drivers/media/v4l2-core/v4l2-ctrls-defs.c
> @@ -1135,6 +1135,7 @@ const char *v4l2_ctrl_get_name(u32 id)
>  	case V4L2_CID_FLASH_FAULT:		return "Faults";
>  	case V4L2_CID_FLASH_CHARGE:		return "Charge";
>  	case V4L2_CID_FLASH_READY:		return "Ready to Strobe";
> +	case V4L2_CID_FLASH_DURATION:		return "Strobe Duration";
>  
>  	/* JPEG encoder controls */
>  	/* Keep the order of the 'case's the same as in v4l2-controls.h! */
> diff --git a/include/uapi/linux/v4l2-controls.h b/include/uapi/linux/v4l2-controls.h
> index f836512e9debbc65d62a9fe04069b056be42f7b2..a5b7c382d77118eb7966385c5b22d5a89bc2b272 100644
> --- a/include/uapi/linux/v4l2-controls.h
> +++ b/include/uapi/linux/v4l2-controls.h
> @@ -1186,6 +1186,7 @@ enum v4l2_flash_strobe_source {
>  
>  #define V4L2_CID_FLASH_CHARGE			(V4L2_CID_FLASH_CLASS_BASE + 11)
>  #define V4L2_CID_FLASH_READY			(V4L2_CID_FLASH_CLASS_BASE + 12)
> +#define V4L2_CID_FLASH_DURATION			(V4L2_CID_FLASH_CLASS_BASE + 13)
>  
>  
>  /* JPEG-class control IDs */

-- 
Regards,

Laurent Pinchart