Add to the driver-api documentation the v4l2-isp.h types and
helpers documentation.
Reviewed-by: Daniel Scally <dan.scally@ideasonboard.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 | 37 ++++++++++++++++++++++++++++
MAINTAINERS | 1 +
3 files changed, 39 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..d778aa799347bfd0a95bd6887dd944ddad0fe4d1
--- /dev/null
+++ b/Documentation/driver-api/media/v4l2-isp.rst
@@ -0,0 +1,37 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+V4L2 generic ISP parameters and statistics support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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 format for parameters and statistics,
+and exposing the registers layout in the format definition, part of the Linux
+kernel uAPI/uABI interface, makes it really hard, if not impossible, to extend
+the format in a backward compatible way to support new hardware blocks or
+different revisions of the same peripheral IP.
+
+For these reasons Video4Linux2 defines generic types for ISP configuration
+parameters and statistics with a set of associated helpers to support drivers
+and users using generic types.
+
+Generic ISP configuration parameters
+====================================
+
+Drivers can use the generic and extensible configuration parameters format by
+re-using the types defined in the include/uapi/linux/media/v4l2-isp.h uAPI
+header file.
+
+The uAPI header defines generic types which the driver is expected to re-use and
+provide definitions for the types of supported ISP blocks, their control
+flags and the expected maximum size of a buffer of parameters.
+
+When a driver receives a buffer of parameters from userspace it shall validate
+it by using the helper functions and types available in include/media/v4l2-isp.h
+before accessing the buffer to apply the parameters to the hardware registers.
+
+Generic ISP support driver documentation
+========================================
+.. kernel-doc:: include/media/v4l2-isp.h
diff --git a/MAINTAINERS b/MAINTAINERS
index 5e0e4208ebe6c58a9ea0834e1ebb36abd2de06e1..b0c5e6c2b21a5d5ebc63d2ae8b5c1b68fa912b33 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -26414,6 +26414,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/extensible-parameters.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, Sep 15, 2025 at 07:18:17PM +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> > Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com> > --- > Documentation/driver-api/media/v4l2-core.rst | 1 + > Documentation/driver-api/media/v4l2-isp.rst | 37 ++++++++++++++++++++++++++++ > MAINTAINERS | 1 + > 3 files changed, 39 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 At what point we should structure the documentation. At one point :-) > diff --git a/Documentation/driver-api/media/v4l2-isp.rst b/Documentation/driver-api/media/v4l2-isp.rst > new file mode 100644 > index 0000000000000000000000000000000000000000..d778aa799347bfd0a95bd6887dd944ddad0fe4d1 > --- /dev/null > +++ b/Documentation/driver-api/media/v4l2-isp.rst > @@ -0,0 +1,37 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +V4L2 generic ISP parameters and statistics support > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > + > +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 format for parameters and statistics, > +and exposing the registers layout in the format definition, part of the Linux > +kernel uAPI/uABI interface, makes it really hard, if not impossible, to extend > +the format in a backward compatible way to support new hardware blocks or > +different revisions of the same peripheral IP. > + > +For these reasons Video4Linux2 defines generic types for ISP configuration > +parameters and statistics with a set of associated helpers to support drivers > +and users using generic types. > + > +Generic ISP configuration parameters > +==================================== > + > +Drivers can use the generic and extensible configuration parameters format by > +re-using the types defined in the include/uapi/linux/media/v4l2-isp.h uAPI > +header file. > + > +The uAPI header defines generic types which the driver is expected to re-use and > +provide definitions for the types of supported ISP blocks, their control > +flags and the expected maximum size of a buffer of parameters. > + > +When a driver receives a buffer of parameters from userspace it shall validate > +it by using the helper functions and types available in include/media/v4l2-isp.h > +before accessing the buffer to apply the parameters to the hardware registers. > + Same comments are for the UAPI, I think this will need a full rewrite later. > +Generic ISP support driver documentation > +======================================== > +.. kernel-doc:: include/media/v4l2-isp.h > diff --git a/MAINTAINERS b/MAINTAINERS > index 5e0e4208ebe6c58a9ea0834e1ebb36abd2de06e1..b0c5e6c2b21a5d5ebc63d2ae8b5c1b68fa912b33 100644 > --- a/MAINTAINERS > +++ b/MAINTAINERS > @@ -26414,6 +26414,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/extensible-parameters.rst > F: drivers/media/v4l2-core/v4l2-isp.c > F: include/media/v4l2-isp.h -- Regards, Laurent Pinchart
© 2016 - 2026 Red Hat, Inc.