Add to the driver-api documentation the v4l2-isp.h types and
helpers documentation.
Reviewed-by: Daniel Scally <dan.scally@ideasonboard.com>
Reviewed-by: Michael Riesch <michael.riesch@collabora.com>
Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
---
Documentation/driver-api/media/v4l2-core.rst | 1 +
Documentation/driver-api/media/v4l2-isp.rst | 49 ++++++++++++++++++++++++++++
MAINTAINERS | 1 +
3 files changed, 51 insertions(+)
diff --git a/Documentation/driver-api/media/v4l2-core.rst b/Documentation/driver-api/media/v4l2-core.rst
index ad987c34ad2a8460bb95e97adc4d850d624e0b81..a5f5102c64cca57b57b54ab95882b26286fb27de 100644
--- a/Documentation/driver-api/media/v4l2-core.rst
+++ b/Documentation/driver-api/media/v4l2-core.rst
@@ -27,3 +27,4 @@ Video4Linux devices
v4l2-common
v4l2-tveeprom
v4l2-jpeg
+ v4l2-isp
diff --git a/Documentation/driver-api/media/v4l2-isp.rst b/Documentation/driver-api/media/v4l2-isp.rst
new file mode 100644
index 0000000000000000000000000000000000000000..150ba39b257b23e6a8ca1a348047f5b55588fbf7
--- /dev/null
+++ b/Documentation/driver-api/media/v4l2-isp.rst
@@ -0,0 +1,49 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+V4L2 generic ISP parameters and statistics support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Design rationale
+================
+
+ISP configuration parameters and statistics are processed and collected by
+drivers and exchanged with userspace through data types that usually
+reflect the ISP peripheral registers layout.
+
+Each ISP driver defines its own metadata output format for parameters and
+a metadata capture format for statistics. The buffer layout is realized by a
+set of C structures that reflects the registers layout. The number and types
+of C structures is fixed by the format definition and becomes part of the Linux
+kernel uAPI/uABI interface.
+
+Because of the hard requirement of backward compatibility when extending the
+user API/ABI interface, modifying an ISP driver capture or output metadata
+format after it has been accepted by mainline is very hard if not impossible.
+
+It generally happens, in fact, that after the first accepted revision of an ISP
+driver the buffers layout need to be modified, either to support new hardware
+blocks, to fix bugs or to support different revisions of the hardware.
+
+Each of these situations would require defining a new metadata format, making it
+really hard to maintain and extend drivers and requiring userspace to use
+the correct format depending on the kernel revision in use.
+
+V4L2 ISP configuration parameters
+=================================
+
+For these reasons, Video4Linux2 defines generic types for ISP configuration
+parameters and statistics. Drivers are still expected to define their own
+formats for their metadata output and capture nodes, but the buffers layout can
+be defined using the extensible and versioned types defined by
+include/uapi/linux/media/v4l2-isp.h.
+
+Drivers are expected to provide the definitions of their supported ISP blocks,
+the control flags and the expected maximum size of a buffer.
+
+For driver developers a set of helper functions to assist them with validation
+of the buffer received from userspace is available in
+drivers/media/v4l2-core/v4l2-isp.c
+
+V4L2 ISP support driver documentation
+=====================================
+.. kernel-doc:: include/media/v4l2-isp.h
diff --git a/MAINTAINERS b/MAINTAINERS
index 5833f82caa7f2f734bb0e1be144ade2109b23988..cd1137c7754538d02bd72521fec6c89e082246d2 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -26856,6 +26856,7 @@ V4L2 GENERIC ISP PARAMETERS AND STATISTIC FORMATS
M: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
L: linux-media@vger.kernel.org
S: Maintained
+F: Documentation/driver-api/media/v4l2-isp.rst
F: Documentation/userspace-api/media/v4l/v4l2-isp.rst
F: drivers/media/v4l2-core/v4l2-isp.c
F: include/media/v4l2-isp.h
--
2.51.0Hi Jacopo, Thank you for the patch. On Mon, Oct 20, 2025 at 10:24:54AM +0200, Jacopo Mondi wrote: > Add to the driver-api documentation the v4l2-isp.h types and > helpers documentation. > > Reviewed-by: Daniel Scally <dan.scally@ideasonboard.com> > Reviewed-by: Michael Riesch <michael.riesch@collabora.com> > Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com> > Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com> > --- > Documentation/driver-api/media/v4l2-core.rst | 1 + > Documentation/driver-api/media/v4l2-isp.rst | 49 ++++++++++++++++++++++++++++ > MAINTAINERS | 1 + > 3 files changed, 51 insertions(+) > > diff --git a/Documentation/driver-api/media/v4l2-core.rst b/Documentation/driver-api/media/v4l2-core.rst > index ad987c34ad2a8460bb95e97adc4d850d624e0b81..a5f5102c64cca57b57b54ab95882b26286fb27de 100644 > --- a/Documentation/driver-api/media/v4l2-core.rst > +++ b/Documentation/driver-api/media/v4l2-core.rst > @@ -27,3 +27,4 @@ Video4Linux devices > v4l2-common > v4l2-tveeprom > v4l2-jpeg > + v4l2-isp > diff --git a/Documentation/driver-api/media/v4l2-isp.rst b/Documentation/driver-api/media/v4l2-isp.rst > new file mode 100644 > index 0000000000000000000000000000000000000000..150ba39b257b23e6a8ca1a348047f5b55588fbf7 > --- /dev/null > +++ b/Documentation/driver-api/media/v4l2-isp.rst > @@ -0,0 +1,49 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +V4L2 generic ISP parameters and statistics support > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > + > +Design rationale > +================ > + > +ISP configuration parameters and statistics are processed and collected by > +drivers and exchanged with userspace through data types that usually > +reflect the ISP peripheral registers layout. > + > +Each ISP driver defines its own metadata output format for parameters and > +a metadata capture format for statistics. The buffer layout is realized by a > +set of C structures that reflects the registers layout. The number and types > +of C structures is fixed by the format definition and becomes part of the Linux > +kernel uAPI/uABI interface. > + > +Because of the hard requirement of backward compatibility when extending the > +user API/ABI interface, modifying an ISP driver capture or output metadata > +format after it has been accepted by mainline is very hard if not impossible. > + > +It generally happens, in fact, that after the first accepted revision of an ISP > +driver the buffers layout need to be modified, either to support new hardware > +blocks, to fix bugs or to support different revisions of the hardware. > + > +Each of these situations would require defining a new metadata format, making it > +really hard to maintain and extend drivers and requiring userspace to use > +the correct format depending on the kernel revision in use. > + > +V4L2 ISP configuration parameters > +================================= > + > +For these reasons, Video4Linux2 defines generic types for ISP configuration > +parameters and statistics. Drivers are still expected to define their own > +formats for their metadata output and capture nodes, but the buffers layout can > +be defined using the extensible and versioned types defined by > +include/uapi/linux/media/v4l2-isp.h. > + > +Drivers are expected to provide the definitions of their supported ISP blocks, > +the control flags and the expected maximum size of a buffer. What are the control flags here ? Is it a leftover from a previous version ? With this addressed, Reviewed-by: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> > + > +For driver developers a set of helper functions to assist them with validation > +of the buffer received from userspace is available in > +drivers/media/v4l2-core/v4l2-isp.c > + > +V4L2 ISP support driver documentation > +===================================== > +.. kernel-doc:: include/media/v4l2-isp.h > diff --git a/MAINTAINERS b/MAINTAINERS > index 5833f82caa7f2f734bb0e1be144ade2109b23988..cd1137c7754538d02bd72521fec6c89e082246d2 100644 > --- a/MAINTAINERS > +++ b/MAINTAINERS > @@ -26856,6 +26856,7 @@ V4L2 GENERIC ISP PARAMETERS AND STATISTIC FORMATS > M: Jacopo Mondi <jacopo.mondi@ideasonboard.com> > L: linux-media@vger.kernel.org > S: Maintained > +F: Documentation/driver-api/media/v4l2-isp.rst > F: Documentation/userspace-api/media/v4l/v4l2-isp.rst > F: drivers/media/v4l2-core/v4l2-isp.c > F: include/media/v4l2-isp.h -- Regards, Laurent Pinchart
© 2016 - 2026 Red Hat, Inc.