From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 29696CCD193 for ; Tue, 14 Oct 2025 08:01:33 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender: Content-Transfer-Encoding:Content-Type:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:Cc:To:In-Reply-To:References:Message-Id :MIME-Version:Subject:Date:From:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=D/mgQ1a9ub9Yin2gwHfKk60tTQ6u4IcppofnvEvXXFQ=; b=mc+EC6mItKu/9K 4/73gv1IjYItjv2rzPxQaTL4MpD3R2RXPpcAGN3Epj90XZuP3BZP2Yr7XDDEeYfd7qBcxqh40eEpu Kak7/gBdaqcsaVL4YtyHHs5VwwLZ9YvgOKMoDBasqXLefJw/pFoxxrXC1ErsdiCSpkXYqUuMW6WvN hFsb99+Mflix89VRTLJ4NEALkLcATra0shqLnhgDk3gAwzuOEoUC5LGrPZMVg8ffn6mIgWRSTgS/r jT8g7vb7WbfmQ7VSo7TTrN+OBnrs4JICvQNxyLyQG0yE51o+l5tME/f2kII7D8xMkqFudS2p2f5BN LtdvW43CYkAZMh9dSQYA==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.98.2 #2 (Red Hat Linux)) id 1v8ZyH-0000000FWvn-2uZ5; Tue, 14 Oct 2025 08:01:25 +0000 Received: from perceval.ideasonboard.com ([213.167.242.64]) by bombadil.infradead.org with esmtps (Exim 4.98.2 #2 (Red Hat Linux)) id 1v8ZyA-0000000FWoS-18ht; Tue, 14 Oct 2025 08:01:21 +0000 Received: from [192.168.1.182] (93-46-82-201.ip106.fastwebnet.it [93.46.82.201]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id CFB13EAE; Tue, 14 Oct 2025 09:59:35 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1760428776; bh=XF6muoDpgftcMNaVPGf+dJ0kUhnTFQpZE9vUqI8xmTw=; h=From:Date:Subject:References:In-Reply-To:To:Cc:From; b=FCyKFkxly/gxs47ZOdWPJSQ5hgTR+W80/u79ATriQoJM4247+3IV7vi6PVto/Tvoq PAd1IzpKc8wS+EznRdbi30c/rPLl4J+gRL6TsfWtk1/tJcNnKKjqIqCHIs2mnukAAV nsA4XCeBfJpSjE617ujSf1Tgux6dKxTkaocN7tIs= From: Jacopo Mondi Date: Tue, 14 Oct 2025 10:00:56 +0200 Subject: [PATCH v7 4/8] media: Documentation: uapi: Add V4L2 ISP documentation MIME-Version: 1.0 Message-Id: <20251014-extensible-parameters-validation-v7-4-6628bed5ca98@ideasonboard.com> References: <20251014-extensible-parameters-validation-v7-0-6628bed5ca98@ideasonboard.com> In-Reply-To: <20251014-extensible-parameters-validation-v7-0-6628bed5ca98@ideasonboard.com> To: Dafna Hirschfeld , Laurent Pinchart , Keke Li , Mauro Carvalho Chehab , Heiko Stuebner , Dan Scally , Sakari Ailus , Antoine Bouyer Cc: linux-kernel@vger.kernel.org, linux-media@vger.kernel.org, linux-rockchip@lists.infradead.org, linux-arm-kernel@lists.infradead.org, Jacopo Mondi X-Mailer: b4 0.14.2 X-Developer-Signature: v=1; a=openpgp-sha256; l=7257; i=jacopo.mondi@ideasonboard.com; h=from:subject:message-id; bh=XF6muoDpgftcMNaVPGf+dJ0kUhnTFQpZE9vUqI8xmTw=; b=owEBbQKS/ZANAwAKAXI0Bo8WoVY8AcsmYgBo7gNGvtweY6kzNxleJHEu684WFSl2vUZCu7ygV nFpmrGNNoaJAjMEAAEKAB0WIQS1xD1IgJogio9YOMByNAaPFqFWPAUCaO4DRgAKCRByNAaPFqFW PEUzD/9sCAs1ULlw3cNj1lmhEEh9OVkC5jKNU/iCyMUUV94KkvWBxfJqueBxYDqM4gSaCwDz3Qw /jD9Zwsks4LmOXBVKejuStgBlIcNVthue4APpf+9w4tfilK6Vm4UBzdydCd+IZNg2IoGdbRoNle NvdaPwRLe8B6IPIOTHqSkpk4dtTNhRHiSF9glq9O9614iTjNLhU5vz1c3duVq8CZQZ4l6vOMygr G7qqg/dMtDIjSlg2i+qNs9GYZAnN6Xurc+y4AKGzM+c6hpuU3os5KGEcgOtf7ViJmIuta7BWsmw rBAMyq8tt+LDjwADEZIl8/Pe72S6vF8uiqtCJ3XqFsF9ZINS5TquBFjd21yxBvfLhISO6MqSQae ppoqMBo12hg+5wGBJWi+Ic0N2NQUUU/3d9+xW5llJF4yvdSiuM9FNs6vOPn3JWLJeCkjIiA1Omz k7U3uBvF+IB004ERxeV1XH3HJRmWQfIIzkuOk22gHI2a+v2qYDRKg3IIDhGuI245sX+q2sa1Qz0 lUwLlowDqBRN3FPj4cbjnvgZbVOnLwIrvb8cZN1rKppGnEKlE1kCTEJTh1cjqhpx7+tTkyh4OUW GOp6zgHAuK6SGZWo075oQ6JDJfXNXRX0rKAQnDhbup8DxUizjFDlnrfAaUjAigGKoDjGS217rFI OJDseE0CU/kdbng== X-Developer-Key: i=jacopo.mondi@ideasonboard.com; a=openpgp; fpr=72392EDC88144A65C701EA9BA5826A2587AD026B X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20251014_010118_454639_08EF8123 X-CRM114-Status: GOOD ( 23.03 ) X-BeenThere: linux-rockchip@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Upstream kernel work for Rockchip platforms List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Sender: "Linux-rockchip" Errors-To: linux-rockchip-bounces+linux-rockchip=archiver.kernel.org@lists.infradead.org Add userspace documentation for V4L2 ISP generic parameters and statistics formats. Reviewed-by: Daniel Scally Signed-off-by: Jacopo Mondi --- .../userspace-api/media/v4l/meta-formats.rst | 1 + Documentation/userspace-api/media/v4l/v4l2-isp.rst | 121 +++++++++++++++++++++ MAINTAINERS | 1 + 3 files changed, 123 insertions(+) diff --git a/Documentation/userspace-api/media/v4l/meta-formats.rst b/Documentation/userspace-api/media/v4l/meta-formats.rst index 0de80328c36bf148051a19abe9e5241234ddfe5c..261483f8e4d832d3d0ce8aa11df4b4eb1645f22f 100644 --- a/Documentation/userspace-api/media/v4l/meta-formats.rst +++ b/Documentation/userspace-api/media/v4l/meta-formats.rst @@ -24,3 +24,4 @@ These formats are used for the :ref:`metadata` interface only. metafmt-vivid metafmt-vsp1-hgo metafmt-vsp1-hgt + v4l2-isp diff --git a/Documentation/userspace-api/media/v4l/v4l2-isp.rst b/Documentation/userspace-api/media/v4l/v4l2-isp.rst new file mode 100644 index 0000000000000000000000000000000000000000..41078558ba5cc1faf922a9b9112e64c99ff37080 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/v4l2-isp.rst @@ -0,0 +1,121 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _v4l2-isp: + +************************ +Generic V4L2 ISP formats +************************ + +ISP configuration and statistics: theory of operations +====================================================== + +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. + +ISP statistics are collected by the driver at a specific time point and drivers +use them to populate a *statistics buffer* which is then returned to userspace. + +The parameters and statistics buffers are organized in a driver-specific +way, and their data layout differs between one driver and another. + +ISP drivers generally exchange parameters and statistics with userspace through +a metadata capture and output node respectively, implementing the +:c:type:`v4l2_meta_format` interface. Each ISP driver defines a metadata capture +and output format to be used on those video nodes, and the buffer layout and +organization is fixed by the format definition. + +The uAPI/ABI problem +-------------------- + +By upstreaming the metadata formats that describe the parameters and statistics +buffers 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 formats, +this is considered an ABI-breakage that is strictly forbidden by the Linux +kernel policies. For this reason, any change in the ISP parameters and +statistics buffer layout would require defining a new metadata format. + +For these reasons Video4Linux2 has introduced support for generic ISP parameters +and statistics data types, designed with the goal 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 + +ISP configuration +================= + +Before the introduction of generic formats +------------------------------------------ + +Metadata cature formats that describe ISP configuration parameters were most +the time realized by defining C structures that reflect the ISP 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 number of supported ISP blocks, the layout of their configuration data are +fixed by the format definition, incurring the in the above described uAPI/uABI +problems. + +Generic ISP parameters +---------------------- + +The generic ISP configuration parameters format is realized by a defining a +single C structure that contains an header, followed by a binary buffer where +userspace programs a variable number of ISP configuration data block, one for +each supported ISP feature. + +The :c:type:`v4l2_isp_params_buffer` structure defines the parameters buffer +header which is followed by a binary buffer of ISP configuration parameters. +Userspace shall correctly populate the buffer header with the versioning +information and with the size (in bytes) of the binary data buffer where it will +store the ISP blocks configuration. + +Each *ISP configuration block* is preceded by an header implemented by the +:c:type:`v4l2_isp_params_block_header` structure, followed by the configuration +parameters for that specific block, defined by the ISP driver specific data +types. + +Userspace applications are responsible for correctly populating each block's +header fields (type, flags and size) and the block-specific parameters. + +ISP Block enabling, disabling and configuration +----------------------------------------------- + +When userspace wants to configure and enable an ISP block it shall fully +populate the block configuration and set the V4L2_ISP_PARAMS_FL_BLOCK_ENABLE +bit in the block header's `flags` field. + +When userspace simply wants to disable an ISP block the +V4L2_ISP_PARAMS_FL_BLOCK_DISABLE bit should be set in block header's `flags` +field. Drivers accept a configuration parameters block with no additional +data after the header in this case. + +If the configuration of an already active ISP block has to be updated, +userspace shall fully populate the ISP block parameters and omit setting the +V4L2_ISP_PARAMS_FL_BLOCK_ENABLE and V4L2_ISP_PARAMS_FL_BLOCK_DISABLE bits in the +header's `flags` field. + +Setting both the V4L2_ISP_PARAMS_FL_BLOCK_ENABLE and +V4L2_ISP_PARAMS_FL_BLOCK_DISABLE bits in the flags field is not allowed and not +accepted. + +Any further extension to the parameters layout that happens after the ISP driver +has been merged in Linux can be implemented by adding new blocks definition +without invalidating the existing ones. + +ISP statistics +============== + +Support for generic statistics format is not yet implemented in Video4Linux2. + +V4L2 ISP uAPI data types +======================== + +.. kernel-doc:: include/uapi/linux/media/v4l2-isp.h diff --git a/MAINTAINERS b/MAINTAINERS index e9ac834d212f88222437e8d806800b2516d44f01..340353334299cd5eebf1f72132b7e91b6f5fdbfe 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -26857,6 +26857,7 @@ V4L2 GENERIC ISP PARAMETERS AND STATISTIC FORMATS M: Jacopo Mondi L: linux-media@vger.kernel.org S: Maintained +F: Documentation/userspace-api/media/v4l/v4l2-isp.rst F: include/uapi/linux/media/v4l2-isp.h VF610 NAND DRIVER -- 2.51.0 _______________________________________________ Linux-rockchip mailing list Linux-rockchip@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-rockchip