Received-SPF: pass (google.com: domain of linux-kernel+bounces-52243-linux.lists.archive=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99;
From: Changhuang Liang <changhuang.liang@starfivetech.com>
To: Mauro Carvalho Chehab <mchehab@kernel.org>,
	Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
	Matthias Brugger <matthias.bgg@gmail.com>,
	Hans Verkuil <hverkuil-cisco@xs4all.nl>,
	Ming Qian <ming.qian@nxp.com>,
	Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
	Nicolas Dufresne <nicolas.dufresne@collabora.com>,
	Benjamin Gaignard <benjamin.gaignard@collabora.com>,
	Tomi Valkeinen <tomi.valkeinen+renesas@ideasonboard.com>,
	Mingjia Zhang <mingjia.zhang@mediatek.com>
Cc: Jack Zhu <jack.zhu@starfivetech.com>,
	Changhuang Liang <changhuang.liang@starfivetech.com>,
	linux-media@vger.kernel.org,
	linux-kernel@vger.kernel.org,
	linux-staging@lists.linux.dev
Subject: [PATCH v3 02/13] media: Documentation: Add description for StarFive ISP metadata formats
Date: Mon,  5 Feb 2024 01:04:13 -0800
Message-Id: <20240205090424.40302-3-changhuang.liang@starfivetech.com>
In-Reply-To: <20240205090424.40302-1-changhuang.liang@starfivetech.com>
References: <20240205090424.40302-1-changhuang.liang@starfivetech.com>
Content-Transfer-Encoding: 8bit
Content-Type: text/plain
Precedence: bulk
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0:
	=?us-ascii?Q?rKgHpZa9Ar7xDABbxO6KQ2VC6d2skbCuA9EPRnHp2SAfOlgUteo9eNOZJT1f?=
 =?us-ascii?Q?e58q7smQWrtWo8cz/YJdJfEykIhtopmlysylrEa789qCWEoKX108kh1Wrb28?=
 =?us-ascii?Q?AUEfXC9a5GmrkPEo/vTrX5p0frIiQt2JSO6v0b2FpITrBcVZ1Gw3dhmHBYTQ?=
 =?us-ascii?Q?FzsE11D4DRpLNavLzZ2VdiiyZ+TDZkS/yVcbz6OqgmgAYFXNYtMXYeZGrS8J?=
 =?us-ascii?Q?wI0ZGdo1e7JAQNBKO/DalWbMQdV7Q8m2mOomxfLi2iRzge8Dy5iRN0eIgyHH?=
 =?us-ascii?Q?KThyP1jc46yWnj5oPaBK0kvzWzpQnGmpLFrCS3BipX1hcEio45hdyL/1R9OX?=
 =?us-ascii?Q?cvFyi8DYP0Ty4/yLWC9yat4PU6F0owGezHX8s1IdMpZjsXTx2jT4Nk2UWx+u?=
 =?us-ascii?Q?cJtL5g4jEZJkNfl+d7qQdHwt8hV+J88GtYoydL4Pej5KWI3NzckTiR5uSE0F?=
 =?us-ascii?Q?HYmQvme3XPDjzqbgr+ZN9Nyfrfwb21y2Ayg9bYlXRCWx9sMMcn6LN9Jf0wyX?=
 =?us-ascii?Q?kwD3JPoUBkmRnWMQflJ6Tep/T98GXI0K1NTQQgqbGYaHZfTugkHIhWR6zOhq?=
 =?us-ascii?Q?HnXsos/yxGGDkEXywUjjXYcaV8Uok0+VhB/28GsxbkRTns/dqKHXWnLUc/Nl?=
 =?us-ascii?Q?JFNidRiOLuxhIqrmjf7okI1bLzuc181creewU+Nfb9jUURaj1O4PL3Xga+r8?=
 =?us-ascii?Q?EoNvEC3LxL1JLzWK1hH8Lm7zdRTng+7cdZxf66dnKJHfYUZQ/GpzDykbVwv2?=
 =?us-ascii?Q?W/lACvjY6yBLAcLhwdt8jOeOPQXjxRN10Yh+cv5MRzh5zp5/nYoOIknFpQzk?=
 =?us-ascii?Q?WAieuNU5NTiEqyXWf2RmopIHn9kXRVX+Q4eRYTEgdjCnyg9JnjWPRvddjsei?=
 =?us-ascii?Q?uwC5puNGvJ3Oacrn2Ul4dIMh5wCKkIimWVcz6YbdjuBiXkcadQO0INqJK7VR?=
 =?us-ascii?Q?f3k4ezLxuwtXLETFERM6ZPBLhN9FMQcMPWpP8F2nzd5zYazp3nw0lYRiMv0w?=
 =?us-ascii?Q?dCopYlt2Ofi+qLzwalW7R/cyw1D8hvXxz4FiMkXg9Gg8U0ltRzl2qvsJRrQj?=
 =?us-ascii?Q?zPMAs/zn2dyWNIy0GpJp033XzBStoXQnTD0jnUyXhmxsDKhQFyKggYvzZRbU?=
 =?us-ascii?Q?di5EcMLWZNqtKmlZ5fxVfRqKAiZ+jeYs1S6yGTqito0ulQS5wYBp7Ec5gwhA?=
 =?us-ascii?Q?rKWp4xvqMLeE3J9GlfHz+ZWY6u0kKKFccuSy9UXaBgIUxJUWUlQzddHtFJr2?=
 =?us-ascii?Q?klzCPSZjN6KXG3hIqAOx1E/DhgsRBPmK0VaADh+3UXNJ2ZWcP6GD9rmw8wkR?=
 =?us-ascii?Q?KaxgGyndhI/EgrJAk6gDkNEY992qK1cwUrISa87PRHyuUkK5G+SGpBhP0EHB?=
 =?us-ascii?Q?00b/zUrClKzKaWtCqpQ3AxgGOQc/Nrnj+HY7Hzu7zxDJnJ2zyBLOVHfoDZ05?=
 =?us-ascii?Q?HYGO/aofTFYaXuLgZ7EPAi3HCCWcDpAAExqdL4vEgTdqVNnJGvQDJ9g7bibP?=
 =?us-ascii?Q?jCV6XeBBCDjv1M6tvYo9wPLzbEPDro4tcMTkvY2KyPZF6LzYofzfvOia0aaJ?=
 =?us-ascii?Q?g2qtdHWGY9ZpbVewvQLbLOaVOKHTpI5svTXi3Pj+D65I10gFj/uYNgP+eYLp?=
 =?us-ascii?Q?FVOxOgy4muSX3/VR9jfErms=3D?=
X-OriginatorOrg: starfivetech.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 4da0e80d-04d5-409c-9f62-08dc26297a59
X-MS-Exchange-CrossTenant-AuthSource: SHXPR01MB0671.CHNPR01.prod.partner.outlook.cn
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 05 Feb 2024 09:04:36.9317
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 06fe3fa3-1221-43d3-861b-5a4ee687a85c
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: 78aNcK7gaLGV0nH09YGD3iYhzcFfagXo+rEn0+Ifm20RYn0R6oGU4a5NxbNnW5/tEnUipSMj5YpzkUgFI0/UpPrBZEGoENnj/6dBPVWpHo0/KMCjsmMx5saSLGkhdjN6
X-MS-Exchange-Transport-CrossTenantHeadersStamped: SHXPR01MB0815

Add description for V4L2_META_FMT_STF_ISP_PARAMS and
V4L2_META_FMT_STF_ISP_STAT_3A meta data formats.

Signed-off-by: Changhuang Liang <changhuang.liang@starfivetech.com>
---
 .../media/v4l/metafmt-starfive-isp.rst        | 75 +++++++++++++++++++
 MAINTAINERS                                   |  1 +
 2 files changed, 76 insertions(+)
 create mode 100644 Documentation/userspace-api/media/v4l/metafmt-starfive-isp.rst

diff --git a/Documentation/userspace-api/media/v4l/metafmt-starfive-isp.rst b/Documentation/userspace-api/media/v4l/metafmt-starfive-isp.rst
new file mode 100644
index 000000000000..ebb4291833d6
--- /dev/null
+++ b/Documentation/userspace-api/media/v4l/metafmt-starfive-isp.rst
@@ -0,0 +1,75 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _v4l2-meta-fmt-stf-isp-params:
+
+.. _v4l2-meta-fmt-stf-isp-stat-3a:
+
+*****************************************************************************
+V4L2_META_FMT_STF_ISP_PARAMS ('stfp'), V4L2_META_FMT_STF_ISP_STAT_3A ('stfs')
+*****************************************************************************
+
+.. jh7110_isp_params_buffer
+
+Configuration parameters
+========================
+
+The configuration parameters are passed to the "output_params" metadata output
+video node, using the :c:type:`v4l2_meta_format` interface. They are formatted
+as described by the :c:type:`jh7110_isp_params_buffer` structure.
+
+.. code-block:: c
+
+	struct jh7110_isp_params_buffer {
+		__u32 enable_setting;
+		struct jh7110_isp_wb_setting wb_setting;
+		struct jh7110_isp_car_setting car_setting;
+		struct jh7110_isp_ccm_setting ccm_setting;
+		struct jh7110_isp_cfa_setting cfa_setting;
+		struct jh7110_isp_ctc_setting ctc_setting;
+		struct jh7110_isp_dbc_setting dbc_setting;
+		struct jh7110_isp_dnyuv_setting dnyuv_setting;
+		struct jh7110_isp_gmargb_setting gmargb_setting;
+		struct jh7110_isp_lccf_setting lccf_setting;
+		struct jh7110_isp_obc_setting obc_setting;
+		struct jh7110_isp_oecf_setting oecf_setting;
+		struct jh7110_isp_r2y_setting r2y_setting;
+		struct jh7110_isp_sat_setting sat_setting;
+		struct jh7110_isp_sharp_setting sharp_setting;
+		struct jh7110_isp_ycrv_setting ycrv_setting;
+		struct jh7110_isp_sc_setting sc_setting;
+	};
+
+.. jh7110_isp_sc_buffer
+
+3A and histogram statistics
+===========================
+
+The ISP device collects different statistics over an input Bayer frame.
+Those statistics are obtained from the "capture_scd" metadata capture video
+node, using the :c:type:`v4l2_meta_format` interface. They are formatted as
+described by the :c:type:`jh7110_isp_sc_buffer` structure.
+
+.. code-block:: c
+
+	struct jh7110_isp_sc_buffer {
+		__u32 y_histogram[64];
+		__u32 reserv0[33];
+		__u32 bright_sc[4096];
+		__u32 reserv1[96];
+		__u32 ae_hist_y[128];
+		__u32 reserv2[511];
+		__u16 flag;
+	};
+
+The statistics collected are Auto Exposure, AWB (Auto-white balance), Histogram
+and AF (Auto-focus). See :c:type:`jh7110_isp_sc_buffer` for details of the
+statistics.
+
+The 3A statistics and configuration parameters described here are usually
+consumed and produced by dedicated user space libraries that comprise the
+important tuning tools using software control loop.
+
+JH7110 ISP uAPI data types
+======================
+
+.. kernel-doc:: include/uapi/linux/jh7110-isp.h
diff --git a/MAINTAINERS b/MAINTAINERS
index d5679e5410bd..f4017aece273 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -20838,6 +20838,7 @@ L:	linux-media@vger.kernel.org
 S:	Maintained
 F:	Documentation/admin-guide/media/starfive_camss.rst
 F:	Documentation/devicetree/bindings/media/starfive,jh7110-camss.yaml
+F:	Documentation/userspace-api/media/v4l/metafmt-starfive-isp.rst
 F:	drivers/staging/media/starfive/camss
 F:	include/uapi/linux/jh7110-isp.h
 
-- 
2.25.1