[Intel-gfx] [PATCH 00/24] drm/i915: fix kernel-doc warnings, enable kernel-doc -Werror

[Intel-gfx] [PATCH 00/24] drm/i915: fix kernel-doc warnings, enable kernel-doc -Werror

[Jani Nikula]

Fix all the remaining kernel-doc warnings, and enable -Werror for
kernel-doc.

Jani Nikula (24):
  drm/i915/gvt: fix intel_vgpu_alloc_resource() kernel-doc parameter
  drm/i915/vma: fix kernel-doc function name for i915_vma_size()
  drm/i915/utils: drop kernel-doc from __wait_for()
  drm/i915/vma: document struct i915_vma_resource wakeref member
  drm/i915/vma: fix struct i915_vma_bindinfo kernel-doc
  drm/i915/perf: fix i915_perf_ioctl_version() kernel-doc
  drm/i915/error: fix i915_capture_error_state() kernel-doc
  drm/i915/request: drop kernel-doc
  drm/i915/gem: fix i915_gem_object_lookup_rcu() kernel-doc parameter
    name
  drm/i915/gem: fix function pointer member kernel-doc
  drm/i915/ttm: fix i915_ttm_to_gem() kernel-doc
  drm/i915/engine: fix kernel-doc function name for
    intel_engine_cleanup_common()
  drm/i915/context: fix kernel-doc parameter descriptions
  drm/i915/gtt: fix i915_vm_resv_put() kernel-doc parameter name
  drm/i915/engine: hide preempt_hang selftest member from kernel-doc
  drm/i915/guc: add dbgfs_node member kernel-doc
  drm/i915/guc: drop lots of kernel-doc markers
  drm/i915/guc: add intel_guc_state_capture member docs for
    ads_null_cache and max_mmio_per_node
  drm/i915/active: fix kernel-doc for function parameters
  drm/i915/pmu: drop kernel-doc
  drm/i915/pxp: fix kernel-doc for member dev_link
  drm/i915/scatterlist: fix kernel-doc
  drm/i915/scatterlist: fix kernel-doc parameter documentation
  drm/i915: use kernel-doc -Werror when CONFIG_DRM_I915_WERROR=y

 drivers/gpu/drm/i915/Makefile                 |  4 +-
 drivers/gpu/drm/i915/gem/i915_gem_object.h    |  2 +-
 drivers/gpu/drm/i915/gem/i915_gem_region.h    |  4 +-
 drivers/gpu/drm/i915/gem/i915_gem_ttm.h       |  1 +
 drivers/gpu/drm/i915/gt/intel_context.h       |  6 +--
 drivers/gpu/drm/i915/gt/intel_engine_cs.c     |  2 +-
 drivers/gpu/drm/i915/gt/intel_engine_types.h  |  1 +
 drivers/gpu/drm/i915/gt/intel_gtt.h           |  2 +-
 drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h | 20 ++++---
 drivers/gpu/drm/i915/gt/uc/intel_guc.h        |  1 +
 drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h   |  2 +-
 drivers/gpu/drm/i915/gvt/aperture_gm.c        |  2 +-
 drivers/gpu/drm/i915/i915_active.h            | 14 ++---
 drivers/gpu/drm/i915/i915_gpu_error.c         |  2 +-
 drivers/gpu/drm/i915/i915_perf.c              |  1 +
 drivers/gpu/drm/i915/i915_pmu.h               |  6 +--
 drivers/gpu/drm/i915/i915_request.h           | 52 +++++++++----------
 drivers/gpu/drm/i915/i915_scatterlist.h       |  9 ++--
 drivers/gpu/drm/i915/i915_utils.h             |  2 +-
 drivers/gpu/drm/i915/i915_vma.h               |  2 +-
 drivers/gpu/drm/i915/i915_vma_resource.h      | 46 +++++++++-------
 drivers/gpu/drm/i915/pxp/intel_pxp_types.h    |  4 +-
 22 files changed, 103 insertions(+), 82 deletions(-)

-- 
2.39.2

[Intel-gfx] [PATCH 01/24] drm/i915/gvt: fix intel_vgpu_alloc_resource() kernel-doc parameter

[Jani Nikula]

drivers/gpu/drm/i915/gvt/aperture_gm.c:344: warning: Function parameter or member 'conf' not described in 'intel_vgpu_alloc_resource'
drivers/gpu/drm/i915/gvt/aperture_gm.c:344: warning: Excess function parameter 'param' description in 'intel_vgpu_alloc_resource'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/gvt/aperture_gm.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/gvt/aperture_gm.c b/drivers/gpu/drm/i915/gvt/aperture_gm.c
index 076c779f776a..eedd1865bb98 100644
--- a/drivers/gpu/drm/i915/gvt/aperture_gm.c
+++ b/drivers/gpu/drm/i915/gvt/aperture_gm.c
@@ -330,7 +330,7 @@ void intel_vgpu_reset_resource(struct intel_vgpu *vgpu)
 /**
  * intel_vgpu_alloc_resource() - allocate HW resource for a vGPU
  * @vgpu: vGPU
- * @param: vGPU creation params
+ * @conf: vGPU creation params
  *
  * This function is used to allocate HW resource for a vGPU. User specifies
  * the resource configuration through the creation params.
-- 
2.39.2

[Intel-gfx] [PATCH 02/24] drm/i915/vma: fix kernel-doc function name for i915_vma_size()

[Jani Nikula]

drivers/gpu/drm/i915/i915_vma.h:145: warning: expecting prototype for i915_vma_offset(). Prototype was for i915_vma_size() instead

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/i915_vma.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/i915_vma.h b/drivers/gpu/drm/i915/i915_vma.h
index ed5c9d682a1b..38c8c66ed724 100644
--- a/drivers/gpu/drm/i915/i915_vma.h
+++ b/drivers/gpu/drm/i915/i915_vma.h
@@ -132,7 +132,7 @@ static inline u64 __i915_vma_size(const struct i915_vma *vma)
 }
 
 /**
- * i915_vma_offset - Obtain the va range size of the vma
+ * i915_vma_size - Obtain the va range size of the vma
  * @vma: The vma
  *
  * GPU virtual address space may be allocated with padding. This
-- 
2.39.2

[Intel-gfx] [PATCH 03/24] drm/i915/utils: drop kernel-doc from __wait_for()

[Jani Nikula]

The parameters aren't documented, and the file isn't included in Sphinx
build anyway, so demote the kernel-doc to a regular comment.

drivers/gpu/drm/i915/i915_utils.h:284: warning: Function parameter or member 'OP' not described in '__wait_for'
drivers/gpu/drm/i915/i915_utils.h:284: warning: Function parameter or member 'COND' not described in '__wait_for'
drivers/gpu/drm/i915/i915_utils.h:284: warning: Function parameter or member 'US' not described in '__wait_for'
drivers/gpu/drm/i915/i915_utils.h:284: warning: Function parameter or member 'Wmin' not described in '__wait_for'
drivers/gpu/drm/i915/i915_utils.h:284: warning: Function parameter or member 'Wmax' not described in '__wait_for'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/i915_utils.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/i915_utils.h b/drivers/gpu/drm/i915/i915_utils.h
index 2c430c0c3bad..c61066498bf2 100644
--- a/drivers/gpu/drm/i915/i915_utils.h
+++ b/drivers/gpu/drm/i915/i915_utils.h
@@ -250,7 +250,7 @@ wait_remaining_ms_from_jiffies(unsigned long timestamp_jiffies, int to_wait_ms)
 	}
 }
 
-/**
+/*
  * __wait_for - magic wait macro
  *
  * Macro to help avoid open coding check/wait/timeout patterns. Note that it's
-- 
2.39.2

[Intel-gfx] [PATCH 04/24] drm/i915/vma: document struct i915_vma_resource wakeref member

[Jani Nikula]

drivers/gpu/drm/i915/i915_vma_resource.h:129: warning: Function parameter or member 'wakeref' not described in 'i915_vma_resource'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/i915_vma_resource.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/drivers/gpu/drm/i915/i915_vma_resource.h b/drivers/gpu/drm/i915/i915_vma_resource.h
index c1864e3d0b43..2053c037dbfb 100644
--- a/drivers/gpu/drm/i915/i915_vma_resource.h
+++ b/drivers/gpu/drm/i915/i915_vma_resource.h
@@ -47,6 +47,7 @@ struct i915_page_sizes {
  * @chain: Pointer to struct i915_sw_fence used to await dependencies.
  * @rb: Rb node for the vm's pending unbind interval tree.
  * @__subtree_last: Interval tree private member.
+ * @wakeref: wakeref.
  * @vm: non-refcounted pointer to the vm. This is for internal use only and
  * this member is cleared after vm_resource unbind.
  * @mr: The memory region of the object pointed to by the vma.
-- 
2.39.2

[Intel-gfx] [PATCH 05/24] drm/i915/vma: fix struct i915_vma_bindinfo kernel-doc

[Jani Nikula]

You can't document both a sub-struct type and a struct member at the
same time. Separate them.

drivers/gpu/drm/i915/i915_vma_resource.h:91: warning: Incorrect use of kernel-doc format:          * struct i915_vma_bindinfo - Information needed for async bind
drivers/gpu/drm/i915/i915_vma_resource.h:129: warning: Function parameter or member 'bi' not described in 'i915_vma_resource'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/i915_vma_resource.h | 45 ++++++++++++++----------
 1 file changed, 27 insertions(+), 18 deletions(-)

diff --git a/drivers/gpu/drm/i915/i915_vma_resource.h b/drivers/gpu/drm/i915/i915_vma_resource.h
index 2053c037dbfb..ca2b0f7f59bc 100644
--- a/drivers/gpu/drm/i915/i915_vma_resource.h
+++ b/drivers/gpu/drm/i915/i915_vma_resource.h
@@ -33,6 +33,27 @@ struct i915_page_sizes {
 	unsigned int sg;
 };
 
+/**
+ * struct i915_vma_bindinfo - Information needed for async bind
+ * only but that can be dropped after the bind has taken place.
+ * Consider making this a separate argument to the bind_vma
+ * op, coalescing with other arguments like vm, stash, cache_level
+ * and flags
+ * @pages: The pages sg-table.
+ * @page_sizes: Page sizes of the pages.
+ * @pages_rsgt: Refcounted sg-table when delayed object destruction
+ * is supported. May be NULL.
+ * @readonly: Whether the vma should be bound read-only.
+ * @lmem: Whether the vma points to lmem.
+ */
+struct i915_vma_bindinfo {
+	struct sg_table *pages;
+	struct i915_page_sizes page_sizes;
+	struct i915_refct_sgt *pages_rsgt;
+	bool readonly:1;
+	bool lmem:1;
+};
+
 /**
  * struct i915_vma_resource - Snapshotted unbind information.
  * @unbind_fence: Fence to mark unbinding complete. Note that this fence
@@ -89,25 +110,13 @@ struct i915_vma_resource {
 	intel_wakeref_t wakeref;
 
 	/**
-	 * struct i915_vma_bindinfo - Information needed for async bind
-	 * only but that can be dropped after the bind has taken place.
-	 * Consider making this a separate argument to the bind_vma
-	 * op, coalescing with other arguments like vm, stash, cache_level
-	 * and flags
-	 * @pages: The pages sg-table.
-	 * @page_sizes: Page sizes of the pages.
-	 * @pages_rsgt: Refcounted sg-table when delayed object destruction
-	 * is supported. May be NULL.
-	 * @readonly: Whether the vma should be bound read-only.
-	 * @lmem: Whether the vma points to lmem.
+	 * @bi: Information needed for async bind only but that can be dropped
+	 * after the bind has taken place.
+	 *
+	 * Consider making this a separate argument to the bind_vma op,
+	 * coalescing with other arguments like vm, stash, cache_level and flags
 	 */
-	struct i915_vma_bindinfo {
-		struct sg_table *pages;
-		struct i915_page_sizes page_sizes;
-		struct i915_refct_sgt *pages_rsgt;
-		bool readonly:1;
-		bool lmem:1;
-	} bi;
+	struct i915_vma_bindinfo bi;
 
 #if IS_ENABLED(CONFIG_DRM_I915_CAPTURE_ERROR)
 	struct intel_memory_region *mr;
-- 
2.39.2

[Intel-gfx] [PATCH 06/24] drm/i915/perf: fix i915_perf_ioctl_version() kernel-doc

[Jani Nikula]

drivers/gpu/drm/i915/i915_perf.c:5307: warning: Function parameter or member 'i915' not described in 'i915_perf_ioctl_version'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/i915_perf.c | 1 +
 1 file changed, 1 insertion(+)

diff --git a/drivers/gpu/drm/i915/i915_perf.c b/drivers/gpu/drm/i915/i915_perf.c
index 050b8ae7b8e7..19d5652300ee 100644
--- a/drivers/gpu/drm/i915/i915_perf.c
+++ b/drivers/gpu/drm/i915/i915_perf.c
@@ -5300,6 +5300,7 @@ void i915_perf_fini(struct drm_i915_private *i915)
 
 /**
  * i915_perf_ioctl_version - Version of the i915-perf subsystem
+ * @i915: The i915 device
  *
  * This version number is used by userspace to detect available features.
  */
-- 
2.39.2

[Intel-gfx] [PATCH 07/24] drm/i915/error: fix i915_capture_error_state() kernel-doc

[Jani Nikula]

drivers/gpu/drm/i915/i915_gpu_error.c:2174: warning: Function parameter or member 'dump_flags' not described in 'i915_capture_error_state'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/i915_gpu_error.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/i915_gpu_error.c b/drivers/gpu/drm/i915/i915_gpu_error.c
index f020c0086fbc..04ad30274896 100644
--- a/drivers/gpu/drm/i915/i915_gpu_error.c
+++ b/drivers/gpu/drm/i915/i915_gpu_error.c
@@ -2162,7 +2162,7 @@ void i915_error_state_store(struct i915_gpu_coredump *error)
  * i915_capture_error_state - capture an error record for later analysis
  * @gt: intel_gt which originated the hang
  * @engine_mask: hung engines
- *
+ * @dump_flags: dump flags
  *
  * Should be called when an error is detected (either a hang or an error
  * interrupt) to capture error state from the time of the error.  Fills
-- 
2.39.2

[Intel-gfx] [PATCH 08/24] drm/i915/request: drop kernel-doc

[Jani Nikula]

The documentation is closer to not being kernel-doc. Just drop the
kernel-doc /** indicators.

drivers/gpu/drm/i915/i915_request.h:176: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * Request queue structure.
drivers/gpu/drm/i915/i915_request.h:477: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * Returns true if seq1 is later than seq2.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/i915_request.h | 52 ++++++++++++++---------------
 1 file changed, 26 insertions(+), 26 deletions(-)

diff --git a/drivers/gpu/drm/i915/i915_request.h b/drivers/gpu/drm/i915/i915_request.h
index f5e1bb5e857a..0ac55b2e4223 100644
--- a/drivers/gpu/drm/i915/i915_request.h
+++ b/drivers/gpu/drm/i915/i915_request.h
@@ -172,7 +172,7 @@ enum {
 	I915_FENCE_FLAG_COMPOSITE,
 };
 
-/**
+/*
  * Request queue structure.
  *
  * The request queue allows us to note sequence numbers that have been emitted
@@ -198,7 +198,7 @@ struct i915_request {
 
 	struct drm_i915_private *i915;
 
-	/**
+	/*
 	 * Context and ring buffer related to this request
 	 * Contexts are refcounted, so when this request is associated with a
 	 * context, we must increment the context's refcount, to guarantee that
@@ -251,9 +251,9 @@ struct i915_request {
 	};
 	struct llist_head execute_cb;
 	struct i915_sw_fence semaphore;
-	/**
-	 * @submit_work: complete submit fence from an IRQ if needed for
-	 * locking hierarchy reasons.
+	/*
+	 * complete submit fence from an IRQ if needed for locking hierarchy
+	 * reasons.
 	 */
 	struct irq_work submit_work;
 
@@ -277,35 +277,35 @@ struct i915_request {
 	 */
 	const u32 *hwsp_seqno;
 
-	/** Position in the ring of the start of the request */
+	/* Position in the ring of the start of the request */
 	u32 head;
 
-	/** Position in the ring of the start of the user packets */
+	/* Position in the ring of the start of the user packets */
 	u32 infix;
 
-	/**
+	/*
 	 * Position in the ring of the start of the postfix.
 	 * This is required to calculate the maximum available ring space
 	 * without overwriting the postfix.
 	 */
 	u32 postfix;
 
-	/** Position in the ring of the end of the whole request */
+	/* Position in the ring of the end of the whole request */
 	u32 tail;
 
-	/** Position in the ring of the end of any workarounds after the tail */
+	/* Position in the ring of the end of any workarounds after the tail */
 	u32 wa_tail;
 
-	/** Preallocate space in the ring for the emitting the request */
+	/* Preallocate space in the ring for the emitting the request */
 	u32 reserved_space;
 
-	/** Batch buffer pointer for selftest internal use. */
+	/* Batch buffer pointer for selftest internal use. */
 	I915_SELFTEST_DECLARE(struct i915_vma *batch);
 
 	struct i915_vma_resource *batch_res;
 
 #if IS_ENABLED(CONFIG_DRM_I915_CAPTURE_ERROR)
-	/**
+	/*
 	 * Additional buffers requested by userspace to be captured upon
 	 * a GPU hang. The vma/obj on this list are protected by their
 	 * active reference - all objects on this list must also be
@@ -314,29 +314,29 @@ struct i915_request {
 	struct i915_capture_list *capture_list;
 #endif
 
-	/** Time at which this request was emitted, in jiffies. */
+	/* Time at which this request was emitted, in jiffies. */
 	unsigned long emitted_jiffies;
 
-	/** timeline->request entry for this request */
+	/* timeline->request entry for this request */
 	struct list_head link;
 
-	/** Watchdog support fields. */
+	/* Watchdog support fields. */
 	struct i915_request_watchdog {
 		struct llist_node link;
 		struct hrtimer timer;
 	} watchdog;
 
-	/**
-	 * @guc_fence_link: Requests may need to be stalled when using GuC
-	 * submission waiting for certain GuC operations to complete. If that is
-	 * the case, stalled requests are added to a per context list of stalled
-	 * requests. The below list_head is the link in that list. Protected by
+	/*
+	 * Requests may need to be stalled when using GuC submission waiting for
+	 * certain GuC operations to complete. If that is the case, stalled
+	 * requests are added to a per context list of stalled requests. The
+	 * below list_head is the link in that list. Protected by
 	 * ce->guc_state.lock.
 	 */
 	struct list_head guc_fence_link;
 
-	/**
-	 * @guc_prio: Priority level while the request is in flight. Differs
+	/*
+	 * Priority level while the request is in flight. Differs
 	 * from i915 scheduler priority. See comment above
 	 * I915_SCHEDULER_CAP_STATIC_PRIORITY_MAP for details. Protected by
 	 * ce->guc_active.lock. Two special values (GUC_PRIO_INIT and
@@ -348,8 +348,8 @@ struct i915_request {
 #define	GUC_PRIO_FINI	0xfe
 	u8 guc_prio;
 
-	/**
-	 * @hucq: wait queue entry used to wait on the HuC load to complete
+	/*
+	 * wait queue entry used to wait on the HuC load to complete
 	 */
 	wait_queue_entry_t hucq;
 
@@ -473,7 +473,7 @@ i915_request_has_initial_breadcrumb(const struct i915_request *rq)
 	return test_bit(I915_FENCE_FLAG_INITIAL_BREADCRUMB, &rq->fence.flags);
 }
 
