[PATCH] drm: amd: display: fix dc/core/dc.c kernel-doc

Fri Dec 30 19:33:32 UTC 2022

On 12/28/22 20:00, Randy Dunlap wrote:
> Fix all kernel-doc warnings in dc/core/dc.c:
> 
> dc.c:385: warning: missing initial short description on line:
>   *  dc_stream_adjust_vmin_vmax:
> dc.c:392: warning: contents before sections
> dc.c:399: warning: No description found for return value of 'dc_stream_adjust_vmin_vmax'
> dc.c:434: warning: Excess function parameter 'adjust' description in 'dc_stream_get_last_used_drr_vtotal'
> dc.c:434: warning: No description found for return value of 'dc_stream_get_last_used_drr_vtotal'
> dc.c:574: warning: No description found for return value of 'dc_stream_configure_crc'
> dc.c:1746: warning: No description found for return value of 'dc_commit_state_no_check'
> dc.c:4991: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   * dc_extended_blank_supported 0 Decide whether extended blank is supported
> dc.c:4991: warning: missing initial short description on line:
>   * dc_extended_blank_supported 0 Decide whether extended blank is supported
> dc.c:4723: warning: Function parameter or member 'dc' not described in 'dc_enable_dmub_outbox'
> dc.c:4926: warning: Function parameter or member 'dc' not described in 'dc_process_dmub_dpia_hpd_int_enable'
> dc.c:4926: warning: Function parameter or member 'hpd_int_enable' not described in 'dc_process_dmub_dpia_hpd_int_enable'
> 12 warnings
> 
> Signed-off-by: Randy Dunlap <rdunlap at infradead.org>
> Reported-by: kernel test robot <lkp at intel.com>
> Cc: Rodrigo Siqueira <Rodrigo.Siqueira at amd.com>
> Cc: Alex Deucher <alexander.deucher at amd.com>
> Cc: Hamza Mahfooz <hamza.mahfooz at amd.com>
> Cc: Harry Wentland <harry.wentland at amd.com>
> Cc: Leo Li <sunpeng.li at amd.com>
> Cc: Christian König <christian.koenig at amd.com>
> Cc: "Pan, Xinhui" <Xinhui.Pan at amd.com>
> Cc: amd-gfx at lists.freedesktop.org

Applied, thanks!

