diff mbox series

[v2,06/39] drm/i915: gt: fix some Kernel-doc issues

Message ID 3cb8ebff378fc0634e992eba68176ed30842572a.1657699522.git.mchehab@kernel.org (mailing list archive)
State New, archived
Headers show
Series drm/i915: fix kernel-doc issues | expand

Commit Message

Mauro Carvalho Chehab July 13, 2022, 8:11 a.m. UTC
There are several trivial warnings there, due to trivial things:
	- lack of function name at the kerneldoc markup;
	- undocumented structs with kernel-doc markups;
	- wrong parameter syntax.

    Fix such warnings:

	drivers/gpu/drm/i915/gt/intel_context.h:107: warning: Function parameter or member 'ce' not described in 'intel_context_lock_pinned'
	drivers/gpu/drm/i915/gt/intel_context.h:122: warning: Function parameter or member 'ce' not described in 'intel_context_is_pinned'
	drivers/gpu/drm/i915/gt/intel_context.h:141: warning: Function parameter or member 'ce' not described in 'intel_context_unlock_pinned'
	drivers/gpu/drm/i915/gt/intel_gtt.h:510: warning: Function parameter or member 'vm' not described in 'i915_vm_resv_put'
	drivers/gpu/drm/i915/gt/intel_gtt.h:510: warning: Excess function parameter 'resv' description in 'i915_vm_resv_put'
	drivers/gpu/drm/i915/gt/intel_gtt.h:615: warning: Function parameter or member 'i915' not described in 'i915_ggtt_mark_pte_lost'
	drivers/gpu/drm/i915/gt/intel_gtt.h:615: warning: Function parameter or member 'val' not described in 'i915_ggtt_mark_pte_lost'
	drivers/gpu/drm/i915/gt/intel_rps.c:2343: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
	 * Tells the intel_ips driver that the i915 driver is now loaded, if
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'size' not described in '__guc_capture_bufstate'
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'data' not described in '__guc_capture_bufstate'
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'rd' not described in '__guc_capture_bufstate'
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'wr' not described in '__guc_capture_bufstate'
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'link' not described in '__guc_capture_parsed_output'
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'is_partial' not described in '__guc_capture_parsed_output'
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'eng_class' not described in '__guc_capture_parsed_output'
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'eng_inst' not described in '__guc_capture_parsed_output'
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'guc_id' not described in '__guc_capture_parsed_output'
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'lrca' not described in '__guc_capture_parsed_output'
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'reginfo' not described in '__guc_capture_parsed_output'
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:63: warning: wrong kernel-doc identifier on line:
	 * struct guc_debug_capture_list_header / struct guc_debug_capture_list
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:81: warning: wrong kernel-doc identifier on line:
	 * struct __guc_mmio_reg_descr / struct __guc_mmio_reg_descr_group
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:106: warning: wrong kernel-doc identifier on line:
	 * struct guc_state_capture_header_t / struct guc_state_capture_t /
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'is_valid' not described in '__guc_capture_ads_cache'
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'ptr' not described in '__guc_capture_ads_cache'
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'size' not described in '__guc_capture_ads_cache'
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'status' not described in '__guc_capture_ads_cache'
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:217: warning: Function parameter or member 'ads_null_cache' not described in 'intel_guc_state_capture'
	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:217: warning: Function parameter or member 'max_mmio_per_node' not described in 'intel_guc_state_capture'
	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'marker' not described in 'guc_log_buffer_state'
	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'read_ptr' not described in 'guc_log_buffer_state'
	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'write_ptr' not described in 'guc_log_buffer_state'
	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'size' not described in 'guc_log_buffer_state'
	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'sampled_write_ptr' not described in 'guc_log_buffer_state'
	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'wrap_offset' not described in 'guc_log_buffer_state'
	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'flush_to_file' not described in 'guc_log_buffer_state'
	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'buffer_full_cnt' not described in 'guc_log_buffer_state'
	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'reserved' not described in 'guc_log_buffer_state'
	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'flags' not described in 'guc_log_buffer_state'
	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'version' not described in 'guc_log_buffer_state'

Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/cover.1657699522.git.mchehab@kernel.org/

 drivers/gpu/drm/i915/gt/intel_context.h       |  6 +++---
 drivers/gpu/drm/i915/gt/intel_engine_cs.c     |  4 ++--
 drivers/gpu/drm/i915/gt/intel_gtt.h           |  6 +++---
 drivers/gpu/drm/i915/gt/intel_rps.c           |  4 ++--
 drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h | 14 +++++++-------
 drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h   |  2 +-
 6 files changed, 18 insertions(+), 18 deletions(-)

