Re: [PATCH 2/6] media: Documentation: uapi: Update V4L2 ISP for extensible stats

[Niklas Söderlund]

Hello Antoine and Jacopo,

Thanks for your work.

On 2026-05-05 16:12:13 +0200, Jacopo Mondi wrote:
> From: Antoine Bouyer <antoine.bouyer@xxxxxxx>
> 
> Rework the userspace-api documentation of V4L2 ISP to support
> statistics.
> 
> Update all occurences of 'v4l2_isp_param' types to match the uAPI
> changes and add a section to document the statistics serialization
> format.
> 
> Signed-off-by: Antoine Bouyer <antoine.bouyer@xxxxxxx>
> [Update on uAPI changes]
> Signed-off-by: Jacopo Mondi <jacopo.mondi@xxxxxxxxxxxxxxxx>

Reviewed-by: Niklas Söderlund <niklas.soderlund+renesas@xxxxxxxxxxxx>

> ---
>  Documentation/userspace-api/media/v4l/v4l2-isp.rst | 45 ++++++++++++++++------
>  1 file changed, 34 insertions(+), 11 deletions(-)
> 
> diff --git a/Documentation/userspace-api/media/v4l/v4l2-isp.rst b/Documentation/userspace-api/media/v4l/v4l2-isp.rst
> index facf6dba1ca7..8a3f05b5e85f 100644
> --- a/Documentation/userspace-api/media/v4l/v4l2-isp.rst
> +++ b/Documentation/userspace-api/media/v4l/v4l2-isp.rst
> @@ -18,22 +18,22 @@ single C structure that contains a header, followed by a binary buffer where
>  userspace programs a variable number of ISP configuration data block, one for
>  each supported ISP feature.
>  
> -The :c:type:`v4l2_isp_params_buffer` structure defines the buffer header which
> -is followed by a binary buffer of ISP configuration data. Userspace shall
> -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
> -:c:type:`v4l2_isp_params_block_header` structure, followed by the configuration
> +The :c:type:`v4l2_isp_buffer` structure defines the buffer header which is
> +followed by a binary buffer of ISP configuration data. Userspace shall correctly
> +populate the buffer header with the serialization 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 a header implemented by the
> +:c:type:`v4l2_isp_block_header` structure, followed by the configuration
>  parameters for that specific block, defined by the ISP driver specific data
>  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,30 @@ 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 identical to the generic ISP configuration
> +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 blocks.
> +
> +Extensible statistics buffers have :c:type:`v4l2_isp_buffer` header followed by
> +a binary buffer of ISP statistics data. ISP drivers populate the buffer header
> +with the serialization format version and with the size (in bytes) of the binary
> +data buffer where ISP statistics data are serialized. Applications shall
> +validate that the serialization format version matches the expected one and that
> +the buffer size doesn't exceed the maximum size for a statistics buffer as
> +declared by the driver's uAPI header.
> +
> +Each *ISP statistics block* is preceded by a header implemented by the
> +:c:type:`v4l2_isp_block_header` structure, followed by the statistics data for
> +that specific block. The driver might optionally report platform-specific flags
> +associated with each statistics block.
> +
> +Applications inspect the statistics block type as reported in the header and
> +validates the reported size matches the block's expected size before accessing
> +the ISP statistics data.
> +
> +Extension to the statistics format can be implemented by adding new blocks
> +definition without invalidating the existing ones.
>  
>  V4L2 ISP uAPI data types
>  ========================
> 
> -- 
> 2.53.0
> 

-- 
Kind Regards,
Niklas Söderlund