[PATCH] drm/amd/display: Fix up kdoc formats in dcn32_fpu.c

[PATCH] drm/amd/display: Fix up kdoc formats in dcn32_fpu.c

[Srinivasan Shanmugam]

Fixes the following gcc with W=1:

drivers/gpu/drm/amd/amdgpu/../display/dc/dml/dcn32/dcn32_fpu.c:2806: warning: Cannot understand  * *************************************************************************
drivers/gpu/drm/amd/amdgpu/../display/dc/dml/dcn32/dcn32_fpu.c:2855: warning: Cannot understand  * *************************************************************************
drivers/gpu/drm/amd/amdgpu/../display/dc/dml/dcn32/dcn32_fpu.c:2900: warning: Function parameter or member 'dc' not described in 'dcn32_assign_fpo_vactive_candidate'
drivers/gpu/drm/amd/amdgpu/../display/dc/dml/dcn32/dcn32_fpu.c:2900: warning: Function parameter or member 'context' not described in 'dcn32_assign_fpo_vactive_candidate'
drivers/gpu/drm/amd/amdgpu/../display/dc/dml/dcn32/dcn32_fpu.c:2900: warning: Function parameter or member 'fpo_candidate_stream' not described in 'dcn32_assign_fpo_vactive_candidate'
drivers/gpu/drm/amd/amdgpu/../display/dc/dml/dcn32/dcn32_fpu.c:2929: warning: Function parameter or member 'dc' not described in 'dcn32_find_vactive_pipe'
drivers/gpu/drm/amd/amdgpu/../display/dc/dml/dcn32/dcn32_fpu.c:2929: warning: Function parameter or member 'context' not described in 'dcn32_find_vactive_pipe'
drivers/gpu/drm/amd/amdgpu/../display/dc/dml/dcn32/dcn32_fpu.c:2929: warning: Function parameter or member 'vactive_margin_req_us' not described in 'dcn32_find_vactive_pipe'

Cc: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
Cc: Harry Wentland <harry.wentland@amd.com>
Cc: Aurabindo Pillai <aurabindo.pillai@amd.com>
Signed-off-by: Srinivasan Shanmugam <srinivasan.shanmugam@amd.com>
---
 .../drm/amd/display/dc/dml/dcn32/dcn32_fpu.c  | 46 +++++++++----------
 1 file changed, 22 insertions(+), 24 deletions(-)

diff --git a/drivers/gpu/drm/amd/display/dc/dml/dcn32/dcn32_fpu.c b/drivers/gpu/drm/amd/display/dc/dml/dcn32/dcn32_fpu.c
index 137ff970c9aa..6d8dda4cb065 100644
--- a/drivers/gpu/drm/amd/display/dc/dml/dcn32/dcn32_fpu.c
+++ b/drivers/gpu/drm/amd/display/dc/dml/dcn32/dcn32_fpu.c
@@ -2802,13 +2802,12 @@ bool dcn32_allow_subvp_with_active_margin(struct pipe_ctx *pipe)
 	return allow;
 }
 
