Hi Benjamin,
On 26/08/2024 19:24, Benjamin Gaignard wrote:
> When the index is ORed with V4L2_FMTDESC_FLAG_ENUM_ALL the
> driver clears the flag and enumerate all the possible formats,
> ignoring any limitations from the current configuration.
> Drivers which do not support this flag yet always return an EINVAL.
>
> Signed-off-by: Benjamin Gaignard <benjamin.gaignard@xxxxxxxxxxxxx>
> ---
> change in version 7:
> - Rework documentation about which drivers should use the flag
>
> .../media/v4l/vidioc-enum-fmt.rst | 18 +++++++++++++++++-
> .../media/videodev2.h.rst.exceptions | 1 +
> include/uapi/linux/videodev2.h | 3 +++
> 3 files changed, 21 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst
> index 3adb3d205531..e39c87bcbfc3 100644
> --- a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst
> +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst
> @@ -85,7 +85,17 @@ the ``mbus_code`` field is handled differently:
> * - __u32
> - ``index``
> - Number of the format in the enumeration, set by the application.
> - This is in no way related to the ``pixelformat`` field.
> + This is in no way related to the ``pixelformat`` field.
> + When the index is ORed with ``V4L2_FMTDESC_FLAG_ENUM_ALL`` the
> + driver clears the flag and enumerates all the possible formats,
> + ignoring any limitations from the current configuration. Drivers
> + which do not support this flag always return an ``EINVAL``
> + error code.
I would like to add: " without clearing this flag."
> + Formats enumerated when using ``V4L2_FMTDESC_FLAG_ENUM_ALL`` flag
> + shouldn't be used when calling :c:func:`VIDIOC_ENUM_FRAMESIZES`
> + or :c:func:`VIDIOC_ENUM_FRAMEINTERVALS`.
> + ``V4L2_FMTDESC_FLAG_ENUM_ALL`` should only be used by drivers that
> + can return different format list depending on this flag.
> * - __u32
> - ``type``
> - Type of the data stream, set by the application. Only these types
> @@ -234,6 +244,12 @@ the ``mbus_code`` field is handled differently:
> valid. The buffer consists of ``height`` lines, each having ``width``
> Data Units of data and the offset (in bytes) between the beginning of
> each two consecutive lines is ``bytesperline``.
> + * - ``V4L2_FMTDESC_FLAG_ENUM_ALL``
> + - 0x80000000
> + - When the applications ORs ``index`` with ``V4L2_FMTDESC_FLAG_ENUM_ALL`` flag
> + the driver enumerates all the possible pixel formats without taking care
> + of any already set configuration. Drivers which do not support this flag,
> + always return ``EINVAL``.
Ditto.
If you agree, then I can make that change myself, no need to post a new version.
Regards,
Hans
>
> Return Value
> ============
> diff --git a/Documentation/userspace-api/media/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/videodev2.h.rst.exceptions
> index bdc628e8c1d6..0a9ea9686c24 100644
> --- a/Documentation/userspace-api/media/videodev2.h.rst.exceptions
> +++ b/Documentation/userspace-api/media/videodev2.h.rst.exceptions
> @@ -216,6 +216,7 @@ replace define V4L2_FMT_FLAG_CSC_YCBCR_ENC fmtdesc-flags
> replace define V4L2_FMT_FLAG_CSC_HSV_ENC fmtdesc-flags
> replace define V4L2_FMT_FLAG_CSC_QUANTIZATION fmtdesc-flags
> replace define V4L2_FMT_FLAG_META_LINE_BASED fmtdesc-flags
> +replace define V4L2_FMTDESC_FLAG_ENUM_ALL fmtdesc-flags
>
> # V4L2 timecode types
> replace define V4L2_TC_TYPE_24FPS timecode-type
> diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> index 4e91362da6da..421a30cb0c51 100644
> --- a/include/uapi/linux/videodev2.h
> +++ b/include/uapi/linux/videodev2.h
> @@ -904,6 +904,9 @@ struct v4l2_fmtdesc {
> #define V4L2_FMT_FLAG_CSC_QUANTIZATION 0x0100
> #define V4L2_FMT_FLAG_META_LINE_BASED 0x0200
>
> +/* Format description flag, to be ORed with the index */
> +#define V4L2_FMTDESC_FLAG_ENUM_ALL 0x80000000
> +
> /* Frame Size and frame rate enumeration */
> /*
> * F R A M E S I Z E E N U M E R A T I O N
