Skip to contentSkip to conversation

drm/amd/display: Address kernel doc warnings

PATCH In review Rodrigo Siqueira 2 participants 8 messages Jul 16, 2024

Subsystems (5)
lore
Share & tools
lore
#0 lore raw

cover drm/amd/display: Address kernel doc warnings

This patchset fixes many of the kernel-doc warnings caused by the display documentation. This series addresses the following warnings:

./drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h:1: warning: no structured comments found ./drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h:1: warning: no structured comments found ./drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h:1: warning: no structured comments found ./drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h:1: warning: no structured comments found ./drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h:1: warning: no structured comments found ./drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h:1: warning: no structured comments found ./drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h:1: warning: no structured comments found ./drivers/gpu/drm/amd/display/dc/inc/hw/opp.h:1: warning: no structured comments found ./drivers/gpu/drm/amd/display/dc/inc/hw/opp.h:1: warning: no structured comments found ./drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h:1: warning: no structured comments found ./drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h:1: warning: no structured comments found

/home/siqueira/Documents/Repositories/kernels/amd-next_dal-dev/Documentation/gpu/amdgpu/display/display-manager:134: ./drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h:3: WARNING: Duplicate C declaration, also defined at gpu/amdgpu/display/dcn-blocks:101. Declaration is '.. c:struct:: mpcc_blnd_cfg'.
/home/siqueira/Documents/Repositories/kernels/amd-next_dal-dev/Documentation/gpu/amdgpu/display/display-manager:146: ./drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h:3: WARNING: Duplicate C declaration, also defined at gpu/amdgpu/display/dcn-blocks:3. Declaration is '.. c:enum:: mpcc_alpha_blend_mode'.
/home/siqueira/Documents/Repositories/kernels/amd-next_dal-dev/Documentation/gpu/amdgpu/display/display-manager.rst:3: WARNING: Duplicate C declaration, also defined at gpu/amdgpu/display/dcn-blocks:101. Declaration is '.. c:struct:: mpcc_blnd_cfg'.
/home/siqueira/Documents/Repositories/kernels/amd-next_dal-dev/Documentation/gpu/amdgpu/display/display-manager.rst:3: WARNING: Duplicate C declaration, also defined at gpu/amdgpu/display/dcn-blocks:3. Declaration is '.. c:enum:: mpcc_alpha_blend_mode'.

I tested it on amd-staging-drm-next.

Cc Alex Deucher <[email protected]>
Cc Stephen Rothwell <[email protected]>

Thanks
Siqueira

Rodrigo Siqueira (6):
drm/amd/display: Move DIO documentation to the right place Documentation/gpu: Remove ':export:' option from DCN documentation Documentation/gpu: Adjust DCN documentation paths drm/amd/display: Add simple struct doc to remove doc build warning Documentation/gpu: Remove undocumented files from dcn-blockshubbub.h Documentation/amdgpu: Fix duplicate declaration

 .../gpu/amdgpu/display/dcn-blocks.rst         | 35 ++++---------------
 .../gpu/amdgpu/display/display-manager.rst    |  4 +--
 drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h   | 22 +++++++++---
 drivers/gpu/drm/amd/display/dc/inc/hw/opp.h   | 15 ++++++++
 .../amd/display/dc/link/hwss/link_hwss_dio.c  | 29 +++++++++++++++
 .../amd/display/dc/link/hwss/link_hwss_dio.h  |  9 -----
 6 files changed, 69 insertions(+), 45 deletions(-)
Signature · 1 line
2.43.0
#1 lore raw

PATCH 1/6 drm/amd/display: Move DIO documentation to the right place

When building the kernel-doc, it complains with the below warning:

./drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h:1: warning: no structured comments found ./drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h:1: warning: no structured comments found

This warning was caused by the wrong use of the ':export:' and the lack of function documentation in the file pointed under the ':internal:'. This commit addresses those issues by relocating the overview documentation to the correct C file, removing the ':export:' options, and adding two simple kernel-doc to ensure that ':internal:' does not have any warning.

---
 .../gpu/amdgpu/display/dcn-blocks.rst         |  7 ++---
 .../amd/display/dc/link/hwss/link_hwss_dio.c  | 29 +++++++++++++++++++
 .../amd/display/dc/link/hwss/link_hwss_dio.h  |  9 ------
 3 files changed, 31 insertions(+), 14 deletions(-)
Documentation/gpu/amdgpu/display/dcn-blocks.rst +2 -5
index a3fbd3ea028b..118aeb9fd2b4 100644
@@ -68,11 +68,8 @@ OPP
 DIO
 ---
 
-.. kernel-doc:: drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.c
    :doc: overview
 
