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

[Laurent Pinchart <laurent.pinchart@ideasonboard.com>]

On Tue, Feb 03, 2026 at 05:58:25PM +0100, Jacopo Mondi wrote:
> 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

s/defineing/defining/

> > +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

s/driver/drivers/

> > +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

s/Driver is/Drivers are/

> > +(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

s/ISP driver/an ISP driver/

> > +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 ?

It seems simpler to just omit the block completely indeed. The only case
where I could imagine this being useful is if the hardware writes the
statistics data to memory through DMA, with different stats engines
writing to different parts of the buffer concurrently.

In that case though, we will need to ensure the buffer format can
accommodate DMA alignment requirements of different devices, which is
likely not the case of the format proposed in this series. The size of
the top-level header and of the block headers are fixed, we would likely
need to make them configurable by the driver.

> > +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
> >  ========================

-- 
Regards,

Laurent Pinchart