> ---
> Based on linux-next-20221226 but also applies to mainline.
> 
>   drivers/gpu/drm/amd/display/dc/core/dc.c |   40 +++++++++++++--------
>   1 file changed, 25 insertions(+), 15 deletions(-)
> 
> diff -- a/drivers/gpu/drm/amd/display/dc/core/dc.c b/drivers/gpu/drm/amd/display/dc/core/dc.c
> --- a/drivers/gpu/drm/amd/display/dc/core/dc.c
> +++ b/drivers/gpu/drm/amd/display/dc/core/dc.c
> @@ -382,16 +382,18 @@ static void dc_perf_trace_destroy(struct
>   }
>   
>   /**
> - *  dc_stream_adjust_vmin_vmax:
> + *  dc_stream_adjust_vmin_vmax - look up pipe context & update parts of DRR
> + *  @dc:     dc reference
> + *  @stream: Initial dc stream state
> + *  @adjust: Updated parameters for vertical_total_min and vertical_total_max
>    *
>    *  Looks up the pipe context of dc_stream_state and updates the
>    *  vertical_total_min and vertical_total_max of the DRR, Dynamic Refresh
>    *  Rate, which is a power-saving feature that targets reducing panel
>    *  refresh rate while the screen is static
>    *
> - *  @dc:     dc reference
> - *  @stream: Initial dc stream state
> - *  @adjust: Updated parameters for vertical_total_min and vertical_total_max
> + *  Return: %true if the pipe context is found and adjusted;
> + *          %false if the pipe context is not found.
>    */
>   bool dc_stream_adjust_vmin_vmax(struct dc *dc,
>   		struct dc_stream_state *stream,
> @@ -419,14 +421,17 @@ bool dc_stream_adjust_vmin_vmax(struct d
>   }
>   
>   /**
> - * dc_stream_get_last_used_drr_vtotal - dc_stream_get_last_vrr_vtotal
> + * dc_stream_get_last_used_drr_vtotal - Looks up the pipe context of
> + * dc_stream_state and gets the last VTOTAL used by DRR (Dynamic Refresh Rate)
>    *
>    * @dc: [in] dc reference
>    * @stream: [in] Initial dc stream state
> - * @adjust: [in] Updated parameters for vertical_total_min and
> + * @refresh_rate: [in] new refresh_rate
>    *
> - * Looks up the pipe context of dc_stream_state and gets the last VTOTAL used
> - * by DRR (Dynamic Refresh Rate)
> + * Return: %true if the pipe context is found and there is an associated
> + *         timing_generator for the DC;
> + *         %false if the pipe context is not found or there is no
> + *         timing_generator for the DC.
>    */
>   bool dc_stream_get_last_used_drr_vtotal(struct dc *dc,
>   		struct dc_stream_state *stream,
> @@ -567,7 +572,10 @@ dc_stream_forward_crc_window(struct dc_s
>    *              once.
>    *
>    * By default, only CRC0 is configured, and the entire frame is used to
> - * calculate the crc.
> + * calculate the CRC.
> + *
> + * Return: %false if the stream is not found or CRC capture is not supported;
> + *         %true if the stream has been configured.
>    */
>   bool dc_stream_configure_crc(struct dc *dc, struct dc_stream_state *stream,
>   			     struct crc_params *crc_window, bool enable, bool continuous)
> @@ -636,7 +644,7 @@ bool dc_stream_configure_crc(struct dc *
>    * dc_stream_configure_crc needs to be called beforehand to enable CRCs.
>    *
>    * Return:
> - * false if stream is not found, or if CRCs are not enabled.
> + * %false if stream is not found, or if CRCs are not enabled.
>    */
>   bool dc_stream_get_crc(struct dc *dc, struct dc_stream_state *stream,
>   		       uint32_t *r_cr, uint32_t *g_y, uint32_t *b_cb)
> @@ -1741,6 +1749,8 @@ void dc_z10_save_init(struct dc *dc)
>    *
>    * Applies given context to the hardware and copy it into current context.
>    * It's up to the user to release the src context afterwards.
> + *
> + * Return: an enum dc_status result code for the operation
>    */
>   static enum dc_status dc_commit_state_no_check(struct dc *dc, struct dc_state *context)
>   {
> @@ -4705,7 +4715,7 @@ bool dc_enable_dmub_notifications(struct
>   /**
>    * dc_enable_dmub_outbox - Enables DMUB unsolicited notification
>    *
> - * dc: [in] dc structure
> + * @dc: [in] dc structure
>    *
>    * Enables DMUB unsolicited notifications to x86 via outbox.
>    */
> @@ -4906,8 +4916,8 @@ enum dc_status dc_process_dmub_set_mst_s
>   /**
>    * dc_process_dmub_dpia_hpd_int_enable - Submits DPIA DPD interruption
>    *
> - * @dc [in]: dc structure
> - * @hpd_int_enable [in]: 1 for hpd int enable, 0 to disable
> + * @dc: [in] dc structure
> + * @hpd_int_enable: [in] 1 for hpd int enable, 0 to disable
>    *
>    * Submits dpia hpd int enable command to dmub via inbox message
>    */
> @@ -4988,7 +4998,7 @@ void dc_notify_vsync_int_state(struct dc
>   }
>   
>   /**
> - * dc_extended_blank_supported 0 Decide whether extended blank is supported
> + * dc_extended_blank_supported - Decide whether extended blank is supported
>    *
>    * @dc: [in] Current DC state
>    *
> @@ -4997,7 +5007,7 @@ void dc_notify_vsync_int_state(struct dc
>    * ability to enter z9/z10.
>    *
>    * Return:
> - * Indicate whether extended blank is supported (true or false)
> + * Indicate whether extended blank is supported (%true or %false)
>    */
>   bool dc_extended_blank_supported(struct dc *dc)
>   {

-- 
Hamza