-.. kernel-doc:: drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h
-   :export:
-
-.. kernel-doc:: drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.c
    :internal:
drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.c +29 -0
index 81e335280e0f..3e47a6735912 100644
@@ -26,6 +26,16 @@
 #include "core_types.h"
 #include "link_enc_cfg.h"
 
+/**
+ * DOC: overview
+ *
+ * Display Input Output (DIO), is the display input and output unit in DCN. It
+ * includes output encoders to support different display output, like
+ * DisplayPort, HDMI, DVI interface, and others. It also includes the control
+ * and status channels for these interfaces.
+ */
+
+
 void set_dio_throttled_vcp_size(struct pipe_ctx *pipe_ctx,
 		struct fixed31_32 throttled_vcp_size)
 {
@@ -257,12 +267,31 @@ static const struct link_hwss dio_link_hwss = {
 	},
 };
 
+/**
+ * can_use_dio_link_hwss - Check if the link_hwss is accessible
+ *
+ * @link: Reference a link struct containing one or more sinks and the
+ *	  connective status.
+ * @link_res: Mappable hardware resource used to enable a link.
+ *
+ * Returns:
+ * Return true if the link encoder is accessible from link.
+ */
 bool can_use_dio_link_hwss(const struct dc_link *link,
 		const struct link_resource *link_res)
 {
 	return link->link_enc != NULL;
 }
 
