Add documentation for extensible parameters format to the V4L2
userspace API documentation.

Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.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@ideasonboard.com>
 L:	linux-media@vger.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

-- 
2.49.0

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@ideasonboard.com>
Reviewed-by: Daniel Scally <dan.scally@ideasonboard.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@ideasonboard.com>
>   L:	linux-media@vger.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
>