-/**
+/*
  * Returns true if seq1 is later than seq2.
  */
 static inline bool i915_seqno_passed(u32 seq1, u32 seq2)
-- 
2.39.2

[Intel-gfx] [PATCH 09/24] drm/i915/gem: fix i915_gem_object_lookup_rcu() kernel-doc parameter name

[Jani Nikula]

drivers/gpu/drm/i915/gem/i915_gem_object.h:94: warning: Function parameter or member 'file' not described in 'i915_gem_object_lookup_rcu'
drivers/gpu/drm/i915/gem/i915_gem_object.h:94: warning: Excess function parameter 'filp' description in 'i915_gem_object_lookup_rcu'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/gem/i915_gem_object.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/gem/i915_gem_object.h b/drivers/gpu/drm/i915/gem/i915_gem_object.h
index 885ccde9dc3c..bc1291887d4f 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_object.h
+++ b/drivers/gpu/drm/i915/gem/i915_gem_object.h
@@ -80,7 +80,7 @@ __i915_gem_object_unset_pages(struct drm_i915_gem_object *obj);
 
 /**
  * i915_gem_object_lookup_rcu - look up a temporary GEM object from its handle
- * @filp: DRM file private date
+ * @file: DRM file private date
  * @handle: userspace handle
  *
  * Returns:
-- 
2.39.2

[Intel-gfx] [PATCH 10/24] drm/i915/gem: fix function pointer member kernel-doc

[Jani Nikula]

You can't document function pointer member as functions.

drivers/gpu/drm/i915/gem/i915_gem_region.h:25: warning: Incorrect use of kernel-doc format:          * process_obj - Process the current object
drivers/gpu/drm/i915/gem/i915_gem_region.h:35: warning: Function parameter or member 'process_obj' not described in 'i915_gem_apply_to_region_ops'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/gem/i915_gem_region.h | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/i915/gem/i915_gem_region.h b/drivers/gpu/drm/i915/gem/i915_gem_region.h
index 2dfcc41c0170..8a7650b27cc2 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_region.h
+++ b/drivers/gpu/drm/i915/gem/i915_gem_region.h
@@ -22,9 +22,7 @@ struct i915_gem_apply_to_region;
  */
 struct i915_gem_apply_to_region_ops {
 	/**
-	 * process_obj - Process the current object
-	 * @apply: Embed this for private data.
-	 * @obj: The current object.
+	 * @process_obj: Process the current object
 	 *
 	 * Note that if this function is part of a ww transaction, and
 	 * if returns -EDEADLK for one of the objects, it may be
-- 
2.39.2

[Intel-gfx] [PATCH 11/24] drm/i915/ttm: fix i915_ttm_to_gem() kernel-doc

[Jani Nikula]

drivers/gpu/drm/i915/gem/i915_gem_ttm.h:50: warning: Function parameter or member 'bo' not described in 'i915_ttm_to_gem'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/gem/i915_gem_ttm.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/drivers/gpu/drm/i915/gem/i915_gem_ttm.h b/drivers/gpu/drm/i915/gem/i915_gem_ttm.h
index f8f6bed1b297..70abdc3061a9 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_ttm.h
+++ b/drivers/gpu/drm/i915/gem/i915_gem_ttm.h
@@ -42,6 +42,7 @@ static inline bool i915_ttm_is_ghost_object(struct ttm_buffer_object *bo)
 /**
  * i915_ttm_to_gem - Convert a struct ttm_buffer_object to an embedding
  * struct drm_i915_gem_object.
+ * @bo: Pointer to the ttm buffer object
  *
  * Return: Pointer to the embedding struct ttm_buffer_object.
  */
-- 
2.39.2

[Intel-gfx] [PATCH 12/24] drm/i915/engine: fix kernel-doc function name for intel_engine_cleanup_common()

[Jani Nikula]

drivers/gpu/drm/i915/gt/intel_engine_cs.c:1525: warning: expecting prototype for intel_engines_cleanup_common(). Prototype was for intel_engine_cleanup_common() instead

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/gt/intel_engine_cs.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/gt/intel_engine_cs.c b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
index 5c6c9a6d469c..0aff5bb13c53 100644
--- a/drivers/gpu/drm/i915/gt/intel_engine_cs.c
+++ b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
@@ -1515,7 +1515,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.
  *
-- 
2.39.2

[Intel-gfx] [PATCH 13/24] drm/i915/context: fix kernel-doc parameter descriptions

[Jani Nikula]

drivers/gpu/drm/i915/gt/intel_context.h:108: warning: Function parameter or member 'ce' not described in 'intel_context_lock_pinned'
drivers/gpu/drm/i915/gt/intel_context.h:123: warning: Function parameter or member 'ce' not described in 'intel_context_is_pinned'
drivers/gpu/drm/i915/gt/intel_context.h:142: warning: Function parameter or member 'ce' not described in 'intel_context_unlock_pinned'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/gt/intel_context.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/i915/gt/intel_context.h b/drivers/gpu/drm/i915/gt/intel_context.h
index 48f888c3da08..6b5eae7b88bc 100644
--- a/drivers/gpu/drm/i915/gt/intel_context.h
+++ b/drivers/gpu/drm/i915/gt/intel_context.h
@@ -97,7 +97,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.
@@ -111,7 +111,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.
@@ -133,7 +133,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().
  */
-- 
2.39.2

[Intel-gfx] [PATCH 14/24] drm/i915/gtt: fix i915_vm_resv_put() kernel-doc parameter name

[Jani Nikula]

drivers/gpu/drm/i915/gt/intel_gtt.h:515: warning: Function parameter or member 'vm' not described in 'i915_vm_resv_put'
drivers/gpu/drm/i915/gt/intel_gtt.h:515: warning: Excess function parameter 'resv' description in 'i915_vm_resv_put'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/gt/intel_gtt.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/gt/intel_gtt.h b/drivers/gpu/drm/i915/gt/intel_gtt.h
index 1910683f03b4..9aff343beaa8 100644
--- a/drivers/gpu/drm/i915/gt/intel_gtt.h
+++ b/drivers/gpu/drm/i915/gt/intel_gtt.h
@@ -509,7 +509,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 reference we want to release
  */
 static inline void i915_vm_resv_put(struct i915_address_space *vm)
 {
-- 
2.39.2

[Intel-gfx] [PATCH 15/24] drm/i915/engine: hide preempt_hang selftest member from kernel-doc

[Jani Nikula]

drivers/gpu/drm/i915/gt/intel_engine_types.h:293: warning: Function parameter or member 'preempt_hang' not described in 'intel_engine_execlists'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/gt/intel_engine_types.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/drivers/gpu/drm/i915/gt/intel_engine_types.h b/drivers/gpu/drm/i915/gt/intel_engine_types.h
index 960291f88fd6..e99a6fa03d45 100644
--- a/drivers/gpu/drm/i915/gt/intel_engine_types.h
+++ b/drivers/gpu/drm/i915/gt/intel_engine_types.h
@@ -289,6 +289,7 @@ struct intel_engine_execlists {
 	 */
 	u8 csb_head;
 
+	/* private: selftest */
 	I915_SELFTEST_DECLARE(struct st_preempt_hang preempt_hang;)
 };
 
-- 
2.39.2

[Intel-gfx] [PATCH 16/24] drm/i915/guc: add dbgfs_node member kernel-doc

[Jani Nikula]

drivers/gpu/drm/i915/gt/uc/intel_guc.h:274: warning: Function parameter or member 'dbgfs_node' not described in 'intel_guc'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/gt/uc/intel_guc.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc.h b/drivers/gpu/drm/i915/gt/uc/intel_guc.h
index e46aac1a41e6..8dc291ff0093 100644
--- a/drivers/gpu/drm/i915/gt/uc/intel_guc.h
+++ b/drivers/gpu/drm/i915/gt/uc/intel_guc.h
@@ -42,6 +42,7 @@ struct intel_guc {
 	/** @capture: the error-state-capture module's data and objects */
 	struct intel_guc_state_capture *capture;
 
+	/** @dbgfs_node: debugfs node */
 	struct dentry *dbgfs_node;
 
 	/** @sched_engine: Global engine used to submit requests to GuC */
-- 
2.39.2

[Intel-gfx] [PATCH 17/24] drm/i915/guc: drop lots of kernel-doc markers

[Jani Nikula]

The documentation is closer to not being kernel-doc, so just drop the
kernel-doc markers.

drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:27: warning: Function parameter or member 'size' not described in '__guc_capture_bufstate'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:27: warning: Function parameter or member 'data' not described in '__guc_capture_bufstate'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:27: warning: Function parameter or member 'rd' not described in '__guc_capture_bufstate'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:27: warning: Function parameter or member 'wr' not described in '__guc_capture_bufstate'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:59: warning: Function parameter or member 'link' not described in '__guc_capture_parsed_output'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:59: warning: Function parameter or member 'is_partial' not described in '__guc_capture_parsed_output'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:59: warning: Function parameter or member 'eng_class' not described in '__guc_capture_parsed_output'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:59: warning: Function parameter or member 'eng_inst' not described in '__guc_capture_parsed_output'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:59: warning: Function parameter or member 'guc_id' not described in '__guc_capture_parsed_output'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:59: warning: Function parameter or member 'lrca' not described in '__guc_capture_parsed_output'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:59: warning: Function parameter or member 'reginfo' not described in '__guc_capture_parsed_output'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:62: 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:80: 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:105: 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:163: warning: Function parameter or member 'is_valid' not described in '__guc_capture_ads_cache'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:163: warning: Function parameter or member 'ptr' not described in '__guc_capture_ads_cache'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:163: warning: Function parameter or member 'size' not described in '__guc_capture_ads_cache'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:163: warning: Function parameter or member 'status' not described in '__guc_capture_ads_cache'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:491: warning: Function parameter or member 'marker' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:491: warning: Function parameter or member 'read_ptr' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:491: warning: Function parameter or member 'write_ptr' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:491: warning: Function parameter or member 'size' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:491: 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:491: warning: Function parameter or member 'wrap_offset' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:491: 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:491: 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:491: warning: Function parameter or member 'reserved' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:491: warning: Function parameter or member 'flags' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:491: warning: Function parameter or member 'version' not described in 'guc_log_buffer_state'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h | 12 ++++++------
 drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h   |  2 +-
 2 files changed, 7 insertions(+), 7 deletions(-)

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 9d589c28f40f..1b6c219e1675 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[];
 } __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[];
 } __packed;
 
-/**
+/*
  * struct __guc_capture_ads_cache
  *
  * A structure to cache register lists that were populated and registered
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 4ae5fc2f6002..8bb9ed7c7b4d 100644
--- a/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h
+++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h
@@ -451,7 +451,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.39.2

[Intel-gfx] [PATCH 18/24] drm/i915/guc: add intel_guc_state_capture member docs for ads_null_cache and max_mmio_per_node

[Jani Nikula]

drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:216: 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:216: warning: Function parameter or member 'max_mmio_per_node' not described in 'intel_guc_state_capture'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h | 8 ++++++++
 1 file changed, 8 insertions(+)

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 1b6c219e1675..1fc0c17b1230 100644
--- a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
+++ b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
@@ -187,6 +187,10 @@ struct intel_guc_state_capture {
 	struct __guc_capture_ads_cache ads_cache[GUC_CAPTURE_LIST_INDEX_MAX]
 						[GUC_CAPTURE_LIST_TYPE_MAX]
 						[GUC_MAX_ENGINE_CLASSES];
+
+	/**
+	 * @ads_null_cache: ADS null cache.
+	 */
 	void *ads_null_cache;
 
 	/**
@@ -202,6 +206,10 @@ struct intel_guc_state_capture {
 	struct list_head cachelist;
 #define PREALLOC_NODES_MAX_COUNT (3 * GUC_MAX_ENGINE_CLASSES * GUC_MAX_INSTANCES_PER_CLASS)
 #define PREALLOC_NODES_DEFAULT_NUMREGS 64
+
+	/**
+	 * @max_mmio_per_node: Max MMIO per node.
+	 */
 	int max_mmio_per_node;
 
 	/**
-- 
2.39.2

[Intel-gfx] [PATCH 19/24] drm/i915/active: fix kernel-doc for function parameters

[Jani Nikula]

drivers/gpu/drm/i915/i915_active.h:66: warning: Function parameter or member 'active' not described in '__i915_active_fence_init'
drivers/gpu/drm/i915/i915_active.h:66: warning: Function parameter or member 'fence' not described in '__i915_active_fence_init'
drivers/gpu/drm/i915/i915_active.h:66: warning: Function parameter or member 'fn' not described in '__i915_active_fence_init'
drivers/gpu/drm/i915/i915_active.h:89: warning: Function parameter or member 'active' not described in 'i915_active_fence_set'
drivers/gpu/drm/i915/i915_active.h:89: warning: Function parameter or member 'rq' not described in 'i915_active_fence_set'
drivers/gpu/drm/i915/i915_active.h:102: warning: Function parameter or member 'active' not described in 'i915_active_fence_get'
drivers/gpu/drm/i915/i915_active.h:122: warning: Function parameter or member 'active' not described in 'i915_active_fence_isset'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/i915_active.h | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/drivers/gpu/drm/i915/i915_active.h b/drivers/gpu/drm/i915/i915_active.h
index 7eb44132183a..77c676ecc263 100644
--- a/drivers/gpu/drm/i915/i915_active.h
+++ b/drivers/gpu/drm/i915/i915_active.h
@@ -49,9 +49,9 @@ void i915_active_noop(struct dma_fence *fence, struct dma_fence_cb *cb);
 
 /**
  * __i915_active_fence_init - prepares the activity tracker for use
- * @active - the active tracker
- * @fence - initial fence to track, can be NULL
- * @func - a callback when then the tracker is retired (becomes idle),
+ * @active: the active tracker
+ * @fence: initial fence to track, can be NULL
+ * @fn: a callback when then the tracker is retired (becomes idle),
  *         can be NULL
  *
  * i915_active_fence_init() prepares the embedded @active struct for use as
@@ -77,8 +77,8 @@ __i915_active_fence_set(struct i915_active_fence *active,
 
 /**
  * i915_active_fence_set - updates the tracker to watch the current fence
- * @active - the active tracker
- * @rq - the request to watch
+ * @active: the active tracker
+ * @rq: the request to watch
  *
  * i915_active_fence_set() watches the given @rq for completion. While
  * that @rq is busy, the @active reports busy. When that @rq is signaled
@@ -89,7 +89,7 @@ i915_active_fence_set(struct i915_active_fence *active,
 		      struct i915_request *rq);
 /**
  * i915_active_fence_get - return a reference to the active fence
- * @active - the active tracker
+ * @active: the active tracker
  *
  * i915_active_fence_get() returns a reference to the active fence,
  * or NULL if the active tracker is idle. The reference is obtained under RCU,
@@ -111,7 +111,7 @@ i915_active_fence_get(struct i915_active_fence *active)
 
 /**
  * i915_active_fence_isset - report whether the active tracker is assigned
- * @active - the active tracker
+ * @active: the active tracker
  *
  * i915_active_fence_isset() returns true if the active tracker is currently
  * assigned to a fence. Due to the lazy retiring, that fence may be idle
-- 
2.39.2

[Intel-gfx] [PATCH 20/24] drm/i915/pmu: drop kernel-doc

[Jani Nikula]

The comments are closer to not being kernel-doc.

drivers/gpu/drm/i915/i915_pmu.h:21: warning: cannot understand function prototype: 'enum i915_pmu_tracked_events '
drivers/gpu/drm/i915/i915_pmu.h:32: warning: cannot understand function prototype: 'enum '
drivers/gpu/drm/i915/i915_pmu.h:41: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * How many different events we track in the global PMU mask.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/i915_pmu.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/i915/i915_pmu.h b/drivers/gpu/drm/i915/i915_pmu.h
index 449057648f39..c30f43319a78 100644
--- a/drivers/gpu/drm/i915/i915_pmu.h
+++ b/drivers/gpu/drm/i915/i915_pmu.h
@@ -14,7 +14,7 @@
 
 struct drm_i915_private;
 
-/**
+/*
  * Non-engine events that we need to track enabled-disabled transition and
  * current state.
  */
@@ -25,7 +25,7 @@ enum i915_pmu_tracked_events {
 	__I915_PMU_TRACKED_EVENT_COUNT, /* count marker */
 };
 
-/**
+/*
  * Slots used from the sampling timer (non-engine events) with some extras for
  * convenience.
  */
@@ -37,7 +37,7 @@ enum {
 	__I915_NUM_PMU_SAMPLERS
 };
 
-/**
+/*
  * How many different events we track in the global PMU mask.
  *
  * It is also used to know to needed number of event reference counters.
-- 
2.39.2

[Intel-gfx] [PATCH 21/24] drm/i915/pxp: fix kernel-doc for member dev_link

[Jani Nikula]

Add /** to make it a kernel-doc.

drivers/gpu/drm/i915/pxp/intel_pxp_types.h:96: warning: Function parameter or member 'dev_link' not described in 'intel_pxp'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/pxp/intel_pxp_types.h | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/pxp/intel_pxp_types.h b/drivers/gpu/drm/i915/pxp/intel_pxp_types.h
index 007de49e1ea4..c445f7f2f47a 100644
--- a/drivers/gpu/drm/i915/pxp/intel_pxp_types.h
+++ b/drivers/gpu/drm/i915/pxp/intel_pxp_types.h
@@ -33,7 +33,9 @@ struct intel_pxp {
 	 */
 	struct i915_pxp_component *pxp_component;
 
-	/* @dev_link: Enforce module relationship for power management ordering. */
+	/**
+	 * @dev_link: Enforce module relationship for power management ordering.
+	 */
 	struct device_link *dev_link;
 	/**
 	 * @pxp_component_added: track if the pxp component has been added.
-- 
2.39.2

[Intel-gfx] [PATCH 22/24] drm/i915/scatterlist: fix kernel-doc

[Jani Nikula]

Can't document function pointer members as if they are functions.

drivers/gpu/drm/i915/i915_scatterlist.h:160: warning: Incorrect use of kernel-doc format:          * release() - Free the memory of the struct i915_refct_sgt

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/i915_scatterlist.h | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/drivers/gpu/drm/i915/i915_scatterlist.h b/drivers/gpu/drm/i915/i915_scatterlist.h
index b0a1db44f895..fe9ae863f9b9 100644
--- a/drivers/gpu/drm/i915/i915_scatterlist.h
+++ b/drivers/gpu/drm/i915/i915_scatterlist.h
@@ -157,8 +157,7 @@ bool i915_sg_trim(struct sg_table *orig_st);
  */
 struct i915_refct_sgt_ops {
 	/**
-	 * release() - Free the memory of the struct i915_refct_sgt
-	 * @ref: struct kref that is embedded in the struct i915_refct_sgt
+	 * @release: Free the memory of the struct i915_refct_sgt
 	 */
 	void (*release)(struct kref *ref);
 };
-- 
2.39.2

[Intel-gfx] [PATCH 23/24] drm/i915/scatterlist: fix kernel-doc parameter documentation

[Jani Nikula]

drivers/gpu/drm/i915/i915_scatterlist.h:164: warning: Function parameter or member 'release' not described in 'i915_refct_sgt_ops'
drivers/gpu/drm/i915/i915_scatterlist.h:187: warning: Function parameter or member 'rsgt' not described in 'i915_refct_sgt_put'
drivers/gpu/drm/i915/i915_scatterlist.h:198: warning: Function parameter or member 'rsgt' not described in 'i915_refct_sgt_get'
drivers/gpu/drm/i915/i915_scatterlist.h:214: warning: Function parameter or member 'rsgt' not described in '__i915_refct_sgt_init'

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/i915_scatterlist.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/i915/i915_scatterlist.h b/drivers/gpu/drm/i915/i915_scatterlist.h
index fe9ae863f9b9..5a10c1a31183 100644
--- a/drivers/gpu/drm/i915/i915_scatterlist.h
+++ b/drivers/gpu/drm/i915/i915_scatterlist.h
@@ -180,7 +180,7 @@ struct i915_refct_sgt {
 
 /**
  * i915_refct_sgt_put - Put a refcounted sg-table
- * @rsgt the struct i915_refct_sgt to put.
+ * @rsgt: the struct i915_refct_sgt to put.
  */
 static inline void i915_refct_sgt_put(struct i915_refct_sgt *rsgt)
 {
@@ -190,7 +190,7 @@ static inline void i915_refct_sgt_put(struct i915_refct_sgt *rsgt)
 
 /**
  * i915_refct_sgt_get - Get a refcounted sg-table
- * @rsgt the struct i915_refct_sgt to get.
+ * @rsgt: the struct i915_refct_sgt to get.
  */
 static inline struct i915_refct_sgt *
 i915_refct_sgt_get(struct i915_refct_sgt *rsgt)
@@ -202,7 +202,7 @@ i915_refct_sgt_get(struct i915_refct_sgt *rsgt)
 /**
  * __i915_refct_sgt_init - Initialize a refcounted sg-list with a custom
  * operations structure
- * @rsgt The struct i915_refct_sgt to initialize.
+ * @rsgt: The struct i915_refct_sgt to initialize.
  * @size: Size in bytes of the underlying memory buffer.
  * @ops: A customized operations structure in case the refcounted sg-list
  * is embedded into another structure.
-- 
2.39.2

[Intel-gfx] [PATCH 24/24] drm/i915: use kernel-doc -Werror when CONFIG_DRM_I915_WERROR=y

[Jani Nikula]

With CONFIG_DRM_I915_WERROR=y, we enable kernel-doc check for both
objects and headers. Now that the kernel-doc warnings have been fixed,
also enable kernel-doc -Werror to fail the build on kernel-doc warnings.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 drivers/gpu/drm/i915/Makefile | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/gpu/drm/i915/Makefile b/drivers/gpu/drm/i915/Makefile
index 9af76e376ca9..f43734f13471 100644
--- a/drivers/gpu/drm/i915/Makefile
+++ b/drivers/gpu/drm/i915/Makefile
@@ -377,7 +377,7 @@ obj-$(CONFIG_DRM_I915_GVT_KVMGT) += kvmgt.o
 #
 # Enable locally for CONFIG_DRM_I915_WERROR=y. See also scripts/Makefile.build
 ifdef CONFIG_DRM_I915_WERROR
-    cmd_checkdoc = $(srctree)/scripts/kernel-doc -none $<
+    cmd_checkdoc = $(srctree)/scripts/kernel-doc -none -Werror $<
 endif
 
 # header test
@@ -392,7 +392,7 @@ always-$(CONFIG_DRM_I915_WERROR) += \
 
 quiet_cmd_hdrtest = HDRTEST $(patsubst %.hdrtest,%.h,$@)
       cmd_hdrtest = $(CC) $(filter-out $(CFLAGS_GCOV), $(c_flags)) -S -o /dev/null -x c /dev/null -include $<; \
-		$(srctree)/scripts/kernel-doc -none $<; touch $@
+		$(srctree)/scripts/kernel-doc -none -Werror $<; touch $@
 
 $(obj)/%.hdrtest: $(src)/%.h FORCE
 	$(call if_changed_dep,hdrtest)
-- 
2.39.2

[Intel-gfx] ✗ Fi.CI.SPARSE: warning for drm/i915: fix kernel-doc warnings, enable kernel-doc -Werror

[Patchwork]

== Series Details ==

Series: drm/i915: fix kernel-doc warnings, enable kernel-doc -Werror
URL   : https://patchwork.freedesktop.org/series/117207/
State : warning

== Summary ==

Error: dim sparse failed
Sparse version: v0.6.2
Fast mode used, each commit won't be checked separately.

[Intel-gfx] ✓ Fi.CI.BAT: success for drm/i915: fix kernel-doc warnings, enable kernel-doc -Werror

[Patchwork]

[-- Attachment #1: Type: text/plain, Size: 6570 bytes --]

== Series Details ==

Series: drm/i915: fix kernel-doc warnings, enable kernel-doc -Werror
URL   : https://patchwork.freedesktop.org/series/117207/
State : success

== Summary ==

CI Bug Log - changes from CI_DRM_13097 -> Patchwork_117207v1
====================================================

Summary
-------

  **SUCCESS**

  No regressions found.

  External URL: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/index.html

Participating hosts (38 -> 37)
------------------------------

  Missing    (1): fi-snb-2520m 

Known issues
------------

  Here are the changes found in Patchwork_117207v1 that come from known issues:

### IGT changes ###

#### Issues hit ####

  * igt@i915_selftest@live@gt_heartbeat:
    - fi-apl-guc:         [PASS][1] -> [DMESG-FAIL][2] ([i915#5334])
   [1]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_13097/fi-apl-guc/igt@i915_selftest@live@gt_heartbeat.html
   [2]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/fi-apl-guc/igt@i915_selftest@live@gt_heartbeat.html

  * igt@i915_selftest@live@gt_lrc:
    - bat-adln-1:         [PASS][3] -> [INCOMPLETE][4] ([i915#4983] / [i915#7609])
   [3]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_13097/bat-adln-1/igt@i915_selftest@live@gt_lrc.html
   [4]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/bat-adln-1/igt@i915_selftest@live@gt_lrc.html

  * igt@i915_selftest@live@requests:
    - bat-rpls-1:         [PASS][5] -> [ABORT][6] ([i915#4983] / [i915#7911] / [i915#7920])
   [5]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_13097/bat-rpls-1/igt@i915_selftest@live@requests.html
   [6]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/bat-rpls-1/igt@i915_selftest@live@requests.html

  
#### Possible fixes ####

  * igt@gem_exec_parallel@engines@fds:
    - {bat-mtlp-8}:       [ABORT][7] -> [PASS][8]
   [7]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_13097/bat-mtlp-8/igt@gem_exec_parallel@engines@fds.html
   [8]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/bat-mtlp-8/igt@gem_exec_parallel@engines@fds.html

  * igt@i915_selftest@live@requests:
    - {bat-mtlp-6}:       [ABORT][9] ([i915#4983] / [i915#7920]) -> [PASS][10]
   [9]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_13097/bat-mtlp-6/igt@i915_selftest@live@requests.html
   [10]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/bat-mtlp-6/igt@i915_selftest@live@requests.html

  
  {name}: This element is suppressed. This means it is ignored when computing
          the status of the difference (SUCCESS, WARNING, or FAILURE).

  [fdo#109285]: https://bugs.freedesktop.org/show_bug.cgi?id=109285
  [i915#1845]: https://gitlab.freedesktop.org/drm/intel/issues/1845
  [i915#3595]: https://gitlab.freedesktop.org/drm/intel/issues/3595
  [i915#3708]: https://gitlab.freedesktop.org/drm/intel/issues/3708
  [i915#4077]: https://gitlab.freedesktop.org/drm/intel/issues/4077
  [i915#4078]: https://gitlab.freedesktop.org/drm/intel/issues/4078
  [i915#4079]: https://gitlab.freedesktop.org/drm/intel/issues/4079
  [i915#4083]: https://gitlab.freedesktop.org/drm/intel/issues/4083
  [i915#4212]: https://gitlab.freedesktop.org/drm/intel/issues/4212
  [i915#4213]: https://gitlab.freedesktop.org/drm/intel/issues/4213
  [i915#4579]: https://gitlab.freedesktop.org/drm/intel/issues/4579
  [i915#4613]: https://gitlab.freedesktop.org/drm/intel/issues/4613
  [i915#4983]: https://gitlab.freedesktop.org/drm/intel/issues/4983
  [i915#5190]: https://gitlab.freedesktop.org/drm/intel/issues/5190
  [i915#5274]: https://gitlab.freedesktop.org/drm/intel/issues/5274
  [i915#5334]: https://gitlab.freedesktop.org/drm/intel/issues/5334
  [i915#6367]: https://gitlab.freedesktop.org/drm/intel/issues/6367
  [i915#6621]: https://gitlab.freedesktop.org/drm/intel/issues/6621
  [i915#6645]: https://gitlab.freedesktop.org/drm/intel/issues/6645
  [i915#7609]: https://gitlab.freedesktop.org/drm/intel/issues/7609
  [i915#7699]: https://gitlab.freedesktop.org/drm/intel/issues/7699
  [i915#7828]: https://gitlab.freedesktop.org/drm/intel/issues/7828
  [i915#7911]: https://gitlab.freedesktop.org/drm/intel/issues/7911
  [i915#7920]: https://gitlab.freedesktop.org/drm/intel/issues/7920
  [i915#8368]: https://gitlab.freedesktop.org/drm/intel/issues/8368
  [i915#8379]: https://gitlab.freedesktop.org/drm/intel/issues/8379


Build changes
-------------

  * Linux: CI_DRM_13097 -> Patchwork_117207v1

  CI-20190529: 20190529
  CI_DRM_13097: 1413856e3770380da743e274a06896acabf49e0e @ git://anongit.freedesktop.org/gfx-ci/linux
  IGT_7277: 1cb3507f3ff28d11bd5cfabcde576fe78ddab571 @ https://gitlab.freedesktop.org/drm/igt-gpu-tools.git
  Patchwork_117207v1: 1413856e3770380da743e274a06896acabf49e0e @ git://anongit.freedesktop.org/gfx-ci/linux


### Linux commits

ad6fdf0ba067 drm/i915: use kernel-doc -Werror when CONFIG_DRM_I915_WERROR=y
6f1d3b3d2f74 drm/i915/scatterlist: fix kernel-doc parameter documentation
0019c25445e8 drm/i915/scatterlist: fix kernel-doc
aabb90062836 drm/i915/pxp: fix kernel-doc for member dev_link
73af7bd35f45 drm/i915/pmu: drop kernel-doc
fbd0c0300468 drm/i915/active: fix kernel-doc for function parameters
ded538d1f4c5 drm/i915/guc: add intel_guc_state_capture member docs for ads_null_cache and max_mmio_per_node
b53dd492eec3 drm/i915/guc: drop lots of kernel-doc markers
5d282e0c3801 drm/i915/guc: add dbgfs_node member kernel-doc
5e51f1082da0 drm/i915/engine: hide preempt_hang selftest member from kernel-doc
252b5418fc2c drm/i915/gtt: fix i915_vm_resv_put() kernel-doc parameter name
378a17d0b8bd drm/i915/context: fix kernel-doc parameter descriptions
50512647a486 drm/i915/engine: fix kernel-doc function name for intel_engine_cleanup_common()
80b0a872e853 drm/i915/ttm: fix i915_ttm_to_gem() kernel-doc
d4fbc5c22cd6 drm/i915/gem: fix function pointer member kernel-doc
bc02cfa5ca46 drm/i915/gem: fix i915_gem_object_lookup_rcu() kernel-doc parameter name
844b95a27beb drm/i915/request: drop kernel-doc
48b3951660b6 drm/i915/error: fix i915_capture_error_state() kernel-doc
cac8e4b6db10 drm/i915/perf: fix i915_perf_ioctl_version() kernel-doc
92562690fd06 drm/i915/vma: fix struct i915_vma_bindinfo kernel-doc
e962b41554a1 drm/i915/vma: document struct i915_vma_resource wakeref member
fa21baa66aaa drm/i915/utils: drop kernel-doc from __wait_for()
3c5d8150aa19 drm/i915/vma: fix kernel-doc function name for i915_vma_size()
0e1b3f55358a drm/i915/gvt: fix intel_vgpu_alloc_resource() kernel-doc parameter

== Logs ==

For more details see: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/index.html

[-- Attachment #2: Type: text/html, Size: 6209 bytes --]

[Intel-gfx] ✗ Fi.CI.IGT: failure for drm/i915: fix kernel-doc warnings, enable kernel-doc -Werror

[Patchwork]

[-- Attachment #1: Type: text/plain, Size: 8838 bytes --]

== Series Details ==

Series: drm/i915: fix kernel-doc warnings, enable kernel-doc -Werror
URL   : https://patchwork.freedesktop.org/series/117207/
State : failure

== Summary ==

CI Bug Log - changes from CI_DRM_13097_full -> Patchwork_117207v1_full
====================================================

Summary
-------

  **FAILURE**

  Serious unknown changes coming with Patchwork_117207v1_full absolutely need to be
  verified manually.
  
  If you think the reported changes have nothing to do with the changes
  introduced in Patchwork_117207v1_full, please notify your bug team to allow them
  to document this new failure mode, which will reduce false positives in CI.

  

Participating hosts (7 -> 8)
------------------------------

  Additional (1): shard-rkl0 

Possible new issues
-------------------

  Here are the unknown changes that may have been introduced in Patchwork_117207v1_full:

### IGT changes ###

#### Possible regressions ####

  * igt@perf_pmu@rc6-suspend:
    - shard-apl:          [PASS][1] -> [ABORT][2]
   [1]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_13097/shard-apl6/igt@perf_pmu@rc6-suspend.html
   [2]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/shard-apl6/igt@perf_pmu@rc6-suspend.html

  
Known issues
------------

  Here are the changes found in Patchwork_117207v1_full that come from known issues:

### IGT changes ###

#### Issues hit ####

  * igt@gem_barrier_race@remote-request@rcs0:
    - shard-apl:          [PASS][3] -> [ABORT][4] ([i915#7461] / [i915#8211] / [i915#8234])
   [3]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_13097/shard-apl7/igt@gem_barrier_race@remote-request@rcs0.html
   [4]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/shard-apl4/igt@gem_barrier_race@remote-request@rcs0.html

  * igt@gem_lmem_swapping@parallel-random-engines:
    - shard-glk:          NOTRUN -> [SKIP][5] ([fdo#109271] / [i915#4613])
   [5]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/shard-glk9/igt@gem_lmem_swapping@parallel-random-engines.html

  * igt@kms_atomic@plane-primary-overlay-mutable-zpos:
    - shard-glk:          NOTRUN -> [SKIP][6] ([fdo#109271]) +37 similar issues
   [6]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/shard-glk9/igt@kms_atomic@plane-primary-overlay-mutable-zpos.html

  * igt@kms_ccs@pipe-c-bad-pixel-format-y_tiled_gen12_rc_ccs_cc:
    - shard-glk:          NOTRUN -> [SKIP][7] ([fdo#109271] / [i915#3886]) +1 similar issue
   [7]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/shard-glk9/igt@kms_ccs@pipe-c-bad-pixel-format-y_tiled_gen12_rc_ccs_cc.html

  * igt@kms_cursor_legacy@flip-vs-cursor-atomic-transitions:
    - shard-glk:          [PASS][8] -> [FAIL][9] ([i915#2346])
   [8]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_13097/shard-glk8/igt@kms_cursor_legacy@flip-vs-cursor-atomic-transitions.html
   [9]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/shard-glk4/igt@kms_cursor_legacy@flip-vs-cursor-atomic-transitions.html

  * igt@kms_plane_scaling@planes-downscale-factor-0-5-unity-scaling@pipe-b-vga-1:
    - shard-snb:          NOTRUN -> [SKIP][10] ([fdo#109271]) +37 similar issues
   [10]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/shard-snb2/igt@kms_plane_scaling@planes-downscale-factor-0-5-unity-scaling@pipe-b-vga-1.html

  * igt@kms_psr2_sf@overlay-primary-update-sf-dmg-area:
    - shard-glk:          NOTRUN -> [SKIP][11] ([fdo#109271] / [i915#658])
   [11]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/shard-glk9/igt@kms_psr2_sf@overlay-primary-update-sf-dmg-area.html

  
#### Possible fixes ####

  * igt@gem_ctx_isolation@preservation-s3@vcs1:
    - {shard-dg1}:        [DMESG-WARN][12] ([i915#4391]) -> [PASS][13]
   [12]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_13097/shard-dg1-12/igt@gem_ctx_isolation@preservation-s3@vcs1.html
   [13]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/shard-dg1-13/igt@gem_ctx_isolation@preservation-s3@vcs1.html

  * igt@gem_exec_fair@basic-pace-share@rcs0:
    - {shard-tglu}:       [FAIL][14] ([i915#2842]) -> [PASS][15]
   [14]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_13097/shard-tglu-5/igt@gem_exec_fair@basic-pace-share@rcs0.html
   [15]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/shard-tglu-6/igt@gem_exec_fair@basic-pace-share@rcs0.html

  * igt@gen9_exec_parse@allowed-single:
    - shard-glk:          [ABORT][16] ([i915#5566]) -> [PASS][17]
   [16]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_13097/shard-glk3/igt@gen9_exec_parse@allowed-single.html
   [17]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/shard-glk9/igt@gen9_exec_parse@allowed-single.html

  * igt@i915_pm_rc6_residency@rc6-idle@vecs0:
    - {shard-dg1}:        [FAIL][18] ([i915#3591]) -> [PASS][19]
   [18]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_13097/shard-dg1-12/igt@i915_pm_rc6_residency@rc6-idle@vecs0.html
   [19]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/shard-dg1-12/igt@i915_pm_rc6_residency@rc6-idle@vecs0.html

  * igt@kms_cursor_legacy@2x-long-flip-vs-cursor-legacy:
    - shard-glk:          [FAIL][20] ([i915#72]) -> [PASS][21]
   [20]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_13097/shard-glk8/igt@kms_cursor_legacy@2x-long-flip-vs-cursor-legacy.html
   [21]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/shard-glk4/igt@kms_cursor_legacy@2x-long-flip-vs-cursor-legacy.html

  * igt@kms_cursor_legacy@single-move@pipe-b:
    - {shard-rkl}:        [INCOMPLETE][22] ([i915#8011]) -> [PASS][23]
   [22]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_13097/shard-rkl-7/igt@kms_cursor_legacy@single-move@pipe-b.html
   [23]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/shard-rkl-3/igt@kms_cursor_legacy@single-move@pipe-b.html

  * igt@kms_fbcon_fbt@fbc-suspend:
    - {shard-tglu}:       [FAIL][24] ([i915#4767]) -> [PASS][25]
   [24]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_13097/shard-tglu-10/igt@kms_fbcon_fbt@fbc-suspend.html
   [25]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/shard-tglu-4/igt@kms_fbcon_fbt@fbc-suspend.html

  
  {name}: This element is suppressed. This means it is ignored when computing
          the status of the difference (SUCCESS, WARNING, or FAILURE).

  [fdo#109271]: https://bugs.freedesktop.org/show_bug.cgi?id=109271
  [fdo#110189]: https://bugs.freedesktop.org/show_bug.cgi?id=110189
  [i915#1072]: https://gitlab.freedesktop.org/drm/intel/issues/1072
  [i915#1397]: https://gitlab.freedesktop.org/drm/intel/issues/1397
  [i915#2346]: https://gitlab.freedesktop.org/drm/intel/issues/2346
  [i915#2681]: https://gitlab.freedesktop.org/drm/intel/issues/2681
  [i915#2842]: https://gitlab.freedesktop.org/drm/intel/issues/2842
  [i915#3458]: https://gitlab.freedesktop.org/drm/intel/issues/3458
  [i915#3591]: https://gitlab.freedesktop.org/drm/intel/issues/3591
  [i915#3804]: https://gitlab.freedesktop.org/drm/intel/issues/3804
  [i915#3886]: https://gitlab.freedesktop.org/drm/intel/issues/3886
  [i915#3955]: https://gitlab.freedesktop.org/drm/intel/issues/3955
  [i915#4078]: https://gitlab.freedesktop.org/drm/intel/issues/4078
  [i915#4391]: https://gitlab.freedesktop.org/drm/intel/issues/4391
  [i915#4613]: https://gitlab.freedesktop.org/drm/intel/issues/4613
  [i915#4767]: https://gitlab.freedesktop.org/drm/intel/issues/4767
  [i915#5176]: https://gitlab.freedesktop.org/drm/intel/issues/5176
  [i915#5235]: https://gitlab.freedesktop.org/drm/intel/issues/5235
  [i915#5566]: https://gitlab.freedesktop.org/drm/intel/issues/5566
  [i915#658]: https://gitlab.freedesktop.org/drm/intel/issues/658
  [i915#72]: https://gitlab.freedesktop.org/drm/intel/issues/72
  [i915#7461]: https://gitlab.freedesktop.org/drm/intel/issues/7461
  [i915#7711]: https://gitlab.freedesktop.org/drm/intel/issues/7711
  [i915#8011]: https://gitlab.freedesktop.org/drm/intel/issues/8011
  [i915#8211]: https://gitlab.freedesktop.org/drm/intel/issues/8211
  [i915#8234]: https://gitlab.freedesktop.org/drm/intel/issues/8234
  [i915#8253]: https://gitlab.freedesktop.org/drm/intel/issues/8253
  [i915#8272]: https://gitlab.freedesktop.org/drm/intel/issues/8272


Build changes
-------------

  * Linux: CI_DRM_13097 -> Patchwork_117207v1

  CI-20190529: 20190529
  CI_DRM_13097: 1413856e3770380da743e274a06896acabf49e0e @ git://anongit.freedesktop.org/gfx-ci/linux
  IGT_7277: 1cb3507f3ff28d11bd5cfabcde576fe78ddab571 @ https://gitlab.freedesktop.org/drm/igt-gpu-tools.git
  Patchwork_117207v1: 1413856e3770380da743e274a06896acabf49e0e @ git://anongit.freedesktop.org/gfx-ci/linux
  piglit_4509: fdc5a4ca11124ab8413c7988896eec4c97336694 @ git://anongit.freedesktop.org/piglit

== Logs ==

For more details see: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_117207v1/index.html

[-- Attachment #2: Type: text/html, Size: 9199 bytes --]

Re: [Intel-gfx] [PATCH 01/24] drm/i915/gvt: fix intel_vgpu_alloc_resource() kernel-doc parameter

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:18PM +0300, Jani Nikula wrote:
> drivers/gpu/drm/i915/gvt/aperture_gm.c:344: warning: Function parameter or member 'conf' not described in 'intel_vgpu_alloc_resource'
> drivers/gpu/drm/i915/gvt/aperture_gm.c:344: warning: Excess function parameter 'param' description in 'intel_vgpu_alloc_resource'
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

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

> ---
>  drivers/gpu/drm/i915/gvt/aperture_gm.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/gpu/drm/i915/gvt/aperture_gm.c b/drivers/gpu/drm/i915/gvt/aperture_gm.c
> index 076c779f776a..eedd1865bb98 100644
> --- a/drivers/gpu/drm/i915/gvt/aperture_gm.c
> +++ b/drivers/gpu/drm/i915/gvt/aperture_gm.c
> @@ -330,7 +330,7 @@ void intel_vgpu_reset_resource(struct intel_vgpu *vgpu)
>  /**
>   * intel_vgpu_alloc_resource() - allocate HW resource for a vGPU
>   * @vgpu: vGPU
> - * @param: vGPU creation params
> + * @conf: vGPU creation params
>   *
>   * This function is used to allocate HW resource for a vGPU. User specifies
>   * the resource configuration through the creation params.
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 02/24] drm/i915/vma: fix kernel-doc function name for i915_vma_size()

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:19PM +0300, Jani Nikula wrote:
> drivers/gpu/drm/i915/i915_vma.h:145: warning: expecting prototype for i915_vma_offset(). Prototype was for i915_vma_size() instead
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

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

> ---
>  drivers/gpu/drm/i915/i915_vma.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/gpu/drm/i915/i915_vma.h b/drivers/gpu/drm/i915/i915_vma.h
> index ed5c9d682a1b..38c8c66ed724 100644
> --- a/drivers/gpu/drm/i915/i915_vma.h
> +++ b/drivers/gpu/drm/i915/i915_vma.h
> @@ -132,7 +132,7 @@ static inline u64 __i915_vma_size(const struct i915_vma *vma)
>  }
>  
>  /**
> - * i915_vma_offset - Obtain the va range size of the vma
> + * i915_vma_size - Obtain the va range size of the vma
>   * @vma: The vma
>   *
>   * GPU virtual address space may be allocated with padding. This
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 03/24] drm/i915/utils: drop kernel-doc from __wait_for()

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:20PM +0300, Jani Nikula wrote:
> The parameters aren't documented, and the file isn't included in Sphinx
> build anyway, so demote the kernel-doc to a regular comment.
> 
> drivers/gpu/drm/i915/i915_utils.h:284: warning: Function parameter or member 'OP' not described in '__wait_for'
> drivers/gpu/drm/i915/i915_utils.h:284: warning: Function parameter or member 'COND' not described in '__wait_for'
> drivers/gpu/drm/i915/i915_utils.h:284: warning: Function parameter or member 'US' not described in '__wait_for'
> drivers/gpu/drm/i915/i915_utils.h:284: warning: Function parameter or member 'Wmin' not described in '__wait_for'
> drivers/gpu/drm/i915/i915_utils.h:284: warning: Function parameter or member 'Wmax' not described in '__wait_for'
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

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

> ---
>  drivers/gpu/drm/i915/i915_utils.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/gpu/drm/i915/i915_utils.h b/drivers/gpu/drm/i915/i915_utils.h
> index 2c430c0c3bad..c61066498bf2 100644
> --- a/drivers/gpu/drm/i915/i915_utils.h
> +++ b/drivers/gpu/drm/i915/i915_utils.h
> @@ -250,7 +250,7 @@ wait_remaining_ms_from_jiffies(unsigned long timestamp_jiffies, int to_wait_ms)
>  	}
>  }
>  
> -/**
> +/*
>   * __wait_for - magic wait macro
>   *
>   * Macro to help avoid open coding check/wait/timeout patterns. Note that it's
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 05/24] drm/i915/vma: fix struct i915_vma_bindinfo kernel-doc

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:22PM +0300, Jani Nikula wrote:
> You can't document both a sub-struct type and a struct member at the
> same time. Separate them.

another way would be to kill the 'i915_vma_bindinfo' name entirely and
document only as '@bi:' and then move the individual documentations near
their definitions.

> 
> drivers/gpu/drm/i915/i915_vma_resource.h:91: warning: Incorrect use of kernel-doc format:          * struct i915_vma_bindinfo - Information needed for async bind
> drivers/gpu/drm/i915/i915_vma_resource.h:129: warning: Function parameter or member 'bi' not described in 'i915_vma_resource'
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> ---
>  drivers/gpu/drm/i915/i915_vma_resource.h | 45 ++++++++++++++----------
>  1 file changed, 27 insertions(+), 18 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/i915_vma_resource.h b/drivers/gpu/drm/i915/i915_vma_resource.h
> index 2053c037dbfb..ca2b0f7f59bc 100644
> --- a/drivers/gpu/drm/i915/i915_vma_resource.h
> +++ b/drivers/gpu/drm/i915/i915_vma_resource.h
> @@ -33,6 +33,27 @@ struct i915_page_sizes {
>  	unsigned int sg;
>  };
>  
> +/**
> + * struct i915_vma_bindinfo - Information needed for async bind
> + * only but that can be dropped after the bind has taken place.
> + * Consider making this a separate argument to the bind_vma
> + * op, coalescing with other arguments like vm, stash, cache_level
> + * and flags
> + * @pages: The pages sg-table.
> + * @page_sizes: Page sizes of the pages.
> + * @pages_rsgt: Refcounted sg-table when delayed object destruction
> + * is supported. May be NULL.
> + * @readonly: Whether the vma should be bound read-only.
> + * @lmem: Whether the vma points to lmem.
> + */
> +struct i915_vma_bindinfo {
> +	struct sg_table *pages;
> +	struct i915_page_sizes page_sizes;
> +	struct i915_refct_sgt *pages_rsgt;
> +	bool readonly:1;
> +	bool lmem:1;

btw, I believe we should move all the individual docs near to its
declarations. easier to forget updating the documentation when updating
fields here.

> +};
> +
>  /**
>   * struct i915_vma_resource - Snapshotted unbind information.
>   * @unbind_fence: Fence to mark unbinding complete. Note that this fence
> @@ -89,25 +110,13 @@ struct i915_vma_resource {
>  	intel_wakeref_t wakeref;
>  
>  	/**
> -	 * struct i915_vma_bindinfo - Information needed for async bind
> -	 * only but that can be dropped after the bind has taken place.
> -	 * Consider making this a separate argument to the bind_vma
> -	 * op, coalescing with other arguments like vm, stash, cache_level
> -	 * and flags
> -	 * @pages: The pages sg-table.
> -	 * @page_sizes: Page sizes of the pages.
> -	 * @pages_rsgt: Refcounted sg-table when delayed object destruction
> -	 * is supported. May be NULL.
> -	 * @readonly: Whether the vma should be bound read-only.
> -	 * @lmem: Whether the vma points to lmem.
> +	 * @bi: Information needed for async bind only but that can be dropped
> +	 * after the bind has taken place.
> +	 *
> +	 * Consider making this a separate argument to the bind_vma op,
> +	 * coalescing with other arguments like vm, stash, cache_level and flags
>  	 */
> -	struct i915_vma_bindinfo {
> -		struct sg_table *pages;
> -		struct i915_page_sizes page_sizes;
> -		struct i915_refct_sgt *pages_rsgt;
> -		bool readonly:1;
> -		bool lmem:1;
> -	} bi;
> +	struct i915_vma_bindinfo bi;
>  
>  #if IS_ENABLED(CONFIG_DRM_I915_CAPTURE_ERROR)
>  	struct intel_memory_region *mr;
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 06/24] drm/i915/perf: fix i915_perf_ioctl_version() kernel-doc

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:23PM +0300, Jani Nikula wrote:
> drivers/gpu/drm/i915/i915_perf.c:5307: warning: Function parameter or member 'i915' not described in 'i915_perf_ioctl_version'
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>


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

> ---
>  drivers/gpu/drm/i915/i915_perf.c | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/drivers/gpu/drm/i915/i915_perf.c b/drivers/gpu/drm/i915/i915_perf.c
> index 050b8ae7b8e7..19d5652300ee 100644
> --- a/drivers/gpu/drm/i915/i915_perf.c
> +++ b/drivers/gpu/drm/i915/i915_perf.c
> @@ -5300,6 +5300,7 @@ void i915_perf_fini(struct drm_i915_private *i915)
>  
>  /**
>   * i915_perf_ioctl_version - Version of the i915-perf subsystem
> + * @i915: The i915 device
>   *
>   * This version number is used by userspace to detect available features.
>   */
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 07/24] drm/i915/error: fix i915_capture_error_state() kernel-doc

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:24PM +0300, Jani Nikula wrote:
> drivers/gpu/drm/i915/i915_gpu_error.c:2174: warning: Function parameter or member 'dump_flags' not described in 'i915_capture_error_state'
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>


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


> ---
>  drivers/gpu/drm/i915/i915_gpu_error.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/gpu/drm/i915/i915_gpu_error.c b/drivers/gpu/drm/i915/i915_gpu_error.c
> index f020c0086fbc..04ad30274896 100644
> --- a/drivers/gpu/drm/i915/i915_gpu_error.c
> +++ b/drivers/gpu/drm/i915/i915_gpu_error.c
> @@ -2162,7 +2162,7 @@ void i915_error_state_store(struct i915_gpu_coredump *error)
>   * i915_capture_error_state - capture an error record for later analysis
>   * @gt: intel_gt which originated the hang
>   * @engine_mask: hung engines
> - *
> + * @dump_flags: dump flags
>   *
>   * Should be called when an error is detected (either a hang or an error
>   * interrupt) to capture error state from the time of the error.  Fills
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 04/24] drm/i915/vma: document struct i915_vma_resource wakeref member

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:21PM +0300, Jani Nikula wrote:
> drivers/gpu/drm/i915/i915_vma_resource.h:129: warning: Function parameter or member 'wakeref' not described in 'i915_vma_resource'
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> ---
>  drivers/gpu/drm/i915/i915_vma_resource.h | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/drivers/gpu/drm/i915/i915_vma_resource.h b/drivers/gpu/drm/i915/i915_vma_resource.h
> index c1864e3d0b43..2053c037dbfb 100644
> --- a/drivers/gpu/drm/i915/i915_vma_resource.h
> +++ b/drivers/gpu/drm/i915/i915_vma_resource.h
> @@ -47,6 +47,7 @@ struct i915_page_sizes {
>   * @chain: Pointer to struct i915_sw_fence used to await dependencies.
>   * @rb: Rb node for the vm's pending unbind interval tree.
>   * @__subtree_last: Interval tree private member.
> + * @wakeref: wakeref.

if all of these were near their declarations it wouldn't get missed.
But anyway, this is not part of this patch to move all of them, so


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


>   * @vm: non-refcounted pointer to the vm. This is for internal use only and
>   * this member is cleared after vm_resource unbind.
>   * @mr: The memory region of the object pointed to by the vma.
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 08/24] drm/i915/request: drop kernel-doc

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:25PM +0300, Jani Nikula wrote:
> The documentation is closer to not being kernel-doc. Just drop the
> kernel-doc /** indicators.
> 
> drivers/gpu/drm/i915/i915_request.h:176: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * Request queue structure.
> drivers/gpu/drm/i915/i915_request.h:477: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * Returns true if seq1 is later than seq2.
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> ---
>  drivers/gpu/drm/i915/i915_request.h | 52 ++++++++++++++---------------
>  1 file changed, 26 insertions(+), 26 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/i915_request.h b/drivers/gpu/drm/i915/i915_request.h
> index f5e1bb5e857a..0ac55b2e4223 100644
> --- a/drivers/gpu/drm/i915/i915_request.h
> +++ b/drivers/gpu/drm/i915/i915_request.h
> @@ -172,7 +172,7 @@ enum {
>  	I915_FENCE_FLAG_COMPOSITE,
>  };
>  
> -/**
> +/*
>   * Request queue structure.
>   *
>   * The request queue allows us to note sequence numbers that have been emitted
> @@ -198,7 +198,7 @@ struct i915_request {
>  
>  	struct drm_i915_private *i915;
>  
> -	/**
> +	/*
>  	 * Context and ring buffer related to this request
>  	 * Contexts are refcounted, so when this request is associated with a
>  	 * context, we must increment the context's refcount, to guarantee that
> @@ -251,9 +251,9 @@ struct i915_request {
>  	};
>  	struct llist_head execute_cb;
>  	struct i915_sw_fence semaphore;
> -	/**
> -	 * @submit_work: complete submit fence from an IRQ if needed for
> -	 * locking hierarchy reasons.
> +	/*
> +	 * complete submit fence from an IRQ if needed for locking hierarchy
> +	 * reasons.
>  	 */
>  	struct irq_work submit_work;
>  
> @@ -277,35 +277,35 @@ struct i915_request {
>  	 */
>  	const u32 *hwsp_seqno;
>  
> -	/** Position in the ring of the start of the request */
> +	/* Position in the ring of the start of the request */
>  	u32 head;
>  
> -	/** Position in the ring of the start of the user packets */
> +	/* Position in the ring of the start of the user packets */
>  	u32 infix;
>  
> -	/**
> +	/*
>  	 * Position in the ring of the start of the postfix.
>  	 * This is required to calculate the maximum available ring space
>  	 * without overwriting the postfix.
>  	 */
>  	u32 postfix;
>  
> -	/** Position in the ring of the end of the whole request */
> +	/* Position in the ring of the end of the whole request */
>  	u32 tail;
>  
> -	/** Position in the ring of the end of any workarounds after the tail */
> +	/* Position in the ring of the end of any workarounds after the tail */
>  	u32 wa_tail;
>  
> -	/** Preallocate space in the ring for the emitting the request */
> +	/* Preallocate space in the ring for the emitting the request */
>  	u32 reserved_space;
>  
> -	/** Batch buffer pointer for selftest internal use. */
> +	/* Batch buffer pointer for selftest internal use. */
>  	I915_SELFTEST_DECLARE(struct i915_vma *batch);
>  
>  	struct i915_vma_resource *batch_res;
>  
>  #if IS_ENABLED(CONFIG_DRM_I915_CAPTURE_ERROR)
> -	/**
> +	/*
>  	 * Additional buffers requested by userspace to be captured upon
>  	 * a GPU hang. The vma/obj on this list are protected by their
>  	 * active reference - all objects on this list must also be
> @@ -314,29 +314,29 @@ struct i915_request {
>  	struct i915_capture_list *capture_list;
>  #endif
>  
> -	/** Time at which this request was emitted, in jiffies. */
> +	/* Time at which this request was emitted, in jiffies. */
>  	unsigned long emitted_jiffies;
>  
> -	/** timeline->request entry for this request */
> +	/* timeline->request entry for this request */
>  	struct list_head link;
>  
> -	/** Watchdog support fields. */
> +	/* Watchdog support fields. */
>  	struct i915_request_watchdog {
>  		struct llist_node link;
>  		struct hrtimer timer;
>  	} watchdog;
>  
> -	/**
> -	 * @guc_fence_link: Requests may need to be stalled when using GuC
> -	 * submission waiting for certain GuC operations to complete. If that is
> -	 * the case, stalled requests are added to a per context list of stalled
> -	 * requests. The below list_head is the link in that list. Protected by
> +	/*
> +	 * Requests may need to be stalled when using GuC submission waiting for
> +	 * certain GuC operations to complete. If that is the case, stalled
> +	 * requests are added to a per context list of stalled requests. The
> +	 * below list_head is the link in that list. Protected by
>  	 * ce->guc_state.lock.
>  	 */
>  	struct list_head guc_fence_link;
>  
> -	/**
> -	 * @guc_prio: Priority level while the request is in flight. Differs
> +	/*
> +	 * Priority level while the request is in flight. Differs
>  	 * from i915 scheduler priority. See comment above
>  	 * I915_SCHEDULER_CAP_STATIC_PRIORITY_MAP for details. Protected by
>  	 * ce->guc_active.lock. Two special values (GUC_PRIO_INIT and
> @@ -348,8 +348,8 @@ struct i915_request {
>  #define	GUC_PRIO_FINI	0xfe
>  	u8 guc_prio;
>  
> -	/**
> -	 * @hucq: wait queue entry used to wait on the HuC load to complete
> +	/*
> +	 * wait queue entry used to wait on the HuC load to complete
>  	 */
>  	wait_queue_entry_t hucq;
>  
> @@ -473,7 +473,7 @@ i915_request_has_initial_breadcrumb(const struct i915_request *rq)
>  	return test_bit(I915_FENCE_FLAG_INITIAL_BREADCRUMB, &rq->fence.flags);
>  }
>  
> -/**
> +/*
>   * Returns true if seq1 is later than seq2.
>   */