+/**
+ * get_dio_link_hwss - Return link_hwss reference
+ *
+ * This function behaves like a get function to return the link_hwss populated
+ * in the link_hwss_dio.c file.
+ *
+ * Returns:
+ * Return the reference to the filled struct of link_hwss.
+ */
 const struct link_hwss *get_dio_link_hwss(void)
 {
 	return &dio_link_hwss;
drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h +0 -9
index a1f72fe378ee..45f0e091fcb0 100644
@@ -23,15 +23,6 @@
  *
  */
 
-/**
- * DOC: overview
- *
- * Display Input Output (DIO), is the display input and output unit in DCN. It
- * includes output encoders to support different display output, like
- * DisplayPort, HDMI, DVI interface, and others. It also includes the control
- * and status channels for these interfaces.
- */
-
 #ifndef __LINK_HWSS_DIO_H__
 #define __LINK_HWSS_DIO_H__
 
Signature · 1 line
2.43.0
#2 lore raw

PATCH 2/6 Documentation/gpu: Remove ':export:' option from DCN documentation

In reply to Rodrigo Siqueira

This commit reduces, but does not fix, all the occurrences and some of the documentation warnings related to the 'no structured comments.' This was caused by the wrong use of the ':export:' option in the DCN kernel-doc, so this commit drops the usage of those options.

---
 Documentation/gpu/amdgpu/display/dcn-blocks.rst | 15 ---------------
 1 file changed, 15 deletions(-)
Documentation/gpu/amdgpu/display/dcn-blocks.rst +0 -15
index 118aeb9fd2b4..582a5fee7f29 100644
@@ -11,9 +11,6 @@ DCHUBBUB
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
    :doc: overview
 
-.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
-   :export:
-
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
    :internal:
 
@@ -23,9 +20,6 @@ HUBP
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
    :doc: overview
 
-.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
-   :export:
-
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
    :internal:
 
@@ -35,9 +29,6 @@ DPP
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
    :doc: overview
 
-.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
-   :export:
-
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
    :internal:
 
@@ -47,9 +38,6 @@ MPC
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
    :doc: overview
 
-.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
-   :export:
-
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
    :internal:
 
@@ -59,9 +47,6 @@ OPP
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/opp.h
    :doc: overview
 
-.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/opp.h
-   :export:
-
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/opp.h
    :internal:
 
Signature · 1 line
2.43.0
#3 lore raw

PATCH 3/6 Documentation/gpu: Adjust DCN documentation paths

In reply to Rodrigo Siqueira

When building the kernel-doc, it has the following complaints:

Documentation/gpu/amdgpu/display/dcn-blocks:23:
drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h:3: WARNING: Duplicate C declaration, also defined at gpu/amdgpu/display/dcn-blocks:3.

Declaration is '.. c:struct:: surface_flip_registers'.

Documentation/gpu/amdgpu/display/dcn-blocks:35:
drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h:3: WARNING: Duplicate C declaration, also defined at gpu/amdgpu/display/dcn-blocks:3. Declaration is '.. c:struct:: surface_flip_registers'.

This error happened due to a copy-and-paste where the same file path was duplicated multiple times to a different set of blocks. This commit addresses this issue by using the correct file path.

---
 Documentation/gpu/amdgpu/display/dcn-blocks.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/gpu/amdgpu/display/dcn-blocks.rst +4 -4
index 582a5fee7f29..00bc0607e98c 100644
@@ -8,10 +8,10 @@ and the code documentation when it is automatically generated.
 DCHUBBUB
 --------
 
-.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/dchubbub.h
    :doc: overview
 
-.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/dchubbub.h
    :internal:
 
 HUBP
@@ -26,10 +26,10 @@ HUBP
 DPP
 ---
 
-.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h
    :doc: overview
 
-.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h
    :internal:
 
 MPC
Signature · 1 line
2.43.0
#4 lore raw

PATCH 4/6 drm/amd/display: Add simple struct doc to remove doc build warning

In reply to Rodrigo Siqueira

This commit is a part of a series that addresses the following build warning for opp:

./drivers/gpu/drm/amd/display/dc/inc/hw/opp.h:1: warning: no structured comments found ./drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h:1: warning: no structured comments found

This commit fixes this issue by adding a simple kernel-doc to a struct in the opp.h and the dpp.h files.

---
 drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h | 22 ++++++++++++++++-----
 drivers/gpu/drm/amd/display/dc/inc/hw/opp.h | 15 ++++++++++++++
 2 files changed, 32 insertions(+), 5 deletions(-)
drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h +17 -5
index 9ac7fc717a92..0150f2581ee4 100644
@@ -147,16 +147,28 @@ struct cnv_color_keyer_params {
 	int color_keyer_blue_high;
 };
 
-/* new for dcn2: set the 8bit alpha values based on the 2 bit alpha
- *ALPHA_2BIT_LUT. ALPHA_2BIT_LUT0   default: 0b00000000
- *ALPHA_2BIT_LUT. ALPHA_2BIT_LUT1   default: 0b01010101
- *ALPHA_2BIT_LUT. ALPHA_2BIT_LUT2   default: 0b10101010
- *ALPHA_2BIT_LUT. ALPHA_2BIT_LUT3   default: 0b11111111
+/**
+ * struct cnv_alpha_2bit_lut - Set the 8bit alpha values based on the 2 bit alpha
  */
 struct cnv_alpha_2bit_lut {
+	/**
+	* @lut0: ALPHA_2BIT_LUT. ALPHA_2BIT_LUT0. Default: 0b00000000
+	*/
 	int lut0;
+
+	/**
+	 * @lut1: ALPHA_2BIT_LUT. ALPHA_2BIT_LUT1. Default: 0b01010101
+	 */
 	int lut1;
+
+	/**
+	 * @lut2: ALPHA_2BIT_LUT. ALPHA_2BIT_LUT2. Default: 0b10101010
+	 */
 	int lut2;
+
+	/**
+	 * @lut3: ALPHA_2BIT_LUT. ALPHA_2BIT_LUT3. Default: 0b11111111
+	 */
 	int lut3;
 };
 
drivers/gpu/drm/amd/display/dc/inc/hw/opp.h +15 -0
index 127fb1a51654..747679cb4944 100644
@@ -205,9 +205,24 @@ struct gamma_coefficients {
 	struct fixed31_32 user_brightness;
 };
 
+/**
+ * struct pwl_float_data - Fixed point RGB color
+ */
 struct pwl_float_data {
+	/**
+	 * @r: Component Red.
+	 */
 	struct fixed31_32 r;
+
+	/**
+	 * @g: Component Green.
+	 */
+
 	struct fixed31_32 g;
+
+	/**
+	 * @b: Component Blue.
+	 */
 	struct fixed31_32 b;
 };
 
Signature · 1 line
2.43.0
#5 lore raw

PATCH 5/6 Documentation/gpu: Remove undocumented files from dcn-blockshubbub.h

In reply to Rodrigo Siqueira

The dchubbub.h and hubp.h do not have any meaningful documentation; for this reason, this commit removes those files from the dcn-blocks documentation.

---
 Documentation/gpu/amdgpu/display/dcn-blocks.rst | 6 ------
 1 file changed, 6 deletions(-)
Documentation/gpu/amdgpu/display/dcn-blocks.rst +0 -6
index 00bc0607e98c..f80df596ef5c 100644
@@ -11,18 +11,12 @@ DCHUBBUB
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/dchubbub.h
    :doc: overview
 
-.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/dchubbub.h
-   :internal:
-
 HUBP
 ----
 
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
    :doc: overview
 
-.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
-   :internal:
-
 DPP
 ---
 
Signature · 1 line
2.43.0
#6 lore raw

PATCH 6/6 Documentation/amdgpu: Fix duplicate declaration

In reply to Rodrigo Siqueira

Address the below kernel doc warning:

Documentation/gpu/amdgpu/display/display-manager:134:
drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h:3: WARNING: Duplicate C declaration, also defined at gpu/amdgpu/display/dcn-blocks:101. Declaration is '.. c:struct:: mpcc_blnd_cfg'. Documentation/gpu/amdgpu/display/display-manager:146:
drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h:3: WARNING: Duplicate C declaration, also defined at gpu/amdgpu/display/dcn-blocks:3. Declaration is '.. c:enum:: mpcc_alpha_blend_mode'.

To address the above warnings, this commit uses the 'no-identifiers' option in the dcn-blocks to avoid duplication with the previous use of this function doc in the display-manager file. Finally, replaces the deprecated ':function:' in favor of ':identifiers:'.

---
 Documentation/gpu/amdgpu/display/dcn-blocks.rst      | 1 +
 Documentation/gpu/amdgpu/display/display-manager.rst | 4 ++--
 2 files changed, 3 insertions(+), 2 deletions(-)
Documentation/gpu/amdgpu/display/dcn-blocks.rst +1 -0
index f80df596ef5c..5e34366f6dbe 100644
@@ -34,6 +34,7 @@ MPC
 
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
    :internal:
+   :no-identifiers: mpcc_blnd_cfg mpcc_alpha_blend_mode
 
 OPP
 ---
Documentation/gpu/amdgpu/display/display-manager.rst +2 -2
index 67a811e6891f..b269ff3f7a54 100644
@@ -132,7 +132,7 @@ The DRM blend mode and its elements are then mapped by AMDGPU display manager
 (MPC), as follows:
 
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
-   :functions: mpcc_blnd_cfg
+   :identifiers: mpcc_blnd_cfg
 
 Therefore, the blending configuration for a single MPCC instance on the MPC
 tree is defined by :c:type:`mpcc_blnd_cfg`, where
@@ -144,7 +144,7 @@ alpha and plane alpha values. It sets one of the three modes for
 :c:type:`MPCC_ALPHA_BLND_MODE`, as described below.
 
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
-   :functions: mpcc_alpha_blend_mode
+   :identifiers: mpcc_alpha_blend_mode
 
 DM then maps the elements of `enum mpcc_alpha_blend_mode` to those in the DRM
 blend formula, as follows:
Signature · 1 line
2.43.0
Acked-by on v1 6/6
#7 lore raw

Re: [PATCH 6/6] Documentation/amdgpu: Fix duplicate declaration

Series is:

Quoted 62 lines · Rodrigo Siqueira

Address the below kernel doc warning:

Documentation/gpu/amdgpu/display/display-manager:134:
drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h:3: WARNING: Duplicate C declaration, also defined at gpu/amdgpu/display/dcn-blocks:101. Declaration is '.. c:struct:: mpcc_blnd_cfg'. Documentation/gpu/amdgpu/display/display-manager:146:
drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h:3: WARNING: Duplicate C declaration, also defined at gpu/amdgpu/display/dcn-blocks:3. Declaration is '.. c:enum:: mpcc_alpha_blend_mode'.

To address the above warnings, this commit uses the 'no-identifiers' option in the dcn-blocks to avoid duplication with the previous use of this function doc in the display-manager file. Finally, replaces the deprecated ':function:' in favor of ':identifiers:'.

---
 Documentation/gpu/amdgpu/display/dcn-blocks.rst      | 1 +
 Documentation/gpu/amdgpu/display/display-manager.rst | 4 ++--
 2 files changed, 3 insertions(+), 2 deletions(-)
Documentation/gpu/amdgpu/display/dcn-blocks.rst +1 -0
index f80df596ef5c..5e34366f6dbe 100644
@@ -34,6 +34,7 @@ MPC
 
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
    :internal:
+   :no-identifiers: mpcc_blnd_cfg mpcc_alpha_blend_mode
 
 OPP
 ---
Documentation/gpu/amdgpu/display/display-manager.rst +2 -3
index 67a811e6891f..b269ff3f7a54 100644
@@ -132,7 +132,7 @@ The DRM blend mode and its elements are then mapped by AMDGPU display manager
 (MPC), as follows:
 
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
-   :functions: mpcc_blnd_cfg
+   :identifiers: mpcc_blnd_cfg
 
 Therefore, the blending configuration for a single MPCC instance on the MPC
 tree is defined by :c:type:`mpcc_blnd_cfg`, where
@@ -144,7 +144,7 @@ alpha and plane alpha values. It sets one of the three modes for
 :c:type:`MPCC_ALPHA_BLND_MODE`, as described below.
 
 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
-   :functions: mpcc_alpha_blend_mode
+   :identifiers: mpcc_alpha_blend_mode
 
 DM then maps the elements of `enum mpcc_alpha_blend_mode` to those in the DRM
 blend formula, as follows:
--

2.43.0