Re: [RFC v1 03/11] media: Documentation: uapi: Update V4L2 ISP for extensible stats

[Jacopo Mondi <jacopo.mondi@ideasonboard.com>]

Hi Antoine

On Fri, Jan 23, 2026 at 09:09:30AM +0100, Antoine Bouyer wrote:
> Add driver documentation for V4L2 ISP generic statistics format, mainly
> copied from the generic parameters one.
>
> Signed-off-by: Antoine Bouyer <antoine.bouyer@nxp.com>
> ---
>  .../userspace-api/media/v4l/v4l2-isp.rst      | 42 +++++++++++++++++--
>  1 file changed, 39 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/userspace-api/media/v4l/v4l2-isp.rst b/Documentation/userspace-api/media/v4l/v4l2-isp.rst
> index facf6dba1ca7..9024c6998b2c 100644
> --- a/Documentation/userspace-api/media/v4l/v4l2-isp.rst
> +++ b/Documentation/userspace-api/media/v4l/v4l2-isp.rst
> @@ -32,8 +32,8 @@ types.
>  Userspace applications are responsible for correctly populating each block's
>  header fields (type, flags and size) and the block-specific parameters.
>
> -ISP block enabling, disabling and configuration
> ------------------------------------------------
> +ISP parameters block enabling, disabling and configuration
> +----------------------------------------------------------
>
>  When userspace wants to configure and enable an ISP block it shall fully
>  populate the block configuration and set the V4L2_ISP_PARAMS_FL_BLOCK_ENABLE
> @@ -59,7 +59,43 @@ definition without invalidating the existing ones.
>  ISP statistics
>  ==============
>
> -Support for generic statistics format is not yet implemented in Video4Linux2.
> +The generic ISP statistics format is similar to the generic ISP configuration
> +parameters format. It is realized by defineing a C structure that contains a
> +header, followed by binary buffer where the ISP driver copies a variable number
> +of ISP statistics block.
> +
> +The :c:type:`v4l2_isp_stats_buffer` structure defines the buffer header which
> +is followed by a binary buffer of ISP statistics data. ISP driver shall
> +correctly populate the buffer header with the generic statistics format version
> +and with the size (in bytes) of the binary data buffer where it will store the
> +ISP statistics data.
> +
> +Each *ISP statistics block* is preceded by a header implemented by the
> +:c:type:`v4l2_isp_stats_block_header` structure, followed by the statistics
> +data for that specific block, defined by the ISP driver specific data types.
> +
> +Driver is responsible for correctly populating each block's header fields
> +(type, flags and size) and the block-specific statistics data.
> +
> +ISP statistics block configuration
> +----------------------------------
> +
> +When ISP driver wants to share statistics from an ISP block, it shall fully
> +populate the block statistics and set the V4L2_ISP_STATS_FL_BLOCK_VALID
> +bit in the block header's `flags` field.
> +
> +When ISP driver wants userspace to ignore statistics from an ISP block, it can

What would be the use case here ?

I checked a few datasheet and drivers and I haven't found any "failed
to read stats" bits, and even if that would be a thing, isn't it easier to
simply overwrite the header of the failed stat block instead of
marking it invalid ?


> +simply omit the full block, or set the V4L2_ISP_STATS_FL_BLOCK_INVALID bit in
> +the block headers's `flags` field. Then driver can omit the additional data
> +after header, and set block header's `size` to the header structure's size only
> +in such case.
> +
> +Setting both the V4L2_ISP_STATS_FL_BLOCK_VALID and
> +V4L2_ISP_STATS_FL_BLOCK_INVALID  bits in the flags field is not allowed and
> +userspace shall not handle it.
> +
> +Extension to the statistics format can be implemented by adding new blocks
> +definition without invalidating the existing ones.
>
>  V4L2 ISP uAPI data types
>  ========================
> --
> 2.52.0
>
>