hmmm... or all of these or properly move everything else to look like kernel doc,
but looking to this struct, let's just do this for now...


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


>  static inline bool i915_seqno_passed(u32 seq1, u32 seq2)
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 09/24] drm/i915/gem: fix i915_gem_object_lookup_rcu() kernel-doc parameter name

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:26PM +0300, Jani Nikula wrote:
> drivers/gpu/drm/i915/gem/i915_gem_object.h:94: warning: Function parameter or member 'file' not described in 'i915_gem_object_lookup_rcu'
> drivers/gpu/drm/i915/gem/i915_gem_object.h:94: warning: Excess function parameter 'filp' description in 'i915_gem_object_lookup_rcu'
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

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

> ---
>  drivers/gpu/drm/i915/gem/i915_gem_object.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/gpu/drm/i915/gem/i915_gem_object.h b/drivers/gpu/drm/i915/gem/i915_gem_object.h
> index 885ccde9dc3c..bc1291887d4f 100644
> --- a/drivers/gpu/drm/i915/gem/i915_gem_object.h
> +++ b/drivers/gpu/drm/i915/gem/i915_gem_object.h
> @@ -80,7 +80,7 @@ __i915_gem_object_unset_pages(struct drm_i915_gem_object *obj);
>  
>  /**
>   * i915_gem_object_lookup_rcu - look up a temporary GEM object from its handle
> - * @filp: DRM file private date
> + * @file: DRM file private date
>   * @handle: userspace handle
>   *
>   * Returns:
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 10/24] drm/i915/gem: fix function pointer member kernel-doc

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:27PM +0300, Jani Nikula wrote:
> You can't document function pointer member as functions.
>
> drivers/gpu/drm/i915/gem/i915_gem_region.h:25: warning: Incorrect use of kernel-doc format:          * process_obj - Process the current object
> drivers/gpu/drm/i915/gem/i915_gem_region.h:35: warning: Function parameter or member 'process_obj' not described in 'i915_gem_apply_to_region_ops'
>
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> ---
>  drivers/gpu/drm/i915/gem/i915_gem_region.h | 4 +---
>  1 file changed, 1 insertion(+), 3 deletions(-)
>
> diff --git a/drivers/gpu/drm/i915/gem/i915_gem_region.h b/drivers/gpu/drm/i915/gem/i915_gem_region.h
> index 2dfcc41c0170..8a7650b27cc2 100644
> --- a/drivers/gpu/drm/i915/gem/i915_gem_region.h
> +++ b/drivers/gpu/drm/i915/gem/i915_gem_region.h
> @@ -22,9 +22,7 @@ struct i915_gem_apply_to_region;
>   */
>  struct i915_gem_apply_to_region_ops {
>  	/**
> -	 * process_obj - Process the current object
> -	 * @apply: Embed this for private data.
> -	 * @obj: The current object.
> +	 * @process_obj: Process the current object

hmm...
looking to the process_obj itself I wonder if we don't have a better way
to document these function pointer arguments that could be acceptable
instead of simply removing them.

+Mauro in case he has some idea.

and the declaration for reference:

 int (*process_obj)(struct i915_gem_apply_to_region *apply,
                           struct drm_i915_gem_object *obj);

>  	 *
>  	 * Note that if this function is part of a ww transaction, and
>  	 * if returns -EDEADLK for one of the objects, it may be
> --
> 2.39.2
>

Re: [Intel-gfx] [PATCH 11/24] drm/i915/ttm: fix i915_ttm_to_gem() kernel-doc

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:28PM +0300, Jani Nikula wrote:
> drivers/gpu/drm/i915/gem/i915_gem_ttm.h:50: warning: Function parameter or member 'bo' not described in 'i915_ttm_to_gem'
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> ---
>  drivers/gpu/drm/i915/gem/i915_gem_ttm.h | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/drivers/gpu/drm/i915/gem/i915_gem_ttm.h b/drivers/gpu/drm/i915/gem/i915_gem_ttm.h
> index f8f6bed1b297..70abdc3061a9 100644
> --- a/drivers/gpu/drm/i915/gem/i915_gem_ttm.h
> +++ b/drivers/gpu/drm/i915/gem/i915_gem_ttm.h
> @@ -42,6 +42,7 @@ static inline bool i915_ttm_is_ghost_object(struct ttm_buffer_object *bo)
>  /**
>   * i915_ttm_to_gem - Convert a struct ttm_buffer_object to an embedding
>   * struct drm_i915_gem_object.
> + * @bo: Pointer to the ttm buffer object
>   *
>   * Return: Pointer to the embedding struct ttm_buffer_object.

I understand the goal is to fix the warnings, but while at it,
would you mind also fixing the Return?

this was likely a bad copy and paste from i915_gem_to_ttm
and the right one should be something like

Return: Pointer to the embedding struct drm_i915_gem_object.

>   */
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 12/24] drm/i915/engine: fix kernel-doc function name for intel_engine_cleanup_common()

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:29PM +0300, Jani Nikula wrote:
> drivers/gpu/drm/i915/gt/intel_engine_cs.c:1525: warning: expecting prototype for intel_engines_cleanup_common(). Prototype was for intel_engine_cleanup_common() instead
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

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

