Re: [PATCH v5 8/8] media: Documentation: kapi: Add v4l2 generic ISP support
From: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Date: 2025-10-06 01:18:36
Also in:
linux-media, linux-rockchip, lkml
Hi Jacopo, Thank you for the patch. On Mon, Sep 15, 2025 at 07:18:17PM +0200, Jacopo Mondi wrote:
quoted hunk ↗ jump to hunk
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 :-)
quoted hunk ↗ jump to hunk
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.
quoted hunk ↗ jump to hunk
+Generic ISP support driver documentation +======================================== +.. kernel-doc:: include/media/v4l2-isp.hdiff --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