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

Antoine Bouyer
2026-04-13T16:04:37Z

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 | 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
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
+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
+is followed by a binary buffer of ISP statistics data. ISP drivers 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.
+
+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.
+
+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.
+
+Extension to the statistics format can be implemented by adding new blocks
+definition without invalidating the existing ones.

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