diff mbox series

[1/2] media: pixfmt-meta-rkisp1.rst: add description of rkisp1 metadata formats in pixfmt-meta-rkisp1.rst

Message ID 20200731121243.25882-2-dafna.hirschfeld@collabora.com (mailing list archive)
State New, archived
Headers show
Series media: admin-guide: add documentation for rkisp1 | expand

Commit Message

Dafna Hirschfeld July 31, 2020, 12:12 p.m. UTC 
The metadata formats V4L2_META_FMT_IPU3_PARAMS, V4L2_META_FMT_IPU3_3A
are currently described in two files under
drivers/staging/media/rkisp1/Documentation/media/uapi/v4l

This patch moves the description to one file:
Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst
The patch also extends the description and adds the rst file to
toctree.

Signed-off-by: Dafna Hirschfeld <dafna.hirschfeld@collabora.com>
---
 .../userspace-api/media/v4l/meta-formats.rst  |  1 +
 .../media/v4l/pixfmt-meta-rkisp1.rst          | 49 +++++++++++++++++++
 .../uapi/v4l/pixfmt-meta-rkisp1-params.rst    | 23 ---------
 .../uapi/v4l/pixfmt-meta-rkisp1-stat.rst      | 22 ---------
 4 files changed, 50 insertions(+), 45 deletions(-)
 create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst
 delete mode 100644 drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-params.rst
 delete mode 100644 drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-stat.rst

Comments

Sakari Ailus Aug. 3, 2020, 7:34 a.m. UTC | #1 
Hi Dafna,

Thanks for the patchset.

On Fri, Jul 31, 2020 at 02:12:42PM +0200, Dafna Hirschfeld wrote:
> The metadata formats V4L2_META_FMT_IPU3_PARAMS, V4L2_META_FMT_IPU3_3A
> are currently described in two files under
> drivers/staging/media/rkisp1/Documentation/media/uapi/v4l
> 
> This patch moves the description to one file:
> Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst
> The patch also extends the description and adds the rst file to
> toctree.
> 
> Signed-off-by: Dafna Hirschfeld <dafna.hirschfeld@collabora.com>
> ---
>  .../userspace-api/media/v4l/meta-formats.rst  |  1 +
>  .../media/v4l/pixfmt-meta-rkisp1.rst          | 49 +++++++++++++++++++
>  .../uapi/v4l/pixfmt-meta-rkisp1-params.rst    | 23 ---------
>  .../uapi/v4l/pixfmt-meta-rkisp1-stat.rst      | 22 ---------
>  4 files changed, 50 insertions(+), 45 deletions(-)
>  create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst
>  delete mode 100644 drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-params.rst
>  delete mode 100644 drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-stat.rst
> 
> diff --git a/Documentation/userspace-api/media/v4l/meta-formats.rst b/Documentation/userspace-api/media/v4l/meta-formats.rst
> index 7dcc4bacbb0c..55a635534bc9 100644
> --- a/Documentation/userspace-api/media/v4l/meta-formats.rst
> +++ b/Documentation/userspace-api/media/v4l/meta-formats.rst
> @@ -21,6 +21,7 @@ These formats are used for the :ref:`metadata` interface only.
>  
>      pixfmt-meta-d4xx
>      pixfmt-meta-intel-ipu3
> +    pixfmt-meta-rkisp1
>      pixfmt-meta-uvc
>      pixfmt-meta-vsp1-hgo
>      pixfmt-meta-vsp1-hgt
> diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst b/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst
> new file mode 100644
> index 000000000000..c8effdfd27bf
> --- /dev/null
> +++ b/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst
> @@ -0,0 +1,49 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _v4l2-meta-fmt-params-rkisp1:
> +.. _v4l2-meta-fmt-stat-rkisp1:
> +
> +*****************************************************************************
> +V4L2_META_FMT_RK_ISP1_PARAMS ('rk1p'), V4L2_META_FMT_RK_ISP1_STAT_3A ('rk1s')
> +*****************************************************************************
> +
> +.. rkisp1_stat_buffer
> +
> +3A and histogram statistics
> +===========================
> +
> +The ISP1 device collects different statistics over an input Bayer frame.
> +Those statistics are obtained from the :ref:`rkisp1_stats <rkisp1_stats>` metadata capture video node,
> +using the :c:type:`v4l2_meta_format` interface. The buffer contains a single instance of

Please wrap lines at most at 80 characters if possible.