-/**
- * ************************************************************************************************
+/*
  * dcn32_allow_subvp_high_refresh_rate: Determine if the high refresh rate config will allow subvp
  *
- * @param [in]: dc: Current DC state
- * @param [in]: context: New DC state to be programmed
- * @param [in]: pipe: Pipe to be considered for use in subvp
+ * @dc: Current DC state
+ * @context: New DC state to be programmed
+ * @pipe: Pipe to be considered for use in subvp
  *
  * On high refresh rate display configs, we will allow subvp under the following conditions:
  * 1. Resolution is 3840x2160, 3440x1440, or 2560x1440
@@ -2817,9 +2816,8 @@ bool dcn32_allow_subvp_with_active_margin(struct pipe_ctx *pipe)
  * 4. Freesync is inactive
  * 5. For single display cases, freesync must be disabled
  *
- * @return: True if pipe can be used for subvp, false otherwise
- *
- * ************************************************************************************************
+ * Returns:
+ *	True if pipe can be used for subvp, false otherwise
  */
 bool dcn32_allow_subvp_high_refresh_rate(struct dc *dc, struct dc_state *context, struct pipe_ctx *pipe)
 {
@@ -2851,16 +2849,15 @@ bool dcn32_allow_subvp_high_refresh_rate(struct dc *dc, struct dc_state *context
 	return allow;
 }
 
-/**
- * *******************************************************************************************
+/*
  * dcn32_determine_max_vratio_prefetch: Determine max Vratio for prefetch by driver policy
  *
- * @param [in]: dc: Current DC state
- * @param [in]: context: New DC state to be programmed
+ * @dc: Current DC state
+ * @context: New DC state to be programmed
  *
- * @return: Max vratio for prefetch
+ * Returns:
+ *	Max vratio for prefetch
  *
- * *******************************************************************************************
  */
 double dcn32_determine_max_vratio_prefetch(struct dc *dc, struct dc_state *context)
 {
@@ -2881,7 +2878,7 @@ double dcn32_determine_max_vratio_prefetch(struct dc *dc, struct dc_state *conte
 	return max_vratio_pre;
 }
 
-/**
+/*
  * dcn32_assign_fpo_vactive_candidate - Assign the FPO stream candidate for FPO + VActive case
  *
  * This function chooses the FPO candidate stream for FPO + VActive cases (2 stream config).
@@ -2890,11 +2887,12 @@ double dcn32_determine_max_vratio_prefetch(struct dc *dc, struct dc_state *conte
  * ActiveMargin <= 0 to be the FPO stream candidate if found.
  *
  *
- * @param [in]: dc - current dc state
- * @param [in]: context - new dc state
- * @param [out]: fpo_candidate_stream - pointer to FPO stream candidate if one is found
+ * @dc: current dc state
+ * @context: new dc state
+ * @fpo_candidate_stream: pointer to FPO stream candidate if one is found
  *
- * Return: void
+ * Return:
+ *	void
  */
 void dcn32_assign_fpo_vactive_candidate(struct dc *dc, const struct dc_state *context, struct dc_stream_state **fpo_candidate_stream)
 {
@@ -2915,13 +2913,13 @@ void dcn32_assign_fpo_vactive_candidate(struct dc *dc, const struct dc_state *co
 	}
 }
 
-/**
+/*
  * dcn32_find_vactive_pipe - Determines if the config has a pipe that can switch in VACTIVE
  *
- * @param [in]: dc - current dc state
- * @param [in]: context - new dc state
- * @param [in]: vactive_margin_req_us - The vactive marign required for a vactive pipe to be
- *                                      considered "found"
+ * @dc: current dc state
+ * @context: new dc state
+ * @vactive_margin_req_us: The vactive marign required for a vactive pipe to be
+ *                              considered "found"
  *
  * Return: True if VACTIVE display is found, false otherwise
  */
-- 
2.25.1

Re: [PATCH] drm/amd/display: Fix up kdoc formats in dcn32_fpu.c

[Aurabindo Pillai]

Hi Srinivasan,

Please see my inline comments:

On 5/27/23 12:42, Srinivasan Shanmugam wrote:
> Fixes the following gcc with W=1:
> 
> drivers/gpu/drm/amd/amdgpu/../display/dc/dml/dcn32/dcn32_fpu.c:2806: warning: Cannot understand  * *************************************************************************
> drivers/gpu/drm/amd/amdgpu/../display/dc/dml/dcn32/dcn32_fpu.c:2855: warning: Cannot understand  * *************************************************************************
> drivers/gpu/drm/amd/amdgpu/../display/dc/dml/dcn32/dcn32_fpu.c:2900: warning: Function parameter or member 'dc' not described in 'dcn32_assign_fpo_vactive_candidate'
> drivers/gpu/drm/amd/amdgpu/../display/dc/dml/dcn32/dcn32_fpu.c:2900: warning: Function parameter or member 'context' not described in 'dcn32_assign_fpo_vactive_candidate'
> drivers/gpu/drm/amd/amdgpu/../display/dc/dml/dcn32/dcn32_fpu.c:2900: warning: Function parameter or member 'fpo_candidate_stream' not described in 'dcn32_assign_fpo_vactive_candidate'
> drivers/gpu/drm/amd/amdgpu/../display/dc/dml/dcn32/dcn32_fpu.c:2929: warning: Function parameter or member 'dc' not described in 'dcn32_find_vactive_pipe'
> drivers/gpu/drm/amd/amdgpu/../display/dc/dml/dcn32/dcn32_fpu.c:2929: warning: Function parameter or member 'context' not described in 'dcn32_find_vactive_pipe'
> drivers/gpu/drm/amd/amdgpu/../display/dc/dml/dcn32/dcn32_fpu.c:2929: warning: Function parameter or member 'vactive_margin_req_us' not described in 'dcn32_find_vactive_pipe'
> 
> Cc: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
> Cc: Harry Wentland <harry.wentland@amd.com>
> Cc: Aurabindo Pillai <aurabindo.pillai@amd.com>
> Signed-off-by: Srinivasan Shanmugam <srinivasan.shanmugam@amd.com>
> ---
>  .../drm/amd/display/dc/dml/dcn32/dcn32_fpu.c  | 46 +++++++++----------
>  1 file changed, 22 insertions(+), 24 deletions(-)
> 
> diff --git a/drivers/gpu/drm/amd/display/dc/dml/dcn32/dcn32_fpu.c b/drivers/gpu/drm/amd/display/dc/dml/dcn32/dcn32_fpu.c
> index 137ff970c9aa..6d8dda4cb065 100644
> --- a/drivers/gpu/drm/amd/display/dc/dml/dcn32/dcn32_fpu.c
> +++ b/drivers/gpu/drm/amd/display/dc/dml/dcn32/dcn32_fpu.c
> @@ -2802,13 +2802,12 @@ bool dcn32_allow_subvp_with_active_margin(struct pipe_ctx *pipe)
>  	return allow;
>  }
>  
> -/**
> - * ************************************************************************************************
> +/*
>   * dcn32_allow_subvp_high_refresh_rate: Determine if the high refresh rate config will allow subvp
>   *
> - * @param [in]: dc: Current DC state
> - * @param [in]: context: New DC state to be programmed
> - * @param [in]: pipe: Pipe to be considered for use in subvp
> + * @dc: Current DC state
> + * @context: New DC state to be programmed
> + * @pipe: Pipe to be considered for use in subvp
>   *
>   * On high refresh rate display configs, we will allow subvp under the following conditions:
>   * 1. Resolution is 3840x2160, 3440x1440, or 2560x1440
> @@ -2817,9 +2816,8 @@ bool dcn32_allow_subvp_with_active_margin(struct pipe_ctx *pipe)
>   * 4. Freesync is inactive
>   * 5. For single display cases, freesync must be disabled
>   *
> - * @return: True if pipe can be used for subvp, false otherwise
> - *
> - * ************************************************************************************************
> + * Returns:
> + *	True if pipe can be used for subvp, false otherwise
>   */
>  bool dcn32_allow_subvp_high_refresh_rate(struct dc *dc, struct dc_state *context, struct pipe_ctx *pipe)
>  {
> @@ -2851,16 +2849,15 @@ bool dcn32_allow_subvp_high_refresh_rate(struct dc *dc, struct dc_state *context
>  	return allow;
>  }
>  
> -/**
> - * *******************************************************************************************
> +/*
>   * dcn32_determine_max_vratio_prefetch: Determine max Vratio for prefetch by driver policy
>   *
> - * @param [in]: dc: Current DC state
> - * @param [in]: context: New DC state to be programmed
> + * @dc: Current DC state
> + * @context: New DC state to be programmed
>   *
> - * @return: Max vratio for prefetch
> + * Returns:
> + *	Max vratio for prefetch
>   *
> - * *******************************************************************************************
>   */
>  double dcn32_determine_max_vratio_prefetch(struct dc *dc, struct dc_state *context)
>  {
> @@ -2881,7 +2878,7 @@ double dcn32_determine_max_vratio_prefetch(struct dc *dc, struct dc_state *conte
>  	return max_vratio_pre;
>  }
>  
> -/**
> +/*
>   * dcn32_assign_fpo_vactive_candidate - Assign the FPO stream candidate for FPO + VActive case
>   *
>   * This function chooses the FPO candidate stream for FPO + VActive cases (2 stream config).
> @@ -2890,11 +2887,12 @@ double dcn32_determine_max_vratio_prefetch(struct dc *dc, struct dc_state *conte
>   * ActiveMargin <= 0 to be the FPO stream candidate if found.
>   *
>   *
> - * @param [in]: dc - current dc state
> - * @param [in]: context - new dc state
> - * @param [out]: fpo_candidate_stream - pointer to FPO stream candidate if one is found
> + * @dc: current dc state
> + * @context: new dc state
> + * @fpo_candidate_stream: pointer to FPO stream candidate if one is found
>   *
> - * Return: void
> + * Return:
> + *	void
>   */
>  void dcn32_assign_fpo_vactive_candidate(struct dc *dc, const struct dc_state *context, struct dc_stream_state **fpo_candidate_stream)
>  {
> @@ -2915,13 +2913,13 @@ void dcn32_assign_fpo_vactive_candidate(struct dc *dc, const struct dc_state *co
>  	}
>  }
>  
> -/**
> +/*
>   * dcn32_find_vactive_pipe - Determines if the config has a pipe that can switch in VACTIVE
>   *
> - * @param [in]: dc - current dc state
> - * @param [in]: context - new dc state
> - * @param [in]: vactive_margin_req_us - The vactive marign required for a vactive pipe to be
> - *                                      considered "found"
> + * @dc: current dc state
> + * @context: new dc state
> + * @vactive_margin_req_us: The vactive marign required for a vactive pipe to be
> + *                              considered "found"

Multiline description for arguments should start at the same line as the previous. Please see https://www.kernel.org/doc/html/v5.0/doc-guide/kernel-doc.html for details.
>   *
>   * Return: True if VACTIVE display is found, false otherwise
>   */




Return section in kernel-doc does not recognize line breaks, so you could put them into the same line itself, or you would need use something like:

* Return:
* * 0             - OK to runtime suspend the device
* * -EBUSY        - Device should not be runtime suspended

For this patch, multiline issue with Return section is not an issue. With the argument multiline issue fixed, the patch is:

Reviewed-by: Aurabindo Pillai <aurabindo.pillai@amd.com>