Comments

Rodrigo Vivi July 13, 2022, 10:07 p.m. UTC | #1
On Wed, Jul 13, 2022 at 09:11:54AM +0100, Mauro Carvalho Chehab wrote:
> There are several trivial warnings there, due to trivial things:
> 	- lack of function name at the kerneldoc markup;
> 	- undocumented structs with kernel-doc markups;
> 	- wrong parameter syntax.
> 
>     Fix such warnings:
> 
> 	drivers/gpu/drm/i915/gt/intel_context.h:107: warning: Function parameter or member 'ce' not described in 'intel_context_lock_pinned'
> 	drivers/gpu/drm/i915/gt/intel_context.h:122: warning: Function parameter or member 'ce' not described in 'intel_context_is_pinned'
> 	drivers/gpu/drm/i915/gt/intel_context.h:141: warning: Function parameter or member 'ce' not described in 'intel_context_unlock_pinned'
> 	drivers/gpu/drm/i915/gt/intel_gtt.h:510: warning: Function parameter or member 'vm' not described in 'i915_vm_resv_put'
> 	drivers/gpu/drm/i915/gt/intel_gtt.h:510: warning: Excess function parameter 'resv' description in 'i915_vm_resv_put'
> 	drivers/gpu/drm/i915/gt/intel_gtt.h:615: warning: Function parameter or member 'i915' not described in 'i915_ggtt_mark_pte_lost'
> 	drivers/gpu/drm/i915/gt/intel_gtt.h:615: warning: Function parameter or member 'val' not described in 'i915_ggtt_mark_pte_lost'
> 	drivers/gpu/drm/i915/gt/intel_rps.c:2343: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> 	 * Tells the intel_ips driver that the i915 driver is now loaded, if
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'size' not described in '__guc_capture_bufstate'
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'data' not described in '__guc_capture_bufstate'
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'rd' not described in '__guc_capture_bufstate'
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'wr' not described in '__guc_capture_bufstate'
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'link' not described in '__guc_capture_parsed_output'
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'is_partial' not described in '__guc_capture_parsed_output'
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'eng_class' not described in '__guc_capture_parsed_output'
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'eng_inst' not described in '__guc_capture_parsed_output'
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'guc_id' not described in '__guc_capture_parsed_output'
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'lrca' not described in '__guc_capture_parsed_output'
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'reginfo' not described in '__guc_capture_parsed_output'
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:63: warning: wrong kernel-doc identifier on line:
> 	 * struct guc_debug_capture_list_header / struct guc_debug_capture_list
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:81: warning: wrong kernel-doc identifier on line:
> 	 * struct __guc_mmio_reg_descr / struct __guc_mmio_reg_descr_group
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:106: warning: wrong kernel-doc identifier on line:
> 	 * struct guc_state_capture_header_t / struct guc_state_capture_t /
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'is_valid' not described in '__guc_capture_ads_cache'
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'ptr' not described in '__guc_capture_ads_cache'
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'size' not described in '__guc_capture_ads_cache'
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'status' not described in '__guc_capture_ads_cache'
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:217: warning: Function parameter or member 'ads_null_cache' not described in 'intel_guc_state_capture'
> 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:217: warning: Function parameter or member 'max_mmio_per_node' not described in 'intel_guc_state_capture'
> 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'marker' not described in 'guc_log_buffer_state'
> 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'read_ptr' not described in 'guc_log_buffer_state'
> 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'write_ptr' not described in 'guc_log_buffer_state'
> 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'size' not described in 'guc_log_buffer_state'
> 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'sampled_write_ptr' not described in 'guc_log_buffer_state'
> 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'wrap_offset' not described in 'guc_log_buffer_state'
> 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'flush_to_file' not described in 'guc_log_buffer_state'
> 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'buffer_full_cnt' not described in 'guc_log_buffer_state'
> 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'reserved' not described in 'guc_log_buffer_state'
> 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'flags' not described in 'guc_log_buffer_state'
> 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'version' not described in 'guc_log_buffer_state'
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
> 
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/cover.1657699522.git.mchehab@kernel.org/
> 
>  drivers/gpu/drm/i915/gt/intel_context.h       |  6 +++---
>  drivers/gpu/drm/i915/gt/intel_engine_cs.c     |  4 ++--
>  drivers/gpu/drm/i915/gt/intel_gtt.h           |  6 +++---
>  drivers/gpu/drm/i915/gt/intel_rps.c           |  4 ++--
>  drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h | 14 +++++++-------
>  drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h   |  2 +-
>  6 files changed, 18 insertions(+), 18 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/gt/intel_context.h b/drivers/gpu/drm/i915/gt/intel_context.h
> index 8e2d70630c49..91c092d5deae 100644
> --- a/drivers/gpu/drm/i915/gt/intel_context.h
> +++ b/drivers/gpu/drm/i915/gt/intel_context.h
> @@ -96,7 +96,7 @@ void intel_context_bind_parent_child(struct intel_context *parent,
>  
>  /**
>   * intel_context_lock_pinned - Stablises the 'pinned' status of the HW context
> - * @ce - the context
> + * @ce: the context
>   *
>   * Acquire a lock on the pinned status of the HW context, such that the context
>   * can neither be bound to the GPU or unbound whilst the lock is held, i.e.
> @@ -110,7 +110,7 @@ static inline int intel_context_lock_pinned(struct intel_context *ce)
>  
>  /**
>   * intel_context_is_pinned - Reports the 'pinned' status
> - * @ce - the context
> + * @ce: the context
>   *
>   * While in use by the GPU, the context, along with its ring and page
>   * tables is pinned into memory and the GTT.
> @@ -132,7 +132,7 @@ static inline void intel_context_cancel_request(struct intel_context *ce,
>  
>  /**
>   * intel_context_unlock_pinned - Releases the earlier locking of 'pinned' status
> - * @ce - the context
> + * @ce: the context
>   *
>   * Releases the lock earlier acquired by intel_context_unlock_pinned().
>   */
> diff --git a/drivers/gpu/drm/i915/gt/intel_engine_cs.c b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> index 37fa813af766..da225f5db2a4 100644
> --- a/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> +++ b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> @@ -1197,7 +1197,7 @@ create_kernel_context(struct intel_engine_cs *engine)
>  }
>  
>  /**
> - * intel_engines_init_common - initialize cengine state which might require hw access
> + * engine_init_common - initialize cengine state which might require hw access
>   * @engine: Engine to initialize.
>   *
>   * Initializes @engine@ structure members shared between legacy and execlists
> @@ -1278,7 +1278,7 @@ int intel_engines_init(struct intel_gt *gt)
>  }
>  
>  /**
> - * intel_engines_cleanup_common - cleans up the engine state created by
> + * intel_engine_cleanup_common - cleans up the engine state created by
>   *                                the common initiailizers.
>   * @engine: Engine to cleanup.
>   *
> diff --git a/drivers/gpu/drm/i915/gt/intel_gtt.h b/drivers/gpu/drm/i915/gt/intel_gtt.h
> index e639434e97fd..fca8eedee1d8 100644
> --- a/drivers/gpu/drm/i915/gt/intel_gtt.h
> +++ b/drivers/gpu/drm/i915/gt/intel_gtt.h
> @@ -503,7 +503,7 @@ static inline void i915_vm_put(struct i915_address_space *vm)
>  
>  /**
>   * i915_vm_resv_put - Release a reference on the vm's reservation lock
> - * @resv: Pointer to a reservation lock obtained from i915_vm_resv_get()
> + * @vm: The vm whose reservation lock was obtained from i915_vm_resv_get()
>   */
>  static inline void i915_vm_resv_put(struct i915_address_space *vm)
>  {
> @@ -604,8 +604,8 @@ void i915_ggtt_resume(struct i915_ggtt *ggtt);
>  
>  /**
>   * i915_ggtt_mark_pte_lost - Mark ggtt ptes as lost or clear such a marking
> - * @i915 The device private.
> - * @val whether the ptes should be marked as lost.
> + * @i915: The device private.
> + * @val: whether the ptes should be marked as lost.
>   *
>   * In some cases pte content is retained across suspend, but typically lost
>   * across hibernate. Typically they should be marked as lost on
> diff --git a/drivers/gpu/drm/i915/gt/intel_rps.c b/drivers/gpu/drm/i915/gt/intel_rps.c
> index fb3f57ee450b..8aefc427e06e 100644
> --- a/drivers/gpu/drm/i915/gt/intel_rps.c
> +++ b/drivers/gpu/drm/i915/gt/intel_rps.c
> @@ -2339,8 +2339,8 @@ bool rps_read_mask_mmio(struct intel_rps *rps,
>  static struct drm_i915_private __rcu *ips_mchdev;
>  
>  /**
> - * Tells the intel_ips driver that the i915 driver is now loaded, if
> - * IPS got loaded first.
> + * ips_ping_for_i915_load - Tells the intel_ips driver that the i915 driver
> + *	 is now loaded, if IPS got loaded first.
>   *
>   * This awkward dance is so that neither module has to depend on the
>   * other in order for IPS to do the appropriate communication of
> diff --git a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> index 3624abfd22d1..58f93226b1c1 100644
> --- a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> +++ b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> @@ -12,7 +12,7 @@
>  struct intel_guc;
>  struct file;
>  
> -/**
> +/*
>   * struct __guc_capture_bufstate
>   *
>   * Book-keeping structure used to track read and write pointers
> @@ -26,7 +26,7 @@ struct __guc_capture_bufstate {
>  	u32 wr;
>  };
>  
> -/**
> +/*
>   * struct __guc_capture_parsed_output - extracted error capture node
>   *
>   * A single unit of extracted error-capture output data grouped together
> @@ -58,7 +58,7 @@ struct __guc_capture_parsed_output {
>  #define GCAP_PARSED_REGLIST_INDEX_ENGINST  BIT(GUC_CAPTURE_LIST_TYPE_ENGINE_INSTANCE)
>  };
>  
> -/**
> +/*
>   * struct guc_debug_capture_list_header / struct guc_debug_capture_list
>   *
>   * As part of ADS registration, these header structures (followed by
> @@ -76,7 +76,7 @@ struct guc_debug_capture_list {
>  	struct guc_mmio_reg regs[0];
>  } __packed;
>  
> -/**
> +/*
>   * struct __guc_mmio_reg_descr / struct __guc_mmio_reg_descr_group
>   *
>   * intel_guc_capture module uses these structures to maintain static
> @@ -101,7 +101,7 @@ struct __guc_mmio_reg_descr_group {
>  	struct __guc_mmio_reg_descr *extlist; /* only used for steered registers */
>  };
>  
> -/**
> +/*
>   * struct guc_state_capture_header_t / struct guc_state_capture_t /
>   * guc_state_capture_group_header_t / guc_state_capture_group_t
>   *
> @@ -148,7 +148,7 @@ struct guc_state_capture_group_t {
>  	struct guc_state_capture_t capture_entries[0];
>  } __packed;
>  
> -/**
> +/*
>   * struct __guc_capture_ads_cache

and many more here... :/
Hopefully this great work on the docs will make these ugly
"exported" "__" prefixes visible and we will fix them 

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>

>   *
>   * A structure to cache register lists that were populated and registered
> @@ -162,7 +162,7 @@ struct __guc_capture_ads_cache {
>  	int status;
>  };
>  
> -/**
> +/*
>   * struct intel_guc_state_capture
>   *
>   * Internal context of the intel_guc_capture module.
> diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h b/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h
> index b3c9a9327f76..237019e98ede 100644
> --- a/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h
> +++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h
> @@ -360,7 +360,7 @@ enum guc_log_buffer_type {
>  	GUC_MAX_LOG_BUFFER
>  };
>  
> -/**
> +/*
>   * struct guc_log_buffer_state - GuC log buffer state
>   *
>   * Below state structure is used for coordination of retrieval of GuC firmware
> -- 
> 2.36.1
>
Mauro Carvalho Chehab July 14, 2022, 10:01 a.m. UTC | #2
On Wed, 13 Jul 2022 18:07:44 -0400
Rodrigo Vivi <rodrigo.vivi@intel.com> wrote:

> On Wed, Jul 13, 2022 at 09:11:54AM +0100, Mauro Carvalho Chehab wrote:
> > There are several trivial warnings there, due to trivial things:
> > 	- lack of function name at the kerneldoc markup;
> > 	- undocumented structs with kernel-doc markups;
> > 	- wrong parameter syntax.
> > 
> >     Fix such warnings:
> > 
> > 	drivers/gpu/drm/i915/gt/intel_context.h:107: warning: Function parameter or member 'ce' not described in 'intel_context_lock_pinned'
> > 	drivers/gpu/drm/i915/gt/intel_context.h:122: warning: Function parameter or member 'ce' not described in 'intel_context_is_pinned'
> > 	drivers/gpu/drm/i915/gt/intel_context.h:141: warning: Function parameter or member 'ce' not described in 'intel_context_unlock_pinned'
> > 	drivers/gpu/drm/i915/gt/intel_gtt.h:510: warning: Function parameter or member 'vm' not described in 'i915_vm_resv_put'
> > 	drivers/gpu/drm/i915/gt/intel_gtt.h:510: warning: Excess function parameter 'resv' description in 'i915_vm_resv_put'
> > 	drivers/gpu/drm/i915/gt/intel_gtt.h:615: warning: Function parameter or member 'i915' not described in 'i915_ggtt_mark_pte_lost'
> > 	drivers/gpu/drm/i915/gt/intel_gtt.h:615: warning: Function parameter or member 'val' not described in 'i915_ggtt_mark_pte_lost'
> > 	drivers/gpu/drm/i915/gt/intel_rps.c:2343: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> > 	 * Tells the intel_ips driver that the i915 driver is now loaded, if
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'size' not described in '__guc_capture_bufstate'
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'data' not described in '__guc_capture_bufstate'
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'rd' not described in '__guc_capture_bufstate'
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'wr' not described in '__guc_capture_bufstate'
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'link' not described in '__guc_capture_parsed_output'
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'is_partial' not described in '__guc_capture_parsed_output'
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'eng_class' not described in '__guc_capture_parsed_output'
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'eng_inst' not described in '__guc_capture_parsed_output'
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'guc_id' not described in '__guc_capture_parsed_output'
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'lrca' not described in '__guc_capture_parsed_output'
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'reginfo' not described in '__guc_capture_parsed_output'
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:63: warning: wrong kernel-doc identifier on line:
> > 	 * struct guc_debug_capture_list_header / struct guc_debug_capture_list
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:81: warning: wrong kernel-doc identifier on line:
> > 	 * struct __guc_mmio_reg_descr / struct __guc_mmio_reg_descr_group
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:106: warning: wrong kernel-doc identifier on line:
> > 	 * struct guc_state_capture_header_t / struct guc_state_capture_t /
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'is_valid' not described in '__guc_capture_ads_cache'
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'ptr' not described in '__guc_capture_ads_cache'
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'size' not described in '__guc_capture_ads_cache'
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'status' not described in '__guc_capture_ads_cache'
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:217: warning: Function parameter or member 'ads_null_cache' not described in 'intel_guc_state_capture'
> > 	drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:217: warning: Function parameter or member 'max_mmio_per_node' not described in 'intel_guc_state_capture'
> > 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'marker' not described in 'guc_log_buffer_state'
> > 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'read_ptr' not described in 'guc_log_buffer_state'
> > 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'write_ptr' not described in 'guc_log_buffer_state'
> > 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'size' not described in 'guc_log_buffer_state'
> > 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'sampled_write_ptr' not described in 'guc_log_buffer_state'
> > 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'wrap_offset' not described in 'guc_log_buffer_state'
> > 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'flush_to_file' not described in 'guc_log_buffer_state'
> > 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'buffer_full_cnt' not described in 'guc_log_buffer_state'
> > 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'reserved' not described in 'guc_log_buffer_state'
> > 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'flags' not described in 'guc_log_buffer_state'
> > 	drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'version' not described in 'guc_log_buffer_state'
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> > ---
> > 
> > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> > See [PATCH v2 00/39] at: https://lore.kernel.org/all/cover.1657699522.git.mchehab@kernel.org/
> > 
> >  drivers/gpu/drm/i915/gt/intel_context.h       |  6 +++---
> >  drivers/gpu/drm/i915/gt/intel_engine_cs.c     |  4 ++--
> >  drivers/gpu/drm/i915/gt/intel_gtt.h           |  6 +++---
> >  drivers/gpu/drm/i915/gt/intel_rps.c           |  4 ++--
> >  drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h | 14 +++++++-------
> >  drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h   |  2 +-
> >  6 files changed, 18 insertions(+), 18 deletions(-)
> > 
> > diff --git a/drivers/gpu/drm/i915/gt/intel_context.h b/drivers/gpu/drm/i915/gt/intel_context.h
> > index 8e2d70630c49..91c092d5deae 100644
> > --- a/drivers/gpu/drm/i915/gt/intel_context.h
> > +++ b/drivers/gpu/drm/i915/gt/intel_context.h
> > @@ -96,7 +96,7 @@ void intel_context_bind_parent_child(struct intel_context *parent,
> >  
> >  /**
> >   * intel_context_lock_pinned - Stablises the 'pinned' status of the HW context
> > - * @ce - the context
> > + * @ce: the context
> >   *
> >   * Acquire a lock on the pinned status of the HW context, such that the context
> >   * can neither be bound to the GPU or unbound whilst the lock is held, i.e.
> > @@ -110,7 +110,7 @@ static inline int intel_context_lock_pinned(struct intel_context *ce)
> >  
> >  /**
> >   * intel_context_is_pinned - Reports the 'pinned' status
> > - * @ce - the context
> > + * @ce: the context
> >   *
> >   * While in use by the GPU, the context, along with its ring and page
> >   * tables is pinned into memory and the GTT.
> > @@ -132,7 +132,7 @@ static inline void intel_context_cancel_request(struct intel_context *ce,
> >  
> >  /**
> >   * intel_context_unlock_pinned - Releases the earlier locking of 'pinned' status
> > - * @ce - the context
> > + * @ce: the context
> >   *
> >   * Releases the lock earlier acquired by intel_context_unlock_pinned().
> >   */
> > diff --git a/drivers/gpu/drm/i915/gt/intel_engine_cs.c b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> > index 37fa813af766..da225f5db2a4 100644
> > --- a/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> > +++ b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> > @@ -1197,7 +1197,7 @@ create_kernel_context(struct intel_engine_cs *engine)
> >  }
> >  
> >  /**
> > - * intel_engines_init_common - initialize cengine state which might require hw access
> > + * engine_init_common - initialize cengine state which might require hw access
> >   * @engine: Engine to initialize.
> >   *
> >   * Initializes @engine@ structure members shared between legacy and execlists
> > @@ -1278,7 +1278,7 @@ int intel_engines_init(struct intel_gt *gt)
> >  }
> >  
> >  /**
> > - * intel_engines_cleanup_common - cleans up the engine state created by
> > + * intel_engine_cleanup_common - cleans up the engine state created by
> >   *                                the common initiailizers.
> >   * @engine: Engine to cleanup.
> >   *
> > diff --git a/drivers/gpu/drm/i915/gt/intel_gtt.h b/drivers/gpu/drm/i915/gt/intel_gtt.h
> > index e639434e97fd..fca8eedee1d8 100644
> > --- a/drivers/gpu/drm/i915/gt/intel_gtt.h
> > +++ b/drivers/gpu/drm/i915/gt/intel_gtt.h
> > @@ -503,7 +503,7 @@ static inline void i915_vm_put(struct i915_address_space *vm)
> >  
> >  /**
> >   * i915_vm_resv_put - Release a reference on the vm's reservation lock
> > - * @resv: Pointer to a reservation lock obtained from i915_vm_resv_get()
> > + * @vm: The vm whose reservation lock was obtained from i915_vm_resv_get()
> >   */
> >  static inline void i915_vm_resv_put(struct i915_address_space *vm)
> >  {
> > @@ -604,8 +604,8 @@ void i915_ggtt_resume(struct i915_ggtt *ggtt);
> >  
> >  /**
> >   * i915_ggtt_mark_pte_lost - Mark ggtt ptes as lost or clear such a marking
> > - * @i915 The device private.
> > - * @val whether the ptes should be marked as lost.
> > + * @i915: The device private.
> > + * @val: whether the ptes should be marked as lost.
> >   *
> >   * In some cases pte content is retained across suspend, but typically lost
> >   * across hibernate. Typically they should be marked as lost on
> > diff --git a/drivers/gpu/drm/i915/gt/intel_rps.c b/drivers/gpu/drm/i915/gt/intel_rps.c
> > index fb3f57ee450b..8aefc427e06e 100644
> > --- a/drivers/gpu/drm/i915/gt/intel_rps.c
> > +++ b/drivers/gpu/drm/i915/gt/intel_rps.c
> > @@ -2339,8 +2339,8 @@ bool rps_read_mask_mmio(struct intel_rps *rps,
> >  static struct drm_i915_private __rcu *ips_mchdev;
> >  
> >  /**
> > - * Tells the intel_ips driver that the i915 driver is now loaded, if
> > - * IPS got loaded first.
> > + * ips_ping_for_i915_load - Tells the intel_ips driver that the i915 driver
> > + *	 is now loaded, if IPS got loaded first.
> >   *
> >   * This awkward dance is so that neither module has to depend on the
> >   * other in order for IPS to do the appropriate communication of
> > diff --git a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> > index 3624abfd22d1..58f93226b1c1 100644
> > --- a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> > +++ b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> > @@ -12,7 +12,7 @@
> >  struct intel_guc;
> >  struct file;
> >  
> > -/**
> > +/*
> >   * struct __guc_capture_bufstate
> >   *
> >   * Book-keeping structure used to track read and write pointers
> > @@ -26,7 +26,7 @@ struct __guc_capture_bufstate {
> >  	u32 wr;
> >  };
> >  
> > -/**
> > +/*
> >   * struct __guc_capture_parsed_output - extracted error capture node
> >   *
> >   * A single unit of extracted error-capture output data grouped together
> > @@ -58,7 +58,7 @@ struct __guc_capture_parsed_output {
> >  #define GCAP_PARSED_REGLIST_INDEX_ENGINST  BIT(GUC_CAPTURE_LIST_TYPE_ENGINE_INSTANCE)
> >  };
> >  
> > -/**
> > +/*
> >   * struct guc_debug_capture_list_header / struct guc_debug_capture_list
> >   *
> >   * As part of ADS registration, these header structures (followed by
> > @@ -76,7 +76,7 @@ struct guc_debug_capture_list {
> >  	struct guc_mmio_reg regs[0];
> >  } __packed;
> >  
> > -/**
> > +/*
> >   * struct __guc_mmio_reg_descr / struct __guc_mmio_reg_descr_group
> >   *
> >   * intel_guc_capture module uses these structures to maintain static
> > @@ -101,7 +101,7 @@ struct __guc_mmio_reg_descr_group {
> >  	struct __guc_mmio_reg_descr *extlist; /* only used for steered registers */
> >  };
> >  
> > -/**
> > +/*
> >   * struct guc_state_capture_header_t / struct guc_state_capture_t /
> >   * guc_state_capture_group_header_t / guc_state_capture_group_t
> >   *
> > @@ -148,7 +148,7 @@ struct guc_state_capture_group_t {
> >  	struct guc_state_capture_t capture_entries[0];
> >  } __packed;
> >  
> > -/**
> > +/*
> >   * struct __guc_capture_ads_cache  
> 
> and many more here... :/
> Hopefully this great work on the docs will make these ugly
> "exported" "__" prefixes visible and we will fix them 

Yeah, while I can see why __function would be ok on some cases
(like for lock/unlock variants and on some special macros like the ones
that use THIS_MODULE), I can't see any reason why struct/enum/union 
would ever need to have __ prefixes on it ;-)

> Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>

Thanks!

Regards,
Mauro
diff mbox series

Patch

diff --git a/drivers/gpu/drm/i915/gt/intel_context.h b/drivers/gpu/drm/i915/gt/intel_context.h
index 8e2d70630c49..91c092d5deae 100644
--- a/drivers/gpu/drm/i915/gt/intel_context.h
+++ b/drivers/gpu/drm/i915/gt/intel_context.h
@@ -96,7 +96,7 @@  void intel_context_bind_parent_child(struct intel_context *parent,
 
 /**
  * intel_context_lock_pinned - Stablises the 'pinned' status of the HW context
- * @ce - the context
+ * @ce: the context
  *
  * Acquire a lock on the pinned status of the HW context, such that the context
  * can neither be bound to the GPU or unbound whilst the lock is held, i.e.
@@ -110,7 +110,7 @@  static inline int intel_context_lock_pinned(struct intel_context *ce)
 
 /**
  * intel_context_is_pinned - Reports the 'pinned' status
- * @ce - the context
+ * @ce: the context
  *
  * While in use by the GPU, the context, along with its ring and page
  * tables is pinned into memory and the GTT.
@@ -132,7 +132,7 @@  static inline void intel_context_cancel_request(struct intel_context *ce,
 
 /**
  * intel_context_unlock_pinned - Releases the earlier locking of 'pinned' status
- * @ce - the context
+ * @ce: the context
  *
  * Releases the lock earlier acquired by intel_context_unlock_pinned().
  */
