Re: [PATCH v5 02/14] media: Documentation: Add description for StarFive ISP metadata formats

[Jacopo Mondi]

Hi Changhuang

On Tue, Jul 09, 2024 at 01:38:12AM GMT, Changhuang Liang wrote:
> 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@xxxxxxxxxxxxxxxx>

I get this warnings when compiling documentation

Please fix these in the uapi header

../include/uapi/linux/jh7110-isp.h:17: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * ISP Module Diagram
../include/uapi/linux/jh7110-isp.h:152: warning: expecting prototype for struct jh7110_isp_cfa_params. Prototype was for struct jh7110_isp_cfa_setting instead
../include/uapi/linux/jh7110-isp.h:178: warning: expecting prototype for struct jh7110_isp_ctc_params. Prototype was for struct jh7110_isp_ctc_setting instead
../include/uapi/linux/jh7110-isp.h:200: warning: expecting prototype for struct jh7110_isp_dbc_params. Prototype was for struct jh7110_isp_dbc_setting instead
../include/uapi/linux/jh7110-isp.h:226: warning: expecting prototype for struct jh7110_isp_dnyuv_params. Prototype was for struct jh7110_isp_dnyuv_setting instead
../include/uapi/linux/jh7110-isp.h:707: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * Statistics Collection Meta Data Flag

and this in the documentation here below:

Documentation/userspace-api/media/v4l/metafmt-starfive-isp.rst:73: WARNING: Title underline too short.

JH7110 ISP uAPI data types
======================

Documentation/userspace-api/media/v4l/metafmt-starfive-isp.rst: WARNING: document isn't included in any toctree

(You should  add this file to
Documentation/userspace-api/media/v4l/meta-formats.rst)

> ---
>  .../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

Is this used ?

> +
> +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 890604eb0d64..8fd613c93e62 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -21304,6 +21304,7 @@ L:	linux-media@xxxxxxxxxxxxxxx
>  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
>
>