> +the C structure :c:type:`rkisp1_stat_buffer` defined in ``rkisp1-config.h``.
> +So the structure can be obtained from the buffer by:
> +
> +.. code-block:: c
> +
> +	struct rkisp1_stat_buffer *stats = (struct rkisp1_stat_buffer*) buffer;
> +
> +The statistics collected are Exposure, AWB (Auto-white balance), Histogram and
> +AF (Auto-focus). See :c:type:`rkisp1_stat_buffer` for details of the statistics.
> +
> +.. ipu3_uapi_params
> +
> +Configuration parameters
> +========================

I'd move configuration parameters before statistics --- they're first in
the section name and are also used to calculate the statistics.

> +
> +The configuration parameters are passed to the :ref:`rkisp1_params <rkisp1_params>` metadata
> +output video node, using the :c:type:`v4l2_meta_format` interface. The buffer contains
> +a single instance of the C structure :c:type:`rkisp1_params_cfg` defined in
> +``rkisp1-config.h``. So the structure can be obtained from the buffer by:
> +
> +.. code-block:: c
> +
> +	struct rkisp1_params_cfg *stats = (struct rkisp1_params_cfg*) buffer;
> +
> +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.
> +
> +rkisp1 uAPI data types
> +======================
> +
> +.. kernel-doc:: drivers/staging/media/rkisp1/uapi/rkisp1-config.h
> diff --git a/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-params.rst b/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-params.rst
> deleted file mode 100644
> index 32034e481357..000000000000
> --- a/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-params.rst
> +++ /dev/null
> @@ -1,23 +0,0 @@
> -.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
> -
> -.. _v4l2-meta-fmt-rkisp1-params:
> -
> -============================
> -V4L2_META_FMT_RK_ISP1_PARAMS
> -============================
> -
> -Rockchip ISP1 Parameters Data
> -
> -Description
> -===========
> -
> -This format describes input parameters for the Rockchip ISP1.
> -
> -It uses c-struct :c:type:`rkisp1_params_cfg`, which is defined in
> -the ``linux/rkisp1-config.h`` header file.
> -
> -The parameters consist of multiple modules.
> -The module won't be updated if the corresponding bit was not set in module_*_update.
> -
> -.. kernel-doc:: include/uapi/linux/rkisp1-config.h
> -   :functions: rkisp1_params_cfg
> diff --git a/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-stat.rst b/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-stat.rst
> deleted file mode 100644
> index 4ad303f96421..000000000000
> --- a/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-stat.rst
> +++ /dev/null
> @@ -1,22 +0,0 @@
> -.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
> -
> -.. _v4l2-meta-fmt-rkisp1-stat:
> -
> -=============================
> -V4L2_META_FMT_RK_ISP1_STAT_3A
> -=============================
> -
> -
> -Rockchip ISP1 Statistics Data
> -
> -Description
> -===========
> -
> -This format describes image color statistics information generated by the Rockchip
> -ISP1.
> -
> -It uses c-struct :c:type:`rkisp1_stat_buffer`, which is defined in
> -the ``linux/rkisp1-config.h`` header file.
> -
> -.. kernel-doc:: include/uapi/linux/rkisp1-config.h
> -   :functions: rkisp1_stat_buffer
Helen Koike Aug. 10, 2020, 8 p.m. UTC | #2 
Hi Dafna,

Thanks for the patch,

On 7/31/20 9:12 AM, Dafna Hirschfeld wrote:
> The metadata formats V4L2_META_FMT_IPU3_PARAMS, V4L2_META_FMT_IPU3_3A

I believe you meant V4L2_META_FMT_RK_ISP1_PARAMS and
V4L2_META_FMT_RK_ISP1_STAT_3A

> are currently described in two files under
> drivers/staging/media/rkisp1/Documentation/media/uapi/v4l
> 
> This patch moves the description to one file:
> Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst
> The patch also extends the description and adds the rst file to
> toctree.
> 
> Signed-off-by: Dafna Hirschfeld <dafna.hirschfeld@collabora.com>
> ---
>  .../userspace-api/media/v4l/meta-formats.rst  |  1 +
>  .../media/v4l/pixfmt-meta-rkisp1.rst          | 49 +++++++++++++++++++
>  .../uapi/v4l/pixfmt-meta-rkisp1-params.rst    | 23 ---------
>  .../uapi/v4l/pixfmt-meta-rkisp1-stat.rst      | 22 ---------
>  4 files changed, 50 insertions(+), 45 deletions(-)
>  create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst
>  delete mode 100644 drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-params.rst
>  delete mode 100644 drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-stat.rst
> 
> diff --git a/Documentation/userspace-api/media/v4l/meta-formats.rst b/Documentation/userspace-api/media/v4l/meta-formats.rst
> index 7dcc4bacbb0c..55a635534bc9 100644
> --- a/Documentation/userspace-api/media/v4l/meta-formats.rst
> +++ b/Documentation/userspace-api/media/v4l/meta-formats.rst
> @@ -21,6 +21,7 @@ These formats are used for the :ref:`metadata` interface only.
>  
>      pixfmt-meta-d4xx
>      pixfmt-meta-intel-ipu3
> +    pixfmt-meta-rkisp1
>      pixfmt-meta-uvc
>      pixfmt-meta-vsp1-hgo
>      pixfmt-meta-vsp1-hgt
> diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst b/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst
> new file mode 100644
> index 000000000000..c8effdfd27bf
> --- /dev/null
> +++ b/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst
> @@ -0,0 +1,49 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _v4l2-meta-fmt-params-rkisp1:
> +.. _v4l2-meta-fmt-stat-rkisp1:
> +
> +*****************************************************************************
> +V4L2_META_FMT_RK_ISP1_PARAMS ('rk1p'), V4L2_META_FMT_RK_ISP1_STAT_3A ('rk1s')
> +*****************************************************************************
> +
> +.. rkisp1_stat_buffer

