Re: [Intel-gfx] [PATCH v2 14/39] drm/i915: document kernel-doc trivial issues
On Wed, Jul 13, 2022 at 09:12:02AM +0100, Mauro Carvalho Chehab wrote:
> Fix those kernel-doc warnings:
> drivers/gpu/drm/i915/intel_region_ttm.c:199: warning: Function
> parameter or member 'offset' not described in
> 'intel_region_ttm_resource_alloc'
> drivers/gpu/drm/i915/i915_vma_resource.h:123: warning: Function
> parameter or member 'wakeref' not described in 'i915_vma_resource'
> drivers/gpu/drm/i915/i915_vma.c:1703: warning: Function parameter or
> member 'vma' not described in 'i915_vma_destroy_locked'
> drivers/gpu/drm/i915/i915_vma.c:751: warning: Function parameter or
> member 'ww' not described in 'i915_vma_insert'
> drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:159: warning: Function
> parameter or member 'gt' not described in 'intel_gt_fini_hwconfig'
> drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:146: warning: Function
> parameter or member 'gt' not described in 'intel_gt_init_hwconfig'
> drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:113: warning: expecting
> prototype for intel_guc_hwconfig_init(). Prototype was for
> guc_hwconfig_init() instead
> drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:113: warning: Function
> parameter or member 'gt' not described in 'guc_hwconfig_init'
> drivers/gpu/drm/i915/gt/intel_engine_types.h:276: warning: Function
> parameter or member 'preempt_hang' not described in 'intel_engine_execlists'
>
> That are due undocumented parameters.
>
> Signed-off-by: Mauro Carvalho Chehab
Reviewed-by: Rodrigo Vivi
> ---
>
> 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.mche...@kernel.org/
>
> drivers/gpu/drm/i915/gt/intel_engine_types.h| 1 +
> drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c | 5 -
> drivers/gpu/drm/i915/i915_vma.c | 2 ++
> drivers/gpu/drm/i915/i915_vma_resource.h| 1 +
> drivers/gpu/drm/i915/intel_region_ttm.c | 3 ++-
> 5 files changed, 10 insertions(+), 2 deletions(-)
>
> diff --git a/drivers/gpu/drm/i915/gt/intel_engine_types.h
> b/drivers/gpu/drm/i915/gt/intel_engine_types.h
> index 633a7e5dba3b..7c5ad9071fe7 100644
> --- a/drivers/gpu/drm/i915/gt/intel_engine_types.h
> +++ b/drivers/gpu/drm/i915/gt/intel_engine_types.h
> @@ -271,6 +271,7 @@ struct intel_engine_execlists {
>*/
> u8 csb_head;
>
> + /* private: Used only in selftests */
> I915_SELFTEST_DECLARE(struct st_preempt_hang preempt_hang;)
> };
>
> diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
> b/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
> index 4781fccc2687..76f7447302a6 100644
> --- a/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
> +++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
> @@ -103,7 +103,8 @@ static bool has_table(struct drm_i915_private *i915)
> }
>
> /**
> - * intel_guc_hwconfig_init - Initialize the HWConfig
> + * guc_hwconfig_init - Initialize the HWConfig
> + * @gt: GT structure
> *
> * Retrieve the HWConfig table from the GuC and save it locally.
> * It can then be queried on demand by other users later on.
> @@ -138,6 +139,7 @@ static int guc_hwconfig_init(struct intel_gt *gt)
>
> /**
> * intel_gt_init_hwconfig - Initialize the HWConfig if available
> + * @gt: GT structure
> *
> * Retrieve the HWConfig table if available on the current platform.
> */
> @@ -151,6 +153,7 @@ int intel_gt_init_hwconfig(struct intel_gt *gt)
>
> /**
> * intel_gt_fini_hwconfig - Finalize the HWConfig
> + * @gt: GT structure
> *
> * Free up the memory allocation holding the table.
> */
> diff --git a/drivers/gpu/drm/i915/i915_vma.c b/drivers/gpu/drm/i915/i915_vma.c
> index ef3b04c7e153..ddf348c597b0 100644
> --- a/drivers/gpu/drm/i915/i915_vma.c
> +++ b/drivers/gpu/drm/i915/i915_vma.c
> @@ -733,6 +733,7 @@ bool i915_gem_valid_gtt_space(struct i915_vma *vma,
> unsigned long color)
> /**
> * i915_vma_insert - finds a slot for the vma in its address space
> * @vma: the vma
> + * @ww: An optional struct i915_gem_ww_ctx
> * @size: requested size in bytes (can be larger than the VMA)
> * @alignment: required alignment
> * @flags: mask of PIN_* flags to use
> @@ -1675,6 +1676,7 @@ static void release_references(struct i915_vma *vma,
> struct intel_gt *gt,
> /**
> * i915_vma_destroy_locked - Remove all weak reference to the vma and put
> * the initial reference.
> + * @vma: VMA to destroy
> *
> * This function should be called when it's decided the vma isn't needed
> * anymore. The caller must assure that it doesn't race with another lookup
> diff --git a/drivers/gpu/drm/i915/i915_vma_resource.h
> b/drivers/gpu/drm/i915/i915_vma_resource.h
> index 14a0327b2080..a15271d96b7e 100644
> --- a/drivers/gpu/drm/i915/i915_vma_resource.h
> +++ b/drivers/gpu/drm/i915/i915_vma_resource.h
> @@ -49,6 +49,7 @@ struct i915_page_sizes {
> * @__subtree_last:
[Intel-gfx] [PATCH v2 14/39] drm/i915: document kernel-doc trivial issues
Fix those kernel-doc warnings:
drivers/gpu/drm/i915/intel_region_ttm.c:199: warning: Function
parameter or member 'offset' not described in 'intel_region_ttm_resource_alloc'
drivers/gpu/drm/i915/i915_vma_resource.h:123: warning: Function
parameter or member 'wakeref' not described in 'i915_vma_resource'
drivers/gpu/drm/i915/i915_vma.c:1703: warning: Function parameter or
member 'vma' not described in 'i915_vma_destroy_locked'
drivers/gpu/drm/i915/i915_vma.c:751: warning: Function parameter or
member 'ww' not described in 'i915_vma_insert'
drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:159: warning: Function
parameter or member 'gt' not described in 'intel_gt_fini_hwconfig'
drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:146: warning: Function
parameter or member 'gt' not described in 'intel_gt_init_hwconfig'
drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:113: warning: expecting
prototype for intel_guc_hwconfig_init(). Prototype was for guc_hwconfig_init()
instead
drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:113: warning: Function
parameter or member 'gt' not described in 'guc_hwconfig_init'
drivers/gpu/drm/i915/gt/intel_engine_types.h:276: warning: Function
parameter or member 'preempt_hang' not described in 'intel_engine_execlists'
That are due undocumented parameters.
Signed-off-by: Mauro Carvalho Chehab
---
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.mche...@kernel.org/
drivers/gpu/drm/i915/gt/intel_engine_types.h| 1 +
drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c | 5 -
drivers/gpu/drm/i915/i915_vma.c | 2 ++
drivers/gpu/drm/i915/i915_vma_resource.h| 1 +
drivers/gpu/drm/i915/intel_region_ttm.c | 3 ++-
5 files changed, 10 insertions(+), 2 deletions(-)
diff --git a/drivers/gpu/drm/i915/gt/intel_engine_types.h
b/drivers/gpu/drm/i915/gt/intel_engine_types.h
index 633a7e5dba3b..7c5ad9071fe7 100644
--- a/drivers/gpu/drm/i915/gt/intel_engine_types.h
+++ b/drivers/gpu/drm/i915/gt/intel_engine_types.h
@@ -271,6 +271,7 @@ struct intel_engine_execlists {
*/
u8 csb_head;
+ /* private: Used only in selftests */
I915_SELFTEST_DECLARE(struct st_preempt_hang preempt_hang;)
};
diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
b/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
index 4781fccc2687..76f7447302a6 100644
--- a/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
+++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
@@ -103,7 +103,8 @@ static bool has_table(struct drm_i915_private *i915)
}
/**
- * intel_guc_hwconfig_init - Initialize the HWConfig
+ * guc_hwconfig_init - Initialize the HWConfig
+ * @gt: GT structure
*
* Retrieve the HWConfig table from the GuC and save it locally.
* It can then be queried on demand by other users later on.
@@ -138,6 +139,7 @@ static int guc_hwconfig_init(struct intel_gt *gt)
/**
* intel_gt_init_hwconfig - Initialize the HWConfig if available
+ * @gt: GT structure
*
* Retrieve the HWConfig table if available on the current platform.
*/
@@ -151,6 +153,7 @@ int intel_gt_init_hwconfig(struct intel_gt *gt)
/**
* intel_gt_fini_hwconfig - Finalize the HWConfig
+ * @gt: GT structure
*
* Free up the memory allocation holding the table.
*/
diff --git a/drivers/gpu/drm/i915/i915_vma.c b/drivers/gpu/drm/i915/i915_vma.c
index ef3b04c7e153..ddf348c597b0 100644
--- a/drivers/gpu/drm/i915/i915_vma.c
+++ b/drivers/gpu/drm/i915/i915_vma.c
@@ -733,6 +733,7 @@ bool i915_gem_valid_gtt_space(struct i915_vma *vma,
unsigned long color)
/**
* i915_vma_insert - finds a slot for the vma in its address space
* @vma: the vma
+ * @ww: An optional struct i915_gem_ww_ctx
* @size: requested size in bytes (can be larger than the VMA)
* @alignment: required alignment
* @flags: mask of PIN_* flags to use
@@ -1675,6 +1676,7 @@ static void release_references(struct i915_vma *vma,
struct intel_gt *gt,
/**
* i915_vma_destroy_locked - Remove all weak reference to the vma and put
* the initial reference.
+ * @vma: VMA to destroy
*
* This function should be called when it's decided the vma isn't needed
* anymore. The caller must assure that it doesn't race with another lookup
diff --git a/drivers/gpu/drm/i915/i915_vma_resource.h
b/drivers/gpu/drm/i915/i915_vma_resource.h
index 14a0327b2080..a15271d96b7e 100644
--- a/drivers/gpu/drm/i915/i915_vma_resource.h
+++ b/drivers/gpu/drm/i915/i915_vma_resource.h
@@ -49,6 +49,7 @@ struct i915_page_sizes {
* @__subtree_last: Interval tree private member.
* @vm: non-refcounted pointer to the vm. This is for internal use only and
* this member is cleared after vm_resource unbind.
+ * @wakeref: wakeref used for runtime PM reference.
* @mr: The memory region of the object pointed to by the vma.
* @ops: Pointer to the