> ---
>  drivers/gpu/drm/i915/gt/intel_engine_cs.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/gpu/drm/i915/gt/intel_engine_cs.c b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> index 5c6c9a6d469c..0aff5bb13c53 100644
> --- a/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> +++ b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> @@ -1515,7 +1515,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.
>   *
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 13/24] drm/i915/context: fix kernel-doc parameter descriptions

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:30PM +0300, Jani Nikula wrote:
> drivers/gpu/drm/i915/gt/intel_context.h:108: warning: Function parameter or member 'ce' not described in 'intel_context_lock_pinned'
> drivers/gpu/drm/i915/gt/intel_context.h:123: warning: Function parameter or member 'ce' not described in 'intel_context_is_pinned'
> drivers/gpu/drm/i915/gt/intel_context.h:142: warning: Function parameter or member 'ce' not described in 'intel_context_unlock_pinned'
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

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

> ---
>  drivers/gpu/drm/i915/gt/intel_context.h | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/gt/intel_context.h b/drivers/gpu/drm/i915/gt/intel_context.h
> index 48f888c3da08..6b5eae7b88bc 100644
> --- a/drivers/gpu/drm/i915/gt/intel_context.h
> +++ b/drivers/gpu/drm/i915/gt/intel_context.h
> @@ -97,7 +97,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.
> @@ -111,7 +111,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.
> @@ -133,7 +133,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().
>   */
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 14/24] drm/i915/gtt: fix i915_vm_resv_put() kernel-doc parameter name

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:31PM +0300, Jani Nikula wrote:
> drivers/gpu/drm/i915/gt/intel_gtt.h:515: warning: Function parameter or member 'vm' not described in 'i915_vm_resv_put'
> drivers/gpu/drm/i915/gt/intel_gtt.h:515: warning: Excess function parameter 'resv' description in 'i915_vm_resv_put'
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

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