what is this for? This is a hyperlink right?

> +
> +3A and histogram statistics
> +===========================
> +
> +The ISP1 device collects different statistics over an input Bayer frame.
> +Those statistics are obtained from the :ref:`rkisp1_stats <rkisp1_stats>` metadata capture video node,
> +using the :c:type:`v4l2_meta_format` interface. The buffer contains a single instance of
> +the C structure :c:type:`rkisp1_stat_buffer` defined in ``rkisp1-config.h``.
> +So the structure can be obtained from the buffer by:
> +
> +.. code-block:: c
> +
> +	struct rkisp1_stat_buffer *stats = (struct rkisp1_stat_buffer*) buffer;
> +
> +The statistics collected are Exposure, AWB (Auto-white balance), Histogram and
> +AF (Auto-focus). See :c:type:`rkisp1_stat_buffer` for details of the statistics.
> +
> +.. ipu3_uapi_params

ipu3 here too

Thanks,
Helen

> +
> +Configuration parameters
> +========================
> +
> +The configuration parameters are passed to the :ref:`rkisp1_params <rkisp1_params>` metadata
> +output video node, using the :c:type:`v4l2_meta_format` interface. The buffer contains
> +a single instance of the C structure :c:type:`rkisp1_params_cfg` defined in
> +``rkisp1-config.h``. So the structure can be obtained from the buffer by:
> +
> +.. code-block:: c
> +
> +	struct rkisp1_params_cfg *stats = (struct rkisp1_params_cfg*) buffer;
> +
> +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.
> +
> +rkisp1 uAPI data types
> +======================
> +
> +.. kernel-doc:: drivers/staging/media/rkisp1/uapi/rkisp1-config.h
> diff --git a/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-params.rst b/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-params.rst
> deleted file mode 100644
> index 32034e481357..000000000000
> --- a/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-params.rst
> +++ /dev/null
> @@ -1,23 +0,0 @@
> -.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
> -
> -.. _v4l2-meta-fmt-rkisp1-params:
> -
> -============================
> -V4L2_META_FMT_RK_ISP1_PARAMS
> -============================
> -
> -Rockchip ISP1 Parameters Data
> -
> -Description
> -===========
> -
> -This format describes input parameters for the Rockchip ISP1.
> -
> -It uses c-struct :c:type:`rkisp1_params_cfg`, which is defined in
> -the ``linux/rkisp1-config.h`` header file.
> -
> -The parameters consist of multiple modules.
> -The module won't be updated if the corresponding bit was not set in module_*_update.
> -
> -.. kernel-doc:: include/uapi/linux/rkisp1-config.h
> -   :functions: rkisp1_params_cfg
> diff --git a/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-stat.rst b/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-stat.rst
> deleted file mode 100644
> index 4ad303f96421..000000000000
> --- a/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-stat.rst
> +++ /dev/null
> @@ -1,22 +0,0 @@
> -.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
> -
> -.. _v4l2-meta-fmt-rkisp1-stat:
> -
> -=============================
> -V4L2_META_FMT_RK_ISP1_STAT_3A
> -=============================
> -
> -
> -Rockchip ISP1 Statistics Data
> -
> -Description
> -===========
> -
> -This format describes image color statistics information generated by the Rockchip
> -ISP1.
> -
> -It uses c-struct :c:type:`rkisp1_stat_buffer`, which is defined in
> -the ``linux/rkisp1-config.h`` header file.
> -
> -.. kernel-doc:: include/uapi/linux/rkisp1-config.h
> -   :functions: rkisp1_stat_buffer
>
diff mbox series

