drm/amd/display: Address kernel doc warnings
Subsystems (5)
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.
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
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
@@ -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
@@ -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
@@ -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
PATCH 2/6 Documentation/gpu: Remove ':export:' option from DCN documentation
In reply to Rodrigo SiqueiraThis 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
@@ -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
PATCH 3/6 Documentation/gpu: Adjust DCN documentation paths
In reply to Rodrigo SiqueiraWhen 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
@@ -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
PATCH 4/6 drm/amd/display: Add simple struct doc to remove doc build warning
In reply to Rodrigo SiqueiraThis 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
@@ -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
@@ -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
PATCH 5/6 Documentation/gpu: Remove undocumented files from dcn-blockshubbub.h
In reply to Rodrigo SiqueiraThe 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
@@ -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
PATCH 6/6 Documentation/amdgpu: Fix duplicate declaration
In reply to Rodrigo SiqueiraAddress 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
@@ -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
@@ -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
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:'.
Cc Alex Deucher <[email protected]>Reported-by Stephen Rothwell <[email protected]>Signed-off-by Rodrigo Siqueira <[email protected]>--- 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@@ -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@@ -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