> ---
>  drivers/gpu/drm/i915/gt/intel_gtt.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/gpu/drm/i915/gt/intel_gtt.h b/drivers/gpu/drm/i915/gt/intel_gtt.h
> index 1910683f03b4..9aff343beaa8 100644
> --- a/drivers/gpu/drm/i915/gt/intel_gtt.h
> +++ b/drivers/gpu/drm/i915/gt/intel_gtt.h
> @@ -509,7 +509,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 reference we want to release
>   */
>  static inline void i915_vm_resv_put(struct i915_address_space *vm)
>  {
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 15/24] drm/i915/engine: hide preempt_hang selftest member from kernel-doc

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:32PM +0300, Jani Nikula wrote:
> drivers/gpu/drm/i915/gt/intel_engine_types.h:293: warning: Function parameter or member 'preempt_hang' not described in 'intel_engine_execlists'
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

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

> ---
>  drivers/gpu/drm/i915/gt/intel_engine_types.h | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/drivers/gpu/drm/i915/gt/intel_engine_types.h b/drivers/gpu/drm/i915/gt/intel_engine_types.h
> index 960291f88fd6..e99a6fa03d45 100644
> --- a/drivers/gpu/drm/i915/gt/intel_engine_types.h
> +++ b/drivers/gpu/drm/i915/gt/intel_engine_types.h
> @@ -289,6 +289,7 @@ struct intel_engine_execlists {
>  	 */
>  	u8 csb_head;
>  
> +	/* private: selftest */
>  	I915_SELFTEST_DECLARE(struct st_preempt_hang preempt_hang;)
>  };
>  
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 16/24] drm/i915/guc: add dbgfs_node member kernel-doc

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:33PM +0300, Jani Nikula wrote:
> drivers/gpu/drm/i915/gt/uc/intel_guc.h:274: warning: Function parameter or member 'dbgfs_node' not described in 'intel_guc'
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

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

> ---
>  drivers/gpu/drm/i915/gt/uc/intel_guc.h | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc.h b/drivers/gpu/drm/i915/gt/uc/intel_guc.h
> index e46aac1a41e6..8dc291ff0093 100644
> --- a/drivers/gpu/drm/i915/gt/uc/intel_guc.h
> +++ b/drivers/gpu/drm/i915/gt/uc/intel_guc.h
> @@ -42,6 +42,7 @@ struct intel_guc {
>  	/** @capture: the error-state-capture module's data and objects */
>  	struct intel_guc_state_capture *capture;
>  
> +	/** @dbgfs_node: debugfs node */
>  	struct dentry *dbgfs_node;
>  
>  	/** @sched_engine: Global engine used to submit requests to GuC */
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 17/24] drm/i915/guc: drop lots of kernel-doc markers

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:34PM +0300, Jani Nikula wrote:
> The documentation is closer to not being kernel-doc, so just drop the
> kernel-doc markers.
> 
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:27: warning: Function parameter or member 'size' not described in '__guc_capture_bufstate'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:27: warning: Function parameter or member 'data' not described in '__guc_capture_bufstate'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:27: warning: Function parameter or member 'rd' not described in '__guc_capture_bufstate'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:27: warning: Function parameter or member 'wr' not described in '__guc_capture_bufstate'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:59: warning: Function parameter or member 'link' not described in '__guc_capture_parsed_output'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:59: warning: Function parameter or member 'is_partial' not described in '__guc_capture_parsed_output'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:59: warning: Function parameter or member 'eng_class' not described in '__guc_capture_parsed_output'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:59: warning: Function parameter or member 'eng_inst' not described in '__guc_capture_parsed_output'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:59: warning: Function parameter or member 'guc_id' not described in '__guc_capture_parsed_output'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:59: warning: Function parameter or member 'lrca' not described in '__guc_capture_parsed_output'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:59: warning: Function parameter or member 'reginfo' not described in '__guc_capture_parsed_output'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:62: 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:80: 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:105: 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:163: warning: Function parameter or member 'is_valid' not described in '__guc_capture_ads_cache'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:163: warning: Function parameter or member 'ptr' not described in '__guc_capture_ads_cache'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:163: warning: Function parameter or member 'size' not described in '__guc_capture_ads_cache'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:163: warning: Function parameter or member 'status' not described in '__guc_capture_ads_cache'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:491: warning: Function parameter or member 'marker' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:491: warning: Function parameter or member 'read_ptr' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:491: warning: Function parameter or member 'write_ptr' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:491: warning: Function parameter or member 'size' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:491: 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:491: warning: Function parameter or member 'wrap_offset' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:491: 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:491: 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:491: warning: Function parameter or member 'reserved' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:491: warning: Function parameter or member 'flags' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:491: warning: Function parameter or member 'version' not described in 'guc_log_buffer_state'
> 

It looks they are all internal and the only one that deserves documentation
is intel_guc_state_capture and that is properly documented...

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

> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> ---
>  drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h | 12 ++++++------
>  drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h   |  2 +-
>  2 files changed, 7 insertions(+), 7 deletions(-)
> 
> 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 9d589c28f40f..1b6c219e1675 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[];
>  } __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[];
>  } __packed;
>  
> -/**
> +/*
>   * struct __guc_capture_ads_cache
>   *
>   * A structure to cache register lists that were populated and registered
> 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 4ae5fc2f6002..8bb9ed7c7b4d 100644
> --- a/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h
> +++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h
> @@ -451,7 +451,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.39.2
> 

Re: [Intel-gfx] [PATCH 18/24] drm/i915/guc: add intel_guc_state_capture member docs for ads_null_cache and max_mmio_per_node

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:35PM +0300, Jani Nikula wrote:
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:216: 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:216: warning: Function parameter or member 'max_mmio_per_node' not described in 'intel_guc_state_capture'
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

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

> ---
>  drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> 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 1b6c219e1675..1fc0c17b1230 100644
> --- a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> +++ b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> @@ -187,6 +187,10 @@ struct intel_guc_state_capture {
>  	struct __guc_capture_ads_cache ads_cache[GUC_CAPTURE_LIST_INDEX_MAX]
>  						[GUC_CAPTURE_LIST_TYPE_MAX]
>  						[GUC_MAX_ENGINE_CLASSES];
> +
> +	/**
> +	 * @ads_null_cache: ADS null cache.
> +	 */
>  	void *ads_null_cache;
>  
>  	/**
> @@ -202,6 +206,10 @@ struct intel_guc_state_capture {
>  	struct list_head cachelist;
>  #define PREALLOC_NODES_MAX_COUNT (3 * GUC_MAX_ENGINE_CLASSES * GUC_MAX_INSTANCES_PER_CLASS)
>  #define PREALLOC_NODES_DEFAULT_NUMREGS 64
> +
> +	/**
> +	 * @max_mmio_per_node: Max MMIO per node.
> +	 */
>  	int max_mmio_per_node;
>  
>  	/**
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 19/24] drm/i915/active: fix kernel-doc for function parameters

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:36PM +0300, Jani Nikula wrote:
> drivers/gpu/drm/i915/i915_active.h:66: warning: Function parameter or member 'active' not described in '__i915_active_fence_init'
> drivers/gpu/drm/i915/i915_active.h:66: warning: Function parameter or member 'fence' not described in '__i915_active_fence_init'
> drivers/gpu/drm/i915/i915_active.h:66: warning: Function parameter or member 'fn' not described in '__i915_active_fence_init'
> drivers/gpu/drm/i915/i915_active.h:89: warning: Function parameter or member 'active' not described in 'i915_active_fence_set'
> drivers/gpu/drm/i915/i915_active.h:89: warning: Function parameter or member 'rq' not described in 'i915_active_fence_set'
> drivers/gpu/drm/i915/i915_active.h:102: warning: Function parameter or member 'active' not described in 'i915_active_fence_get'
> drivers/gpu/drm/i915/i915_active.h:122: warning: Function parameter or member 'active' not described in 'i915_active_fence_isset'
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

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

> ---
>  drivers/gpu/drm/i915/i915_active.h | 14 +++++++-------
>  1 file changed, 7 insertions(+), 7 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/i915_active.h b/drivers/gpu/drm/i915/i915_active.h
> index 7eb44132183a..77c676ecc263 100644
> --- a/drivers/gpu/drm/i915/i915_active.h
> +++ b/drivers/gpu/drm/i915/i915_active.h
> @@ -49,9 +49,9 @@ void i915_active_noop(struct dma_fence *fence, struct dma_fence_cb *cb);
>  
>  /**
>   * __i915_active_fence_init - prepares the activity tracker for use
> - * @active - the active tracker
> - * @fence - initial fence to track, can be NULL
> - * @func - a callback when then the tracker is retired (becomes idle),
> + * @active: the active tracker
> + * @fence: initial fence to track, can be NULL
> + * @fn: a callback when then the tracker is retired (becomes idle),
>   *         can be NULL
>   *
>   * i915_active_fence_init() prepares the embedded @active struct for use as
> @@ -77,8 +77,8 @@ __i915_active_fence_set(struct i915_active_fence *active,
>  
>  /**
>   * i915_active_fence_set - updates the tracker to watch the current fence
> - * @active - the active tracker
> - * @rq - the request to watch
> + * @active: the active tracker
> + * @rq: the request to watch
>   *
>   * i915_active_fence_set() watches the given @rq for completion. While
>   * that @rq is busy, the @active reports busy. When that @rq is signaled
> @@ -89,7 +89,7 @@ i915_active_fence_set(struct i915_active_fence *active,
>  		      struct i915_request *rq);
>  /**
>   * i915_active_fence_get - return a reference to the active fence
> - * @active - the active tracker
> + * @active: the active tracker
>   *
>   * i915_active_fence_get() returns a reference to the active fence,
>   * or NULL if the active tracker is idle. The reference is obtained under RCU,
> @@ -111,7 +111,7 @@ i915_active_fence_get(struct i915_active_fence *active)
>  
>  /**
>   * i915_active_fence_isset - report whether the active tracker is assigned
> - * @active - the active tracker
> + * @active: the active tracker
>   *
>   * i915_active_fence_isset() returns true if the active tracker is currently
>   * assigned to a fence. Due to the lazy retiring, that fence may be idle
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 20/24] drm/i915/pmu: drop kernel-doc

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:37PM +0300, Jani Nikula wrote:
> The comments are closer to not being kernel-doc.
> 
> drivers/gpu/drm/i915/i915_pmu.h:21: warning: cannot understand function prototype: 'enum i915_pmu_tracked_events '
> drivers/gpu/drm/i915/i915_pmu.h:32: warning: cannot understand function prototype: 'enum '
> drivers/gpu/drm/i915/i915_pmu.h:41: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * How many different events we track in the global PMU mask.
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

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

> ---
>  drivers/gpu/drm/i915/i915_pmu.h | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/i915_pmu.h b/drivers/gpu/drm/i915/i915_pmu.h
> index 449057648f39..c30f43319a78 100644
> --- a/drivers/gpu/drm/i915/i915_pmu.h
> +++ b/drivers/gpu/drm/i915/i915_pmu.h
> @@ -14,7 +14,7 @@
>  
>  struct drm_i915_private;
>  
> -/**
> +/*
>   * Non-engine events that we need to track enabled-disabled transition and
>   * current state.
>   */
> @@ -25,7 +25,7 @@ enum i915_pmu_tracked_events {
>  	__I915_PMU_TRACKED_EVENT_COUNT, /* count marker */
>  };
>  
> -/**
> +/*
>   * Slots used from the sampling timer (non-engine events) with some extras for
>   * convenience.
>   */
> @@ -37,7 +37,7 @@ enum {
>  	__I915_NUM_PMU_SAMPLERS
>  };
>  
> -/**
> +/*
>   * How many different events we track in the global PMU mask.
>   *
>   * It is also used to know to needed number of event reference counters.
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 21/24] drm/i915/pxp: fix kernel-doc for member dev_link

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:38PM +0300, Jani Nikula wrote:
> Add /** to make it a kernel-doc.
> 
> drivers/gpu/drm/i915/pxp/intel_pxp_types.h:96: warning: Function parameter or member 'dev_link' not described in 'intel_pxp'
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

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

> ---
>  drivers/gpu/drm/i915/pxp/intel_pxp_types.h | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/drivers/gpu/drm/i915/pxp/intel_pxp_types.h b/drivers/gpu/drm/i915/pxp/intel_pxp_types.h
> index 007de49e1ea4..c445f7f2f47a 100644
> --- a/drivers/gpu/drm/i915/pxp/intel_pxp_types.h
> +++ b/drivers/gpu/drm/i915/pxp/intel_pxp_types.h
> @@ -33,7 +33,9 @@ struct intel_pxp {
>  	 */
>  	struct i915_pxp_component *pxp_component;
>  
> -	/* @dev_link: Enforce module relationship for power management ordering. */
> +	/**
> +	 * @dev_link: Enforce module relationship for power management ordering.
> +	 */
>  	struct device_link *dev_link;
>  	/**
>  	 * @pxp_component_added: track if the pxp component has been added.
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 23/24] drm/i915/scatterlist: fix kernel-doc parameter documentation

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:40PM +0300, Jani Nikula wrote:
> drivers/gpu/drm/i915/i915_scatterlist.h:164: warning: Function parameter or member 'release' not described in 'i915_refct_sgt_ops'
> drivers/gpu/drm/i915/i915_scatterlist.h:187: warning: Function parameter or member 'rsgt' not described in 'i915_refct_sgt_put'
> drivers/gpu/drm/i915/i915_scatterlist.h:198: warning: Function parameter or member 'rsgt' not described in 'i915_refct_sgt_get'
> drivers/gpu/drm/i915/i915_scatterlist.h:214: warning: Function parameter or member 'rsgt' not described in '__i915_refct_sgt_init'
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

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

> ---
>  drivers/gpu/drm/i915/i915_scatterlist.h | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/i915_scatterlist.h b/drivers/gpu/drm/i915/i915_scatterlist.h
> index fe9ae863f9b9..5a10c1a31183 100644
> --- a/drivers/gpu/drm/i915/i915_scatterlist.h
> +++ b/drivers/gpu/drm/i915/i915_scatterlist.h
> @@ -180,7 +180,7 @@ struct i915_refct_sgt {
>  
>  /**
>   * i915_refct_sgt_put - Put a refcounted sg-table
> - * @rsgt the struct i915_refct_sgt to put.
> + * @rsgt: the struct i915_refct_sgt to put.
>   */
>  static inline void i915_refct_sgt_put(struct i915_refct_sgt *rsgt)
>  {
> @@ -190,7 +190,7 @@ static inline void i915_refct_sgt_put(struct i915_refct_sgt *rsgt)
>  
>  /**
>   * i915_refct_sgt_get - Get a refcounted sg-table
> - * @rsgt the struct i915_refct_sgt to get.
> + * @rsgt: the struct i915_refct_sgt to get.
>   */
>  static inline struct i915_refct_sgt *
>  i915_refct_sgt_get(struct i915_refct_sgt *rsgt)
> @@ -202,7 +202,7 @@ i915_refct_sgt_get(struct i915_refct_sgt *rsgt)
>  /**
>   * __i915_refct_sgt_init - Initialize a refcounted sg-list with a custom
>   * operations structure
> - * @rsgt The struct i915_refct_sgt to initialize.
> + * @rsgt: The struct i915_refct_sgt to initialize.
>   * @size: Size in bytes of the underlying memory buffer.
>   * @ops: A customized operations structure in case the refcounted sg-list
>   * is embedded into another structure.
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 24/24] drm/i915: use kernel-doc -Werror when CONFIG_DRM_I915_WERROR=y

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:41PM +0300, Jani Nikula wrote:
> With CONFIG_DRM_I915_WERROR=y, we enable kernel-doc check for both
> objects and headers. Now that the kernel-doc warnings have been fixed,
> also enable kernel-doc -Werror to fail the build on kernel-doc warnings.
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

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

> ---
>  drivers/gpu/drm/i915/Makefile | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/Makefile b/drivers/gpu/drm/i915/Makefile
> index 9af76e376ca9..f43734f13471 100644
> --- a/drivers/gpu/drm/i915/Makefile
> +++ b/drivers/gpu/drm/i915/Makefile
> @@ -377,7 +377,7 @@ obj-$(CONFIG_DRM_I915_GVT_KVMGT) += kvmgt.o
>  #
>  # Enable locally for CONFIG_DRM_I915_WERROR=y. See also scripts/Makefile.build
>  ifdef CONFIG_DRM_I915_WERROR
> -    cmd_checkdoc = $(srctree)/scripts/kernel-doc -none $<
> +    cmd_checkdoc = $(srctree)/scripts/kernel-doc -none -Werror $<
>  endif
>  
>  # header test
> @@ -392,7 +392,7 @@ always-$(CONFIG_DRM_I915_WERROR) += \
>  
>  quiet_cmd_hdrtest = HDRTEST $(patsubst %.hdrtest,%.h,$@)
>        cmd_hdrtest = $(CC) $(filter-out $(CFLAGS_GCOV), $(c_flags)) -S -o /dev/null -x c /dev/null -include $<; \
> -		$(srctree)/scripts/kernel-doc -none $<; touch $@
> +		$(srctree)/scripts/kernel-doc -none -Werror $<; touch $@
>  
>  $(obj)/%.hdrtest: $(src)/%.h FORCE
>  	$(call if_changed_dep,hdrtest)
> -- 
> 2.39.2
> 

Re: [Intel-gfx] [PATCH 01/24] drm/i915/gvt: fix intel_vgpu_alloc_resource() kernel-doc parameter

[Jani Nikula]

On Wed, 03 May 2023, Rodrigo Vivi <rodrigo.vivi@kernel.org> wrote:
> On Tue, May 02, 2023 at 06:37:18PM +0300, Jani Nikula wrote:
>> drivers/gpu/drm/i915/gvt/aperture_gm.c:344: warning: Function parameter or member 'conf' not described in 'intel_vgpu_alloc_resource'
>> drivers/gpu/drm/i915/gvt/aperture_gm.c:344: warning: Excess function parameter 'param' description in 'intel_vgpu_alloc_resource'
>> 
>> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
>
> Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>

Thanks for the reviews. Pushed the reviewed ones to drm-intel-gt-next,
and will repost the rest separately as we get clarity on them.

BR,
Jani.


>
>> ---
>>  drivers/gpu/drm/i915/gvt/aperture_gm.c | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>> 
>> diff --git a/drivers/gpu/drm/i915/gvt/aperture_gm.c b/drivers/gpu/drm/i915/gvt/aperture_gm.c
>> index 076c779f776a..eedd1865bb98 100644
>> --- a/drivers/gpu/drm/i915/gvt/aperture_gm.c
>> +++ b/drivers/gpu/drm/i915/gvt/aperture_gm.c
>> @@ -330,7 +330,7 @@ void intel_vgpu_reset_resource(struct intel_vgpu *vgpu)
>>  /**
>>   * intel_vgpu_alloc_resource() - allocate HW resource for a vGPU
>>   * @vgpu: vGPU
>> - * @param: vGPU creation params
>> + * @conf: vGPU creation params
>>   *
>>   * This function is used to allocate HW resource for a vGPU. User specifies
>>   * the resource configuration through the creation params.
>> -- 
>> 2.39.2
>> 

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [Intel-gfx] [PATCH 10/24] drm/i915/gem: fix function pointer member kernel-doc

[Jani Nikula]

On Wed, 03 May 2023, Rodrigo Vivi <rodrigo.vivi@kernel.org> wrote:
> On Tue, May 02, 2023 at 06:37:27PM +0300, Jani Nikula wrote:
>> You can't document function pointer member as functions.
>>
>> drivers/gpu/drm/i915/gem/i915_gem_region.h:25: warning: Incorrect use of kernel-doc format:          * process_obj - Process the current object
>> drivers/gpu/drm/i915/gem/i915_gem_region.h:35: warning: Function parameter or member 'process_obj' not described in 'i915_gem_apply_to_region_ops'
>>
>> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
>> ---
>>  drivers/gpu/drm/i915/gem/i915_gem_region.h | 4 +---
>>  1 file changed, 1 insertion(+), 3 deletions(-)
>>
>> diff --git a/drivers/gpu/drm/i915/gem/i915_gem_region.h b/drivers/gpu/drm/i915/gem/i915_gem_region.h
>> index 2dfcc41c0170..8a7650b27cc2 100644
>> --- a/drivers/gpu/drm/i915/gem/i915_gem_region.h
>> +++ b/drivers/gpu/drm/i915/gem/i915_gem_region.h
>> @@ -22,9 +22,7 @@ struct i915_gem_apply_to_region;
>>   */
>>  struct i915_gem_apply_to_region_ops {
>>  	/**
>> -	 * process_obj - Process the current object
>> -	 * @apply: Embed this for private data.
>> -	 * @obj: The current object.
>> +	 * @process_obj: Process the current object
>
> hmm...
> looking to the process_obj itself I wonder if we don't have a better way
> to document these function pointer arguments that could be acceptable
> instead of simply removing them.

The alternative is pretty much to document the parameters in plain text
or some mild rst formatting that's not specifically kernel-doc parameter
documentation.

BR,
Jani.

>
> +Mauro in case he has some idea.
>
> and the declaration for reference:
>
>  int (*process_obj)(struct i915_gem_apply_to_region *apply,
>                            struct drm_i915_gem_object *obj);
>
>>  	 *
>>  	 * Note that if this function is part of a ww transaction, and
>>  	 * if returns -EDEADLK for one of the objects, it may be
>> --
>> 2.39.2
>>

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [Intel-gfx] [PATCH 11/24] drm/i915/ttm: fix i915_ttm_to_gem() kernel-doc

[Jani Nikula]

On Wed, 03 May 2023, Rodrigo Vivi <rodrigo.vivi@kernel.org> wrote:
> On Tue, May 02, 2023 at 06:37:28PM +0300, Jani Nikula wrote:
>> drivers/gpu/drm/i915/gem/i915_gem_ttm.h:50: warning: Function parameter or member 'bo' not described in 'i915_ttm_to_gem'
>> 
>> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
>> ---
>>  drivers/gpu/drm/i915/gem/i915_gem_ttm.h | 1 +
>>  1 file changed, 1 insertion(+)
>> 
>> diff --git a/drivers/gpu/drm/i915/gem/i915_gem_ttm.h b/drivers/gpu/drm/i915/gem/i915_gem_ttm.h
>> index f8f6bed1b297..70abdc3061a9 100644
>> --- a/drivers/gpu/drm/i915/gem/i915_gem_ttm.h
>> +++ b/drivers/gpu/drm/i915/gem/i915_gem_ttm.h
>> @@ -42,6 +42,7 @@ static inline bool i915_ttm_is_ghost_object(struct ttm_buffer_object *bo)
>>  /**
>>   * i915_ttm_to_gem - Convert a struct ttm_buffer_object to an embedding
>>   * struct drm_i915_gem_object.
>> + * @bo: Pointer to the ttm buffer object
>>   *
>>   * Return: Pointer to the embedding struct ttm_buffer_object.
>
> I understand the goal is to fix the warnings, but while at it,
> would you mind also fixing the Return?
>
> this was likely a bad copy and paste from i915_gem_to_ttm
> and the right one should be something like
>
> Return: Pointer to the embedding struct drm_i915_gem_object.

v2 at https://patchwork.freedesktop.org/patch/msgid/20230504092320.1787627-1-jani.nikula@intel.com

>
>>   */
>> -- 
>> 2.39.2
>> 

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [Intel-gfx] [PATCH 05/24] drm/i915/vma: fix struct i915_vma_bindinfo kernel-doc

[Jani Nikula]

On Wed, 03 May 2023, Rodrigo Vivi <rodrigo.vivi@kernel.org> wrote:
> On Tue, May 02, 2023 at 06:37:22PM +0300, Jani Nikula wrote:
>> You can't document both a sub-struct type and a struct member at the
>> same time. Separate them.
>
> another way would be to kill the 'i915_vma_bindinfo' name entirely and
> document only as '@bi:' and then move the individual documentations near
> their definitions.

I don't think that will work, because AFAIK kernel-doc does not descend
into struct members recursively.

You can either declare and document the sub-structs as separate types
(the patch at hand), or you can document sub-struct members directly
from the embedding struct as shown below. I don't think the latter is
very nice.

BR,
Jani.


index 2053c037dbfb..ee767cc4de43 100644
--- a/drivers/gpu/drm/i915/i915_vma_resource.h
+++ b/drivers/gpu/drm/i915/i915_vma_resource.h
@@ -48,6 +48,12 @@ struct i915_page_sizes {
  * @rb: Rb node for the vm's pending unbind interval tree.
  * @__subtree_last: Interval tree private member.
  * @wakeref: wakeref.
+ * @bi.pages: The pages sg-table.
+ * @bi.page_sizes: Page sizes of the pages.
+ * @bi.pages_rsgt: Refcounted sg-table when delayed object destruction
+ * is supported. May be NULL.
+ * @bi.readonly: Whether the vma should be bound read-only.
+ * @bi.lmem: Whether the vma points to lmem.
  * @vm: non-refcounted pointer to the vm. This is for internal use only and
  * this member is cleared after vm_resource unbind.
  * @mr: The memory region of the object pointed to by the vma.
@@ -89,17 +95,11 @@ struct i915_vma_resource {
        intel_wakeref_t wakeref;
 
        /**
-        * struct i915_vma_bindinfo - Information needed for async bind
-        * only but that can be dropped after the bind has taken place.
-        * Consider making this a separate argument to the bind_vma
-        * op, coalescing with other arguments like vm, stash, cache_level
-        * and flags
-        * @pages: The pages sg-table.
-        * @page_sizes: Page sizes of the pages.
-        * @pages_rsgt: Refcounted sg-table when delayed object destruction
-        * is supported. May be NULL.
-        * @readonly: Whether the vma should be bound read-only.
-        * @lmem: Whether the vma points to lmem.
+        * @bi: Information needed for async bind only but that can be dropped
+        * after the bind has taken place.
+        *
+        * Consider making this a separate argument to the bind_vma op,
+        * coalescing with other arguments like vm, stash, cache_level and flags
         */
        struct i915_vma_bindinfo {
                struct sg_table *pages;


>
>> 
>> drivers/gpu/drm/i915/i915_vma_resource.h:91: warning: Incorrect use of kernel-doc format:          * struct i915_vma_bindinfo - Information needed for async bind
>> drivers/gpu/drm/i915/i915_vma_resource.h:129: warning: Function parameter or member 'bi' not described in 'i915_vma_resource'
>> 
>> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
>> ---
>>  drivers/gpu/drm/i915/i915_vma_resource.h | 45 ++++++++++++++----------
>>  1 file changed, 27 insertions(+), 18 deletions(-)
>> 
>> diff --git a/drivers/gpu/drm/i915/i915_vma_resource.h b/drivers/gpu/drm/i915/i915_vma_resource.h
>> index 2053c037dbfb..ca2b0f7f59bc 100644
>> --- a/drivers/gpu/drm/i915/i915_vma_resource.h
>> +++ b/drivers/gpu/drm/i915/i915_vma_resource.h
>> @@ -33,6 +33,27 @@ struct i915_page_sizes {
>>  	unsigned int sg;
>>  };
>>  
>> +/**
>> + * struct i915_vma_bindinfo - Information needed for async bind
>> + * only but that can be dropped after the bind has taken place.
>> + * Consider making this a separate argument to the bind_vma
>> + * op, coalescing with other arguments like vm, stash, cache_level
>> + * and flags
>> + * @pages: The pages sg-table.
>> + * @page_sizes: Page sizes of the pages.
>> + * @pages_rsgt: Refcounted sg-table when delayed object destruction
>> + * is supported. May be NULL.
>> + * @readonly: Whether the vma should be bound read-only.
>> + * @lmem: Whether the vma points to lmem.
>> + */
>> +struct i915_vma_bindinfo {
>> +	struct sg_table *pages;
>> +	struct i915_page_sizes page_sizes;
>> +	struct i915_refct_sgt *pages_rsgt;
>> +	bool readonly:1;
>> +	bool lmem:1;
>
> btw, I believe we should move all the individual docs near to its
> declarations. easier to forget updating the documentation when updating
> fields here.
>
>> +};
>> +
>>  /**
>>   * struct i915_vma_resource - Snapshotted unbind information.
>>   * @unbind_fence: Fence to mark unbinding complete. Note that this fence
>> @@ -89,25 +110,13 @@ struct i915_vma_resource {
>>  	intel_wakeref_t wakeref;
>>  
>>  	/**
>> -	 * struct i915_vma_bindinfo - Information needed for async bind
>> -	 * only but that can be dropped after the bind has taken place.
>> -	 * Consider making this a separate argument to the bind_vma
>> -	 * op, coalescing with other arguments like vm, stash, cache_level
>> -	 * and flags
>> -	 * @pages: The pages sg-table.
>> -	 * @page_sizes: Page sizes of the pages.
>> -	 * @pages_rsgt: Refcounted sg-table when delayed object destruction
>> -	 * is supported. May be NULL.
>> -	 * @readonly: Whether the vma should be bound read-only.
>> -	 * @lmem: Whether the vma points to lmem.
>> +	 * @bi: Information needed for async bind only but that can be dropped
>> +	 * after the bind has taken place.
>> +	 *
>> +	 * Consider making this a separate argument to the bind_vma op,
>> +	 * coalescing with other arguments like vm, stash, cache_level and flags
>>  	 */
>> -	struct i915_vma_bindinfo {
>> -		struct sg_table *pages;
>> -		struct i915_page_sizes page_sizes;
>> -		struct i915_refct_sgt *pages_rsgt;
>> -		bool readonly:1;
>> -		bool lmem:1;
>> -	} bi;
>> +	struct i915_vma_bindinfo bi;
>>  
>>  #if IS_ENABLED(CONFIG_DRM_I915_CAPTURE_ERROR)
>>  	struct intel_memory_region *mr;
>> -- 
>> 2.39.2
>> 

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [Intel-gfx] [PATCH 05/24] drm/i915/vma: fix struct i915_vma_bindinfo kernel-doc

[Rodrigo Vivi]

On Thu, May 04, 2023 at 12:43:05PM +0300, Jani Nikula wrote:
> On Wed, 03 May 2023, Rodrigo Vivi <rodrigo.vivi@kernel.org> wrote:
> > On Tue, May 02, 2023 at 06:37:22PM +0300, Jani Nikula wrote:
> >> You can't document both a sub-struct type and a struct member at the
> >> same time. Separate them.
> >
> > another way would be to kill the 'i915_vma_bindinfo' name entirely and
> > document only as '@bi:' and then move the individual documentations near
> > their definitions.
> 
> I don't think that will work, because AFAIK kernel-doc does not descend
> into struct members recursively.

It does:

'In-line member documentation comments' definition of:
Documentation/doc-guide/kernel-doc.rst

> 
> You can either declare and document the sub-structs as separate types
> (the patch at hand), or you can document sub-struct members directly
> from the embedding struct as shown below. I don't think the latter is
> very nice.

what I had in mind was something more like:

        /**
-        * struct i915_vma_bindinfo - Information needed for async bind
-        * only but that can be dropped after the bind has taken place.
-        * Consider making this a separate argument to the bind_vma
-        * op, coalescing with other arguments like vm, stash, cache_level
-        * and flags
-        * @pages: The pages sg-table.
-        * @page_sizes: Page sizes of the pages.
-        * @pages_rsgt: Refcounted sg-table when delayed object destruction
-        * is supported. May be NULL.
-        * @readonly: Whether the vma should be bound read-only.
-        * @lmem: Whether the vma points to lmem.
+        * @bi: Information needed for async bind only but that can be dropped
+        *      after the bind has taken place.
+        *      Consider making this a separate argument to the bind_vma
+        *      op, coalescing with other arguments like vm, stash, cache_level
+        *      and flags
         */
-       struct i915_vma_bindinfo {
+       struct {
+               /** @pages: The pages sg-table. */
                struct sg_table *pages;
+               /** @page_sizes: Page sizes of the pages. */
                struct i915_page_sizes page_sizes;
+               /**
+                * @pages_rsgt: Refcounted sg-table when delayed object
+                *              destruction is supported. May be NULL.
+                */
                struct i915_refct_sgt *pages_rsgt;
+               /** @readonly: Whether the vma should be bound read-only. */
                bool readonly:1;
+               /** @lmem: Whether the vma points to lmem. */
                bool lmem:1;
        } bi;


But let's not block the progress of the much needed fixes. It's your call:

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

> 
> BR,
> Jani.
> 
> 
> index 2053c037dbfb..ee767cc4de43 100644
> --- a/drivers/gpu/drm/i915/i915_vma_resource.h
> +++ b/drivers/gpu/drm/i915/i915_vma_resource.h
> @@ -48,6 +48,12 @@ struct i915_page_sizes {
>   * @rb: Rb node for the vm's pending unbind interval tree.
>   * @__subtree_last: Interval tree private member.
>   * @wakeref: wakeref.
> + * @bi.pages: The pages sg-table.
> + * @bi.page_sizes: Page sizes of the pages.
> + * @bi.pages_rsgt: Refcounted sg-table when delayed object destruction
> + * is supported. May be NULL.
> + * @bi.readonly: Whether the vma should be bound read-only.
> + * @bi.lmem: Whether the vma points to lmem.
>   * @vm: non-refcounted pointer to the vm. This is for internal use only and
>   * this member is cleared after vm_resource unbind.
>   * @mr: The memory region of the object pointed to by the vma.
> @@ -89,17 +95,11 @@ struct i915_vma_resource {
>         intel_wakeref_t wakeref;
>  
>         /**
> -        * struct i915_vma_bindinfo - Information needed for async bind
> -        * only but that can be dropped after the bind has taken place.
> -        * Consider making this a separate argument to the bind_vma
> -        * op, coalescing with other arguments like vm, stash, cache_level
> -        * and flags
> -        * @pages: The pages sg-table.
> -        * @page_sizes: Page sizes of the pages.
> -        * @pages_rsgt: Refcounted sg-table when delayed object destruction
> -        * is supported. May be NULL.
> -        * @readonly: Whether the vma should be bound read-only.
> -        * @lmem: Whether the vma points to lmem.
> +        * @bi: Information needed for async bind only but that can be dropped
> +        * after the bind has taken place.
> +        *
> +        * Consider making this a separate argument to the bind_vma op,
> +        * coalescing with other arguments like vm, stash, cache_level and flags
>          */
>         struct i915_vma_bindinfo {
>                 struct sg_table *pages;
> 
> 
> >
> >> 
> >> drivers/gpu/drm/i915/i915_vma_resource.h:91: warning: Incorrect use of kernel-doc format:          * struct i915_vma_bindinfo - Information needed for async bind
> >> drivers/gpu/drm/i915/i915_vma_resource.h:129: warning: Function parameter or member 'bi' not described in 'i915_vma_resource'
> >> 
> >> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> >> ---
> >>  drivers/gpu/drm/i915/i915_vma_resource.h | 45 ++++++++++++++----------
> >>  1 file changed, 27 insertions(+), 18 deletions(-)
> >> 
> >> diff --git a/drivers/gpu/drm/i915/i915_vma_resource.h b/drivers/gpu/drm/i915/i915_vma_resource.h
> >> index 2053c037dbfb..ca2b0f7f59bc 100644
> >> --- a/drivers/gpu/drm/i915/i915_vma_resource.h
> >> +++ b/drivers/gpu/drm/i915/i915_vma_resource.h
> >> @@ -33,6 +33,27 @@ struct i915_page_sizes {
> >>  	unsigned int sg;
> >>  };
> >>  
> >> +/**
> >> + * struct i915_vma_bindinfo - Information needed for async bind
> >> + * only but that can be dropped after the bind has taken place.
> >> + * Consider making this a separate argument to the bind_vma
> >> + * op, coalescing with other arguments like vm, stash, cache_level
> >> + * and flags
> >> + * @pages: The pages sg-table.
> >> + * @page_sizes: Page sizes of the pages.
> >> + * @pages_rsgt: Refcounted sg-table when delayed object destruction
> >> + * is supported. May be NULL.
> >> + * @readonly: Whether the vma should be bound read-only.
> >> + * @lmem: Whether the vma points to lmem.
> >> + */
> >> +struct i915_vma_bindinfo {
> >> +	struct sg_table *pages;
> >> +	struct i915_page_sizes page_sizes;
> >> +	struct i915_refct_sgt *pages_rsgt;
> >> +	bool readonly:1;
> >> +	bool lmem:1;
> >
> > btw, I believe we should move all the individual docs near to its
> > declarations. easier to forget updating the documentation when updating
> > fields here.
> >
> >> +};
> >> +
> >>  /**
> >>   * struct i915_vma_resource - Snapshotted unbind information.
> >>   * @unbind_fence: Fence to mark unbinding complete. Note that this fence
> >> @@ -89,25 +110,13 @@ struct i915_vma_resource {
> >>  	intel_wakeref_t wakeref;
> >>  
> >>  	/**
> >> -	 * struct i915_vma_bindinfo - Information needed for async bind
> >> -	 * only but that can be dropped after the bind has taken place.
> >> -	 * Consider making this a separate argument to the bind_vma
> >> -	 * op, coalescing with other arguments like vm, stash, cache_level
> >> -	 * and flags
> >> -	 * @pages: The pages sg-table.
> >> -	 * @page_sizes: Page sizes of the pages.
> >> -	 * @pages_rsgt: Refcounted sg-table when delayed object destruction
> >> -	 * is supported. May be NULL.
> >> -	 * @readonly: Whether the vma should be bound read-only.
> >> -	 * @lmem: Whether the vma points to lmem.
> >> +	 * @bi: Information needed for async bind only but that can be dropped
> >> +	 * after the bind has taken place.
> >> +	 *
> >> +	 * Consider making this a separate argument to the bind_vma op,
> >> +	 * coalescing with other arguments like vm, stash, cache_level and flags
> >>  	 */
> >> -	struct i915_vma_bindinfo {
> >> -		struct sg_table *pages;
> >> -		struct i915_page_sizes page_sizes;
> >> -		struct i915_refct_sgt *pages_rsgt;
> >> -		bool readonly:1;
> >> -		bool lmem:1;
> >> -	} bi;
> >> +	struct i915_vma_bindinfo bi;
> >>  
> >>  #if IS_ENABLED(CONFIG_DRM_I915_CAPTURE_ERROR)
> >>  	struct intel_memory_region *mr;
> >> -- 
> >> 2.39.2
> >> 
> 
> -- 
> Jani Nikula, Intel Open Source Graphics Center

Re: [Intel-gfx] [PATCH 10/24] drm/i915/gem: fix function pointer member kernel-doc

[Rodrigo Vivi]

On Thu, May 04, 2023 at 12:20:41PM +0300, Jani Nikula wrote:
> On Wed, 03 May 2023, Rodrigo Vivi <rodrigo.vivi@kernel.org> wrote:
> > On Tue, May 02, 2023 at 06:37:27PM +0300, Jani Nikula wrote:
> >> You can't document function pointer member as functions.
> >>
> >> drivers/gpu/drm/i915/gem/i915_gem_region.h:25: warning: Incorrect use of kernel-doc format:          * process_obj - Process the current object
> >> drivers/gpu/drm/i915/gem/i915_gem_region.h:35: warning: Function parameter or member 'process_obj' not described in 'i915_gem_apply_to_region_ops'
> >>
> >> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> >> ---
> >>  drivers/gpu/drm/i915/gem/i915_gem_region.h | 4 +---
> >>  1 file changed, 1 insertion(+), 3 deletions(-)
> >>
> >> diff --git a/drivers/gpu/drm/i915/gem/i915_gem_region.h b/drivers/gpu/drm/i915/gem/i915_gem_region.h
> >> index 2dfcc41c0170..8a7650b27cc2 100644
> >> --- a/drivers/gpu/drm/i915/gem/i915_gem_region.h
> >> +++ b/drivers/gpu/drm/i915/gem/i915_gem_region.h
> >> @@ -22,9 +22,7 @@ struct i915_gem_apply_to_region;
> >>   */
> >>  struct i915_gem_apply_to_region_ops {
> >>  	/**
> >> -	 * process_obj - Process the current object
> >> -	 * @apply: Embed this for private data.
> >> -	 * @obj: The current object.
> >> +	 * @process_obj: Process the current object
> >
> > hmm...
> > looking to the process_obj itself I wonder if we don't have a better way
> > to document these function pointer arguments that could be acceptable
> > instead of simply removing them.
> 
> The alternative is pretty much to document the parameters in plain text
> or some mild rst formatting that's not specifically kernel-doc parameter
> documentation.

:( something that could be improved in the overall infra since it is a useful
info.

Anyway, let's move with this then:

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


> 
> BR,
> Jani.
> 
> >
> > +Mauro in case he has some idea.
> >
> > and the declaration for reference:
> >
> >  int (*process_obj)(struct i915_gem_apply_to_region *apply,
> >                            struct drm_i915_gem_object *obj);
> >
> >>  	 *
> >>  	 * Note that if this function is part of a ww transaction, and
> >>  	 * if returns -EDEADLK for one of the objects, it may be
> >> --
> >> 2.39.2
> >>
> 
> -- 
> Jani Nikula, Intel Open Source Graphics Center

Re: [Intel-gfx] [PATCH 22/24] drm/i915/scatterlist: fix kernel-doc

[Rodrigo Vivi]

On Tue, May 02, 2023 at 06:37:39PM +0300, Jani Nikula wrote:
> Can't document function pointer members as if they are functions.
> 
> drivers/gpu/drm/i915/i915_scatterlist.h:160: warning: Incorrect use of kernel-doc format:          * release() - Free the memory of the struct i915_refct_sgt
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

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

> ---
>  drivers/gpu/drm/i915/i915_scatterlist.h | 3 +--
>  1 file changed, 1 insertion(+), 2 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/i915_scatterlist.h b/drivers/gpu/drm/i915/i915_scatterlist.h
> index b0a1db44f895..fe9ae863f9b9 100644
> --- a/drivers/gpu/drm/i915/i915_scatterlist.h
> +++ b/drivers/gpu/drm/i915/i915_scatterlist.h
> @@ -157,8 +157,7 @@ bool i915_sg_trim(struct sg_table *orig_st);
>   */
>  struct i915_refct_sgt_ops {
>  	/**
> -	 * release() - Free the memory of the struct i915_refct_sgt
> -	 * @ref: struct kref that is embedded in the struct i915_refct_sgt
> +	 * @release: Free the memory of the struct i915_refct_sgt
>  	 */
>  	void (*release)(struct kref *ref);
>  };
> -- 
> 2.39.2
> 

[Intel-gfx] ✗ Fi.CI.BUILD: failure for drm/i915: fix kernel-doc warnings, enable kernel-doc -Werror (rev2)

[Patchwork]

== Series Details ==

Series: drm/i915: fix kernel-doc warnings, enable kernel-doc -Werror (rev2)
URL   : https://patchwork.freedesktop.org/series/117207/
State : failure

== Summary ==

Error: patch https://patchwork.freedesktop.org/api/1.0/series/117207/revisions/2/mbox/ not applied
Applying: drm/i915/gvt: fix intel_vgpu_alloc_resource() kernel-doc parameter
Using index info to reconstruct a base tree...
M	drivers/gpu/drm/i915/gvt/aperture_gm.c
Falling back to patching base and 3-way merge...
No changes -- Patch already applied.
Applying: drm/i915/vma: fix kernel-doc function name for i915_vma_size()
Using index info to reconstruct a base tree...
M	drivers/gpu/drm/i915/i915_vma.h
Falling back to patching base and 3-way merge...
No changes -- Patch already applied.
Applying: drm/i915/utils: drop kernel-doc from __wait_for()
Using index info to reconstruct a base tree...
M	drivers/gpu/drm/i915/i915_utils.h
Falling back to patching base and 3-way merge...
No changes -- Patch already applied.
Applying: drm/i915/vma: document struct i915_vma_resource wakeref member
Using index info to reconstruct a base tree...
M	drivers/gpu/drm/i915/i915_vma_resource.h
Falling back to patching base and 3-way merge...
No changes -- Patch already applied.
Applying: drm/i915/vma: fix struct i915_vma_bindinfo kernel-doc
error: sha1 information is lacking or useless (drivers/gpu/drm/i915/i915_vma_resource.h).
error: could not build fake ancestor
hint: Use 'git am --show-current-patch=diff' to see the failed patch
Patch failed at 0005 drm/i915/vma: fix struct i915_vma_bindinfo kernel-doc
When you have resolved this problem, run "git am --continue".
If you prefer to skip this patch, run "git am --skip" instead.
To restore the original branch and stop patching, run "git am --abort".
Build failed, no error log produced

Re: [Intel-gfx] [PATCH 05/24] drm/i915/vma: fix struct i915_vma_bindinfo kernel-doc

[Jani Nikula]

On Thu, 04 May 2023, Rodrigo Vivi <rodrigo.vivi@kernel.org> wrote:
> On Thu, May 04, 2023 at 12:43:05PM +0300, Jani Nikula wrote:
>> On Wed, 03 May 2023, Rodrigo Vivi <rodrigo.vivi@kernel.org> wrote:
>> > On Tue, May 02, 2023 at 06:37:22PM +0300, Jani Nikula wrote:
>> >> You can't document both a sub-struct type and a struct member at the
>> >> same time. Separate them.
>> >
>> > another way would be to kill the 'i915_vma_bindinfo' name entirely and
>> > document only as '@bi:' and then move the individual documentations near
>> > their definitions.
>> 
>> I don't think that will work, because AFAIK kernel-doc does not descend
>> into struct members recursively.
>
> It does:
>
> 'In-line member documentation comments' definition of:
> Documentation/doc-guide/kernel-doc.rst

Regardless of what that says, I can't make it work. :(

$ scripts/kernel-doc -function i915_vma_resource drivers/gpu/drm/i915/i915_vma_resource.h

only documents ``bi`` but not the sub-struct. Regardless of whether I
refer to the members as @bi.pages: or @pages: etc.

Let me know if and how you can make it work.

BR,
Jani.

>
>> 
>> You can either declare and document the sub-structs as separate types
>> (the patch at hand), or you can document sub-struct members directly
>> from the embedding struct as shown below. I don't think the latter is
>> very nice.
>
> what I had in mind was something more like:
>
>         /**
> -        * struct i915_vma_bindinfo - Information needed for async bind
> -        * only but that can be dropped after the bind has taken place.
> -        * Consider making this a separate argument to the bind_vma
> -        * op, coalescing with other arguments like vm, stash, cache_level
> -        * and flags
> -        * @pages: The pages sg-table.
> -        * @page_sizes: Page sizes of the pages.
> -        * @pages_rsgt: Refcounted sg-table when delayed object destruction
> -        * is supported. May be NULL.
> -        * @readonly: Whether the vma should be bound read-only.
> -        * @lmem: Whether the vma points to lmem.
> +        * @bi: Information needed for async bind only but that can be dropped
> +        *      after the bind has taken place.
> +        *      Consider making this a separate argument to the bind_vma
> +        *      op, coalescing with other arguments like vm, stash, cache_level
> +        *      and flags
>          */
> -       struct i915_vma_bindinfo {
> +       struct {
> +               /** @pages: The pages sg-table. */
>                 struct sg_table *pages;
> +               /** @page_sizes: Page sizes of the pages. */
>                 struct i915_page_sizes page_sizes;
> +               /**
> +                * @pages_rsgt: Refcounted sg-table when delayed object
> +                *              destruction is supported. May be NULL.
> +                */
>                 struct i915_refct_sgt *pages_rsgt;
> +               /** @readonly: Whether the vma should be bound read-only. */
>                 bool readonly:1;
> +               /** @lmem: Whether the vma points to lmem. */
>                 bool lmem:1;
>         } bi;
>
>
> But let's not block the progress of the much needed fixes. It's your call:
>
> Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
>
>> 
>> BR,
>> Jani.
>> 
>> 
>> index 2053c037dbfb..ee767cc4de43 100644
>> --- a/drivers/gpu/drm/i915/i915_vma_resource.h
>> +++ b/drivers/gpu/drm/i915/i915_vma_resource.h
>> @@ -48,6 +48,12 @@ struct i915_page_sizes {
>>   * @rb: Rb node for the vm's pending unbind interval tree.
>>   * @__subtree_last: Interval tree private member.
>>   * @wakeref: wakeref.
>> + * @bi.pages: The pages sg-table.
>> + * @bi.page_sizes: Page sizes of the pages.
>> + * @bi.pages_rsgt: Refcounted sg-table when delayed object destruction
>> + * is supported. May be NULL.
>> + * @bi.readonly: Whether the vma should be bound read-only.
>> + * @bi.lmem: Whether the vma points to lmem.
>>   * @vm: non-refcounted pointer to the vm. This is for internal use only and
>>   * this member is cleared after vm_resource unbind.
>>   * @mr: The memory region of the object pointed to by the vma.
>> @@ -89,17 +95,11 @@ struct i915_vma_resource {
>>         intel_wakeref_t wakeref;
>>  
>>         /**
>> -        * struct i915_vma_bindinfo - Information needed for async bind
>> -        * only but that can be dropped after the bind has taken place.
>> -        * Consider making this a separate argument to the bind_vma
>> -        * op, coalescing with other arguments like vm, stash, cache_level
>> -        * and flags
>> -        * @pages: The pages sg-table.
>> -        * @page_sizes: Page sizes of the pages.
>> -        * @pages_rsgt: Refcounted sg-table when delayed object destruction
>> -        * is supported. May be NULL.
>> -        * @readonly: Whether the vma should be bound read-only.
>> -        * @lmem: Whether the vma points to lmem.
>> +        * @bi: Information needed for async bind only but that can be dropped
>> +        * after the bind has taken place.
>> +        *
>> +        * Consider making this a separate argument to the bind_vma op,
>> +        * coalescing with other arguments like vm, stash, cache_level and flags
>>          */
>>         struct i915_vma_bindinfo {
>>                 struct sg_table *pages;
>> 
>> 
>> >
>> >> 
>> >> drivers/gpu/drm/i915/i915_vma_resource.h:91: warning: Incorrect use of kernel-doc format:          * struct i915_vma_bindinfo - Information needed for async bind
>> >> drivers/gpu/drm/i915/i915_vma_resource.h:129: warning: Function parameter or member 'bi' not described in 'i915_vma_resource'
>> >> 
>> >> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
>> >> ---
>> >>  drivers/gpu/drm/i915/i915_vma_resource.h | 45 ++++++++++++++----------
>> >>  1 file changed, 27 insertions(+), 18 deletions(-)
>> >> 
>> >> diff --git a/drivers/gpu/drm/i915/i915_vma_resource.h b/drivers/gpu/drm/i915/i915_vma_resource.h
>> >> index 2053c037dbfb..ca2b0f7f59bc 100644
>> >> --- a/drivers/gpu/drm/i915/i915_vma_resource.h
>> >> +++ b/drivers/gpu/drm/i915/i915_vma_resource.h
>> >> @@ -33,6 +33,27 @@ struct i915_page_sizes {
>> >>  	unsigned int sg;
>> >>  };
>> >>  
>> >> +/**
>> >> + * struct i915_vma_bindinfo - Information needed for async bind
>> >> + * only but that can be dropped after the bind has taken place.
>> >> + * Consider making this a separate argument to the bind_vma
>> >> + * op, coalescing with other arguments like vm, stash, cache_level
>> >> + * and flags
>> >> + * @pages: The pages sg-table.
>> >> + * @page_sizes: Page sizes of the pages.
>> >> + * @pages_rsgt: Refcounted sg-table when delayed object destruction
>> >> + * is supported. May be NULL.
>> >> + * @readonly: Whether the vma should be bound read-only.
>> >> + * @lmem: Whether the vma points to lmem.
>> >> + */
>> >> +struct i915_vma_bindinfo {
>> >> +	struct sg_table *pages;
>> >> +	struct i915_page_sizes page_sizes;
>> >> +	struct i915_refct_sgt *pages_rsgt;
>> >> +	bool readonly:1;
>> >> +	bool lmem:1;
>> >
>> > btw, I believe we should move all the individual docs near to its
>> > declarations. easier to forget updating the documentation when updating
>> > fields here.
>> >
>> >> +};
>> >> +
>> >>  /**
>> >>   * struct i915_vma_resource - Snapshotted unbind information.
>> >>   * @unbind_fence: Fence to mark unbinding complete. Note that this fence
>> >> @@ -89,25 +110,13 @@ struct i915_vma_resource {
>> >>  	intel_wakeref_t wakeref;
>> >>  
>> >>  	/**
>> >> -	 * struct i915_vma_bindinfo - Information needed for async bind
>> >> -	 * only but that can be dropped after the bind has taken place.
>> >> -	 * Consider making this a separate argument to the bind_vma
>> >> -	 * op, coalescing with other arguments like vm, stash, cache_level
>> >> -	 * and flags
>> >> -	 * @pages: The pages sg-table.
>> >> -	 * @page_sizes: Page sizes of the pages.
>> >> -	 * @pages_rsgt: Refcounted sg-table when delayed object destruction
>> >> -	 * is supported. May be NULL.
>> >> -	 * @readonly: Whether the vma should be bound read-only.
>> >> -	 * @lmem: Whether the vma points to lmem.
>> >> +	 * @bi: Information needed for async bind only but that can be dropped
>> >> +	 * after the bind has taken place.
>> >> +	 *
>> >> +	 * Consider making this a separate argument to the bind_vma op,
>> >> +	 * coalescing with other arguments like vm, stash, cache_level and flags
>> >>  	 */
>> >> -	struct i915_vma_bindinfo {
>> >> -		struct sg_table *pages;
>> >> -		struct i915_page_sizes page_sizes;
>> >> -		struct i915_refct_sgt *pages_rsgt;
>> >> -		bool readonly:1;
>> >> -		bool lmem:1;
>> >> -	} bi;
>> >> +	struct i915_vma_bindinfo bi;
>> >>  
>> >>  #if IS_ENABLED(CONFIG_DRM_I915_CAPTURE_ERROR)
>> >>  	struct intel_memory_region *mr;
>> >> -- 
>> >> 2.39.2
>> >> 
>> 
>> -- 
>> Jani Nikula, Intel Open Source Graphics Center

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [Intel-gfx] [PATCH 10/24] drm/i915/gem: fix function pointer member kernel-doc

[Jani Nikula]

On Thu, 04 May 2023, Rodrigo Vivi <rodrigo.vivi@kernel.org> wrote:
> On Thu, May 04, 2023 at 12:20:41PM +0300, Jani Nikula wrote:
>> On Wed, 03 May 2023, Rodrigo Vivi <rodrigo.vivi@kernel.org> wrote:
>> > On Tue, May 02, 2023 at 06:37:27PM +0300, Jani Nikula wrote:
>> >> You can't document function pointer member as functions.
>> >>
>> >> drivers/gpu/drm/i915/gem/i915_gem_region.h:25: warning: Incorrect use of kernel-doc format:          * process_obj - Process the current object
>> >> drivers/gpu/drm/i915/gem/i915_gem_region.h:35: warning: Function parameter or member 'process_obj' not described in 'i915_gem_apply_to_region_ops'
>> >>
>> >> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
>> >> ---
>> >>  drivers/gpu/drm/i915/gem/i915_gem_region.h | 4 +---
>> >>  1 file changed, 1 insertion(+), 3 deletions(-)
>> >>
>> >> diff --git a/drivers/gpu/drm/i915/gem/i915_gem_region.h b/drivers/gpu/drm/i915/gem/i915_gem_region.h
>> >> index 2dfcc41c0170..8a7650b27cc2 100644
>> >> --- a/drivers/gpu/drm/i915/gem/i915_gem_region.h
>> >> +++ b/drivers/gpu/drm/i915/gem/i915_gem_region.h
>> >> @@ -22,9 +22,7 @@ struct i915_gem_apply_to_region;
>> >>   */
>> >>  struct i915_gem_apply_to_region_ops {
>> >>  	/**
>> >> -	 * process_obj - Process the current object
>> >> -	 * @apply: Embed this for private data.
>> >> -	 * @obj: The current object.
>> >> +	 * @process_obj: Process the current object
>> >
>> > hmm...
>> > looking to the process_obj itself I wonder if we don't have a better way
>> > to document these function pointer arguments that could be acceptable
>> > instead of simply removing them.
>> 
>> The alternative is pretty much to document the parameters in plain text
>> or some mild rst formatting that's not specifically kernel-doc parameter
>> documentation.
>
> :( something that could be improved in the overall infra since it is a useful
> info.

I don't disagree per se, but I wouldn't touch kernel-doc the script with
a ten-foot pole anymore.

>
> Anyway, let's move with this then:
>
> Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>

Thanks,
Jani.

>
>
>> 
>> BR,
>> Jani.
>> 
>> >
>> > +Mauro in case he has some idea.
>> >
>> > and the declaration for reference:
>> >
>> >  int (*process_obj)(struct i915_gem_apply_to_region *apply,
>> >                            struct drm_i915_gem_object *obj);
>> >
>> >>  	 *
>> >>  	 * Note that if this function is part of a ww transaction, and
>> >>  	 * if returns -EDEADLK for one of the objects, it may be
>> >> --
>> >> 2.39.2
>> >>
>> 
>> -- 
>> Jani Nikula, Intel Open Source Graphics Center

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [Intel-gfx] [PATCH 05/24] drm/i915/vma: fix struct i915_vma_bindinfo kernel-doc

[Jani Nikula]

On Thu, 04 May 2023, Rodrigo Vivi <rodrigo.vivi@kernel.org> wrote:
> But let's not block the progress of the much needed fixes. It's your call:
>
> Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>

Thanks, pushed to drm-intel-gt-next as-is.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [Intel-gfx] [PATCH 10/24] drm/i915/gem: fix function pointer member kernel-doc

[Jani Nikula]

On Thu, 04 May 2023, Rodrigo Vivi <rodrigo.vivi@kernel.org> wrote:
> On Thu, May 04, 2023 at 12:20:41PM +0300, Jani Nikula wrote:
>> On Wed, 03 May 2023, Rodrigo Vivi <rodrigo.vivi@kernel.org> wrote:
>> > On Tue, May 02, 2023 at 06:37:27PM +0300, Jani Nikula wrote:
>> >> You can't document function pointer member as functions.
>> >>
>> >> drivers/gpu/drm/i915/gem/i915_gem_region.h:25: warning: Incorrect use of kernel-doc format:          * process_obj - Process the current object
>> >> drivers/gpu/drm/i915/gem/i915_gem_region.h:35: warning: Function parameter or member 'process_obj' not described in 'i915_gem_apply_to_region_ops'
>> >>
>> >> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
>> >> ---
>> >>  drivers/gpu/drm/i915/gem/i915_gem_region.h | 4 +---
>> >>  1 file changed, 1 insertion(+), 3 deletions(-)
>> >>
>> >> diff --git a/drivers/gpu/drm/i915/gem/i915_gem_region.h b/drivers/gpu/drm/i915/gem/i915_gem_region.h
>> >> index 2dfcc41c0170..8a7650b27cc2 100644
>> >> --- a/drivers/gpu/drm/i915/gem/i915_gem_region.h
>> >> +++ b/drivers/gpu/drm/i915/gem/i915_gem_region.h
>> >> @@ -22,9 +22,7 @@ struct i915_gem_apply_to_region;
>> >>   */
>> >>  struct i915_gem_apply_to_region_ops {
>> >>  	/**
>> >> -	 * process_obj - Process the current object
>> >> -	 * @apply: Embed this for private data.
>> >> -	 * @obj: The current object.
>> >> +	 * @process_obj: Process the current object
>> >
>> > hmm...
>> > looking to the process_obj itself I wonder if we don't have a better way
>> > to document these function pointer arguments that could be acceptable
>> > instead of simply removing them.
>> 
>> The alternative is pretty much to document the parameters in plain text
>> or some mild rst formatting that's not specifically kernel-doc parameter
>> documentation.
>
> :( something that could be improved in the overall infra since it is a useful
> info.
>
> Anyway, let's move with this then:
>
> Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>

Thanks, pushed to drm-intel-gt-next, as well as the other ones.

BR,
Jani.

>
>
>> 
>> BR,
>> Jani.
>> 
>> >
>> > +Mauro in case he has some idea.
>> >
>> > and the declaration for reference:
>> >
>> >  int (*process_obj)(struct i915_gem_apply_to_region *apply,
>> >                            struct drm_i915_gem_object *obj);
>> >
>> >>  	 *
>> >>  	 * Note that if this function is part of a ww transaction, and
>> >>  	 * if returns -EDEADLK for one of the objects, it may be
>> >> --
>> >> 2.39.2
>> >>
>> 
>> -- 
>> Jani Nikula, Intel Open Source Graphics Center

-- 
Jani Nikula, Intel Open Source Graphics Center