diff --git a/drivers/gpu/drm/i915/gt/intel_engine_cs.c b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
index 37fa813af766..da225f5db2a4 100644
--- a/drivers/gpu/drm/i915/gt/intel_engine_cs.c
+++ b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
@@ -1197,7 +1197,7 @@  create_kernel_context(struct intel_engine_cs *engine)
 }
 
 /**
- * intel_engines_init_common - initialize cengine state which might require hw access
+ * engine_init_common - initialize cengine state which might require hw access
  * @engine: Engine to initialize.
  *
  * Initializes @engine@ structure members shared between legacy and execlists
@@ -1278,7 +1278,7 @@  int intel_engines_init(struct intel_gt *gt)
 }
 
 /**
- * intel_engines_cleanup_common - cleans up the engine state created by
+ * intel_engine_cleanup_common - cleans up the engine state created by
  *                                the common initiailizers.
  * @engine: Engine to cleanup.
  *
diff --git a/drivers/gpu/drm/i915/gt/intel_gtt.h b/drivers/gpu/drm/i915/gt/intel_gtt.h
index e639434e97fd..fca8eedee1d8 100644
--- a/drivers/gpu/drm/i915/gt/intel_gtt.h
+++ b/drivers/gpu/drm/i915/gt/intel_gtt.h
@@ -503,7 +503,7 @@  static inline void i915_vm_put(struct i915_address_space *vm)
 
 /**
  * i915_vm_resv_put - Release a reference on the vm's reservation lock
- * @resv: Pointer to a reservation lock obtained from i915_vm_resv_get()
+ * @vm: The vm whose reservation lock was obtained from i915_vm_resv_get()
  */
 static inline void i915_vm_resv_put(struct i915_address_space *vm)
 {
@@ -604,8 +604,8 @@  void i915_ggtt_resume(struct i915_ggtt *ggtt);
 
 /**
  * i915_ggtt_mark_pte_lost - Mark ggtt ptes as lost or clear such a marking
- * @i915 The device private.
- * @val whether the ptes should be marked as lost.
+ * @i915: The device private.
+ * @val: whether the ptes should be marked as lost.
  *
  * In some cases pte content is retained across suspend, but typically lost
  * across hibernate. Typically they should be marked as lost on
diff --git a/drivers/gpu/drm/i915/gt/intel_rps.c b/drivers/gpu/drm/i915/gt/intel_rps.c
index fb3f57ee450b..8aefc427e06e 100644
--- a/drivers/gpu/drm/i915/gt/intel_rps.c
+++ b/drivers/gpu/drm/i915/gt/intel_rps.c
@@ -2339,8 +2339,8 @@  bool rps_read_mask_mmio(struct intel_rps *rps,
 static struct drm_i915_private __rcu *ips_mchdev;
 
 /**
- * Tells the intel_ips driver that the i915 driver is now loaded, if
- * IPS got loaded first.
+ * ips_ping_for_i915_load - Tells the intel_ips driver that the i915 driver
+ *	 is now loaded, if IPS got loaded first.
  *
  * This awkward dance is so that neither module has to depend on the
  * other in order for IPS to do the appropriate communication of
diff --git a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
index 3624abfd22d1..58f93226b1c1 100644
--- a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
+++ b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
@@ -12,7 +12,7 @@ 
 struct intel_guc;
 struct file;
 
-/**
+/*
  * struct __guc_capture_bufstate
  *
  * Book-keeping structure used to track read and write pointers
@@ -26,7 +26,7 @@  struct __guc_capture_bufstate {
 	u32 wr;
 };
 
-/**
+/*
  * struct __guc_capture_parsed_output - extracted error capture node
  *
  * A single unit of extracted error-capture output data grouped together
@@ -58,7 +58,7 @@  struct __guc_capture_parsed_output {
 #define GCAP_PARSED_REGLIST_INDEX_ENGINST  BIT(GUC_CAPTURE_LIST_TYPE_ENGINE_INSTANCE)
 };
 
-/**
+/*
  * struct guc_debug_capture_list_header / struct guc_debug_capture_list
  *
  * As part of ADS registration, these header structures (followed by
@@ -76,7 +76,7 @@  struct guc_debug_capture_list {
 	struct guc_mmio_reg regs[0];
 } __packed;
 
-/**
+/*
  * struct __guc_mmio_reg_descr / struct __guc_mmio_reg_descr_group
  *
  * intel_guc_capture module uses these structures to maintain static
@@ -101,7 +101,7 @@  struct __guc_mmio_reg_descr_group {
 	struct __guc_mmio_reg_descr *extlist; /* only used for steered registers */
 };
 
-/**
+/*
  * struct guc_state_capture_header_t / struct guc_state_capture_t /
  * guc_state_capture_group_header_t / guc_state_capture_group_t
  *
@@ -148,7 +148,7 @@  struct guc_state_capture_group_t {
 	struct guc_state_capture_t capture_entries[0];
 } __packed;
 
-/**
+/*
  * struct __guc_capture_ads_cache
  *
  * A structure to cache register lists that were populated and registered
@@ -162,7 +162,7 @@  struct __guc_capture_ads_cache {
 	int status;
 };
 
-/**
+/*
  * struct intel_guc_state_capture
  *
  * Internal context of the intel_guc_capture module.
diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h b/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h
index b3c9a9327f76..237019e98ede 100644
--- a/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h
+++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h
@@ -360,7 +360,7 @@  enum guc_log_buffer_type {
 	GUC_MAX_LOG_BUFFER
 };
 
-/**
+/*
  * struct guc_log_buffer_state - GuC log buffer state
  *
  * Below state structure is used for coordination of retrieval of GuC firmware