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

[Jacopo Mondi]

Hi Antoine

On Mon, Apr 13, 2026 at 06:03:21PM +0200, 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@xxxxxxx>
> ---
>  .../userspace-api/media/v4l/v4l2-isp.rst      | 39 +++++++++++++++++--
>  1 file changed, 35 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/userspace-api/media/v4l/v4l2-isp.rst b/Documentation/userspace-api/media/v4l/v4l2-isp.rst
> index facf6dba1ca7..9e9c71bfc0df 100644
> --- a/Documentation/userspace-api/media/v4l/v4l2-isp.rst
> +++ b/Documentation/userspace-api/media/v4l/v4l2-isp.rst
> @@ -24,7 +24,7 @@ correctly populate the buffer header with the generic parameters format version
>  and with the size (in bytes) of the binary data buffer where it will store the
>  ISP blocks configuration.
>
> -Each *ISP configuration block* is preceded by an header implemented by the
> +Each *ISP configuration block* is preceded by a header implemented by the
>  :c:type:`v4l2_isp_params_block_header` structure, followed by the configuration

I would update all occurences of v4l2_isp_params_block_header with
v4l2_isp_block_header (same for the stats counterpart).

The same goes for v4l2_isp_params_buffer and v4l2_isp_stats_buffer to be
replaced with v4l2_isp_buffer.

The compatibilty types should only be there to allow existing
applications to continue working.

>  parameters for that specific block, defined by the ISP driver specific data
>  types.
> @@ -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,38 @@ 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

Similar or identical ? :)

> +parameters format. It is realized by defining 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

In this case I would say:

  Extensible statistics buffers have :c:type:`v4l2_isp_buffer` header
  followed by ...


> +is followed by a binary buffer of ISP statistics data. ISP drivers shall
> +correctly populate the buffer header with the generic statistics format version

s/generic statistics format version/serialization format version/

Please check if this has to be changed for paramters as well

> +and with the size (in bytes) of the binary data buffer where it will store the
> +ISP statistics data.

  and with the size (in bytes) of the binary data buffer where ISP statistics
  data are serialized.

> +
> +Each *ISP statistics block* is preceded by a header implemented by the
> +:c:type:`v4l2_isp_stats_block_header` structure, followed by the statistics

Use v4l2_isp_block_header

> +data for that specific block, defined by the ISP driver specific data types.
> +
> +Drivers are responsible for correctly populating each block's header fields
> +(type and size) and the block-specific statistics data. The flags field can be
> +left empty, it is not relevant for statistics data.

I would say that

  The flags field can be populated with driver-specific flags, if any.

> +
> +ISP statistics block configuration
> +----------------------------------
> +
> +When an ISP driver wants to share statistics from an ISP block, it shall fully
> +populate the block statistics.
> +
> +When ISP driver wants userspace to ignore statistics from an ISP block, it can
> +either simply omit the full block, or omit the additional data after header.
> +In second case, block header's `size` shall be filled with header structure's
> +size only.

Mmmm, I would not do that. Drivers should only report stats blocks if
populated. Is there a use case for reporting only the header ? (we
allow this for params as userspace can enable/disable blocks).

> +
> +Extension to the statistics format can be implemented by adding new blocks
> +definition without invalidating the existing ones.

Thanks!
  j

>
>  V4L2 ISP uAPI data types
>  ========================
> --
> 2.51.0
>
>