Message-ID: <80b23a96-fde6-43e3-9b24-98099823a6f5@ideasonboard.com>
Date: Thu, 10 Jul 2025 15:06:47 +0100
From: Dan Scally <dan.scally@...asonboard.com>
To: Jacopo Mondi <jacopo.mondi@...asonboard.com>,
 Dafna Hirschfeld <dafna@...tmail.com>,
 Laurent Pinchart <laurent.pinchart@...asonboard.com>,
 Keke Li <keke.li@...ogic.com>, Mauro Carvalho Chehab <mchehab@...nel.org>,
 Heiko Stuebner <heiko@...ech.de>, Sakari Ailus <sakari.ailus@...ux.intel.com>
Cc: linux-kernel@...r.kernel.org, linux-media@...r.kernel.org,
 linux-rockchip@...ts.infradead.org, linux-arm-kernel@...ts.infradead.org
Subject: Re: [PATCH v2 4/8] media: Documentation: uapi: Add V4L2 extensible
 parameters

Hi Jacopo

On 10/07/2025 14:52, Jacopo Mondi wrote:
> Add documentation for extensible parameters format to the V4L2
> userspace API documentation.
>
> Signed-off-by: Jacopo Mondi <jacopo.mondi@...asonboard.com>
Reviewed-by: Daniel Scally <dan.scally@...asonboard.com>
> ---
>   .../media/v4l/extensible-parameters.rst            | 89 ++++++++++++++++++++++
>   .../userspace-api/media/v4l/meta-formats.rst       |  1 +
>   MAINTAINERS                                        |  1 +
>   3 files changed, 91 insertions(+)
>
> diff --git a/Documentation/userspace-api/media/v4l/extensible-parameters.rst b/Documentation/userspace-api/media/v4l/extensible-parameters.rst
> new file mode 100644
> index 0000000000000000000000000000000000000000..c4caa5c1df991d4dd91f986571db55135d15204a
> --- /dev/null
> +++ b/Documentation/userspace-api/media/v4l/extensible-parameters.rst
> @@ -0,0 +1,89 @@
> +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
> +
> +.. _extensible-parameters:
> +
> +**********************************
> + V4L2 extensible parameters format
> +**********************************
> +
> +ISP configuration
> +=================
> +
> +ISP configuration parameters are computed by userspace and programmed into a
> +*parameters buffer* which is queued to the ISP driver on a per-frame basis. The
> +layout of the *parameters buffer* generally reflects the ISP peripheral
> +registers layout and is, for this reason, platform specific.
> +
> +The ISP configuration parameters are passed to the ISP driver through a metadata
> +output video node, using the :c:type:`v4l2_meta_format` interface. Each ISP
> +driver defines a metadata format that implements the configuration parameters
> +layout.
> +
> +Metadata output formats that describe ISP configuration parameters are most of
> +the time realized by implementing C structures that reflect the registers layout
> +and gets populated by userspace before queueing the buffer to the ISP. Each
> +C structure usually corresponds to one ISP *processing block*, with each block
> +implementing one of the ISP supported features.
> +
> +The uAPI/ABI problem
> +--------------------
> +
> +By upstreaming data types that describe the configuration parameters layout,
> +driver developers make them part of the Linux kernel ABI. As it sometimes
> +happens for most peripherals in Linux, ISP drivers development is often an
> +iterative process, where sometimes not all the hardware features are supported
> +in the first version that lands in the kernel, and some parts of the interface
> +have to later be modified for bug-fixes or improvements.
> +
> +If any later bug-fix/improvement requires changes to the metadata output format,
> +this is considered an ABI-breakage that is strictly forbidden by the Linux
> +kernel policies. For this reason, each new iteration of an ISP driver support
> +would require defining a new metadata output format, implying that drivers have
> +to be made ready to handle several different configuration formats.
> +
> +A new set of metadata output formats has then to be defined, with the design
> +goals of being:
> +
> +- Extensible: new features can be added later on without breaking the existing
> +  interface
> +- Versioned: different versions of the format can be defined without
> +  breaking the existing interface
> +
> +The extensible parameters format
> +================================
> +
> +Extensible configuration formats are realized by a defining a single C structure
> +that contains a few control parameters and a binary buffer where userspace
> +programs a variable number of *ISP configuration blocks* data.
> +
> +The generic :c:type:`v4l2_params_buffer` defines a base type that each driver
> +can use by properly sizing the data buffer array.
> +
> +Each *ISP configuration block* is identified by an header and contains the
> +parameters for that specific block.
> +
> +The generic :c:type:`v4l2_params_block_header` defines a base type that each
> +driver can re-use as it is or extend appropriately.
> +
> +Userspace applications program in the control buffer only the parameters of the
> +ISP whose configuration has changed for the next frame. The ISP driver parses
> +the configuration parameters and apply them to the hardware register.
> +
> +Any further development that happens after the ISP driver has been merged in
> +Linux and which requires supporting new ISP features can be implemented by
> +adding new blocks definition without invalidating the existing ones. Similarly,
> +any change to the existing ISP configuration blocks can be handled by versioning
> +them, again without invalidating the existing ones.
> +
> +Implementations
> +---------------
> +
> +ISP drivers that define an extensible parameters metadata output format:
> +
> +- :ref:`RkISP1 <v4l2-meta-fmt-rk-isp1-ext-params>`
> +- :ref:`Amlogic C3 ISP <v4l2-meta-fmt-c3isp-params>`
> +
> +V4L2 extensible parameters uAPI data types
> +==========================================
> +
> +.. kernel-doc:: include/uapi/linux/media/v4l2-extensible-params.h
> diff --git a/Documentation/userspace-api/media/v4l/meta-formats.rst b/Documentation/userspace-api/media/v4l/meta-formats.rst
> index bb6876cfc271e1a0543eee4209d6251e1a6a73cc..58eb3c9c962bee008eee27d9c16678213c47baa9 100644
> --- a/Documentation/userspace-api/media/v4l/meta-formats.rst
> +++ b/Documentation/userspace-api/media/v4l/meta-formats.rst
> @@ -12,6 +12,7 @@ These formats are used for the :ref:`metadata` interface only.
>   .. toctree::
>       :maxdepth: 1
>   
> +    extensible-parameters
>       metafmt-c3-isp
>       metafmt-d4xx
>       metafmt-generic
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 49a9329e5fe8874bdbaca13946ea28bd80134cb3..beecac86991d988c48d31366ba5201b09ef25715 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -25972,6 +25972,7 @@ V4L2 EXTENSIBLE PARAMETERS FORMAT
>   M:	Jacopo Mondi <jacopo.mondi@...asonboard.com>
>   L:	linux-media@...r.kernel.org
>   S:	Maintained
> +F:	Documentation/userspace-api/media/v4l/extensible-parameters.rst
>   F:	include/uapi/linux/media/v4l2-extensible-params.h
>   
>   VF610 NAND DRIVER
>

Powered by blists - more mailing lists