[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Message-Id: <20251007-extensible-parameters-validation-v6-8-5f719d9f39e5@ideasonboard.com>
Date: Tue, 07 Oct 2025 20:12:17 +0200
From: Jacopo Mondi <jacopo.mondi@...asonboard.com>
To: 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>, Dan Scally <dan.scally@...asonboard.com>,
Sakari Ailus <sakari.ailus@...ux.intel.com>,
Antoine Bouyer <antoine.bouyer@....com>
Cc: linux-kernel@...r.kernel.org, linux-media@...r.kernel.org,
linux-rockchip@...ts.infradead.org, linux-arm-kernel@...ts.infradead.org,
Jacopo Mondi <jacopo.mondi@...asonboard.com>
Subject: [PATCH v6 8/8] media: Documentation: kapi: Add v4l2 generic ISP
support
Add to the driver-api documentation the v4l2-isp.h types and
helpers documentation.
Reviewed-by: Daniel Scally <dan.scally@...asonboard.com>
Signed-off-by: Jacopo Mondi <jacopo.mondi@...asonboard.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..42c2550602979609e92a09e3cd1fe3dcbafd6416
--- /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 capture format for parameters and
+a metadata output 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 facts, that after the first accepted revision of an
+ISP driver the buffer layout need to be modified, either to support new hardware
+blocks, fix bugs found later on or support different revisions of the same IP.
+
+Each of these situation would require defining a new metadata format, making it
+really hard to maintain and extend drivers and requiring userspace to use a
+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 buffer 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 the form of helper
+functions 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 ce57cf3774f6270bfaeffcea8fa63bcbd0a90dbd..ea3ef6544b44df404edcf7926a2802d63f0a40de 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -26414,6 +26414,7 @@ V4L2 GENERIC ISP PARAMETERS AND STATISTIC FORMATS
M: Jacopo Mondi <jacopo.mondi@...asonboard.com>
L: linux-media@...r.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.0
Powered by blists - more mailing lists