Patch

diff --git a/Documentation/userspace-api/media/v4l/meta-formats.rst b/Documentation/userspace-api/media/v4l/meta-formats.rst
index 7dcc4bacbb0c..55a635534bc9 100644
--- a/Documentation/userspace-api/media/v4l/meta-formats.rst
+++ b/Documentation/userspace-api/media/v4l/meta-formats.rst
@@ -21,6 +21,7 @@  These formats are used for the :ref:`metadata` interface only.
 
     pixfmt-meta-d4xx
     pixfmt-meta-intel-ipu3
+    pixfmt-meta-rkisp1
     pixfmt-meta-uvc
     pixfmt-meta-vsp1-hgo
     pixfmt-meta-vsp1-hgt
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst b/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst
new file mode 100644
index 000000000000..c8effdfd27bf
--- /dev/null
+++ b/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst
@@ -0,0 +1,49 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _v4l2-meta-fmt-params-rkisp1:
+.. _v4l2-meta-fmt-stat-rkisp1:
+
+*****************************************************************************
+V4L2_META_FMT_RK_ISP1_PARAMS ('rk1p'), V4L2_META_FMT_RK_ISP1_STAT_3A ('rk1s')
+*****************************************************************************
+
+.. rkisp1_stat_buffer
+
+3A and histogram statistics
+===========================
+
+The ISP1 device collects different statistics over an input Bayer frame.
+Those statistics are obtained from the :ref:`rkisp1_stats <rkisp1_stats>` metadata capture video node,
+using the :c:type:`v4l2_meta_format` interface. The buffer contains a single instance of
+the C structure :c:type:`rkisp1_stat_buffer` defined in ``rkisp1-config.h``.
+So the structure can be obtained from the buffer by:
+
+.. code-block:: c
+
+	struct rkisp1_stat_buffer *stats = (struct rkisp1_stat_buffer*) buffer;
+
+The statistics collected are Exposure, AWB (Auto-white balance), Histogram and
+AF (Auto-focus). See :c:type:`rkisp1_stat_buffer` for details of the statistics.
+
+.. ipu3_uapi_params
+
+Configuration parameters
+========================
+
+The configuration parameters are passed to the :ref:`rkisp1_params <rkisp1_params>` metadata
+output video node, using the :c:type:`v4l2_meta_format` interface. The buffer contains
+a single instance of the C structure :c:type:`rkisp1_params_cfg` defined in
+``rkisp1-config.h``. So the structure can be obtained from the buffer by:
+
+.. code-block:: c
+
+	struct rkisp1_params_cfg *stats = (struct rkisp1_params_cfg*) buffer;
+
+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.
+
+rkisp1 uAPI data types
+======================
+
+.. kernel-doc:: drivers/staging/media/rkisp1/uapi/rkisp1-config.h
diff --git a/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-params.rst b/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-params.rst
deleted file mode 100644
index 32034e481357..000000000000
--- a/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-params.rst
+++ /dev/null
@@ -1,23 +0,0 @@ 
-.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
-
-.. _v4l2-meta-fmt-rkisp1-params:
-
-============================
-V4L2_META_FMT_RK_ISP1_PARAMS
-============================
-
-Rockchip ISP1 Parameters Data
-
-Description
-===========
-
-This format describes input parameters for the Rockchip ISP1.
-
-It uses c-struct :c:type:`rkisp1_params_cfg`, which is defined in
-the ``linux/rkisp1-config.h`` header file.
-
-The parameters consist of multiple modules.
-The module won't be updated if the corresponding bit was not set in module_*_update.
-
-.. kernel-doc:: include/uapi/linux/rkisp1-config.h
-   :functions: rkisp1_params_cfg
diff --git a/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-stat.rst b/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-stat.rst
deleted file mode 100644
index 4ad303f96421..000000000000
--- a/drivers/staging/media/rkisp1/Documentation/media/uapi/v4l/pixfmt-meta-rkisp1-stat.rst
+++ /dev/null
@@ -1,22 +0,0 @@ 
-.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
-
-.. _v4l2-meta-fmt-rkisp1-stat:
-
-=============================
-V4L2_META_FMT_RK_ISP1_STAT_3A
-=============================
-
-
-Rockchip ISP1 Statistics Data
-
-Description
-===========
-
-This format describes image color statistics information generated by the Rockchip
-ISP1.
-
-It uses c-struct :c:type:`rkisp1_stat_buffer`, which is defined in
-the ``linux/rkisp1-config.h`` header file.
-
-.. kernel-doc:: include/uapi/linux/rkisp1-config.h
-   :functions: rkisp1_stat_buffer