[PATCH v3 00/37] drm/i915: fix kernel-doc issues

[PATCH v3 00/37] drm/i915: fix kernel-doc issues

[Mauro Carvalho Chehab]

There are several kernel-doc markups along the i915 driver that aren't part
of the i915.rst file, nor are included on any other file under Documentation.
Maybe due to that, there are several kernel-doc markups that report problems
when checked with scripts/kernel-doc. More than that, some of them also
have problems when actually integrated at the building system, as reported
by Sphinx.

Along the issues we have:

- renamed symbols where the prototype doesn't match the kernel-doc name;
- some markups doesn't have the symbol name on it;
- typos when defining parameter;
- some parameters are missing;
- some ascii artwork aren't properly displayed after parsed by Sphinx;
- some other tags produce bad results and warnings after parsed by html build;
- some "/**" patterns exist on places that aren't kernel-doc markups.

This series, against drm-tip, fix all the above issues and all all such files to
i915.rst. This way, it will be easier to avoid other problems to be introduced.

While here, I also added SPDX on two display files. Besides being the current
way to indicate the license, it also makes easier to find all files with kernel-doc
markups, as all it is needed is to search for "/**" at i915 files to know what of
them have embedded documentation.

PS.: my end goal here is to ensure that the TLB patch series I'm about to
send will be properly documented. For that to happen, let's first fix all
warnings when building the documentation ;-)

---

v3:
- Dropped patches with issues already fixed;
- Addressed Rodrigo's comments.

v2:
- Added 3 already-existing patches form other PRs addressing some of the
  issues. The subjects were renamed, in order to describe what they're
  doing.
- Fixed checkpatch warnings;
- Added 4 additional patches at the end, documenting some structs
  at i915_gem_object_types.h and  intel_gt_pm.h, plus adding 
  intel-guc.c internal functions to the generated documentation.

Mauro Carvalho Chehab (37):
  drm/i915: fix kernel-doc trivial warnings on i915/*.[ch] files
  drm/i915: display: fix kernel-doc markup warnings
  drm/i915: gt: fix some Kernel-doc issues
  drm/i915: gvt: fix kernel-doc trivial warnings
  drm/i915: gem: fix some Kernel-doc issues
  drm/i915: intel_wakeref.h: fix some kernel-doc markups
  drm/i915: i915_gem_ttm: fix a kernel-doc markup
  drm/i915: i915_gem_ttm_pm.c: fix kernel-doc markups
  drm/i915: gem: add kernel-doc description for some function parameters
  drm/i915: i915_gpu_error.c: document dump_flags
  drm/i915: document kernel-doc trivial issues
  drm/i915: intel_dp_link_training.c: fix kernel-doc markup
  drm/i915: intel_fb: fix a kernel-doc issue with Sphinx
  drm/i915: skl_scaler: fix return value kernel-doc markup
  drm/i915: intel_pm.c: fix some ascii artwork at kernel-doc
  drm/i915: i915_gem_region.h: fix i915_gem_apply_to_region_ops doc
  drm/i915: i915_gem_wait.c: fix a kernel-doc markup
  drm/i915: fix i915_gem_ttm_move.c DOC: markup
  drm/i915: stop using kernel-doc markups for something else
  drm/i915: dvo_ch7xxx.c: use SPDX header
  drm/i915: dvo_sil164.c: use SPDX header
  drm/i915: i915_vma_resource.c: fix some kernel-doc markups
  drm/i915: i915_gem.c fix a kernel-doc issue
  drm/i915: i915_scatterlist.h: fix some kernel-doc markups
  drm/i915: i915_deps: use a shorter title markup
  docs: gpu: i915.rst: display: add kernel-doc markups
  docs: gpu: i915.rst: gt: add more kernel-doc markups
  docs: gpu: i915.rst: GuC: add more kernel-doc markups
  docs: gpu: i915.rst: GVT: add more kernel-doc markups
  docs: gpu: i915.rst: PM: add more kernel-doc markups
  docs: gpu: i915.rst: GEM/TTM: add more kernel-doc markups
  docs: gpu: i915.rst: add the remaining kernel-doc markup files
  drm/i915 i915_gem_object_types.h: document struct i915_lut_handle
  drm/i915: document struct drm_i915_gem_object
  drm/i915: add descriptions for some RPM macros at intel_gt_pm.h
  drm/i915: add GuC functions to the documentation
  drm/i915: be consistent with kernel-doc function declaration

 Documentation/gpu/i915.rst                    | 283 +++++++++++++++++-
 drivers/gpu/drm/i915/display/dvo_ch7017.c     |  26 +-
 drivers/gpu/drm/i915/display/dvo_ch7xxx.c     |  39 +--
 drivers/gpu/drm/i915/display/dvo_sil164.c     |  32 +-
 drivers/gpu/drm/i915/display/intel_atomic.c   |   2 +-
 drivers/gpu/drm/i915/display/intel_audio.c    |   4 +-
 drivers/gpu/drm/i915/display/intel_crtc.c     |   4 +-
 .../drm/i915/display/intel_display_debugfs.c  |   2 +-
 .../drm/i915/display/intel_display_power.c    |   2 +-
 .../drm/i915/display/intel_display_types.h    |   2 +-
 drivers/gpu/drm/i915/display/intel_dmc.c      |  10 +-
 .../drm/i915/display/intel_dp_link_training.c |   2 +
 drivers/gpu/drm/i915/display/intel_dsb.c      |  10 +-
 drivers/gpu/drm/i915/display/intel_dvo_dev.h  |   6 +-
 drivers/gpu/drm/i915/display/intel_fb.c       |   2 +-
 .../gpu/drm/i915/display/intel_lpe_audio.c    |   8 +-
 drivers/gpu/drm/i915/display/intel_sdvo.c     |   4 +-
 drivers/gpu/drm/i915/display/intel_tc.c       |   2 +-
 drivers/gpu/drm/i915/display/intel_tv.c       |   2 +-
 drivers/gpu/drm/i915/display/skl_scaler.c     |   6 +-
 drivers/gpu/drm/i915/gem/i915_gem_create.c    |   8 +-
 drivers/gpu/drm/i915/gem/i915_gem_domain.c    |  17 +-
 drivers/gpu/drm/i915/gem/i915_gem_object.c    |   2 +
 drivers/gpu/drm/i915/gem/i915_gem_object.h    |   2 +-
 .../gpu/drm/i915/gem/i915_gem_object_types.h  | 212 ++++++++++---
 drivers/gpu/drm/i915/gem/i915_gem_region.h    |   8 +-
 drivers/gpu/drm/i915/gem/i915_gem_ttm.c       |   2 +
 drivers/gpu/drm/i915/gem/i915_gem_ttm.h       |   1 +
 drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c  |   4 +-
 drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c    |   8 +-
 drivers/gpu/drm/i915/gem/i915_gem_wait.c      |  26 +-
 drivers/gpu/drm/i915/gt/intel_context.h       |   6 +-
 drivers/gpu/drm/i915/gt/intel_context_types.h |  69 +++--
 drivers/gpu/drm/i915/gt/intel_engine_cs.c     |  14 +-
 drivers/gpu/drm/i915/gt/intel_engine_types.h  |   1 +
 drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h  |   2 +-
 drivers/gpu/drm/i915/gt/intel_gt_pm.h         |  51 ++++
 drivers/gpu/drm/i915/gt/intel_gt_types.h      |  12 +-
 drivers/gpu/drm/i915/gt/intel_gtt.h           |   6 +-
 drivers/gpu/drm/i915/gt/intel_reset_types.h   |   4 +-
 drivers/gpu/drm/i915/gt/intel_rps.c           |   4 +-
 .../gpu/drm/i915/gt/intel_timeline_types.h    |   6 +-
 .../drm/i915/gt/shaders/clear_kernel/hsw.asm  |   4 +-
 .../drm/i915/gt/shaders/clear_kernel/ivb.asm  |   4 +-
 drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h |  24 +-
 drivers/gpu/drm/i915/gt/uc/intel_guc.c        |  10 +-
 drivers/gpu/drm/i915/gt/uc/intel_guc.h        |   2 +-
 drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c    |   4 +-
 drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c     |   2 +-
 drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h   |   2 +-
 .../gpu/drm/i915/gt/uc/intel_guc_hwconfig.c   |   5 +-
 drivers/gpu/drm/i915/gt/uc/intel_guc_slpc.c   |   8 +-
 drivers/gpu/drm/i915/gt/uc/intel_huc.c        |   4 +-
 drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c     |   2 +-
 drivers/gpu/drm/i915/gt/uc/intel_uc_fw.h      |   2 +-
 drivers/gpu/drm/i915/gvt/cfg_space.c          |   2 +-
 drivers/gpu/drm/i915/gvt/dmabuf.h             |   2 +-
 drivers/gpu/drm/i915/gvt/page_track.c         |   2 +-
 drivers/gpu/drm/i915/gvt/vgpu.c               |   6 +-
 drivers/gpu/drm/i915/i915_active.h            |  14 +-
 drivers/gpu/drm/i915/i915_cmd_parser.c        |   8 +-
 drivers/gpu/drm/i915/i915_deps.c              |   4 +-
 drivers/gpu/drm/i915/i915_drm_client.h        |   2 +-
 drivers/gpu/drm/i915/i915_drv.h               |  24 +-
 drivers/gpu/drm/i915/i915_file_private.h      |   8 +-
 drivers/gpu/drm/i915/i915_gem.c               |  12 +-
 drivers/gpu/drm/i915/i915_gpu_error.c         |   3 +-
 drivers/gpu/drm/i915/i915_gpu_error.h         |   4 +-
 drivers/gpu/drm/i915/i915_pmu.h               |  38 +--
 drivers/gpu/drm/i915/i915_reg_defs.h          |  12 +-
 drivers/gpu/drm/i915/i915_request.h           |   4 +-
 drivers/gpu/drm/i915/i915_scatterlist.c       |   2 +-
 drivers/gpu/drm/i915/i915_scatterlist.h       |  12 +-
 drivers/gpu/drm/i915/i915_utils.h             |   2 +-
 drivers/gpu/drm/i915/i915_vma.c               |   2 +
 drivers/gpu/drm/i915/i915_vma_resource.c      |   4 +-
 drivers/gpu/drm/i915/i915_vma_resource.h      |   3 +-
 drivers/gpu/drm/i915/intel_pm.c               |  33 +-
 drivers/gpu/drm/i915/intel_region_ttm.c       |   3 +-
 drivers/gpu/drm/i915/intel_uncore.h           |   4 +-
 drivers/gpu/drm/i915/intel_wakeref.h          |   4 +-
 drivers/gpu/drm/i915/intel_wopcm.c            |   4 +-
 82 files changed, 826 insertions(+), 378 deletions(-)

-- 
2.37.3

[PATCH v3 01/37] drm/i915: fix kernel-doc trivial warnings on i915/*.[ch] files

[Mauro Carvalho Chehab]

There are several trivial warnings there, due to trivial things:
	- lack of function name at the kerneldoc markup;
	- renamed functions;
	- wrong parameter syntax.

Fix such warnings:
	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'
	drivers/gpu/drm/i915/i915_gem.c:443: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
	 * Reads data from the object referenced by handle.
	drivers/gpu/drm/i915/i915_gem.c:532: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
	 * This is the fast pwrite path, where we copy the data directly from the
	drivers/gpu/drm/i915/i915_gem.c:717: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
	 * Writes data to the object referenced by handle.
	drivers/gpu/drm/i915/i915_gem.c:802: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
	 * Called when user space has done writes to this buffer
	drivers/gpu/drm/i915/i915_pmu.h:22: warning: cannot understand function prototype: 'enum i915_pmu_tracked_events '
	drivers/gpu/drm/i915/i915_pmu.h:33: warning: cannot understand function prototype: 'enum '
	drivers/gpu/drm/i915/i915_pmu.h:42: 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.
	drivers/gpu/drm/i915/i915_request.h:177: 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:473: 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.
	drivers/gpu/drm/i915/i915_scatterlist.c:63: warning: Function parameter or member 'size' not described in 'i915_refct_sgt_init'
	drivers/gpu/drm/i915/i915_scatterlist.h:153: warning: Incorrect use of kernel-doc format:          * release() - Free the memory of the struct i915_refct_sgt
	drivers/gpu/drm/i915/i915_scatterlist.h:157: warning: Function parameter or member 'release' not described in 'i915_refct_sgt_ops'
	drivers/gpu/drm/i915/i915_scatterlist.h:180: warning: Function parameter or member 'rsgt' not described in 'i915_refct_sgt_put'
	drivers/gpu/drm/i915/i915_scatterlist.h:191: warning: Function parameter or member 'rsgt' not described in 'i915_refct_sgt_get'
	drivers/gpu/drm/i915/i915_scatterlist.h:207: warning: Function parameter or member 'rsgt' not described in '__i915_refct_sgt_init'
	drivers/gpu/drm/i915/i915_utils.h:291: warning: Function parameter or member 'OP' not described in '__wait_for'
	drivers/gpu/drm/i915/i915_utils.h:291: warning: Function parameter or member 'COND' not described in '__wait_for'
	drivers/gpu/drm/i915/i915_utils.h:291: warning: Function parameter or member 'US' not described in '__wait_for'
	drivers/gpu/drm/i915/i915_utils.h:291: warning: Function parameter or member 'Wmin' not described in '__wait_for'
	drivers/gpu/drm/i915/i915_utils.h:291: warning: Function parameter or member 'Wmax' not described in '__wait_for'
	drivers/gpu/drm/i915/i915_vma_resource.h:88: warning: Incorrect use of kernel-doc format:          * struct i915_vma_bindinfo - Information needed for async bind
	drivers/gpu/drm/i915/i915_vma_resource.h:123: warning: Function parameter or member 'bi' not described in 'i915_vma_resource'

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/i915_active.h       | 14 +++++++-------
 drivers/gpu/drm/i915/i915_gem.c          | 10 ++++++----
 drivers/gpu/drm/i915/i915_pmu.h          |  6 +++---
 drivers/gpu/drm/i915/i915_request.h      |  4 ++--
 drivers/gpu/drm/i915/i915_scatterlist.c  |  2 +-
 drivers/gpu/drm/i915/i915_scatterlist.h  | 10 +++++-----
 drivers/gpu/drm/i915/i915_utils.h        |  2 +-
 drivers/gpu/drm/i915/i915_vma_resource.h |  2 +-
 8 files changed, 26 insertions(+), 24 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
diff --git a/drivers/gpu/drm/i915/i915_gem.c b/drivers/gpu/drm/i915/i915_gem.c
index bae857d5221d..f68fa0732363 100644
--- a/drivers/gpu/drm/i915/i915_gem.c
+++ b/drivers/gpu/drm/i915/i915_gem.c
@@ -439,7 +439,7 @@ i915_gem_gtt_pread(struct drm_i915_gem_object *obj,
 }
 
 /**
- * Reads data from the object referenced by handle.
+ * i915_gem_pread_ioctl - Reads data from the object referenced by handle.
  * @dev: drm device pointer
  * @data: ioctl data blob
  * @file: drm file pointer
@@ -528,7 +528,8 @@ ggtt_write(struct io_mapping *mapping,
 }
 
 /**
- * This is the fast pwrite path, where we copy the data directly from the
+ * i915_gem_gtt_pwrite_fast - This is the fast pwrite path, where we copy
+ *	the data directly from the
  * user into the GTT, uncached.
  * @obj: i915 GEM object
  * @args: pwrite arguments structure
@@ -713,7 +714,7 @@ i915_gem_shmem_pwrite(struct drm_i915_gem_object *obj,
 }
 
 /**
- * Writes data to the object referenced by handle.
+ * i915_gem_pwrite_ioctl - Writes data to the object referenced by handle.
  * @dev: drm device
  * @data: ioctl data blob
  * @file: drm file
@@ -798,7 +799,8 @@ i915_gem_pwrite_ioctl(struct drm_device *dev, void *data,
 }
 
 /**
- * Called when user space has done writes to this buffer
+ * i915_gem_sw_finish_ioctl - Called when user space has done writes to
+ *	this buffer
  * @dev: drm device
  * @data: ioctl data blob
  * @file: drm file
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.
diff --git a/drivers/gpu/drm/i915/i915_request.h b/drivers/gpu/drm/i915/i915_request.h
index 47041ec68df8..66d6dee98525 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
@@ -468,7 +468,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)
diff --git a/drivers/gpu/drm/i915/i915_scatterlist.c b/drivers/gpu/drm/i915/i915_scatterlist.c
index dcc081874ec8..f664c1ce02cf 100644
--- a/drivers/gpu/drm/i915/i915_scatterlist.c
+++ b/drivers/gpu/drm/i915/i915_scatterlist.c
@@ -56,7 +56,7 @@ static const struct i915_refct_sgt_ops rsgt_ops = {
 /**
  * i915_refct_sgt_init - Initialize a struct i915_refct_sgt with default ops
  * @rsgt: The struct i915_refct_sgt to initialize.
- * size: The size of the underlying memory buffer.
+ * @size: The size of the underlying memory buffer.
  */
 void i915_refct_sgt_init(struct i915_refct_sgt *rsgt, size_t size)
 {
diff --git a/drivers/gpu/drm/i915/i915_scatterlist.h b/drivers/gpu/drm/i915/i915_scatterlist.h
index 9ddb3e743a3e..79b70ae2e766 100644
--- a/drivers/gpu/drm/i915/i915_scatterlist.h
+++ b/drivers/gpu/drm/i915/i915_scatterlist.h
@@ -149,7 +149,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
+	 * @release: Free the memory of the struct i915_refct_sgt
 	 * @ref: struct kref that is embedded in the struct i915_refct_sgt
 	 */
 	void (*release)(struct kref *ref);
@@ -159,7 +159,7 @@ struct i915_refct_sgt_ops {
  * struct i915_refct_sgt - A refcounted scatter-gather table
  * @kref: struct kref for refcounting
  * @table: struct sg_table holding the scatter-gather table itself. Note that
- * @table->sgl = NULL can be used to determine whether a scatter-gather table
+ * @table->sgl == NULL can be used to determine whether a scatter-gather table
  * is present or not.
  * @size: The size in bytes of the underlying memory buffer
  * @ops: The operations structure.
@@ -173,7 +173,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)
 {
@@ -183,7 +183,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)
@@ -195,7 +195,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.
diff --git a/drivers/gpu/drm/i915/i915_utils.h b/drivers/gpu/drm/i915/i915_utils.h
index 6c14d13364bf..85994298a74e 100644
--- a/drivers/gpu/drm/i915/i915_utils.h
+++ b/drivers/gpu/drm/i915/i915_utils.h
@@ -256,7 +256,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
diff --git a/drivers/gpu/drm/i915/i915_vma_resource.h b/drivers/gpu/drm/i915/i915_vma_resource.h
index 06923d1816e7..e155f6f7af6f 100644
--- a/drivers/gpu/drm/i915/i915_vma_resource.h
+++ b/drivers/gpu/drm/i915/i915_vma_resource.h
@@ -85,7 +85,7 @@ struct i915_vma_resource {
 	intel_wakeref_t wakeref;
 
 	/**
-	 * struct i915_vma_bindinfo - Information needed for async bind
+	 * @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
-- 
2.37.3

[PATCH v3 02/37] drm/i915: display: fix kernel-doc markup warnings

[Mauro Carvalho Chehab]

There are a couple of issues at i915 display kernel-doc markups:

	drivers/gpu/drm/i915/display/intel_display_debugfs.c:2238: warning: Function parameter or member 'intel_connector' not described in 'intel_connector_debugfs_add'
	drivers/gpu/drm/i915/display/intel_display_debugfs.c:2238: warning: Excess function parameter 'connector' description in 'intel_connector_debugfs_add'
	drivers/gpu/drm/i915/display/intel_display_power.c:700: warning: expecting prototype for intel_display_power_put_async(). Prototype was for __intel_display_power_put_async() instead
	drivers/gpu/drm/i915/display/intel_tc.c:807: warning: Function parameter or member 'work' not described in 'intel_tc_port_disconnect_phy_work'
	drivers/gpu/drm/i915/display/intel_tc.c:807: warning: Excess function parameter 'dig_port' description in 'intel_tc_port_disconnect_phy_work'

Those are due to wrong parameter of function name. Address them.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/display/intel_display_debugfs.c | 2 +-
 drivers/gpu/drm/i915/display/intel_display_power.c   | 2 +-
 drivers/gpu/drm/i915/display/intel_tc.c              | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/i915/display/intel_display_debugfs.c b/drivers/gpu/drm/i915/display/intel_display_debugfs.c
index 5dc364e9db49..e8433aa50905 100644
--- a/drivers/gpu/drm/i915/display/intel_display_debugfs.c
+++ b/drivers/gpu/drm/i915/display/intel_display_debugfs.c
@@ -2232,7 +2232,7 @@ DEFINE_SHOW_ATTRIBUTE(i915_current_bpc);
 
 /**
  * intel_connector_debugfs_add - add i915 specific connector debugfs files
- * @connector: pointer to a registered drm_connector
+ * @intel_connector: pointer to a registered drm_connector
  *
  * Cleanup will be done by drm_connector_unregister() through a call to
  * drm_debugfs_connector_remove().
diff --git a/drivers/gpu/drm/i915/display/intel_display_power.c b/drivers/gpu/drm/i915/display/intel_display_power.c
index 1af1705d730d..b080d65d4461 100644
--- a/drivers/gpu/drm/i915/display/intel_display_power.c
+++ b/drivers/gpu/drm/i915/display/intel_display_power.c
@@ -686,7 +686,7 @@ intel_display_power_put_async_work(struct work_struct *work)
 }
 
 /**
- * intel_display_power_put_async - release a power domain reference asynchronously
+ * __intel_display_power_put_async - release a power domain reference asynchronously
  * @i915: i915 device instance
  * @domain: power domain to reference
  * @wakeref: wakeref acquired for the reference that is being released
diff --git a/drivers/gpu/drm/i915/display/intel_tc.c b/drivers/gpu/drm/i915/display/intel_tc.c
index e5af955b5600..10cda362537e 100644
--- a/drivers/gpu/drm/i915/display/intel_tc.c
+++ b/drivers/gpu/drm/i915/display/intel_tc.c
@@ -797,7 +797,7 @@ void intel_tc_port_lock(struct intel_digital_port *dig_port)
 
 /**
  * intel_tc_port_disconnect_phy_work: disconnect TypeC PHY from display port
- * @dig_port: digital port
+ * @work: workqueue struct
  *
  * Disconnect the given digital port from its TypeC PHY (handing back the
  * control of the PHY to the TypeC subsystem). This will happen in a delayed
-- 
2.37.3

[PATCH v3 03/37] drm/i915: gt: fix some Kernel-doc issues

[Mauro Carvalho Chehab]

There are several trivial warnings there, due to trivial things:
	- lack of function name at the kerneldoc markup;
	- undocumented structs with kernel-doc markups;
	- wrong parameter syntax.

    Fix such warnings:

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

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

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

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

[PATCH v3 04/37] drm/i915: gvt: fix kernel-doc trivial warnings

[Mauro Carvalho Chehab]

Some functions seem to have been renamed without updating the kernel-doc
markup causing warnings. Also, struct intel_vgpu_dmabuf_obj is not
properly documented, but has a kerneld-doc markup.

Fix those warnings:
	drivers/gpu/drm/i915/gvt/aperture_gm.c:308: warning: expecting prototype for inte_gvt_free_vgpu_resource(). Prototype was for intel_vgpu_free_resource() instead
	drivers/gpu/drm/i915/gvt/aperture_gm.c:344: warning: expecting prototype for intel_alloc_vgpu_resource(). Prototype was for intel_vgpu_alloc_resource() instead
	drivers/gpu/drm/i915/gvt/cfg_space.c:257: warning: expecting prototype for intel_vgpu_emulate_cfg_read(). Prototype was for intel_vgpu_emulate_cfg_write() instead
	drivers/gpu/drm/i915/gvt/dmabuf.h:61: warning: Function parameter or member 'vgpu' not described in 'intel_vgpu_dmabuf_obj'
	drivers/gpu/drm/i915/gvt/dmabuf.h:61: warning: Function parameter or member 'info' not described in 'intel_vgpu_dmabuf_obj'
	drivers/gpu/drm/i915/gvt/dmabuf.h:61: warning: Function parameter or member 'dmabuf_id' not described in 'intel_vgpu_dmabuf_obj'
	drivers/gpu/drm/i915/gvt/dmabuf.h:61: warning: Function parameter or member 'kref' not described in 'intel_vgpu_dmabuf_obj'
	drivers/gpu/drm/i915/gvt/dmabuf.h:61: warning: Function parameter or member 'initref' not described in 'intel_vgpu_dmabuf_obj'
	drivers/gpu/drm/i915/gvt/dmabuf.h:61: warning: Function parameter or member 'list' not described in 'intel_vgpu_dmabuf_obj'
	drivers/gpu/drm/i915/gvt/handlers.c:3066: warning: expecting prototype for intel_t_default_mmio_write(). Prototype was for intel_vgpu_default_mmio_write() instead
	drivers/gpu/drm/i915/gvt/mmio_context.c:560: warning: expecting prototype for intel_gvt_switch_render_mmio(). Prototype was for intel_gvt_switch_mmio() instead
	drivers/gpu/drm/i915/gvt/page_track.c:131: warning: expecting prototype for intel_vgpu_enable_page_track(). Prototype was for intel_vgpu_disable_page_track() instead
	drivers/gpu/drm/i915/gvt/vgpu.c:215: warning: expecting prototype for intel_gvt_active_vgpu(). Prototype was for intel_gvt_activate_vgpu() instead
	drivers/gpu/drm/i915/gvt/vgpu.c:230: warning: expecting prototype for intel_gvt_deactive_vgpu(). Prototype was for intel_gvt_deactivate_vgpu() instead
	drivers/gpu/drm/i915/gvt/vgpu.c:358: warning: expecting prototype for intel_gvt_destroy_vgpu(). Prototype was for intel_gvt_destroy_idle_vgpu() instead

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Acked-by: Zhenyu Wang <zhenyuw@linux.intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/gvt/cfg_space.c  | 2 +-
 drivers/gpu/drm/i915/gvt/dmabuf.h     | 2 +-
 drivers/gpu/drm/i915/gvt/page_track.c | 2 +-
 drivers/gpu/drm/i915/gvt/vgpu.c       | 6 +++---
 4 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/drivers/gpu/drm/i915/gvt/cfg_space.c b/drivers/gpu/drm/i915/gvt/cfg_space.c
index eef3bba8a41b..bff63babacd5 100644
--- a/drivers/gpu/drm/i915/gvt/cfg_space.c
+++ b/drivers/gpu/drm/i915/gvt/cfg_space.c
@@ -244,7 +244,7 @@ static void emulate_pci_bar_write(struct intel_vgpu *vgpu, unsigned int offset,
 }
 
 /**
- * intel_vgpu_emulate_cfg_read - emulate vGPU configuration space write
+ * intel_vgpu_emulate_cfg_write - emulate vGPU configuration space write
  * @vgpu: target vgpu
  * @offset: offset
  * @p_data: write data ptr
diff --git a/drivers/gpu/drm/i915/gvt/dmabuf.h b/drivers/gpu/drm/i915/gvt/dmabuf.h
index 5f8f03fb1d1b..3dcdb6570eda 100644
--- a/drivers/gpu/drm/i915/gvt/dmabuf.h
+++ b/drivers/gpu/drm/i915/gvt/dmabuf.h
@@ -48,7 +48,7 @@ struct intel_vgpu_fb_info {
 	struct intel_vgpu_dmabuf_obj *obj;
 };
 
-/**
+/*
  * struct intel_vgpu_dmabuf_obj- Intel vGPU device buffer object
  */
 struct intel_vgpu_dmabuf_obj {
diff --git a/drivers/gpu/drm/i915/gvt/page_track.c b/drivers/gpu/drm/i915/gvt/page_track.c
index 3375b51c75f1..df34e73cba41 100644
--- a/drivers/gpu/drm/i915/gvt/page_track.c
+++ b/drivers/gpu/drm/i915/gvt/page_track.c
@@ -120,7 +120,7 @@ int intel_vgpu_enable_page_track(struct intel_vgpu *vgpu, unsigned long gfn)
 }
 
 /**
- * intel_vgpu_enable_page_track - cancel write-protection on guest page
+ * intel_vgpu_disable_page_track - cancel write-protection on guest page
  * @vgpu: a vGPU
  * @gfn: the gfn of guest page
  *
diff --git a/drivers/gpu/drm/i915/gvt/vgpu.c b/drivers/gpu/drm/i915/gvt/vgpu.c
index 46da19b3225d..8e71cda19995 100644
--- a/drivers/gpu/drm/i915/gvt/vgpu.c
+++ b/drivers/gpu/drm/i915/gvt/vgpu.c
@@ -205,7 +205,7 @@ static void intel_gvt_update_vgpu_types(struct intel_gvt *gvt)
 }
 
 /**
- * intel_gvt_active_vgpu - activate a virtual GPU
+ * intel_gvt_activate_vgpu - activate a virtual GPU
  * @vgpu: virtual GPU
  *
  * This function is called when user wants to activate a virtual GPU.
@@ -219,7 +219,7 @@ void intel_gvt_activate_vgpu(struct intel_vgpu *vgpu)
 }
 
 /**
- * intel_gvt_deactive_vgpu - deactivate a virtual GPU
+ * intel_gvt_deactivate_vgpu - deactivate a virtual GPU
  * @vgpu: virtual GPU
  *
  * This function is called when user wants to deactivate a virtual GPU.
@@ -348,7 +348,7 @@ struct intel_vgpu *intel_gvt_create_idle_vgpu(struct intel_gvt *gvt)
 }
 
 /**
- * intel_gvt_destroy_vgpu - destroy an idle virtual GPU
+ * intel_gvt_destroy_idle_vgpu - destroy an idle virtual GPU
  * @vgpu: virtual GPU
  *
  * This function is called when user wants to destroy an idle virtual GPU.
-- 
2.37.3

[PATCH v3 05/37] drm/i915: gem: fix some Kernel-doc issues

[Mauro Carvalho Chehab]

There are several trivial issueson kernel-doc markups at gem:

	drivers/gpu/drm/i915/gem/i915_gem_create.c:146: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
	drivers/gpu/drm/i915/gem/i915_gem_create.c:217: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
	drivers/gpu/drm/i915/gem/i915_gem_create.c:401: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
	drivers/gpu/drm/i915/gem/i915_gem_domain.c:116: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
	drivers/gpu/drm/i915/gem/i915_gem_domain.c:177: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
	drivers/gpu/drm/i915/gem/i915_gem_domain.c:262: warning: expecting prototype for Changes the cache(). Prototype was for i915_gem_object_set_cache_level() instead
	drivers/gpu/drm/i915/gem/i915_gem_domain.c:456: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
	drivers/gpu/drm/i915/gem/i915_gem_domain.c:500: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
	drivers/gpu/drm/i915/gem/i915_gem_object.h:110: warning: Function parameter or member 'file' not described in 'i915_gem_object_lookup_rcu'
	drivers/gpu/drm/i915/gem/i915_gem_object.h:110: warning: Excess function parameter 'filp' description in 'i915_gem_object_lookup_rcu'
	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'
	drivers/gpu/drm/i915/gem/i915_gem_wait.c:130: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst

Caused by:
	- lack of function name at the kernel-doc markup;
	- renamed parameters.

Address them.

Reviewed-by: Nirmoy Das <nirmoy.das@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/gem/i915_gem_create.c |  8 +++++---
 drivers/gpu/drm/i915/gem/i915_gem_domain.c | 17 +++++++++++------
 drivers/gpu/drm/i915/gem/i915_gem_object.h |  2 +-
 drivers/gpu/drm/i915/gem/i915_gem_wait.c   |  2 +-
 4 files changed, 18 insertions(+), 11 deletions(-)

diff --git a/drivers/gpu/drm/i915/gem/i915_gem_create.c b/drivers/gpu/drm/i915/gem/i915_gem_create.c
index 33673fe7ee0a..8cb2eb092031 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_create.c
+++ b/drivers/gpu/drm/i915/gem/i915_gem_create.c
@@ -143,7 +143,8 @@ __i915_gem_object_create_user_ext(struct drm_i915_private *i915, u64 size,
 }
 
 /**
- * Creates a new object using the same path as DRM_I915_GEM_CREATE_EXT
+ * __i915_gem_object_create_user - Creates a new object using the same path
+ *	as DRM_I915_GEM_CREATE_EXT
  * @i915: i915 private
  * @size: size of the buffer, in bytes
  * @placements: possible placement regions, in priority order
@@ -214,7 +215,7 @@ i915_gem_dumb_create(struct drm_file *file,
 }
 
 /**
- * Creates a new mm object and returns a handle to it.
+ * i915_gem_create_ioctl - Creates a new mm object and returns a handle to it.
  * @dev: drm device pointer
  * @data: ioctl data blob
  * @file: drm file pointer
@@ -398,7 +399,8 @@ static const i915_user_extension_fn create_extensions[] = {
 };
 
 /**
- * Creates a new mm object and returns a handle to it.
+ * i915_gem_create_ext_ioctl - Creates a new mm object and returns a handle
+ *	to it.
  * @dev: drm device pointer
  * @data: ioctl data blob
  * @file: drm file pointer
diff --git a/drivers/gpu/drm/i915/gem/i915_gem_domain.c b/drivers/gpu/drm/i915/gem/i915_gem_domain.c
index d44a152ce680..fd4f10765208 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_domain.c
+++ b/drivers/gpu/drm/i915/gem/i915_gem_domain.c
@@ -113,7 +113,8 @@ void i915_gem_object_flush_if_display_locked(struct drm_i915_gem_object *obj)
 }
 
 /**
- * Moves a single object to the WC read, and possibly write domain.
+ * i915_gem_object_set_to_wc_domain - Moves a single object to the WC read,
+ *	and possibly write domain.
  * @obj: object to act on
  * @write: ask for write access or read only
  *
@@ -174,7 +175,8 @@ i915_gem_object_set_to_wc_domain(struct drm_i915_gem_object *obj, bool write)
 }
 
 /**
- * Moves a single object to the GTT read, and possibly write domain.
+ * i915_gem_object_set_to_gtt_domain - Moves a single object to the GTT read,
+ *	and possibly write domain.
  * @obj: object to act on
  * @write: ask for write access or read only
  *
@@ -243,7 +245,8 @@ i915_gem_object_set_to_gtt_domain(struct drm_i915_gem_object *obj, bool write)
 }
 
 /**
- * Changes the cache-level of an object across all VMA.
+ * i915_gem_object_set_cache_level - Changes the cache-level of an object
+ *	across all VMA.
  * @obj: object to act on
  * @cache_level: new cache level to set for the object
  *
@@ -453,7 +456,8 @@ i915_gem_object_pin_to_display_plane(struct drm_i915_gem_object *obj,
 }
 
 /**
- * Moves a single object to the CPU read, and possibly write domain.
+ * i915_gem_object_set_to_cpu_domain - Moves a single object to the CPU read,
+ *	and possibly write domain.
  * @obj: object to act on
  * @write: requesting write or read-only access
  *
@@ -497,8 +501,9 @@ i915_gem_object_set_to_cpu_domain(struct drm_i915_gem_object *obj, bool write)
 }
 
 /**
- * Called when user space prepares to use an object with the CPU, either
- * through the mmap ioctl's mapping or a GTT mapping.
+ * i915_gem_set_domain_ioctl - Called when user space prepares to use an
+ *	object with the CPU, either through the mmap ioctl's mapping or a
+ *	GTT mapping.
  * @dev: drm device
  * @data: ioctl data blob
  * @file: drm file
diff --git a/drivers/gpu/drm/i915/gem/i915_gem_object.h b/drivers/gpu/drm/i915/gem/i915_gem_object.h
index 7317d4102955..df4361e00eb9 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_object.h
+++ b/drivers/gpu/drm/i915/gem/i915_gem_object.h
@@ -96,7 +96,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:
diff --git a/drivers/gpu/drm/i915/gem/i915_gem_wait.c b/drivers/gpu/drm/i915/gem/i915_gem_wait.c
index e6e01c2a74a6..4a33ad2d122b 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_wait.c
+++ b/drivers/gpu/drm/i915/gem/i915_gem_wait.c
@@ -161,7 +161,7 @@ i915_gem_object_wait_priority(struct drm_i915_gem_object *obj,
 }
 
 /**
- * Waits for rendering to the object to be completed
+ * i915_gem_object_wait - Waits for rendering to the object to be completed
  * @obj: i915 gem object
  * @flags: how to wait (under a lock, for all rendering or just for writes etc)
  * @timeout: how long to wait
-- 
2.37.3

[PATCH v3 06/37] drm/i915: intel_wakeref.h: fix some kernel-doc markups

[Mauro Carvalho Chehab]

Two documented functions don't match the kernel-doc comments,
as reported by kernel-doc:

	drivers/gpu/drm/i915/intel_wakeref.h:117: warning: expecting prototype for intel_wakeref_get_if_in_use(). Prototype was for intel_wakeref_get_if_active() instead
	drivers/gpu/drm/i915/intel_wakeref.h:149: warning: expecting prototype for intel_wakeref_put_flags(). Prototype was for __intel_wakeref_put() instead

Fix them.

Additionally, improve title for intel_wakeref_get_if_active().

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/intel_wakeref.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/gpu/drm/i915/intel_wakeref.h b/drivers/gpu/drm/i915/intel_wakeref.h
index 4f4c2e15e736..63e539c9b1f3 100644
--- a/drivers/gpu/drm/i915/intel_wakeref.h
+++ b/drivers/gpu/drm/i915/intel_wakeref.h
@@ -104,7 +104,7 @@ __intel_wakeref_get(struct intel_wakeref *wf)
 }
 
 /**
- * intel_wakeref_get_if_in_use: Acquire the wakeref
+ * intel_wakeref_get_if_active: Acquire the wakeref if active
  * @wf: the wakeref
  *
  * Acquire a hold on the wakeref, but only if the wakeref is already
@@ -130,7 +130,7 @@ intel_wakeref_might_get(struct intel_wakeref *wf)
 }
 
 /**
- * intel_wakeref_put_flags: Release the wakeref
+ * __intel_wakeref_put: Release the wakeref
  * @wf: the wakeref
  * @flags: control flags
  *
-- 
2.37.3

[PATCH v3 07/37] drm/i915: i915_gem_ttm: fix a kernel-doc markup

[Mauro Carvalho Chehab]

Two new fields were added to __i915_gem_ttm_object_init() without
their corresponding documentation.

Document them.

Fixes: 9b78b5dade2d ("drm/i915: add i915_gem_object_create_region_at()")
Reviewed-by: Nirmoy Das <nirmoy.das@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/gem/i915_gem_ttm.c | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/drivers/gpu/drm/i915/gem/i915_gem_ttm.c b/drivers/gpu/drm/i915/gem/i915_gem_ttm.c
index f64a3deb12fc..f5fb06d74f13 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_ttm.c
+++ b/drivers/gpu/drm/i915/gem/i915_gem_ttm.c
@@ -1148,7 +1148,9 @@ void i915_ttm_bo_destroy(struct ttm_buffer_object *bo)
  * __i915_gem_ttm_object_init - Initialize a ttm-backed i915 gem object
  * @mem: The initial memory region for the object.
  * @obj: The gem object.
+ * @offset: The range start.
  * @size: Object size in bytes.
+ * @page_size: The requested page size in bytes for this object.
  * @flags: gem object flags.
  *
  * Return: 0 on success, negative error code on failure.
-- 
2.37.3

[PATCH v3 08/37] drm/i915: i915_gem_ttm_pm.c: fix kernel-doc markups

[Mauro Carvalho Chehab]

The documentation for the flags field is missing there. It sounds
that some last-time change converted some bools into flags, but
the kernel-doc change didn't follow it.

Fix those warnings:

	drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c:135: warning: Function parameter or member 'flags' not described in 'i915_ttm_backup_region'
	drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c:135: warning: Excess function parameter 'allow_gpu' description in 'i915_ttm_backup_region'
	drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c:135: warning: Excess function parameter 'backup_pinned' description in 'i915_ttm_backup_region'
	drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c:199: warning: Function parameter or member 'flags' not described in 'i915_ttm_restore_region'
	drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c:199: warning: Excess function parameter 'allow_gpu' description in 'i915_ttm_restore_region'

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c b/drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c
index 07e49f22f2de..03256ebbeb5f 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c
+++ b/drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c
@@ -128,8 +128,9 @@ void i915_ttm_recover_region(struct intel_memory_region *mr)
 /**
  * i915_ttm_backup_region - Back up all objects of a region to smem.
  * @mr: The memory region
- * @allow_gpu: Whether to allow the gpu blitter for this backup.
- * @backup_pinned: Backup also pinned objects.
+ * @flags: Bitmap field with the following flags:
+ *	%I915_TTM_BACKUP_ALLOW_GPU: allow the gpu blitter for this backup;
+ *	%I915_TTM_BACKUP_PINNED: backup also pinned objects.
  *
  * Loops over all objects of a region and either evicts them if they are
  * evictable or backs them up using a backup object if they are pinned.
@@ -193,7 +194,8 @@ static int i915_ttm_restore(struct i915_gem_apply_to_region *apply,
 /**
  * i915_ttm_restore_region - Restore backed-up objects of a region from smem.
  * @mr: The memory region
- * @allow_gpu: Whether to allow the gpu blitter to recover.
+ * @flags: Bitmap field with the following flags:
+ *	%I915_TTM_BACKUP_ALLOW_GPU: allow the gpu blitter for this backup;
  *
  * Loops over all objects of a region and if they are backed-up, restores
  * them from smem.
-- 
2.37.3

[PATCH v3 09/37] drm/i915: gem: add kernel-doc description for some function parameters

[Mauro Carvalho Chehab]

There are some parameters missing at the kernel-doc markups on
some gem files. Some of those are trivial enough to be added.

Document them.

Reviewed-by: Nirmoy Das <nirmoy.das@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/gem/i915_gem_object.c   | 2 ++
 drivers/gpu/drm/i915/gem/i915_gem_ttm.h      | 1 +
 drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c | 2 ++
 3 files changed, 5 insertions(+)

diff --git a/drivers/gpu/drm/i915/gem/i915_gem_object.c b/drivers/gpu/drm/i915/gem/i915_gem_object.c
index 85482a04d158..35637e2f51f3 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_object.c
+++ b/drivers/gpu/drm/i915/gem/i915_gem_object.c
@@ -815,6 +815,8 @@ int i915_gem_object_wait_moving_fence(struct drm_i915_gem_object *obj,
  * in an unknown_state. This means that userspace must NEVER be allowed to touch
  * the pages, with either the GPU or CPU.
  *
+ * @obj: The object to check its state.
+ *
  * ONLY valid to be called after ensuring that all kernel fences have signalled
  * (in particular the fence for moving/clearing the object).
  */
diff --git a/drivers/gpu/drm/i915/gem/i915_gem_ttm.h b/drivers/gpu/drm/i915/gem/i915_gem_ttm.h
index e4842b4296fc..64151f40098f 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_ttm.h
+++ b/drivers/gpu/drm/i915/gem/i915_gem_ttm.h
@@ -30,6 +30,7 @@ void i915_ttm_bo_destroy(struct ttm_buffer_object *bo);
 /**
  * i915_ttm_to_gem - Convert a struct ttm_buffer_object to an embedding
  * struct drm_i915_gem_object.
+ * @bo: The ttm buffer object.
  *
  * Return: Pointer to the embedding struct ttm_buffer_object, or NULL
  * if the object was not an i915 ttm object.
diff --git a/drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c b/drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c
index 9a7e50534b84..56217d324a9b 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c
+++ b/drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c
@@ -237,6 +237,7 @@ static struct dma_fence *i915_ttm_accel_move(struct ttm_buffer_object *bo,
  * @_src_iter: Storage space for the source kmap iterator.
  * @dst_iter: Pointer to the destination kmap iterator.
  * @src_iter: Pointer to the source kmap iterator.
+ * @num_pages: Number of pages to copy or to be cleared.
  * @clear: Whether to clear instead of copy.
  * @src_rsgt: Refcounted scatter-gather list of source memory.
  * @dst_rsgt: Refcounted scatter-gather list of destination memory.
@@ -541,6 +542,7 @@ __i915_ttm_move(struct ttm_buffer_object *bo,
  * i915_ttm_move - The TTM move callback used by i915.
  * @bo: The buffer object.
  * @evict: Whether this is an eviction.
+ * @ctx: Pointer to a struct ttm_operation_ctx
  * @dst_mem: The destination ttm resource.
  * @hop: If we need multihop, what temporary memory type to move to.
  *
-- 
2.37.3

[PATCH v3 10/37] drm/i915: i915_gpu_error.c: document dump_flags

[Mauro Carvalho Chehab]

Kernel-doc dump_flags parameter is missing at i915_capture_error_state().
Document it.

Fixes: a6f0f9cf330a ("drm/i915/guc: Plumb GuC-capture into gpu_coredump")
Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/i915_gpu_error.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/i915_gpu_error.c b/drivers/gpu/drm/i915/i915_gpu_error.c
index 9ea2fe34e7d3..c2350284f221 100644
--- a/drivers/gpu/drm/i915/i915_gpu_error.c
+++ b/drivers/gpu/drm/i915/i915_gpu_error.c
@@ -2148,7 +2148,8 @@ 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: bitmap flags. When %CORE_DUMP_FLAG_IS_GUC_CAPTURE is used,
+ *	dump engine record registers and execlists.
  *
  * 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.37.3

[PATCH v3 11/37] drm/i915: document kernel-doc trivial issues

[Mauro Carvalho Chehab]

Fix those kernel-doc warnings:
	drivers/gpu/drm/i915/intel_region_ttm.c:199: warning: Function parameter or member 'offset' not described in 'intel_region_ttm_resource_alloc'
	drivers/gpu/drm/i915/i915_vma_resource.h:123: warning: Function parameter or member 'wakeref' not described in 'i915_vma_resource'
	drivers/gpu/drm/i915/i915_vma.c:1703: warning: Function parameter or member 'vma' not described in 'i915_vma_destroy_locked'
	drivers/gpu/drm/i915/i915_vma.c:751: warning: Function parameter or member 'ww' not described in 'i915_vma_insert'
	drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:159: warning: Function parameter or member 'gt' not described in 'intel_gt_fini_hwconfig'
	drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:146: warning: Function parameter or member 'gt' not described in 'intel_gt_init_hwconfig'
	drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:113: warning: expecting prototype for intel_guc_hwconfig_init(). Prototype was for guc_hwconfig_init() instead
	drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:113: warning: Function parameter or member 'gt' not described in 'guc_hwconfig_init'
	drivers/gpu/drm/i915/gt/intel_engine_types.h:276: warning: Function parameter or member 'preempt_hang' not described in 'intel_engine_execlists'

That are due undocumented parameters.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/gt/intel_engine_types.h    | 1 +
 drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c | 5 ++++-
 drivers/gpu/drm/i915/i915_vma.c                 | 2 ++
 drivers/gpu/drm/i915/i915_vma_resource.h        | 1 +
 drivers/gpu/drm/i915/intel_region_ttm.c         | 3 ++-
 5 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/drivers/gpu/drm/i915/gt/intel_engine_types.h b/drivers/gpu/drm/i915/gt/intel_engine_types.h
index 633a7e5dba3b..7c5ad9071fe7 100644
--- a/drivers/gpu/drm/i915/gt/intel_engine_types.h
+++ b/drivers/gpu/drm/i915/gt/intel_engine_types.h
@@ -271,6 +271,7 @@ struct intel_engine_execlists {
 	 */
 	u8 csb_head;
 
+	/* private: Used only in selftests */
 	I915_SELFTEST_DECLARE(struct st_preempt_hang preempt_hang;)
 };
 
diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c b/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
index 4781fccc2687..76f7447302a6 100644
--- a/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
+++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
@@ -103,7 +103,8 @@ static bool has_table(struct drm_i915_private *i915)
 }
 
 /**
- * intel_guc_hwconfig_init - Initialize the HWConfig
+ * guc_hwconfig_init - Initialize the HWConfig
+ * @gt: GT structure
  *
  * Retrieve the HWConfig table from the GuC and save it locally.
  * It can then be queried on demand by other users later on.
@@ -138,6 +139,7 @@ static int guc_hwconfig_init(struct intel_gt *gt)
 
 /**
  * intel_gt_init_hwconfig - Initialize the HWConfig if available
+ * @gt: GT structure
  *
  * Retrieve the HWConfig table if available on the current platform.
  */
@@ -151,6 +153,7 @@ int intel_gt_init_hwconfig(struct intel_gt *gt)
 
 /**
  * intel_gt_fini_hwconfig - Finalize the HWConfig
+ * @gt: GT structure
  *
  * Free up the memory allocation holding the table.
  */
diff --git a/drivers/gpu/drm/i915/i915_vma.c b/drivers/gpu/drm/i915/i915_vma.c
index f17c09ead7d7..946f26138381 100644
--- a/drivers/gpu/drm/i915/i915_vma.c
+++ b/drivers/gpu/drm/i915/i915_vma.c
@@ -731,6 +731,7 @@ bool i915_gem_valid_gtt_space(struct i915_vma *vma, unsigned long color)
 /**
  * i915_vma_insert - finds a slot for the vma in its address space
  * @vma: the vma
+ * @ww: An optional struct i915_gem_ww_ctx
  * @size: requested size in bytes (can be larger than the VMA)
  * @alignment: required alignment
  * @flags: mask of PIN_* flags to use
@@ -1686,6 +1687,7 @@ static void release_references(struct i915_vma *vma, struct intel_gt *gt,
 /**
  * i915_vma_destroy_locked - Remove all weak reference to the vma and put
  * the initial reference.
+ * @vma: VMA to destroy
  *
  * This function should be called when it's decided the vma isn't needed
  * anymore. The caller must assure that it doesn't race with another lookup
diff --git a/drivers/gpu/drm/i915/i915_vma_resource.h b/drivers/gpu/drm/i915/i915_vma_resource.h
index e155f6f7af6f..02dd8bb89c0a 100644
--- a/drivers/gpu/drm/i915/i915_vma_resource.h
+++ b/drivers/gpu/drm/i915/i915_vma_resource.h
@@ -49,6 +49,7 @@ struct i915_page_sizes {
  * @__subtree_last: Interval tree private member.
  * @vm: non-refcounted pointer to the vm. This is for internal use only and
  * this member is cleared after vm_resource unbind.
+ * @wakeref: wakeref used for runtime PM reference.
  * @mr: The memory region of the object pointed to by the vma.
  * @ops: Pointer to the backend i915_vma_ops.
  * @private: Bind backend private info.
diff --git a/drivers/gpu/drm/i915/intel_region_ttm.c b/drivers/gpu/drm/i915/intel_region_ttm.c
index 575d67bc6ffe..c2f87683236a 100644
--- a/drivers/gpu/drm/i915/intel_region_ttm.c
+++ b/drivers/gpu/drm/i915/intel_region_ttm.c
@@ -181,7 +181,8 @@ intel_region_ttm_resource_to_rsgt(struct intel_memory_region *mem,
 #ifdef CONFIG_DRM_I915_SELFTEST
 /**
  * intel_region_ttm_resource_alloc - Allocate memory resources from a region
- * @mem: The memory region,
+ * @mem: The memory region
+ * @offset: The range start
  * @size: The requested size in bytes
  * @flags: Allocation flags
  *
-- 
2.37.3

[PATCH v3 12/37] drm/i915: intel_dp_link_training.c: fix kernel-doc markup

[Mauro Carvalho Chehab]

The return code table is not properly marked, causing warnings
and being badly parsed by Sphinx:

    Documentation/gpu/i915:130: ./drivers/gpu/drm/i915/display/intel_dp_link_training.c:183: WARNING: Block quote ends without a blank line; unexpected unindent.
    Documentation/gpu/i915:130: ./drivers/gpu/drm/i915/display/intel_dp_link_training.c:186: WARNING: Definition list ends without a blank line; unexpected unindent.

Use table markups to fix it.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/display/intel_dp_link_training.c | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/drivers/gpu/drm/i915/display/intel_dp_link_training.c b/drivers/gpu/drm/i915/display/intel_dp_link_training.c
index d213d8ad1ea5..27c3b9f39c8b 100644
--- a/drivers/gpu/drm/i915/display/intel_dp_link_training.c
+++ b/drivers/gpu/drm/i915/display/intel_dp_link_training.c
@@ -177,12 +177,14 @@ static int intel_dp_init_lttpr(struct intel_dp *intel_dp, const u8 dpcd[DP_RECEI
  * transparent mode link training mode.
  *
  * Returns:
+ * ====  =====================================================================
  *   >0  if LTTPRs were detected and the non-transparent LT mode was set. The
  *       DPRX capabilities are read out.
  *    0  if no LTTPRs or more than 8 LTTPRs were detected or in case of a
  *       detection failure and the transparent LT mode was set. The DPRX
  *       capabilities are read out.
  *   <0  Reading out the DPRX capabilities failed.
+ * ====  =====================================================================
  */
 int intel_dp_init_lttpr_and_dprx_caps(struct intel_dp *intel_dp)
 {
-- 
2.37.3

[PATCH v3 13/37] drm/i915: intel_fb: fix a kernel-doc issue with Sphinx

[Mauro Carvalho Chehab]

We can't use %foo[<something>] as this produces a bad markup.
Use instead, the emphasis markup directly.

Fix this issue:
	Documentation/gpu/i915:136: ./drivers/gpu/drm/i915/display/intel_fb.c:280: WARNING: Inline strong start-string without end-string.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/display/intel_fb.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/display/intel_fb.c b/drivers/gpu/drm/i915/display/intel_fb.c
index eefa33c555ac..ba413e38033d 100644
--- a/drivers/gpu/drm/i915/display/intel_fb.c
+++ b/drivers/gpu/drm/i915/display/intel_fb.c
@@ -276,7 +276,7 @@ lookup_format_info(const struct drm_format_info formats[],
  * @cmd: FB add command structure
  *
  * Returns:
- * Returns the format information for @cmd->pixel_format specific to @cmd->modifier[0],
+ * Returns the format information for @cmd->pixel_format specific to ``cmd->modifier[0]``,
  * or %NULL if the modifier doesn't override the format.
  */
 const struct drm_format_info *
-- 
2.37.3

[PATCH v3 14/37] drm/i915: skl_scaler: fix return value kernel-doc markup

[Mauro Carvalho Chehab]

The way it is, it produces this warning:

	Documentation/gpu/i915:150: ./drivers/gpu/drm/i915/display/skl_scaler.c:213: WARNING: Block quote ends without a blank line; unexpected unindent.

Use list markups to suppress the warning.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/display/skl_scaler.c | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/i915/display/skl_scaler.c b/drivers/gpu/drm/i915/display/skl_scaler.c
index 4092679be21e..59099f793d3e 100644
--- a/drivers/gpu/drm/i915/display/skl_scaler.c
+++ b/drivers/gpu/drm/i915/display/skl_scaler.c
@@ -208,9 +208,9 @@ int skl_update_scaler_crtc(struct intel_crtc_state *crtc_state)
  * @crtc_state: crtc's scaler state
  * @plane_state: atomic plane state to update
  *
- * Return
- *     0 - scaler_usage updated successfully
- *    error - requested scaling cannot be supported or other error condition
+ * Return:
+ * * 0 - scaler_usage updated successfully
+ * * error - requested scaling cannot be supported or other error condition
  */
 int skl_update_scaler_plane(struct intel_crtc_state *crtc_state,
 			    struct intel_plane_state *plane_state)
-- 
2.37.3

[PATCH v3 15/37] drm/i915: intel_pm.c: fix some ascii artwork at kernel-doc

[Mauro Carvalho Chehab]

Preserving ascii artwork on kernel-docs is tricky, as it needs
to respect both the Sphinx rules and be properly parsed by
kernel-doc script.

The Sphinx syntax require code-blocks, which is:

	::

followed by a blank line and indented lines.

But kernel-doc only works fine if the first and the last line
are indented with the same amount of spaces.

Also, a "\" at the end means that the next line should be merged
with the first one.

Change the ascii artwork to be on code-blocks, starting all
lines at the same characters and not ending with a backslash.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/intel_pm.c | 33 ++++++++++++++++++---------------
 1 file changed, 18 insertions(+), 15 deletions(-)

diff --git a/drivers/gpu/drm/i915/intel_pm.c b/drivers/gpu/drm/i915/intel_pm.c
index eb9c54bbf51f..1f5e520a6728 100644
--- a/drivers/gpu/drm/i915/intel_pm.c
+++ b/drivers/gpu/drm/i915/intel_pm.c
@@ -683,18 +683,20 @@ static const struct intel_watermark_params i845_wm_info = {
  * FIFO is relatively small compared to the amount of data
  * fetched.
  *
- * The FIFO level vs. time graph might look something like:
+ * The FIFO level vs. time graph might look something like::
  *
- *   |\   |\
- *   | \  | \
- * __---__---__ (- plane active, _ blanking)
- * -> time
+ *   ^
+ *   |   |\   |\      (                          )
+ *   |   | \  | \     (                          )
+ *   |   __---__---__ (- plane active, _ blanking)
+ *   +-------------------> time
  *
- * or perhaps like this:
+ * or perhaps like this::
  *
- *   |\|\  |\|\
- * __----__----__ (- plane active, _ blanking)
- * -> time
+ *   ^
+ *   |     |\|\  |\|\   (                          )
+ *   |   __----__----__ (- plane active, _ blanking)
+ *   +-------------------> time
  *
  * Returns:
  * The watermark in bytes
@@ -730,13 +732,14 @@ static unsigned int intel_wm_method1(unsigned int pixel_rate,
  * FIFO is relatively large compared to the amount of data
  * fetched.
  *
- * The FIFO level vs. time graph might look something like:
+ * The FIFO level vs. time graph might look something like::
  *
- *    |\___       |\___
- *    |    \___   |    \___
- *    |        \  |        \
- * __ --__--__--__--__--__--__ (- plane active, _ blanking)
- * -> time
+ *   ^
+ *   |     |\___       |\___        (                          )
+ *   |     |    \___   |    \___    (                          )
+ *   |     |        \  |        \   (                          )
+ *   |  __ --__--__--__--__--__--__ (- plane active, _ blanking)
+ *   +---------------------------------> time
  *
  * Returns:
  * The watermark in bytes
-- 
2.37.3

[PATCH v3 16/37] drm/i915: i915_gem_region.h: fix i915_gem_apply_to_region_ops doc

[Mauro Carvalho Chehab]

The kernel-doc markup for i915_gem_apply_to_region_ops() has some
issues:

1. The field should be marked as @process_obj;
2. The callback parameters aren't document properly, as sphinx
   will consider them to be placed at the wrong place.

Fix (1) and change the way the parameters are described, using
a list, in order for it to be properly parsed during documentation
build time.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/gem/i915_gem_region.h | 8 +++++---
 1 file changed, 5 insertions(+), 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..b0134bf4b1b7 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_region.h
+++ b/drivers/gpu/drm/i915/gem/i915_gem_region.h
@@ -22,9 +22,11 @@ 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: Callback function to process the current object
+	 * it requires two arguments:
+	 *
+	 * - @apply: Embed this for private data.
+	 * - @obj: 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.37.3

[PATCH v3 17/37] drm/i915: i915_gem_wait.c: fix a kernel-doc markup

[Mauro Carvalho Chehab]

The return codes for i915_gem_wait_ioctl() have identation issues,
and will be displayed on a very confusing way. Use lists to improve
its output.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/gem/i915_gem_wait.c | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/drivers/gpu/drm/i915/gem/i915_gem_wait.c b/drivers/gpu/drm/i915/gem/i915_gem_wait.c
index 4a33ad2d122b..1fd5cff552ed 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_wait.c
+++ b/drivers/gpu/drm/i915/gem/i915_gem_wait.c
@@ -210,23 +210,25 @@ static unsigned long to_wait_timeout(s64 timeout_ns)
  * @data: ioctl data blob
  * @file: drm file pointer
  *
- * Returns 0 if successful, else an error is returned with the remaining time in
- * the timeout parameter.
- *  -ETIME: object is still busy after timeout
- *  -ERESTARTSYS: signal interrupted the wait
- *  -ENONENT: object doesn't exist
- * Also possible, but rare:
- *  -EAGAIN: incomplete, restart syscall
- *  -ENOMEM: damn
- *  -ENODEV: Internal IRQ fail
- *  -E?: The add request failed
- *
  * The wait ioctl with a timeout of 0 reimplements the busy ioctl. With any
  * non-zero timeout parameter the wait ioctl will wait for the given number of
  * nanoseconds on an object becoming unbusy. Since the wait itself does so
  * without holding struct_mutex the object may become re-busied before this
  * function completes. A similar but shorter * race condition exists in the busy
  * ioctl
+ *
+ * Returns:
+ * 0 if successful, else an error is returned with the remaining time in
+ * the timeout parameter.
+ * * -ETIME: object is still busy after timeout
+ * * -ERESTARTSYS: signal interrupted the wait
+ * * -ENONENT: object doesn't exist
+ *
+ * Also possible, but rare:
+ * * -EAGAIN: incomplete, restart syscall
+ * * -ENOMEM: damn
+ * * -ENODEV: Internal IRQ fail
+ * * -E?: The add request failed
  */
 int
 i915_gem_wait_ioctl(struct drm_device *dev, void *data, struct drm_file *file)
-- 
2.37.3

[PATCH v3 18/37] drm/i915: fix i915_gem_ttm_move.c DOC: markup

[Mauro Carvalho Chehab]

The doc markup should not end with ":", as it would generate a
warning on Sphinx while generating the cross-reference tag.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c b/drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c
index 56217d324a9b..16dd4991d527 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c
+++ b/drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c
@@ -20,7 +20,7 @@
 #include "gt/intel_migrate.h"
 
 /**
- * DOC: Selftest failure modes for failsafe migration:
+ * DOC: Selftest failure modes for failsafe migration
  *
  * For fail_gpu_migration, the gpu blit scheduled is always a clear blit
  * rather than a copy blit, and then we force the failure paths as if
-- 
2.37.3

[PATCH v3 19/37] drm/i915: stop using kernel-doc markups for something else

[Mauro Carvalho Chehab]

There are some occurrences of "/**" that aren't actually part of
a kernel-doc markup. Replace them by "/*", in order to make easier
to identify what i915 files contain kernel-doc markups.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/display/dvo_ch7017.c     | 26 +++----
 drivers/gpu/drm/i915/display/dvo_ch7xxx.c     |  6 +-
 .../drm/i915/display/intel_display_types.h    |  2 +-
 drivers/gpu/drm/i915/display/intel_dvo_dev.h  |  6 +-
 drivers/gpu/drm/i915/display/intel_sdvo.c     |  4 +-
 drivers/gpu/drm/i915/display/intel_tv.c       |  2 +-
 drivers/gpu/drm/i915/gt/intel_context_types.h | 69 +++++++++----------
 drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h  |  2 +-
 drivers/gpu/drm/i915/gt/intel_gt_types.h      | 12 ++--
 drivers/gpu/drm/i915/gt/intel_reset_types.h   |  4 +-
 .../gpu/drm/i915/gt/intel_timeline_types.h    |  6 +-
 .../drm/i915/gt/shaders/clear_kernel/hsw.asm  |  4 +-
 .../drm/i915/gt/shaders/clear_kernel/ivb.asm  |  4 +-
 drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h | 10 +--
 drivers/gpu/drm/i915/i915_drm_client.h        |  2 +-
 drivers/gpu/drm/i915/i915_drv.h               | 24 +++----
 drivers/gpu/drm/i915/i915_file_private.h      |  8 +--
 drivers/gpu/drm/i915/i915_gpu_error.h         |  4 +-
 drivers/gpu/drm/i915/i915_pmu.h               | 32 ++++-----
 drivers/gpu/drm/i915/intel_uncore.h           |  4 +-
 20 files changed, 115 insertions(+), 116 deletions(-)

diff --git a/drivers/gpu/drm/i915/display/dvo_ch7017.c b/drivers/gpu/drm/i915/display/dvo_ch7017.c
index 0589994dde11..581e29ab77e4 100644
--- a/drivers/gpu/drm/i915/display/dvo_ch7017.c
+++ b/drivers/gpu/drm/i915/display/dvo_ch7017.c
@@ -55,13 +55,13 @@
 #define CH7017_TEST_PATTERN		0x48
 
 #define CH7017_POWER_MANAGEMENT		0x49
-/** Enables the TV output path. */
+/* Enables the TV output path. */
 #define CH7017_TV_EN			(1 << 0)
 #define CH7017_DAC0_POWER_DOWN		(1 << 1)
 #define CH7017_DAC1_POWER_DOWN		(1 << 2)
 #define CH7017_DAC2_POWER_DOWN		(1 << 3)
 #define CH7017_DAC3_POWER_DOWN		(1 << 4)
-/** Powers down the TV out block, and DAC0-3 */
+/* Powers down the TV out block, and DAC0-3 */
 #define CH7017_TV_POWER_DOWN_EN		(1 << 5)
 
 #define CH7017_VERSION_ID		0x4a
@@ -84,26 +84,26 @@
 #define CH7017_UP_SCALER_HORIZONTAL_INC_1	0x5e
 
 #define CH7017_HORIZONTAL_ACTIVE_PIXEL_INPUT	0x5f
-/**< Low bits of horizontal active pixel input */
+/* Low bits of horizontal active pixel input */
 
 #define CH7017_ACTIVE_INPUT_LINE_OUTPUT	0x60
-/** High bits of horizontal active pixel input */
+/* High bits of horizontal active pixel input */
 #define CH7017_LVDS_HAP_INPUT_MASK	(0x7 << 0)
-/** High bits of vertical active line output */
+/* High bits of vertical active line output */
 #define CH7017_LVDS_VAL_HIGH_MASK	(0x7 << 3)
 
 #define CH7017_VERTICAL_ACTIVE_LINE_OUTPUT	0x61
-/**< Low bits of vertical active line output */
+/* Low bits of vertical active line output */
 
 #define CH7017_HORIZONTAL_ACTIVE_PIXEL_OUTPUT	0x62
-/**< Low bits of horizontal active pixel output */
+/* Low bits of horizontal active pixel output */
 
 #define CH7017_LVDS_POWER_DOWN		0x63
-/** High bits of horizontal active pixel output */
+/* High bits of horizontal active pixel output */
 #define CH7017_LVDS_HAP_HIGH_MASK	(0x7 << 0)
-/** Enables the LVDS power down state transition */
+/* Enables the LVDS power down state transition */
 #define CH7017_LVDS_POWER_DOWN_EN	(1 << 6)
-/** Enables the LVDS upscaler */
+/* Enables the LVDS upscaler */
 #define CH7017_LVDS_UPSCALER_EN		(1 << 7)
 #define CH7017_LVDS_POWER_DOWN_DEFAULT_RESERVED 0x08
 
@@ -116,9 +116,9 @@
 #define CH7017_LVDS_ENCODING_2		0x65
 
 #define CH7017_LVDS_PLL_CONTROL		0x66
-/** Enables the LVDS panel output path */
+/* Enables the LVDS panel output path */
 #define CH7017_LVDS_PANEN		(1 << 0)
-/** Enables the LVDS panel backlight */
+/* Enables the LVDS panel backlight */
 #define CH7017_LVDS_BKLEN		(1 << 3)
 
 #define CH7017_POWER_SEQUENCING_T1	0x67
@@ -197,7 +197,7 @@ static bool ch7017_write(struct intel_dvo_device *dvo, u8 addr, u8 val)
 	return i2c_transfer(dvo->i2c_bus, &msg, 1) == 1;
 }
 
-/** Probes for a CH7017 on the given bus and slave address. */
+/* Probes for a CH7017 on the given bus and slave address. */
 static bool ch7017_init(struct intel_dvo_device *dvo,
 			struct i2c_adapter *adapter)
 {
diff --git a/drivers/gpu/drm/i915/display/dvo_ch7xxx.c b/drivers/gpu/drm/i915/display/dvo_ch7xxx.c
index 54f58ba44b9f..1c1fe1f29675 100644
--- a/drivers/gpu/drm/i915/display/dvo_ch7xxx.c
+++ b/drivers/gpu/drm/i915/display/dvo_ch7xxx.c
@@ -81,7 +81,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #define CH7301_SYNC_RGB_YUV	(1<<0)
 #define CH7301_SYNC_POL_DVI	(1<<5)
 
-/** @file
+/*
  * driver for the Chrontel 7xxx DVI chip over DVO.
  */
 
@@ -132,7 +132,7 @@ static char *ch7xxx_get_did(u8 did)
 	return NULL;
 }
 
-/** Reads an 8 bit register */
+/* Reads an 8 bit register */
 static bool ch7xxx_readb(struct intel_dvo_device *dvo, int addr, u8 *ch)
 {
 	struct ch7xxx_priv *ch7xxx = dvo->dev_priv;
@@ -170,7 +170,7 @@ static bool ch7xxx_readb(struct intel_dvo_device *dvo, int addr, u8 *ch)
 	return false;
 }
 
-/** Writes an 8 bit register */
+/* Writes an 8 bit register */
 static bool ch7xxx_writeb(struct intel_dvo_device *dvo, int addr, u8 ch)
 {
 	struct ch7xxx_priv *ch7xxx = dvo->dev_priv;
diff --git a/drivers/gpu/drm/i915/display/intel_display_types.h b/drivers/gpu/drm/i915/display/intel_display_types.h
index 3b7945aad22a..e46027d2a3c7 100644
--- a/drivers/gpu/drm/i915/display/intel_display_types.h
+++ b/drivers/gpu/drm/i915/display/intel_display_types.h
@@ -1006,7 +1006,7 @@ struct intel_crtc_state {
 		enum drm_scaling_filter scaling_filter;
 	} hw;
 
-	/**
+	/*
 	 * quirks - bitfield with hw state readout quirks
 	 *
 	 * For various reasons the hw state readout code might not be able to
diff --git a/drivers/gpu/drm/i915/display/intel_dvo_dev.h b/drivers/gpu/drm/i915/display/intel_dvo_dev.h
index d96c3cc46e50..45d47209c327 100644
--- a/drivers/gpu/drm/i915/display/intel_dvo_dev.h
+++ b/drivers/gpu/drm/i915/display/intel_dvo_dev.h
@@ -110,7 +110,7 @@ struct intel_dvo_dev_ops {
 	 */
 	bool (*get_hw_state)(struct intel_dvo_device *dev);
 
-	/**
+	/*
 	 * Query the device for the modes it provides.
 	 *
 	 * This function may also update MonInfo, mm_width, and mm_height.
@@ -119,12 +119,12 @@ struct intel_dvo_dev_ops {
 	 */
 	struct drm_display_mode *(*get_modes)(struct intel_dvo_device *dvo);
 
-	/**
+	/*
 	 * Clean up driver-specific bits of the output
 	 */
 	void (*destroy) (struct intel_dvo_device *dvo);
 
-	/**
+	/*
 	 * Debugging hook to dump device registers to log file
 	 */
 	void (*dump_regs)(struct intel_dvo_device *dvo);
diff --git a/drivers/gpu/drm/i915/display/intel_sdvo.c b/drivers/gpu/drm/i915/display/intel_sdvo.c
index f5b744bef18f..87ff910dce05 100644
--- a/drivers/gpu/drm/i915/display/intel_sdvo.c
+++ b/drivers/gpu/drm/i915/display/intel_sdvo.c
@@ -162,7 +162,7 @@ struct intel_sdvo_connector {
 	/* this is to get the range of margin.*/
 	u32 max_hscan, max_vscan;
 
-	/**
+	/*
 	 * This is set if we treat the device as HDMI, instead of DVI.
 	 */
 	bool is_hdmi;
@@ -280,7 +280,7 @@ static bool intel_sdvo_read_byte(struct intel_sdvo *intel_sdvo, u8 addr, u8 *ch)
 
 #define SDVO_CMD_NAME_ENTRY(cmd_) { .cmd = SDVO_CMD_ ## cmd_, .name = #cmd_ }
 
-/** Mapping of command numbers to names, for debug output */
+/* Mapping of command numbers to names, for debug output */
 static const struct {
 	u8 cmd;
 	const char *name;
diff --git a/drivers/gpu/drm/i915/display/intel_tv.c b/drivers/gpu/drm/i915/display/intel_tv.c
index 9379f3463344..2507ab1ceda6 100644
--- a/drivers/gpu/drm/i915/display/intel_tv.c
+++ b/drivers/gpu/drm/i915/display/intel_tv.c
@@ -26,7 +26,7 @@
  *
  */
 
-/** @file
+/*
  * Integrated TV-out support for the 915GM and 945GM.
  */
 
diff --git a/drivers/gpu/drm/i915/gt/intel_context_types.h b/drivers/gpu/drm/i915/gt/intel_context_types.h
index 04eacae1aca5..1be2aad18f2a 100644
--- a/drivers/gpu/drm/i915/gt/intel_context_types.h
+++ b/drivers/gpu/drm/i915/gt/intel_context_types.h
@@ -128,7 +128,6 @@ struct intel_context {
 	struct {
 		u64 timeout_us;
 	} watchdog;
-
 	u32 *lrc_reg_state;
 	union {
 		struct {
@@ -139,7 +138,7 @@ struct intel_context {
 	} lrc;
 	u32 tag; /* cookie passed to HW to track this context on submission */
 
-	/** stats: Context GPU engine busyness tracking. */
+	/* stats: Context GPU engine busyness tracking. */
 	struct intel_context_stats {
 		u64 active;
 
@@ -158,7 +157,7 @@ struct intel_context {
 	atomic_t pin_count;
 	struct mutex pin_mutex; /* guards pinning and associated on-gpuing */
 
-	/**
+	/*
 	 * active: Active tracker for the rq activity (inc. external) on this
 	 * intel_context object.
 	 */
@@ -166,10 +165,10 @@ struct intel_context {
 
 	const struct intel_context_ops *ops;
 
-	/** sseu: Control eu/slice partitioning */
+	/* sseu: Control eu/slice partitioning */
 	struct intel_sseu sseu;
 
-	/**
+	/*
 	 * pinned_contexts_link: List link for the engine's pinned contexts.
 	 * This is only used if this is a perma-pinned kernel context and
 	 * the list is assumed to only be manipulated during driver load
@@ -180,9 +179,9 @@ struct intel_context {
 	u8 wa_bb_page; /* if set, page num reserved for context workarounds */
 
 	struct {
-		/** @lock: protects everything in guc_state */
+		/* @lock: protects everything in guc_state */
 		spinlock_t lock;
-		/**
+		/*
 		 * @sched_state: scheduling state of this context using GuC
 		 * submission
 		 */
@@ -192,18 +191,18 @@ struct intel_context {
 		 * being fenced until a GuC operation completes
 		 */
 		struct list_head fences;
-		/**
+		/*
 		 * @blocked: fence used to signal when the blocking of a
 		 * context's submissions is complete.
 		 */
 		struct i915_sw_fence blocked;
-		/** @number_committed_requests: number of committed requests */
+		/* @number_committed_requests: number of committed requests */
 		int number_committed_requests;
-		/** @requests: list of active requests on this context */
+		/* @requests: list of active requests on this context */
 		struct list_head requests;
-		/** @prio: the context's current guc priority */
+		/* @prio: the context's current guc priority */
 		u8 prio;
-		/**
+		/*
 		 * @prio_count: a counter of the number requests in flight in
 		 * each priority bucket
 		 */
@@ -211,82 +210,82 @@ struct intel_context {
 	} guc_state;
 
 	struct {
-		/**
+		/*
 		 * @id: handle which is used to uniquely identify this context
 		 * with the GuC, protected by guc->submission_state.lock
 		 */
 		u16 id;
-		/**
+		/*
 		 * @ref: the number of references to the guc_id, when
 		 * transitioning in and out of zero protected by
 		 * guc->submission_state.lock
 		 */
 		atomic_t ref;
-		/**
+		/*
 		 * @link: in guc->guc_id_list when the guc_id has no refs but is
 		 * still valid, protected by guc->submission_state.lock
 		 */
 		struct list_head link;
 	} guc_id;
 
-	/**
+	/*
 	 * @destroyed_link: link in guc->submission_state.destroyed_contexts, in
 	 * list when context is pending to be destroyed (deregistered with the
 	 * GuC), protected by guc->submission_state.lock
 	 */
 	struct list_head destroyed_link;
 
-	/** @parallel: sub-structure for parallel submission members */
+	/* @parallel: sub-structure for parallel submission members */
 	struct {
 		union {
-			/**
+			/*
 			 * @child_list: parent's list of children
 			 * contexts, no protection as immutable after context
 			 * creation
 			 */
 			struct list_head child_list;
-			/**
+			/*
 			 * @child_link: child's link into parent's list of
 			 * children
 			 */
 			struct list_head child_link;
 		};
-		/** @parent: pointer to parent if child */
+		/* @parent: pointer to parent if child */
 		struct intel_context *parent;
-		/**
+		/*
 		 * @last_rq: last request submitted on a parallel context, used
 		 * to insert submit fences between requests in the parallel
 		 * context
 		 */
 		struct i915_request *last_rq;
-		/**
+		/*
 		 * @fence_context: fence context composite fence when doing
 		 * parallel submission
 		 */
 		u64 fence_context;
-		/**
+		/*
 		 * @seqno: seqno for composite fence when doing parallel
 		 * submission
 		 */
 		u32 seqno;
-		/** @number_children: number of children if parent */
+		/* @number_children: number of children if parent */
 		u8 number_children;
-		/** @child_index: index into child_list if child */
+		/* @child_index: index into child_list if child */
 		u8 child_index;
-		/** @guc: GuC specific members for parallel submission */
+		/* @guc: GuC specific members for parallel submission */
 		struct {
-			/** @wqi_head: cached head pointer in work queue */
+			/* @wqi_head: cached head pointer in work queue */
 			u16 wqi_head;
-			/** @wqi_tail: cached tail pointer in work queue */
+			/* @wqi_tail: cached tail pointer in work queue */
 			u16 wqi_tail;
-			/** @wq_head: pointer to the actual head in work queue */
+			/* @wq_head: pointer to the actual head in work queue */
 			u32 *wq_head;
-			/** @wq_tail: pointer to the actual head in work queue */
+			/* @wq_tail: pointer to the actual head in work queue */
 			u32 *wq_tail;
-			/** @wq_status: pointer to the status in work queue */
+			/* @wq_status: pointer to the status in work queue */
 			u32 *wq_status;
 
-			/**
+			/*
 			 * @parent_page: page in context state (ce->state) used
 			 * by parent for work queue, process descriptor
 			 */
@@ -295,18 +294,18 @@ struct intel_context {
 	} parallel;
 
 #ifdef CONFIG_DRM_I915_SELFTEST
-	/**
+	/*
 	 * @drop_schedule_enable: Force drop of schedule enable G2H for selftest
 	 */
 	bool drop_schedule_enable;
 
-	/**
+	/*
 	 * @drop_schedule_disable: Force drop of schedule disable G2H for
 	 * selftest
 	 */
 	bool drop_schedule_disable;
 
-	/**
+	/*
 	 * @drop_deregister: Force drop of deregister G2H for selftest
 	 */
 	bool drop_deregister;
diff --git a/drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h b/drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h
index 25340be5ecf0..230e846151a8 100644
--- a/drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h
+++ b/drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h
@@ -26,7 +26,7 @@ struct i915_fence_reg {
 	atomic_t pin_count;
 	struct i915_active active;
 	int id;
-	/**
+	/*
 	 * Whether the tiling parameters for the currently
 	 * associated fence register have changed. Note that
 	 * for the purposes of tracking tiling changes we also
diff --git a/drivers/gpu/drm/i915/gt/intel_gt_types.h b/drivers/gpu/drm/i915/gt/intel_gt_types.h
index 4d56f7d5a3be..c66e3d803666 100644
--- a/drivers/gpu/drm/i915/gt/intel_gt_types.h
+++ b/drivers/gpu/drm/i915/gt/intel_gt_types.h
@@ -114,7 +114,7 @@ struct intel_gt {
 	} timelines;
 
 	struct intel_gt_requests {
-		/**
+		/*
 		 * We leave the user IRQ off as much as possible,
 		 * but this means that requests will finish and never
 		 * be retired once the system goes idle. Set a timer to
@@ -138,7 +138,7 @@ struct intel_gt {
 	ktime_t last_init_time;
 	struct intel_reset reset;
 
-	/**
+	/*
 	 * Is the GPU currently considered idle, or busy executing
 	 * userspace requests? Whilst idle, we allow runtime power
 	 * management to power down the hardware and display clocks.
@@ -164,12 +164,12 @@ struct intel_gt {
 	struct {
 		bool active;
 
-		/**
+		/*
 		 * @lock: Lock protecting the below fields.
 		 */
 		seqcount_mutex_t lock;
 
-		/**
+		/*
 		 * @total: Total time this engine was busy.
 		 *
 		 * Accumulated time not counting the most recent block in cases
@@ -177,7 +177,7 @@ struct intel_gt {
 		 */
 		ktime_t total;
 
-		/**
+		/*
 		 * @start: Timestamp of the last idle to active transition.
 		 *
 		 * Idle is defined as active == 0, active is active > 0.
@@ -243,7 +243,7 @@ struct intel_gt {
 
 		unsigned long mslice_mask;
 
-		/** @hwconfig: hardware configuration data */
+		/* @hwconfig: hardware configuration data */
 		struct intel_hwconfig hwconfig;
 	} info;
 
diff --git a/drivers/gpu/drm/i915/gt/intel_reset_types.h b/drivers/gpu/drm/i915/gt/intel_reset_types.h
index 9312b29f5a97..4ef21186e6d5 100644
--- a/drivers/gpu/drm/i915/gt/intel_reset_types.h
+++ b/drivers/gpu/drm/i915/gt/intel_reset_types.h
@@ -11,7 +11,7 @@
 #include <linux/srcu.h>
 
 struct intel_reset {
-	/**
+	/*
 	 * flags: Control various stages of the GPU reset
 	 *
 	 * #I915_RESET_BACKOFF - When we start a global reset, we need to
@@ -49,7 +49,7 @@ struct intel_reset {
 
 	struct mutex mutex; /* serialises wedging/unwedging */
 
-	/**
+	/*
 	 * Waitqueue to signal when the reset has completed. Used by clients
 	 * that wait for dev_priv->mm.wedged to settle.
 	 */
diff --git a/drivers/gpu/drm/i915/gt/intel_timeline_types.h b/drivers/gpu/drm/i915/gt/intel_timeline_types.h
index 74e67dbf89c5..ae5f859d72c0 100644
--- a/drivers/gpu/drm/i915/gt/intel_timeline_types.h
+++ b/drivers/gpu/drm/i915/gt/intel_timeline_types.h
@@ -50,7 +50,7 @@ struct intel_timeline {
 
 	bool has_initial_breadcrumb;
 
-	/**
+	/*
 	 * List of breadcrumbs associated with GPU requests currently
 	 * outstanding.
 	 */
@@ -66,10 +66,10 @@ struct intel_timeline {
 
 	struct i915_active active;
 
-	/** A chain of completed timelines ready for early retirement. */
+	/* A chain of completed timelines ready for early retirement. */
 	struct intel_timeline *retire;
 
-	/**
+	/*
 	 * We track the most recent seqno that we wait on in every context so
 	 * that we only have to emit a new await and dependency on a more
 	 * recent sync point. As the contexts may be executed out-of-order, we
diff --git a/drivers/gpu/drm/i915/gt/shaders/clear_kernel/hsw.asm b/drivers/gpu/drm/i915/gt/shaders/clear_kernel/hsw.asm
index 5fdf384bb621..88d2dbbf981e 100644
--- a/drivers/gpu/drm/i915/gt/shaders/clear_kernel/hsw.asm
+++ b/drivers/gpu/drm/i915/gt/shaders/clear_kernel/hsw.asm
@@ -14,7 +14,7 @@
 /* Store designated "clear GRF" value */
 mov(1)          f0.1<1>UW       g1.2<0,1,0>UW                   { align1 1N };
 
-/**
+/*
  * Curbe Format
  *
  * DW 1.0 - Block Offset to write Render Cache
@@ -40,7 +40,7 @@ add(1)          g1.2<1>UD       g1.2<0,1,0>UD   0x00000001UD    { align1 1N }; /
 cmp.z.f0.0(1)   null<1>UD       g1.3<0,1,0>UD   0x00000000UD    { align1 1N };
 (+f0.0) jmpi(1) 352D                                            { align1 WE_all 1N };
 
-/**
+/*
  * State Register has info on where this thread is running
  *	IVB: sr0.0 :: [15:13]: MBZ, 12: HSID (Half-Slice ID), [11:8]EUID, [2:0] ThreadSlotID
  *	HSW: sr0.0 :: 15: MBZ, [14:13]: SliceID, 12: HSID (Half-Slice ID), [11:8]EUID, [2:0] ThreadSlotID
diff --git a/drivers/gpu/drm/i915/gt/shaders/clear_kernel/ivb.asm b/drivers/gpu/drm/i915/gt/shaders/clear_kernel/ivb.asm
index 97c7ac9e3854..4d7c5f1981ba 100644
--- a/drivers/gpu/drm/i915/gt/shaders/clear_kernel/ivb.asm
+++ b/drivers/gpu/drm/i915/gt/shaders/clear_kernel/ivb.asm
@@ -14,7 +14,7 @@
 /* Store designated "clear GRF" value */
 mov(1)          f0.1<1>UW       g1.2<0,1,0>UW                   { align1 1N };
 
-/**
+/*
  * Curbe Format
  *
  * DW 1.0 - Block Offset to write Render Cache
@@ -40,7 +40,7 @@ add(1)          g1.2<1>UD       g1.2<0,1,0>UD   0x00000001UD    { align1 1N }; /
 cmp.z.f0.0(1)   null<1>UD       g1.3<0,1,0>UD   0x00000000UD    { align1 1N };
 (+f0.0) jmpi(1) 44D                                             { align1 WE_all 1N };
 
-/**
+/*
  * State Register has info on where this thread is running
  *	IVB: sr0.0 :: [15:13]: MBZ, 12: HSID (Half-Slice ID), [11:8]EUID, [2:0] ThreadSlotID
  *	HSW: sr0.0 :: 15: MBZ, [14:13]: SliceID, 12: HSID (Half-Slice ID), [11:8]EUID, [2:0] ThreadSlotID
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 58f93226b1c1..d8a7659079f5 100644
--- a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
+++ b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
@@ -168,12 +168,12 @@ struct __guc_capture_ads_cache {
  * Internal context of the intel_guc_capture module.
  */
 struct intel_guc_state_capture {
-	/**
+	/*
 	 * @reglists: static table of register lists used for error-capture state.
 	 */
 	const struct __guc_mmio_reg_descr_group *reglists;
 
-	/**
+	/*
 	 * @extlists: allocated table of steered register lists used for error-capture state.
 	 *
 	 * NOTE: steered registers have multiple instances depending on the HW configuration
@@ -181,7 +181,7 @@ struct intel_guc_state_capture {
 	 */
 	struct __guc_mmio_reg_descr_group *extlists;
 
-	/**
+	/*
 	 * @ads_cache: cached register lists that is ADS format ready
 	 */
 	struct __guc_capture_ads_cache ads_cache[GUC_CAPTURE_LIST_INDEX_MAX]
@@ -189,7 +189,7 @@ struct intel_guc_state_capture {
 						[GUC_MAX_ENGINE_CLASSES];
 	void *ads_null_cache;
 
-	/**
+	/*
 	 * @cachelist: Pool of pre-allocated nodes for error capture output
 	 *
 	 * We need this pool of pre-allocated nodes because we cannot
@@ -204,7 +204,7 @@ struct intel_guc_state_capture {
 #define PREALLOC_NODES_DEFAULT_NUMREGS 64
 	int max_mmio_per_node;
 
-	/**
+	/*
 	 * @outlist: Pool of pre-allocated nodes for error capture output
 	 *
 	 * A linked list of parsed GuC error-capture output data before
diff --git a/drivers/gpu/drm/i915/i915_drm_client.h b/drivers/gpu/drm/i915/i915_drm_client.h
index 69496af996d9..c722e3c18694 100644
--- a/drivers/gpu/drm/i915/i915_drm_client.h
+++ b/drivers/gpu/drm/i915/i915_drm_client.h
@@ -34,7 +34,7 @@ struct i915_drm_client {
 
 	struct i915_drm_clients *clients;
 
-	/**
+	/*
 	 * @past_runtime: Accumulation of pphwsp runtimes from closed contexts.
 	 */
 	atomic64_t past_runtime[I915_LAST_UABI_ENGINE_CLASS + 1];
diff --git a/drivers/gpu/drm/i915/i915_drv.h b/drivers/gpu/drm/i915/i915_drv.h
index 76aad81c014b..519e8e8ace45 100644
--- a/drivers/gpu/drm/i915/i915_drv.h
+++ b/drivers/gpu/drm/i915/i915_drv.h
@@ -113,37 +113,37 @@ struct i915_gem_mm {
 	 * support stolen.
 	 */
 	struct intel_memory_region *stolen_region;
-	/** Memory allocator for GTT stolen memory */
+	/* Memory allocator for GTT stolen memory */
 	struct drm_mm stolen;
-	/** Protects the usage of the GTT stolen memory allocator. This is
+	/* Protects the usage of the GTT stolen memory allocator. This is
 	 * always the inner lock when overlapping with struct_mutex. */
 	struct mutex stolen_lock;
 
 	/* Protects bound_list/unbound_list and #drm_i915_gem_object.mm.link */
 	spinlock_t obj_lock;
 
-	/**
+	/*
 	 * List of objects which are purgeable.
 	 */
 	struct list_head purge_list;
 
-	/**
+	/*
 	 * List of objects which have allocated pages and are shrinkable.
 	 */
 	struct list_head shrink_list;
 
-	/**
+	/*
 	 * List of objects which are pending destruction.
 	 */
 	struct llist_head free_list;
 	struct work_struct free_work;
-	/**
+	/*
 	 * Count of objects pending destructions. Used to skip needlessly
 	 * waiting on an RCU barrier if no objects are waiting to be freed.
 	 */
 	atomic_t free_count;
 
-	/**
+	/*
 	 * tmpfs instance used for shmem backed objects
 	 */
 	struct vfsmount *gemfs;
@@ -155,7 +155,7 @@ struct i915_gem_mm {
 	struct shrinker shrinker;
 
 #ifdef CONFIG_MMU_NOTIFIER
-	/**
+	/*
 	 * notifier_lock for mmu notifiers, memory may not be allocated
 	 * while holding this lock.
 	 */
@@ -209,7 +209,7 @@ struct drm_i915_private {
 	struct intel_runtime_info __runtime; /* Use RUNTIME_INFO() to access. */
 	struct intel_driver_caps caps;
 
-	/**
+	/*
 	 * Data Stolen Memory - aka "i915 stolen memory" gives us the start and
 	 * end of stolen which we can optionally use to create GEM objects
 	 * backed by stolen memory. Note that stolen_usable_size tells us
@@ -217,7 +217,7 @@ struct drm_i915_private {
 	 * some portion of it is in fact reserved for use by hardware functions.
 	 */
 	struct resource dsm;
-	/**
+	/*
 	 * Reseved portion of Data Stolen Memory
 	 */
 	struct resource dsm_reserved;
@@ -258,7 +258,7 @@ struct drm_i915_private {
 	struct mutex sb_lock;
 	struct pm_qos_request sb_qos;
 
-	/** Cached value of IMR to avoid reads in updating the bitfield */
+	/* Cached value of IMR to avoid reads in updating the bitfield */
 	union {
 		u32 irq_mask;
 		u32 de_irq_mask[I915_MAX_PIPES];
@@ -274,7 +274,7 @@ struct drm_i915_private {
 	unsigned int hpll_freq;
 	unsigned int czclk_freq;
 
-	/**
+	/*
 	 * wq - Driver workqueue for GEM.
 	 *
 	 * NOTE: Work items scheduled here are not allowed to grab any modeset
diff --git a/drivers/gpu/drm/i915/i915_file_private.h b/drivers/gpu/drm/i915/i915_file_private.h
index f42877869692..282e0c280224 100644
--- a/drivers/gpu/drm/i915/i915_file_private.h
+++ b/drivers/gpu/drm/i915/i915_file_private.h
@@ -22,7 +22,7 @@ struct drm_i915_file_private {
 		struct rcu_head rcu;
 	};
 
-	/** @proto_context_lock: Guards all struct i915_gem_proto_context
+	/* @proto_context_lock: Guards all struct i915_gem_proto_context
 	 * operations
 	 *
 	 * This not only guards @proto_context_xa, but is always held
@@ -33,7 +33,7 @@ struct drm_i915_file_private {
 	 */
 	struct mutex proto_context_lock;
 
-	/** @proto_context_xa: xarray of struct i915_gem_proto_context
+	/* @proto_context_xa: xarray of struct i915_gem_proto_context
 	 *
 	 * Historically, the context uAPI allowed for two methods of
 	 * setting context parameters: SET_CONTEXT_PARAM and
@@ -77,7 +77,7 @@ struct drm_i915_file_private {
 	 */
 	struct xarray proto_context_xa;
 
-	/** @context_xa: xarray of fully created i915_gem_context
+	/* @context_xa: xarray of fully created i915_gem_context
 	 *
 	 * Write access to this xarray is guarded by @proto_context_lock.
 	 * Otherwise, writers may race with finalize_create_context_locked().
@@ -101,7 +101,7 @@ struct drm_i915_file_private {
 #define   I915_CLIENT_FAST_HANG_JIFFIES (60 * HZ)
 #define I915_CLIENT_SCORE_CONTEXT_BAN   3
 #define I915_CLIENT_SCORE_BANNED	9
-	/** ban_score: Accumulated score of all ctx bans and fast hangs. */
+	/* ban_score: Accumulated score of all ctx bans and fast hangs. */
 	atomic_t ban_score;
 	unsigned long hang_timestamp;
 
diff --git a/drivers/gpu/drm/i915/i915_gpu_error.h b/drivers/gpu/drm/i915/i915_gpu_error.h
index efc75cc2ffdb..4e395a9e4c11 100644
--- a/drivers/gpu/drm/i915/i915_gpu_error.h
+++ b/drivers/gpu/drm/i915/i915_gpu_error.h
@@ -224,10 +224,10 @@ struct i915_gpu_error {
 
 	atomic_t pending_fb_pin;
 
-	/** Number of times the device has been reset (global) */
+	/* Number of times the device has been reset (global) */
 	atomic_t reset_count;
 
-	/** Number of times an engine has been reset */
+	/* Number of times an engine has been reset */
 	atomic_t reset_engine_count[I915_NUM_ENGINES];
 };
 
diff --git a/drivers/gpu/drm/i915/i915_pmu.h b/drivers/gpu/drm/i915/i915_pmu.h
index c30f43319a78..9fdb50376995 100644
--- a/drivers/gpu/drm/i915/i915_pmu.h
+++ b/drivers/gpu/drm/i915/i915_pmu.h
@@ -52,34 +52,34 @@ struct i915_pmu_sample {
 };
 
 struct i915_pmu {
-	/**
+	/*
 	 * @cpuhp: Struct used for CPU hotplug handling.
 	 */
 	struct {
 		struct hlist_node node;
 		unsigned int cpu;
 	} cpuhp;
-	/**
+	/*
 	 * @base: PMU base.
 	 */
 	struct pmu base;
-	/**
+	/*
 	 * @closed: i915 is unregistering.
 	 */
 	bool closed;
-	/**
+	/*
 	 * @name: Name as registered with perf core.
 	 */
 	const char *name;
-	/**
+	/*
 	 * @lock: Lock protecting enable mask and ref count handling.
 	 */
 	spinlock_t lock;
-	/**
+	/*
 	 * @timer: Timer for internal i915 PMU sampling.
 	 */
 	struct hrtimer timer;
-	/**
+	/*
 	 * @enable: Bitmask of specific enabled events.
 	 *
 	 * For some events we need to track their state and do some internal
@@ -92,14 +92,14 @@ struct i915_pmu {
 	 */
 	u32 enable;
 
-	/**
+	/*
 	 * @timer_last:
 	 *
 	 * Timestmap of the previous timer invocation.
 	 */
 	ktime_t timer_last;
 
-	/**
+	/*
 	 * @enable_count: Reference counts for the enabled events.
 	 *
 	 * Array indices are mapped in the same way as bits in the @enable field
@@ -107,11 +107,11 @@ struct i915_pmu {
 	 * are using the PMU API.
 	 */
 	unsigned int enable_count[I915_PMU_MASK_BITS];
-	/**
+	/*
 	 * @timer_enabled: Should the internal sampling timer be running.
 	 */
 	bool timer_enabled;
-	/**
+	/*
 	 * @sample: Current and previous (raw) counters for sampling events.
 	 *
 	 * These counters are updated from the i915 PMU sampling timer.
@@ -120,11 +120,11 @@ struct i915_pmu {
 	 * struct intel_engine_cs.
 	 */
 	struct i915_pmu_sample sample[__I915_NUM_PMU_SAMPLERS];
-	/**
+	/*
 	 * @sleep_last: Last time GT parked for RC6 estimation.
 	 */
 	ktime_t sleep_last;
-	/**
+	/*
 	 * @irq_count: Number of interrupts
 	 *
 	 * Intentionally unsigned long to avoid atomics or heuristics on 32bit.
@@ -132,15 +132,15 @@ struct i915_pmu {
 	 * occasional wraparound easily. It's 32bit after all.
 	 */
 	unsigned long irq_count;
-	/**
+	/*
 	 * @events_attr_group: Device events attribute group.
 	 */
 	struct attribute_group events_attr_group;
-	/**
+	/*
 	 * @i915_attr: Memory block holding device attributes.
 	 */
 	void *i915_attr;
-	/**
+	/*
 	 * @pmu_attr: Memory block holding device attributes.
 	 */
 	void *pmu_attr;
diff --git a/drivers/gpu/drm/i915/intel_uncore.h b/drivers/gpu/drm/i915/intel_uncore.h
index b1fa912a65e7..5f896fbf3064 100644
--- a/drivers/gpu/drm/i915/intel_uncore.h
+++ b/drivers/gpu/drm/i915/intel_uncore.h
@@ -39,7 +39,7 @@ struct intel_uncore;
 struct intel_gt;
 
 struct intel_uncore_mmio_debug {
-	spinlock_t lock; /** lock is also taken in irq contexts. */
+	spinlock_t lock; /* lock is also taken in irq contexts. */
 	int unclaimed_mmio_check;
 	int saved_mmio_check;
 	u32 suspend_count;
@@ -133,7 +133,7 @@ struct intel_uncore {
 	struct intel_gt *gt;
 	struct intel_runtime_pm *rpm;
 
-	spinlock_t lock; /** lock is also taken in irq contexts. */
+	spinlock_t lock; /* lock is also taken in irq contexts. */
 
 	unsigned int flags;
 #define UNCORE_HAS_FORCEWAKE		BIT(0)
-- 
2.37.3

[PATCH v3 20/37] drm/i915: dvo_ch7xxx.c: use SPDX header

[Mauro Carvalho Chehab]

This file is licensed with MIT license. Change its license text
to use SPDX.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/display/dvo_ch7xxx.c | 33 +++++------------------
 1 file changed, 6 insertions(+), 27 deletions(-)

diff --git a/drivers/gpu/drm/i915/display/dvo_ch7xxx.c b/drivers/gpu/drm/i915/display/dvo_ch7xxx.c
index 1c1fe1f29675..b4d94a565fdb 100644
--- a/drivers/gpu/drm/i915/display/dvo_ch7xxx.c
+++ b/drivers/gpu/drm/i915/display/dvo_ch7xxx.c
@@ -1,30 +1,9 @@
-/**************************************************************************
-
-Copyright © 2006 Dave Airlie
-
-All Rights Reserved.
-
-Permission is hereby granted, free of charge, to any person obtaining a
-copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sub license, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice (including the
-next paragraph) shall be included in all copies or substantial portions
-of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
-IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-**************************************************************************/
+// SPDX-License-Identifier: MIT
+/*
+ * Copyright © 2006 Dave Airlie
+ *
+ * All Rights Reserved.
+ */
 
 #include "intel_display_types.h"
 #include "intel_dvo_dev.h"
-- 
2.37.3

[PATCH v3 21/37] drm/i915: dvo_sil164.c: use SPDX header

[Mauro Carvalho Chehab]

This file is licensed with MIT license.	Change its license text
to use SPDX.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/display/dvo_sil164.c | 32 +++++------------------
 1 file changed, 6 insertions(+), 26 deletions(-)

diff --git a/drivers/gpu/drm/i915/display/dvo_sil164.c b/drivers/gpu/drm/i915/display/dvo_sil164.c
index 0dfa0a0209ff..12974f7c9dc1 100644
--- a/drivers/gpu/drm/i915/display/dvo_sil164.c
+++ b/drivers/gpu/drm/i915/display/dvo_sil164.c
@@ -1,30 +1,10 @@
-/**************************************************************************
+// SPDX-License-Identifier: MIT
 
-Copyright © 2006 Dave Airlie
-
-All Rights Reserved.
-
-Permission is hereby granted, free of charge, to any person obtaining a
-copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sub license, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice (including the
-next paragraph) shall be included in all copies or substantial portions
-of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
-IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-**************************************************************************/
+/*
+ * Copyright © 2006 Dave Airlie
+ *
+ * All Rights Reserved.
+ */
 
 #include "intel_display_types.h"
 #include "intel_dvo_dev.h"
-- 
2.37.3

[PATCH v3 22/37] drm/i915: i915_vma_resource.c: fix some kernel-doc markups

[Mauro Carvalho Chehab]

Building docs currently produces two warnings:

    Documentation/foo/i915:71: ./drivers/gpu/drm/i915/i915_vma_resource.c:286: WARNING: Inline strong start-string without end-string.
    Documentation/foo/i915:71: ./drivers/gpu/drm/i915/i915_vma_resource.c:370: WARNING: Inline strong start-string without end-string.

That's because @foo evaluates into **foo**, and placing anything
after it without spaces cause Sphinx to warn and do the wrong
thing.. So, replace them by a different Sphinx-compatible tag.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/i915_vma_resource.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/gpu/drm/i915/i915_vma_resource.c b/drivers/gpu/drm/i915/i915_vma_resource.c
index de1342dbfa12..e758e0530175 100644
--- a/drivers/gpu/drm/i915/i915_vma_resource.c
+++ b/drivers/gpu/drm/i915/i915_vma_resource.c
@@ -290,7 +290,7 @@ i915_vma_resource_color_adjust_range(struct i915_address_space *vm,
  *
  * The function needs to be called with the vm lock held.
  *
- * Return: Zero on success, -ERESTARTSYS if interrupted and @intr==true
+ * Return: Zero on success, -ERESTARTSYS if interrupted and ``intr==true``
  */
 int i915_vma_resource_bind_dep_sync(struct i915_address_space *vm,
 				    u64 offset,
@@ -374,7 +374,7 @@ void i915_vma_resource_bind_dep_sync_all(struct i915_address_space *vm)
  * this means that during heavy memory pressure, we will sync in this
  * function.
  *
- * Return: Zero on success, -ERESTARTSYS if interrupted and @intr==true
+ * Return: Zero on success, -ERESTARTSYS if interrupted and ``intr==true``
  */
 int i915_vma_resource_bind_dep_await(struct i915_address_space *vm,
 				     struct i915_sw_fence *sw_fence,
-- 
2.37.3

[PATCH v3 23/37] drm/i915: i915_gem.c fix a kernel-doc issue

[Mauro Carvalho Chehab]

Prevent this Sphinx warning:

	Documentation/foo/i915:728: ./drivers/gpu/drm/i915/i915_gem.c:447: WARNING: Inline emphasis start-string without end-string.

By using @data to identify the data field, as expected by kernel-doc.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/i915_gem.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/i915_gem.c b/drivers/gpu/drm/i915/i915_gem.c
index f68fa0732363..2b5b2be91a24 100644
--- a/drivers/gpu/drm/i915/i915_gem.c
+++ b/drivers/gpu/drm/i915/i915_gem.c
@@ -444,7 +444,7 @@ i915_gem_gtt_pread(struct drm_i915_gem_object *obj,
  * @data: ioctl data blob
  * @file: drm file pointer
  *
- * On error, the contents of *data are undefined.
+ * On error, the contents of @data is undefined.
  */
 int
 i915_gem_pread_ioctl(struct drm_device *dev, void *data,
-- 
2.37.3

[PATCH v3 24/37] drm/i915: i915_scatterlist.h: fix some kernel-doc markups

[Mauro Carvalho Chehab]

Building docs currently produces this warning:

	Documentation/foo/i915:159: ./drivers/gpu/drm/i915/i915_scatterlist.h:73: WARNING: Inline strong start-string without end-string.

That's because @foo evaluates into **foo**, and placing anything
after it without spaces cause Sphinx to warn and do the wrong
thing.. So, replace them by a different Sphinx-compatible tag.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/i915_scatterlist.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/i915_scatterlist.h b/drivers/gpu/drm/i915/i915_scatterlist.h
index 79b70ae2e766..ac77f2668544 100644
--- a/drivers/gpu/drm/i915/i915_scatterlist.h
+++ b/drivers/gpu/drm/i915/i915_scatterlist.h
@@ -70,7 +70,7 @@ static inline struct scatterlist *____sg_next(struct scatterlist *sg)
  *
  * Description:
  *   If the entry is the last, return NULL; otherwise, step to the next
- *   element in the array (@sg@+1). If that's a chain pointer, follow it;
+ *   element in the array (``sg@+1``). If that's a chain pointer, follow it;
  *   otherwise just return the pointer to the current element.
  **/
 static inline struct scatterlist *__sg_next(struct scatterlist *sg)
-- 
2.37.3

[PATCH v3 25/37] drm/i915: i915_deps: use a shorter title markup

[Mauro Carvalho Chehab]

The DOC: tag waits for a one-line short title for the doc
section. Using multiple lines will produce a weird output.
So, add a shorter description for the title, while keeping
the current content below it.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/i915_deps.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/i915_deps.c b/drivers/gpu/drm/i915/i915_deps.c
index 297b8e4e42ee..df6af832e3f2 100644
--- a/drivers/gpu/drm/i915/i915_deps.c
+++ b/drivers/gpu/drm/i915/i915_deps.c
@@ -11,7 +11,9 @@
 #include "i915_deps.h"
 
 /**
- * DOC: Set of utilities to dynamically collect dependencies into a
+ * DOC: Utilities to collect dependencies for GT migration code
+ *
+ * Set of utilities to dynamically collect dependencies into a
  * structure which is fed into the GT migration code.
  *
  * Once we can do async unbinding, this is also needed to coalesce
-- 
2.37.3

[PATCH v3 26/37] docs: gpu: i915.rst: display: add kernel-doc markups

[Mauro Carvalho Chehab]

There are several documented kAPI at the display side that
aren't currently part of the docs. Add them, as this allows
identifying issues with badly-formatted tags.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 Documentation/gpu/i915.rst | 50 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 4e59db1cfb00..2ad7941a79f2 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -100,6 +100,56 @@ Display FIFO Underrun Reporting
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c
    :internal:
 
+Atomic Modeset Support
+----------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic.c
+
+Display Power Domain
+--------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display_power.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display_power_map.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display_power_well.c
+
+Misc display functions
+----------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_backlight.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_crtc.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_connector.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display_debugfs.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp_link_training.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpt.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fb.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fb_pin.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_gmbus.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_lvds.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_opregion.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_snps_phy.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_tc.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/skl_scaler.c
+
+
 Plane Configuration
 -------------------
 
-- 
2.37.3

[PATCH v3 27/37] docs: gpu: i915.rst: gt: add more kernel-doc markups

[Mauro Carvalho Chehab]

There are several documented GT kAPI that aren't currently part
of the docs. Add them, as this allows identifying issues with
badly-formatted tags.

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

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

 Documentation/gpu/i915.rst | 40 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 2ad7941a79f2..b668f36fb0a3 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -149,7 +149,6 @@ Misc display functions
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/skl_scaler.c
 
-
 Plane Configuration
 -------------------
 
@@ -308,6 +307,45 @@ Multicast/Replicated (MCR) Registers
 .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_mcr.c
    :internal:
 
+GT engine
+---------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_types.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_cs.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_pm.c
+
+Graphics Translation Tables
+---------------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.h
+
+Other GT functionality
+----------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_context.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gsc.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_migrate.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_mocs.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rc6.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_reset.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rps_types.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rps.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_sseu.c
+
 Memory Management and Command Submission
 ========================================
 
-- 
2.37.3

[PATCH v3 28/37] docs: gpu: i915.rst: GuC: add more kernel-doc markups

[Mauro Carvalho Chehab]

There are several documented GuC kAPI that aren't currently part
of the docs. Add them, as this allows identifying issues with
badly-formatted tags.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 Documentation/gpu/i915.rst | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index b668f36fb0a3..7f2daa1b4a8b 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -593,6 +593,28 @@ GuC
 
 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.h
 
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_actions_slpc_abi.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_ct.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_ct.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_log.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_slpc.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw.c
+
 GuC Firmware Layout
 ~~~~~~~~~~~~~~~~~~~
 
-- 
2.37.3

[PATCH v3 29/37] docs: gpu: i915.rst: GVT: add more kernel-doc markups

[Mauro Carvalho Chehab]

There are several documented GVT kAPI that aren't currently part
of the docs. Add them, as this allows identifying issues with
badly-formatted tags.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 Documentation/gpu/i915.rst | 41 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 7f2daa1b4a8b..da64ebdaa9e0 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -58,6 +58,47 @@ Intel GVT-g Host Support(vGPU device model)
 .. kernel-doc:: drivers/gpu/drm/i915/intel_gvt.c
    :internal:
 
+Other Intel GVT-g interfaces
+----------------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/gvt.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/aperture_gm.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/cfg_space.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/debugfs.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/display.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/edid.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/fb_decoder.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/firmware.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/gtt.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/handlers.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/interrupt.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/kvmgt.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/intel_gvt_mmio_table.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/mmio.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/mmio_context.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/opregion.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/page_track.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/scheduler.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/vgpu.c
+
 Workarounds
 -----------
 
-- 
2.37.3

[PATCH v3 30/37] docs: gpu: i915.rst: PM: add more kernel-doc markups

[Mauro Carvalho Chehab]

Both intel_runtime_pm.h and intel_pm.c contains kAPI for
runtime PM. So, add them to the documentation.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 Documentation/gpu/i915.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index da64ebdaa9e0..4ce04a457ccc 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -25,6 +25,10 @@ Runtime Power Management
 .. kernel-doc:: drivers/gpu/drm/i915/intel_uncore.c
    :internal:
 
+.. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/intel_pm.c
+
 Interrupt Handling
 ------------------
 
-- 
2.37.3

[PATCH v3 31/37] docs: gpu: i915.rst: GEM/TTM: add more kernel-doc markups

[Mauro Carvalho Chehab]

There are several documented GEM/TTM kAPI that aren't currently part
of the docs. Add them, as this allows identifying issues with
badly-formatted tags.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 Documentation/gpu/i915.rst | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 4ce04a457ccc..545fe630557a 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -612,6 +612,44 @@ Protected Objects
 
 .. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_types.h
 
+Table Manager (TTM)
+-------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c
+
+Graphics Execution Manager (GEM)
+--------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_create.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_domain.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_internal.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_lmem.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_mman.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_object.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_object.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_object_types.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_region.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_region.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_userptr.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_wait.c
+
 Microcontrollers
 ================
 
-- 
2.37.3

[PATCH v3 32/37] docs: gpu: i915.rst: add the remaining kernel-doc markup files

[Mauro Carvalho Chehab]

There are other files with kernel-doc markups:

	$ git grep -l "/\*\*" $(git ls-files|grep drivers/gpu/drm/i915/) >kernel-doc-files
	$ for i in $(cat kernel-doc-files); do if [ "$(git grep $i Documentation/)" == "" ]; then echo "$i"; fi; done >aaa

Add them to i915.rst as well.

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

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

 Documentation/gpu/i915.rst | 85 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 83 insertions(+), 2 deletions(-)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 545fe630557a..7f5cd01ed398 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -13,6 +13,11 @@ Core Driver Infrastructure
 This section covers core driver infrastructure used by both the display
 and the GEM parts of the driver.
 
+Core driver
+-----------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_driver.c
+
 Runtime Power Management
 ------------------------
 
@@ -29,6 +34,8 @@ Runtime Power Management
 
 .. kernel-doc:: drivers/gpu/drm/i915/intel_pm.c
 
+.. kernel-doc:: drivers/gpu/drm/i915/intel_wakeref.h
+
 Interrupt Handling
 ------------------
 
@@ -44,8 +51,25 @@ Interrupt Handling
 .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
    :functions: intel_runtime_pm_enable_interrupts
 
-Intel GVT-g Guest Support(vGPU)
--------------------------------
+Memory Handling
+---------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_resource.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_resource.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_mm.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/intel_memory_region.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_memcpy.c
+
+Intel GVT-g Guest Support (vGPU)
+--------------------------------
 
 .. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c
    :doc: Intel GVT-g guest support
@@ -109,6 +133,55 @@ Workarounds
 .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c
    :doc: Hardware workarounds
 
+Scatterlist handling
+--------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_scatterlist.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_scatterlist.c
+
+i915 request
+------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_request.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_request.c
+
+Others
+------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_ioc32.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_gpu_error.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_active.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_deps.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_deps.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/intel_device_info.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_params.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_sw_fence_work.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_syncmap.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/intel_pcode.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_reg_defs.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.h
+
+
+Protected Xe Path (PXP)
+-----------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_irq.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_tee.c
+
 Display Hardware Handling
 =========================
 
@@ -615,6 +688,12 @@ Protected Objects
 Table Manager (TTM)
 -------------------
 
+.. kernel-doc:: drivers/gpu/drm/i915/i915_ttm_buddy_manager.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_ttm_buddy_manager.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/intel_region_ttm.c
+
 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.c
 
 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.h
@@ -624,6 +703,8 @@ Table Manager (TTM)
 Graphics Execution Manager (GEM)
 --------------------------------
 
+.. kernel-doc:: drivers/gpu/drm/i915/i915_gem.c
+
 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_create.c
 
 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_domain.c
-- 
2.37.3

[PATCH v3 33/37] drm/i915 i915_gem_object_types.h: document struct i915_lut_handle

[Mauro Carvalho Chehab]

commit d1b48c1e7184 ("drm/i915: Replace execbuf vma ht with an idr")
added a rbtree list to allow searching for obj/ctx.

Document it.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 drivers/gpu/drm/i915/gem/i915_gem_object_types.h | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/i915/gem/i915_gem_object_types.h b/drivers/gpu/drm/i915/gem/i915_gem_object_types.h
index 9f6b14ec189a..35746cf268ea 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_object_types.h
+++ b/drivers/gpu/drm/i915/gem/i915_gem_object_types.h
@@ -21,9 +21,15 @@ struct drm_i915_gem_object;
 struct intel_fronbuffer;
 struct intel_memory_region;
 
-/*
- * struct i915_lut_handle tracks the fast lookups from handle to vma used
- * for execbuf. Although we use a radixtree for that mapping, in order to
+/**
+ * struct i915_lut_handle - tracks the fast lookups from handle to vma used
+ * for execbuf.
+ *
+ * @obj_link: link to the object associated with the @handle.
+ * @ctx: context associated with the @handle.
+ * @handle: a rbtree handle to lookup context for specific obj/vma.
+ *
+ * Although we use a radixtree for that mapping, in order to
  * remove them as the object or context is closed, we need a secondary list
  * and a translation entry (i915_lut_handle).
  */
-- 
2.37.3

[PATCH v3 34/37] drm/i915: document struct drm_i915_gem_object

[Mauro Carvalho Chehab]

This is a large struct used to describe gem objects. It is
currently partially documented. Finish its documentation, filling
the gaps from git logs.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 .../gpu/drm/i915/gem/i915_gem_object_types.h  | 200 ++++++++++++++----
 1 file changed, 158 insertions(+), 42 deletions(-)

diff --git a/drivers/gpu/drm/i915/gem/i915_gem_object_types.h b/drivers/gpu/drm/i915/gem/i915_gem_object_types.h
index 35746cf268ea..577f02b16b23 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_object_types.h
+++ b/drivers/gpu/drm/i915/gem/i915_gem_object_types.h
@@ -233,6 +233,9 @@ struct i915_gem_object_page_iter {
 	struct mutex lock; /* protects this cache */
 };
 
+/**
+ * struct drm_i915_gem_object - describes an i915 GEM object
+ */
 struct drm_i915_gem_object {
 	/*
 	 * We might have reason to revisit the below since it wastes
@@ -241,12 +244,16 @@ struct drm_i915_gem_object {
 	 * when accessing it.
 	 */
 	union {
+		/** @base: GEM base object */
 		struct drm_gem_object base;
+		/** @__do_not_access: TTM buffer object */
 		struct ttm_buffer_object __do_not_access;
 	};
 
+	/** @ops: pointer to GEM object ops */
 	const struct drm_i915_gem_object_ops *ops;
 
+	/** @vma: struct containing VMA list, tree and lock */
 	struct {
 		/**
 		 * @vma.lock: protect the list/tree of vmas
@@ -280,10 +287,12 @@ struct drm_i915_gem_object {
 	 *
 	 * If this object is closed, we need to remove all of its VMA from
 	 * the fast lookup index in associated contexts; @lut_list provides
-	 * this translation from object to context->handles_vma.
+	 * this translation from object to ``context->handles_vma``.
 	 */
 	struct list_head lut_list;
-	spinlock_t lut_lock; /* guards lut_list */
+
+	/** @lut_lock: guards @lut_list */
+	spinlock_t lut_lock;
 
 	/**
 	 * @obj_link: Link into @i915_gem_ww_ctx.obj_list
@@ -294,42 +303,88 @@ struct drm_i915_gem_object {
 	 */
 	struct list_head obj_link;
 	/**
-	 * @shared_resv_from: The object shares the resv from this vm.
+	 * @shares_resv_from: The object shares the resv from this vm.
 	 */
 	struct i915_address_space *shares_resv_from;
 
 	union {
+		/** @rcu: head used when freeing objects with RCU */
 		struct rcu_head rcu;
+		/** @freed: list of GEM freed objects */
 		struct llist_node freed;
 	};
 
 	/**
-	 * Whether the object is currently in the GGTT mmap.
+	 * @userfault_count: a value bigger than zero means that the object
+	 * was mmapped into userspace.
+	 *
+	 * Used when the object is currently in the GGTT mmap.
 	 */
 	unsigned int userfault_count;
+	/**
+	 * @userfault_link: list of all objects that were
+	 * mmapped into userspace.
+	 *
+	 * Used when the object is currently in the GGTT mmap.
+	 */
 	struct list_head userfault_link;
 
+	/** @mmo: struct containing mmo offsets and lock */
 	struct {
-		spinlock_t lock; /* Protects access to mmo offsets */
+		/** @mmo.lock: protects access to @mmo.offsets */
+		spinlock_t lock;
+		/** @mmo.offsets: rbtree list of mmo offsets */
 		struct rb_root offsets;
 	} mmo;
 
+	/* private: used on selftest only */
 	I915_SELFTEST_DECLARE(struct list_head st_link);
+	/* public: */
 
+	/**
+	 * @flags: object flags. Current flags are:
+	 *
+	 * %I915_BO_ALLOC_CONTIGUOUS:
+	 *	Object requires to be allocated as a contiguous block
+	 * %I915_BO_ALLOC_VOLATILE:
+	 *	Volatile objects are marked as %DONTNEED while pinned, therefore
+	 *	once unpinned the backing store can be discarded.
+	 *	This is limited to kernel internal objects.
+	 * %I915_BO_ALLOC_CPU_CLEAR:
+	 *	Some internal device local-memory objects may have an option
+	 *	to CPU clear the pages upon gathering the backing store.
+	 *	Note that this might be before the blitter is usable, which
+	 *	is the case for some internal GuC objects.
+	 * %I915_BO_ALLOC_USER:
+	 *	Make sure the object is cleared before any user access.
+	 * %I915_BO_ALLOC_PM_VOLATILE:
+	 *	Object is allowed to lose its contents on suspend / resume,
+	 *	even if pinned
+	 * %I915_BO_ALLOC_PM_EARLY:
+	 *	Object needs to be restored early using memcpy during resume
+	 * %I915_BO_ALLOC_GPU_ONLY:
+	 *	Object is likely never accessed by the CPU. This will
+	 *	prioritise the BO to be allocated in the non-mappable portion
+	 *	of lmem. This is merely a hint, and if dealing with userspace
+	 *	objects the CPU fault handler is free to ignore this.
+	 * %I915_BO_READONLY:
+	 *	User has created object as read-only
+	 * %I915_BO_PROTECTED:
+	 *	User has created protected. All protected objects and
+	 *	contexts will be considered invalid when the PXP session
+	 *	is destroyed and all new submissions using them will be
+	 *	rejected. All intel contexts within the invalidated gem
+	 *	contexts will be marked banned. Userspace can detect that
+	 *	an invalidation has occurred via the %RESET_STATS ioctl,
+	 *	where we report it the same way as a ban due to a hang.
+	 */
 	unsigned long flags;
 #define I915_BO_ALLOC_CONTIGUOUS  BIT(0)
 #define I915_BO_ALLOC_VOLATILE    BIT(1)
 #define I915_BO_ALLOC_CPU_CLEAR   BIT(2)
 #define I915_BO_ALLOC_USER        BIT(3)
-/* Object is allowed to lose its contents on suspend / resume, even if pinned */
 #define I915_BO_ALLOC_PM_VOLATILE BIT(4)
-/* Object needs to be restored early using memcpy during resume */
 #define I915_BO_ALLOC_PM_EARLY    BIT(5)
-/*
- * Object is likely never accessed by the CPU. This will prioritise the BO to be
- * allocated in the non-mappable portion of lmem. This is merely a hint, and if
- * dealing with userspace objects the CPU fault handler is free to ignore this.
- */
 #define I915_BO_ALLOC_GPU_ONLY	  BIT(6)
 #define I915_BO_ALLOC_FLAGS (I915_BO_ALLOC_CONTIGUOUS | \
 			     I915_BO_ALLOC_VOLATILE | \
@@ -342,15 +397,21 @@ struct drm_i915_gem_object {
 #define I915_TILING_QUIRK_BIT     8 /* unknown swizzling; do not release! */
 #define I915_BO_PROTECTED         BIT(9)
 	/**
-	 * @mem_flags - Mutable placement-related flags
+	 * @mem_flags: Mutable placement-related flags
 	 *
 	 * These are flags that indicate specifics of the memory region
 	 * the object is currently in. As such they are only stable
 	 * either under the object lock or if the object is pinned.
+	 * There are two flags:
+	 *
+	 * %I915_BO_FLAG_STRUCT_PAGE:
+	 *	 Object backed by struct pages
+	 * %I915_BO_FLAG_IOMEM:
+	 *	Object backed by IO memory
 	 */
 	unsigned int mem_flags;
-#define I915_BO_FLAG_STRUCT_PAGE BIT(0) /* Object backed by struct pages */
-#define I915_BO_FLAG_IOMEM       BIT(1) /* Object backed by IO memory */
+#define I915_BO_FLAG_STRUCT_PAGE BIT(0)
+#define I915_BO_FLAG_IOMEM       BIT(1)
 	/**
 	 * @cache_level: The desired GTT caching level.
 	 *
@@ -399,7 +460,7 @@ struct drm_i915_gem_object {
 	 *
 	 * Supported values:
 	 *
-	 * I915_BO_CACHE_COHERENT_FOR_READ:
+	 * %I915_BO_CACHE_COHERENT_FOR_READ:
 	 *
 	 * On shared LLC platforms, we use this for special scanout surfaces,
 	 * where the display engine is not coherent with the CPU cache. As such
@@ -422,7 +483,7 @@ struct drm_i915_gem_object {
 	 *
 	 *	cache_coherent = 0
 	 *
-	 * I915_BO_CACHE_COHERENT_FOR_WRITE:
+	 * %I915_BO_CACHE_COHERENT_FOR_WRITE:
 	 *
 	 * When writing through the CPU cache, the GPU is still coherent. Note
 	 * that this also implies I915_BO_CACHE_COHERENT_FOR_READ.
@@ -508,23 +569,29 @@ struct drm_i915_gem_object {
 	 */
 	u16 write_domain;
 
+	/** @frontbuffer: pointer to the object's frontbuffer */
 	struct intel_frontbuffer __rcu *frontbuffer;
 
-	/** Current tiling stride for the object, if it's tiled. */
+	/**
+	 * @tiling_and_stride: current tiling stride for the object,
+	 * if it's tiled.
+	 */
 	unsigned int tiling_and_stride;
 #define FENCE_MINIMUM_STRIDE 128 /* See i915_tiling_ok() */
 #define TILING_MASK (FENCE_MINIMUM_STRIDE - 1)
 #define STRIDE_MASK (~TILING_MASK)
 
+	/** @mm: struct containing mm-specific fields */
 	struct {
-		/*
-		 * Protects the pages and their use. Do not use directly, but
-		 * instead go through the pin/unpin interfaces.
+		/**
+		 * @mm.pages_pin_count: protects the pages and their use. Do
+		 * not use directly, but instead go through the pin/unpin
+		 * interfaces.
 		 */
 		atomic_t pages_pin_count;
 
 		/**
-		 * @shrink_pin: Prevents the pages from being made visible to
+		 * @mm.shrink_pin: Prevents the pages from being made visible to
 		 * the shrinker, while the shrink_pin is non-zero. Most users
 		 * should pretty much never have to care about this, outside of
 		 * some special use cases.
@@ -535,7 +602,7 @@ struct drm_i915_gem_object {
 		 * __i915_gem_object_set_pages(). They will then be removed the
 		 * shrinker list once the pages are released.
 		 *
-		 * The @shrink_pin is incremented by calling
+		 * The @mm.shrink_pin is incremented by calling
 		 * i915_gem_object_make_unshrinkable(), which will also remove
 		 * the object from the shrinker list, if the pin count was zero.
 		 *
@@ -547,13 +614,13 @@ struct drm_i915_gem_object {
 		atomic_t shrink_pin;
 
 		/**
-		 * @ttm_shrinkable: True when the object is using shmem pages
+		 * @mm.ttm_shrinkable: True when the object is using shmem pages
 		 * underneath. Protected by the object lock.
 		 */
 		bool ttm_shrinkable;
 
 		/**
-		 * @unknown_state: Indicate that the object is effectively
+		 * @mm.unknown_state: Indicate that the object is effectively
 		 * borked. This is write-once and set if we somehow encounter a
 		 * fatal error when moving/clearing the pages, and we are not
 		 * able to fallback to memcpy/memset, like on small-BAR systems.
@@ -571,96 +638,145 @@ struct drm_i915_gem_object {
 		bool unknown_state;
 
 		/**
-		 * Priority list of potential placements for this object.
+		 * @mm.placements: priority list of potential placements for
+		 * this object.
 		 */
 		struct intel_memory_region **placements;
+		/**
+		 * @mm.n_placements: Size of @mm.placements.
+		 */
 		int n_placements;
 
 		/**
-		 * Memory region for this object.
+		 * @mm.region: memory region for this object.
 		 */
 		struct intel_memory_region *region;
 
 		/**
-		 * Memory manager resource allocated for this object. Only
-		 * needed for the mock region.
+		 * @mm.res: Memory manager resource allocated for this object.
+		 * Only needed for the mock region.
 		 */
 		struct ttm_resource *res;
 
 		/**
-		 * Element within memory_region->objects or region->purgeable
-		 * if the object is marked as DONTNEED. Access is protected by
-		 * region->obj_lock.
+		 * @mm.region_link: element within memory_region->objects or
+		 * ``region->purgeable`` if the object is marked as %DONTNEED.
+		 * Access is protected by ``region->obj_lock``.
 		 */
 		struct list_head region_link;
 
+		/** @mm.rsgt: refcounted sg-tables */
 		struct i915_refct_sgt *rsgt;
+		/** @mm.pages: pages pointer for GGTT entries */
 		struct sg_table *pages;
+		/**
+		 * @mm.mapping: mapped pages of the object into kernel space.
+		 * can be %NULL if unmapped.
+		 */
 		void *mapping;
 
+		/**
+		 * @mm.page_sizes: Page sizes of the pages.
+		 */
 		struct i915_page_sizes page_sizes;
 
+		/* private: used on selftest only */
 		I915_SELFTEST_DECLARE(unsigned int page_mask);
+		/* public: */
 
+		/** @mm.get_page: */
 		struct i915_gem_object_page_iter get_page;
+		/** @mm.get_dma_page: */
 		struct i915_gem_object_page_iter get_dma_page;
 
 		/**
-		 * Element within i915->mm.shrink_list or i915->mm.purge_list,
-		 * locked by i915->mm.obj_lock.
+		 * @mm.link: element within ``i915->mm.shrink_list`` or
+		 * ``i915->mm.purge_list``, locked by ``i915->mm.obj_lock``.
 		 */
 		struct list_head link;
 
 		/**
-		 * Advice: are the backing pages purgeable?
+		 * @mm.madv: Advice: are the backing pages purgeable?
 		 */
 		unsigned int madv:2;
 
 		/**
-		 * This is set if the object has been written to since the
-		 * pages were last acquired.
+		 * @mm.dirty: this is set if the object has been written to
+		 * since the pages were last acquired.
 		 */
 		bool dirty:1;
 
 		u32 tlb;
 	} mm;
 
+	/** @ttm: struct containing TTM specific fields */
 	struct {
+		/** @ttm.cached_io_rsgt: cached refcounted sg-tables */
 		struct i915_refct_sgt *cached_io_rsgt;
+		/** @ttm.get_io_page: rbtree iterator to get IO pages */
 		struct i915_gem_object_page_iter get_io_page;
+		/** @ttm.backup: list of LMEM objects backed up at suspend */
 		struct drm_i915_gem_object *backup;
+		/** @ttm.created: indicate that object as created with TTM */
 		bool created:1;
 	} ttm;
 
-	/*
-	 * Record which PXP key instance this object was created against (if
-	 * any), so we can use it to determine if the encryption is valid by
-	 * comparing against the current key instance.
+	/**
+	 * @pxp_key_instance: rRecord which PXP key instance this object was
+	 * created against (if any), so we can use it to determine if the
+	 * encryption is valid by comparing against the current key instance.
 	 */
 	u32 pxp_key_instance;
 
-	/** Record of address bit 17 of each page at last unbind. */
+	/** @bit_17: Record of address bit 17 of each page at last unbind. */
 	unsigned long *bit_17;
 
 	union {
 #ifdef CONFIG_MMU_NOTIFIER
+		/**
+		 * @userptr: Struct which supports userptr data
+		 * Only used when %CONFIG_MMU_NOTIFIER is enabled
+		 */
 		struct i915_gem_userptr {
+			/** @userptr.ptr: pointer to the user-mapped ptr */
 			uintptr_t ptr;
+			/** @userptr.notifier_seq: */
 			unsigned long notifier_seq;
 
+			/** @userptr.notifier: data used by MMU notifier */
 			struct mmu_interval_notifier notifier;
+			/** @userptr.pvec: S/G pages used by userptr */
 			struct page **pvec;
+			/**
+			 * @userptr.page_ref: number of page references
+			 * incremented when pages are in usage.
+			 *
+			 */
 			int page_ref;
 		} userptr;
 #endif
 
+		/**
+		 * @stolen: Used to identify an object allocated from
+		 * stolen memory.
+		 */
 		struct drm_mm_node *stolen;
 
+		/**
+		 * @bo_offset: The range start.
+		 * Used only by TTM.
+		 */
 		resource_size_t bo_offset;
 
+		/** @scratch: physical size of huge gem object */
 		unsigned long scratch;
+		/** @encode: gen8 PDE encode address */
 		u64 encode;
 
+		/**
+		 * @gvt_info: contains a pointer to ``dmabuf_obj->info``
+		 * Used only by gvt.
+		 */
 		void *gvt_info;
 	};
 };
-- 
2.37.3

[PATCH v3 35/37] drm/i915: add descriptions for some RPM macros at intel_gt_pm.h

[Mauro Carvalho Chehab]

The intel_gt_pm.h file contains some convenient macros to be used
in GT code in order to get/put runtime PM references and for
checking them.

Add descriptions based on the ones at intel_wakeref.h and
intel_runtime_pm.c.

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

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

 Documentation/gpu/i915.rst            |  2 ++
 drivers/gpu/drm/i915/gt/intel_gt_pm.h | 51 +++++++++++++++++++++++++++
 2 files changed, 53 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 7f5cd01ed398..59c532fe0332 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -446,6 +446,8 @@ Graphics Translation Tables
 Other GT functionality
 ----------------------
 
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_pm.h
+
 .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_context.h
 
 .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gsc.h
diff --git a/drivers/gpu/drm/i915/gt/intel_gt_pm.h b/drivers/gpu/drm/i915/gt/intel_gt_pm.h
index 6c9a46452364..7847e15d102e 100644
--- a/drivers/gpu/drm/i915/gt/intel_gt_pm.h
+++ b/drivers/gpu/drm/i915/gt/intel_gt_pm.h
@@ -11,21 +11,57 @@
 #include "intel_gt_types.h"
 #include "intel_wakeref.h"
 
+/**
+ * intel_gt_pm_is_awake: Query whether the runtime PM is awake held
+ *
+ * @gt: pointer to the graphics engine
+ *
+ * Returns: true if a runtime pm reference is currently held and the GT is
+ * awake.
+ */
 static inline bool intel_gt_pm_is_awake(const struct intel_gt *gt)
 {
 	return intel_wakeref_is_active(&gt->wakeref);
 }
 
+/**
+ * intel_gt_pm_get: grab a runtime PM reference ensuring that GT is powered up
+ * @gt: pointer to the graphics engine
+ *
+ * Any runtime pm reference obtained by this function must have a symmetric
+ * call to intel_gt_pm_put() to release the reference again.
+ *
+ * Note that this is allowed to fail, in which case the runtime-pm wakeref
+ * will be released and the acquisition unwound.
+ */
 static inline void intel_gt_pm_get(struct intel_gt *gt)
 {
 	intel_wakeref_get(&gt->wakeref);
 }
 
+/**
+ * __intel_gt_pm_get: Acquire the runtime PM reference again
+ * @gt: pointer to the graphics engine which contains the wakeref
+ *
+ * Increment the PM reference counter, only valid if it is already held by
+ * the caller.
+ *
+ * See intel_gt_pm_get().
+ */
 static inline void __intel_gt_pm_get(struct intel_gt *gt)
 {
 	__intel_wakeref_get(&gt->wakeref);
 }
 
+/**
+ * intel_gt_pm_get_if_awake: Acquire the runtime PM reference if active
+ * @gt: pointer to the graphics engine which contains the PM reference
+ *
+ * Acquire a hold on the PM reference, but only if the GT is already
+ * active.
+ *
+ * Returns: true if the wakeref was acquired, false otherwise.
+ */
 static inline bool intel_gt_pm_get_if_awake(struct intel_gt *gt)
 {
 	return intel_wakeref_get_if_active(&gt->wakeref);
@@ -36,6 +72,14 @@ static inline void intel_gt_pm_might_get(struct intel_gt *gt)
 	intel_wakeref_might_get(&gt->wakeref);
 }
 
+/**
+ * intel_gt_pm_put: Release the runtime PM reference
+ * @gt: pointer to the graphics engine which contains the PM reference
+ *
+ * Release our hold on the runtime PM for GT.
+ *
+ * It might power down the GT right away if this is the last reference.
+ */
 static inline void intel_gt_pm_put(struct intel_gt *gt)
 {
 	intel_wakeref_put(&gt->wakeref);
@@ -51,6 +95,13 @@ static inline void intel_gt_pm_might_put(struct intel_gt *gt)
 	intel_wakeref_might_put(&gt->wakeref);
 }
 
+/**
+ * with_intel_gt_pm - get a GT reference ensuring that GT is powered up,
+ *	run some code and then put the reference away.
+ *
+ * @gt: pointer to the gt
+ * @tmp: pointer to a temporary wakeref.
+ */
 #define with_intel_gt_pm(gt, tmp) \
 	for (tmp = 1, intel_gt_pm_get(gt); tmp; \
 	     intel_gt_pm_put(gt), tmp = 0)
-- 
2.37.3

[PATCH v3 36/37] drm/i915: add GuC functions to the documentation

[Mauro Carvalho Chehab]

Currently, functions inside GuC aren't presented as part of the
GuC documentation.

Add them.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

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

 Documentation/gpu/i915.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 59c532fe0332..b71e9720a1ac 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -759,6 +759,9 @@ GuC
 
 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.h
 
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c
+   :internal:
+
 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_actions_slpc_abi.h
 
 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c
-- 
2.37.3

[PATCH v3 37/37] drm/i915: be consistent with kernel-doc function declaration

[Mauro Carvalho Chehab]

Currently, 91% of kernel-doc function declarations don't have
parenthesis on it. Let's be consistent inside the driver by
removing the parenthesis from the other ones.

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

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

 drivers/gpu/drm/i915/display/intel_atomic.c    |  2 +-
 drivers/gpu/drm/i915/display/intel_audio.c     |  4 ++--
 drivers/gpu/drm/i915/display/intel_crtc.c      |  4 ++--
 drivers/gpu/drm/i915/display/intel_dmc.c       | 10 +++++-----
 drivers/gpu/drm/i915/display/intel_dsb.c       | 10 +++++-----
 drivers/gpu/drm/i915/display/intel_lpe_audio.c |  8 ++++----
 drivers/gpu/drm/i915/gt/intel_engine_cs.c      | 10 +++++-----
 drivers/gpu/drm/i915/gt/uc/intel_guc.c         | 10 +++++-----
 drivers/gpu/drm/i915/gt/uc/intel_guc.h         |  2 +-
 drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c     |  4 ++--
 drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c      |  2 +-
 drivers/gpu/drm/i915/gt/uc/intel_guc_slpc.c    |  8 ++++----
 drivers/gpu/drm/i915/gt/uc/intel_huc.c         |  4 ++--
 drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c      |  2 +-
 drivers/gpu/drm/i915/gt/uc/intel_uc_fw.h       |  2 +-
 drivers/gpu/drm/i915/i915_cmd_parser.c         |  8 ++++----
 drivers/gpu/drm/i915/i915_reg_defs.h           | 12 ++++++------
 drivers/gpu/drm/i915/intel_wopcm.c             |  4 ++--
 18 files changed, 53 insertions(+), 53 deletions(-)

diff --git a/drivers/gpu/drm/i915/display/intel_atomic.c b/drivers/gpu/drm/i915/display/intel_atomic.c
index 18f0a5ae3bac..9b604a720ff0 100644
--- a/drivers/gpu/drm/i915/display/intel_atomic.c
+++ b/drivers/gpu/drm/i915/display/intel_atomic.c
@@ -373,7 +373,7 @@ static void intel_atomic_setup_scaler(struct intel_crtc_scaler_state *scaler_sta
 }
 
 /**
- * intel_atomic_setup_scalers() - setup scalers for crtc per staged requests
+ * intel_atomic_setup_scalers - setup scalers for crtc per staged requests
  * @dev_priv: i915 device
  * @intel_crtc: intel crtc
  * @crtc_state: incoming crtc_state to validate and setup scalers
diff --git a/drivers/gpu/drm/i915/display/intel_audio.c b/drivers/gpu/drm/i915/display/intel_audio.c
index aacbc6da84ef..667fe9a8ff8e 100644
--- a/drivers/gpu/drm/i915/display/intel_audio.c
+++ b/drivers/gpu/drm/i915/display/intel_audio.c
@@ -1385,7 +1385,7 @@ static void i915_audio_component_cleanup(struct drm_i915_private *dev_priv)
 }
 
 /**
- * intel_audio_init() - Initialize the audio driver either using
+ * intel_audio_init - Initialize the audio driver either using
  * component framework or using lpe audio bridge
  * @dev_priv: the i915 drm device private data
  *
@@ -1397,7 +1397,7 @@ void intel_audio_init(struct drm_i915_private *dev_priv)
 }
 
 /**
- * intel_audio_deinit() - deinitialize the audio driver
+ * intel_audio_deinit - deinitialize the audio driver
  * @dev_priv: the i915 drm device private data
  *
  */
diff --git a/drivers/gpu/drm/i915/display/intel_crtc.c b/drivers/gpu/drm/i915/display/intel_crtc.c
index 6792a9056f46..507d7aec7b1c 100644
--- a/drivers/gpu/drm/i915/display/intel_crtc.c
+++ b/drivers/gpu/drm/i915/display/intel_crtc.c
@@ -463,7 +463,7 @@ static int intel_mode_vblank_start(const struct drm_display_mode *mode)
 }
 
 /**
- * intel_pipe_update_start() - start update of a set of display registers
+ * intel_pipe_update_start - start update of a set of display registers
  * @new_crtc_state: the new crtc state
  *
  * Mark the start of an update to pipe registers that should be updated
@@ -617,7 +617,7 @@ static void dbg_vblank_evade(struct intel_crtc *crtc, ktime_t end) {}
 #endif
 
 /**
- * intel_pipe_update_end() - end update of a set of display registers
+ * intel_pipe_update_end - end update of a set of display registers
  * @new_crtc_state: the new crtc state
  *
  * Mark the end of an update started with intel_pipe_update_start(). This
diff --git a/drivers/gpu/drm/i915/display/intel_dmc.c b/drivers/gpu/drm/i915/display/intel_dmc.c
index e52ecc0738a6..2024884688f6 100644
--- a/drivers/gpu/drm/i915/display/intel_dmc.c
+++ b/drivers/gpu/drm/i915/display/intel_dmc.c
@@ -408,7 +408,7 @@ static void pipedmc_clock_gating_wa(struct drm_i915_private *i915, bool enable)
 }
 
 /**
- * intel_dmc_load_program() - write the firmware from memory to register.
+ * intel_dmc_load_program - write the firmware from memory to register.
  * @dev_priv: i915 drm device.
  *
  * DMC firmware is read from a .bin file and kept in internal memory one time.
@@ -876,7 +876,7 @@ static void dmc_load_work_fn(struct work_struct *work)
 }
 
 /**
- * intel_dmc_ucode_init() - initialize the firmware loading.
+ * intel_dmc_ucode_init - initialize the firmware loading.
  * @dev_priv: i915 drm device.
  *
  * This function is called at the time of loading the display driver to read
@@ -973,7 +973,7 @@ void intel_dmc_ucode_init(struct drm_i915_private *dev_priv)
 }
 
 /**
- * intel_dmc_ucode_suspend() - prepare DMC firmware before system suspend
+ * intel_dmc_ucode_suspend - prepare DMC firmware before system suspend
  * @dev_priv: i915 drm device
  *
  * Prepare the DMC firmware before entering system suspend. This includes
@@ -993,7 +993,7 @@ void intel_dmc_ucode_suspend(struct drm_i915_private *dev_priv)
 }
 
 /**
- * intel_dmc_ucode_resume() - init DMC firmware during system resume
+ * intel_dmc_ucode_resume - init DMC firmware during system resume
  * @dev_priv: i915 drm device
  *
  * Reinitialize the DMC firmware during system resume, reacquiring any
@@ -1013,7 +1013,7 @@ void intel_dmc_ucode_resume(struct drm_i915_private *dev_priv)
 }
 
 /**
- * intel_dmc_ucode_fini() - unload the DMC firmware.
+ * intel_dmc_ucode_fini - unload the DMC firmware.
  * @dev_priv: i915 drm device.
  *
  * Firmmware unloading includes freeing the internal memory and reset the
diff --git a/drivers/gpu/drm/i915/display/intel_dsb.c b/drivers/gpu/drm/i915/display/intel_dsb.c
index c4affcb216fd..2ce406f62d40 100644
--- a/drivers/gpu/drm/i915/display/intel_dsb.c
+++ b/drivers/gpu/drm/i915/display/intel_dsb.c
@@ -80,7 +80,7 @@ static bool intel_dsb_disable_engine(struct drm_i915_private *i915,
 }
 
 /**
- * intel_dsb_indexed_reg_write() -Write to the DSB context for auto
+ * intel_dsb_indexed_reg_write -Write to the DSB context for auto
  * increment register.
  * @crtc_state: intel_crtc_state structure
  * @reg: register address.
@@ -158,7 +158,7 @@ void intel_dsb_indexed_reg_write(const struct intel_crtc_state *crtc_state,
 }
 
 /**
- * intel_dsb_reg_write() -Write to the DSB context for normal
+ * intel_dsb_reg_write -Write to the DSB context for normal
  * register.
  * @crtc_state: intel_crtc_state structure
  * @reg: register address.
@@ -197,7 +197,7 @@ void intel_dsb_reg_write(const struct intel_crtc_state *crtc_state,
 }
 
 /**
- * intel_dsb_commit() - Trigger workload execution of DSB.
+ * intel_dsb_commit - Trigger workload execution of DSB.
  * @crtc_state: intel_crtc_state structure
  *
  * This function is used to do actual write to hardware using DSB.
@@ -254,7 +254,7 @@ void intel_dsb_commit(const struct intel_crtc_state *crtc_state)
 }
 
 /**
- * intel_dsb_prepare() - Allocate, pin and map the DSB command buffer.
+ * intel_dsb_prepare - Allocate, pin and map the DSB command buffer.
  * @crtc_state: intel_crtc_state structure to prepare associated dsb instance.
  *
  * This function prepare the command buffer which is used to store dsb
@@ -316,7 +316,7 @@ void intel_dsb_prepare(struct intel_crtc_state *crtc_state)
 }
 
 /**
- * intel_dsb_cleanup() - To cleanup DSB context.
+ * intel_dsb_cleanup - To cleanup DSB context.
  * @crtc_state: intel_crtc_state structure to cleanup associated dsb instance.
  *
  * This function cleanup the DSB context by unpinning and releasing
diff --git a/drivers/gpu/drm/i915/display/intel_lpe_audio.c b/drivers/gpu/drm/i915/display/intel_lpe_audio.c
index dca6003ccac8..078a14e991a0 100644
--- a/drivers/gpu/drm/i915/display/intel_lpe_audio.c
+++ b/drivers/gpu/drm/i915/display/intel_lpe_audio.c
@@ -250,7 +250,7 @@ static int lpe_audio_setup(struct drm_i915_private *dev_priv)
 }
 
 /**
- * intel_lpe_audio_irq_handler() - forwards the LPE audio irq
+ * intel_lpe_audio_irq_handler - forwards the LPE audio irq
  * @dev_priv: the i915 drm device private data
  *
  * the LPE Audio irq is forwarded to the irq handler registered by LPE audio
@@ -270,7 +270,7 @@ void intel_lpe_audio_irq_handler(struct drm_i915_private *dev_priv)
 }
 
 /**
- * intel_lpe_audio_init() - detect and setup the bridge between HDMI LPE Audio
+ * intel_lpe_audio_init - detect and setup the bridge between HDMI LPE Audio
  * driver and i915
  * @dev_priv: the i915 drm device private data
  *
@@ -291,7 +291,7 @@ int intel_lpe_audio_init(struct drm_i915_private *dev_priv)
 }
 
 /**
- * intel_lpe_audio_teardown() - destroy the bridge between HDMI LPE
+ * intel_lpe_audio_teardown - destroy the bridge between HDMI LPE
  * audio driver and i915
  * @dev_priv: the i915 drm device private data
  *
@@ -311,7 +311,7 @@ void intel_lpe_audio_teardown(struct drm_i915_private *dev_priv)
 }
 
 /**
- * intel_lpe_audio_notify() - notify lpe audio event
+ * intel_lpe_audio_notify - notify lpe audio event
  * audio driver and i915
  * @dev_priv: the i915 drm device private data
  * @pipe: pipe
diff --git a/drivers/gpu/drm/i915/gt/intel_engine_cs.c b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
index da9cd41c45f1..0ac813422809 100644
--- a/drivers/gpu/drm/i915/gt/intel_engine_cs.c
+++ b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
@@ -247,7 +247,7 @@ static const struct engine_info intel_engines[] = {
 };
 
 /**
- * intel_engine_context_size() - return the size of the context for an engine
+ * intel_engine_context_size - return the size of the context for an engine
  * @gt: the gt
  * @class: engine class
  *
@@ -576,7 +576,7 @@ static void intel_setup_engine_capabilities(struct intel_gt *gt)
 }
 
 /**
- * intel_engines_release() - free the resources allocated for Command Streamers
+ * intel_engines_release - free the resources allocated for Command Streamers
  * @gt: pointer to struct intel_gt
  */
 void intel_engines_release(struct intel_gt *gt)
@@ -846,7 +846,7 @@ static void setup_logical_ids(struct intel_gt *gt, u8 *logical_ids, u8 class)
 }
 
 /**
- * intel_engines_init_mmio() - allocate and prepare the Engine Command Streamers
+ * intel_engines_init_mmio - allocate and prepare the Engine Command Streamers
  * @gt: pointer to struct intel_gt
  *
  * Return: non-zero if the initialization failed.
@@ -1631,7 +1631,7 @@ void __intel_engine_flush_submission(struct intel_engine_cs *engine, bool sync)
 }
 
 /**
- * intel_engine_is_idle() - Report if the engine has finished process all work
+ * intel_engine_is_idle - Report if the engine has finished process all work
  * @engine: the intel_engine_cs
  *
  * Return true if there are no requests pending, nothing left to be submitted
@@ -2203,7 +2203,7 @@ void intel_engine_dump(struct intel_engine_cs *engine,
 }
 
 /**
- * intel_engine_get_busy_time() - Return current accumulated engine busyness
+ * intel_engine_get_busy_time - Return current accumulated engine busyness
  * @engine: engine to report on
  * @now: monotonic timestamp of sampling
  *
diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc.c b/drivers/gpu/drm/i915/gt/uc/intel_guc.c
index 24451d000a6a..d969005a857c 100644
--- a/drivers/gpu/drm/i915/gt/uc/intel_guc.c
+++ b/drivers/gpu/drm/i915/gt/uc/intel_guc.c
@@ -599,7 +599,7 @@ int intel_guc_to_host_process_recv_msg(struct intel_guc *guc,
 }
 
 /**
- * intel_guc_auth_huc() - Send action to GuC to authenticate HuC ucode
+ * intel_guc_auth_huc - Send action to GuC to authenticate HuC ucode
  * @guc: intel_guc structure
  * @rsa_offset: rsa offset w.r.t ggtt base of huc vma
  *
@@ -620,7 +620,7 @@ int intel_guc_auth_huc(struct intel_guc *guc, u32 rsa_offset)
 }
 
 /**
- * intel_guc_suspend() - notify GuC entering suspend state
+ * intel_guc_suspend - notify GuC entering suspend state
  * @guc:	the guc
  */
 int intel_guc_suspend(struct intel_guc *guc)
@@ -657,7 +657,7 @@ int intel_guc_suspend(struct intel_guc *guc)
 }
 
 /**
- * intel_guc_resume() - notify GuC resuming from suspend state
+ * intel_guc_resume - notify GuC resuming from suspend state
  * @guc:	the guc
  */
 int intel_guc_resume(struct intel_guc *guc)
@@ -706,7 +706,7 @@ int intel_guc_resume(struct intel_guc *guc)
  */
 
 /**
- * intel_guc_allocate_vma() - Allocate a GGTT VMA for GuC usage
+ * intel_guc_allocate_vma - Allocate a GGTT VMA for GuC usage
  * @guc:	the guc
  * @size:	size of area to allocate (both virtual space and memory)
  *
@@ -756,7 +756,7 @@ struct i915_vma *intel_guc_allocate_vma(struct intel_guc *guc, u32 size)
 }
 
 /**
- * intel_guc_allocate_and_map_vma() - Allocate and map VMA for GuC usage
+ * intel_guc_allocate_and_map_vma - Allocate and map VMA for GuC usage
  * @guc:	the guc
  * @size:	size of area to allocate (both virtual space and memory)
  * @out_vma:	return variable for the allocated vma pointer
diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc.h b/drivers/gpu/drm/i915/gt/uc/intel_guc.h
index 804133df1ac9..04b0cecf12bd 100644
--- a/drivers/gpu/drm/i915/gt/uc/intel_guc.h
+++ b/drivers/gpu/drm/i915/gt/uc/intel_guc.h
@@ -325,7 +325,7 @@ static inline void intel_guc_to_host_event_handler(struct intel_guc *guc)
 #define GUC_GGTT_TOP	0xFEE00000
 
 /**
- * intel_guc_ggtt_offset() - Get and validate the GGTT offset of @vma
+ * intel_guc_ggtt_offset - Get and validate the GGTT offset of @vma
  * @guc: intel_guc structure.
  * @vma: i915 graphics virtual memory area.
  *
diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c b/drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c
index 74cbe8eaf531..77204382cc44 100644
--- a/drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c
+++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c
@@ -786,7 +786,7 @@ static void __guc_ads_init(struct intel_guc *guc)
 }
 
 /**
- * intel_guc_ads_create() - allocates and initializes GuC ADS.
+ * intel_guc_ads_create - allocates and initializes GuC ADS.
  * @guc: intel_guc struct
  *
  * GuC needs memory block (Additional Data Struct), where it will store
@@ -871,7 +871,7 @@ static void guc_ads_private_data_reset(struct intel_guc *guc)
 }
 
 /**
- * intel_guc_ads_reset() - prepares GuC Additional Data Struct for reuse
+ * intel_guc_ads_reset - prepares GuC Additional Data Struct for reuse
  * @guc: intel_guc struct
  *
  * GuC stores some data in ADS, which might be stale after a reset.
diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c b/drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c
index a0372735cddb..bcdc37e6d9c9 100644
--- a/drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c
+++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c
@@ -151,7 +151,7 @@ static int guc_wait_ucode(struct intel_uncore *uncore)
 }
 
 /**
- * intel_guc_fw_upload() - load GuC uCode to device
+ * intel_guc_fw_upload - load GuC uCode to device
  * @guc: intel_guc structure
  *
  * Called from intel_uc_init_hw() during driver load, resume from sleep and
diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc_slpc.c b/drivers/gpu/drm/i915/gt/uc/intel_guc_slpc.c
index fdd895f73f9f..288db5ada139 100644
--- a/drivers/gpu/drm/i915/gt/uc/intel_guc_slpc.c
+++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_slpc.c
@@ -381,7 +381,7 @@ static void slpc_shared_data_reset(struct slpc_shared_data *data)
 }
 
 /**
- * intel_guc_slpc_set_max_freq() - Set max frequency limit for SLPC.
+ * intel_guc_slpc_set_max_freq - Set max frequency limit for SLPC.
  * @slpc: pointer to intel_guc_slpc.
  * @val: frequency (MHz)
  *
@@ -418,7 +418,7 @@ int intel_guc_slpc_set_max_freq(struct intel_guc_slpc *slpc, u32 val)
 }
 
 /**
- * intel_guc_slpc_get_max_freq() - Get max frequency limit for SLPC.
+ * intel_guc_slpc_get_max_freq - Get max frequency limit for SLPC.
  * @slpc: pointer to intel_guc_slpc.
  * @val: pointer to val which will hold max frequency (MHz)
  *
@@ -445,7 +445,7 @@ int intel_guc_slpc_get_max_freq(struct intel_guc_slpc *slpc, u32 *val)
 }
 
 /**
- * intel_guc_slpc_set_min_freq() - Set min frequency limit for SLPC.
+ * intel_guc_slpc_set_min_freq - Set min frequency limit for SLPC.
  * @slpc: pointer to intel_guc_slpc.
  * @val: frequency (MHz)
  *
@@ -498,7 +498,7 @@ int intel_guc_slpc_set_min_freq(struct intel_guc_slpc *slpc, u32 val)
 }
 
 /**
- * intel_guc_slpc_get_min_freq() - Get min frequency limit for SLPC.
+ * intel_guc_slpc_get_min_freq - Get min frequency limit for SLPC.
  * @slpc: pointer to intel_guc_slpc.
  * @val: pointer to val which will hold min frequency (MHz)
  *
diff --git a/drivers/gpu/drm/i915/gt/uc/intel_huc.c b/drivers/gpu/drm/i915/gt/uc/intel_huc.c
index 3bb8838e325a..127f7b952646 100644
--- a/drivers/gpu/drm/i915/gt/uc/intel_huc.c
+++ b/drivers/gpu/drm/i915/gt/uc/intel_huc.c
@@ -126,7 +126,7 @@ void intel_huc_fini(struct intel_huc *huc)
 }
 
 /**
- * intel_huc_auth() - Authenticate HuC uCode
+ * intel_huc_auth - Authenticate HuC uCode
  * @huc: intel_huc structure
  *
  * Called after HuC and GuC firmware loading during intel_uc_init_hw().
@@ -194,7 +194,7 @@ static bool huc_is_authenticated(struct intel_huc *huc)
 }
 
 /**
- * intel_huc_check_status() - check HuC status
+ * intel_huc_check_status - check HuC status
  * @huc: intel_huc structure
  *
  * This function reads status register to verify if HuC
diff --git a/drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c b/drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c
index 9d6ab1e01639..1fb05b45a8d2 100644
--- a/drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c
+++ b/drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c
@@ -8,7 +8,7 @@
 #include "i915_drv.h"
 
 /**
- * intel_huc_fw_upload() - load HuC uCode to device via DMA transfer
+ * intel_huc_fw_upload - load HuC uCode to device via DMA transfer
  * @huc: intel_huc structure
  *
  * Called from intel_uc_init_hw() during driver load, resume from sleep and
diff --git a/drivers/gpu/drm/i915/gt/uc/intel_uc_fw.h b/drivers/gpu/drm/i915/gt/uc/intel_uc_fw.h
index cb586f7df270..b14c82e17a6c 100644
--- a/drivers/gpu/drm/i915/gt/uc/intel_uc_fw.h
+++ b/drivers/gpu/drm/i915/gt/uc/intel_uc_fw.h
@@ -250,7 +250,7 @@ static inline u32 __intel_uc_fw_get_upload_size(struct intel_uc_fw *uc_fw)
 }
 
 /**
- * intel_uc_fw_get_upload_size() - Get size of firmware needed to be uploaded.
+ * intel_uc_fw_get_upload_size - Get size of firmware needed to be uploaded.
  * @uc_fw: uC firmware.
  *
  * Get the size of the firmware and header that will be uploaded to WOPCM.
diff --git a/drivers/gpu/drm/i915/i915_cmd_parser.c b/drivers/gpu/drm/i915/i915_cmd_parser.c
index f93e6122f247..1929aff97fee 100644
--- a/drivers/gpu/drm/i915/i915_cmd_parser.c
+++ b/drivers/gpu/drm/i915/i915_cmd_parser.c
@@ -945,7 +945,7 @@ static void fini_hash_table(struct intel_engine_cs *engine)
 }
 
 /**
- * intel_engine_init_cmd_parser() - set cmd parser related fields for an engine
+ * intel_engine_init_cmd_parser - set cmd parser related fields for an engine
  * @engine: the engine to initialize
  *
  * Optionally initializes fields related to batch buffer command parsing in the
@@ -1059,7 +1059,7 @@ int intel_engine_init_cmd_parser(struct intel_engine_cs *engine)
 }
 
 /**
- * intel_engine_cleanup_cmd_parser() - clean up cmd parser related fields
+ * intel_engine_cleanup_cmd_parser - clean up cmd parser related fields
  * @engine: the engine to clean up
  *
  * Releases any resources related to command parsing that may have been
@@ -1422,7 +1422,7 @@ static unsigned long *alloc_whitelist(u32 batch_length)
 #define LENGTH_BIAS 2
 
 /**
- * intel_engine_cmd_parser() - parse a batch buffer for privilege violations
+ * intel_engine_cmd_parser - parse a batch buffer for privilege violations
  * @engine: the engine on which the batch is to execute
  * @batch: the batch buffer in question
  * @batch_offset: byte offset in the batch at which execution starts
@@ -1578,7 +1578,7 @@ int intel_engine_cmd_parser(struct intel_engine_cs *engine,
 }
 
 /**
- * i915_cmd_parser_get_version() - get the cmd parser version number
+ * i915_cmd_parser_get_version - get the cmd parser version number
  * @dev_priv: i915 device private
  *
  * The cmd parser maintains a simple increasing integer version number suitable
diff --git a/drivers/gpu/drm/i915/i915_reg_defs.h b/drivers/gpu/drm/i915/i915_reg_defs.h
index 8f486f77609f..ce859aedfd01 100644
--- a/drivers/gpu/drm/i915/i915_reg_defs.h
+++ b/drivers/gpu/drm/i915/i915_reg_defs.h
@@ -10,7 +10,7 @@
 #include <linux/bits.h>
 
 /**
- * REG_BIT() - Prepare a u32 bit value
+ * REG_BIT - Prepare a u32 bit value
  * @__n: 0-based bit number
  *
  * Local wrapper for BIT() to force u32, with compile time checks.
@@ -23,7 +23,7 @@
 				 ((__n) < 0 || (__n) > 31))))
 
 /**
- * REG_GENMASK() - Prepare a continuous u32 bitmask
+ * REG_GENMASK - Prepare a continuous u32 bitmask
  * @__high: 0-based high bit
  * @__low: 0-based low bit
  *
@@ -38,7 +38,7 @@
 				 ((__low) < 0 || (__high) > 31 || (__low) > (__high)))))
 
 /**
- * REG_GENMASK64() - Prepare a continuous u64 bitmask
+ * REG_GENMASK64 - Prepare a continuous u64 bitmask
  * @__high: 0-based high bit
  * @__low: 0-based low bit
  *
@@ -58,7 +58,7 @@
 #define IS_POWER_OF_2(__x)		((__x) && (((__x) & ((__x) - 1)) == 0))
 
 /**
- * REG_FIELD_PREP() - Prepare a u32 bitfield value
+ * REG_FIELD_PREP - Prepare a u32 bitfield value
  * @__mask: shifted mask defining the field's length and position
  * @__val: value to put in the field
  *
@@ -75,7 +75,7 @@
 	       BUILD_BUG_ON_ZERO(__builtin_choose_expr(__is_constexpr(__val), (~((__mask) >> __bf_shf(__mask)) & (__val)), 0))))
 
 /**
- * REG_FIELD_GET() - Extract a u32 bitfield value
+ * REG_FIELD_GET - Extract a u32 bitfield value
  * @__mask: shifted mask defining the field's length and position
  * @__val: value to extract the bitfield value from
  *
@@ -87,7 +87,7 @@
 #define REG_FIELD_GET(__mask, __val)	((u32)FIELD_GET(__mask, __val))
 
 /**
- * REG_FIELD_GET64() - Extract a u64 bitfield value
+ * REG_FIELD_GET64 - Extract a u64 bitfield value
  * @__mask: shifted mask defining the field's length and position
  * @__val: value to extract the bitfield value from
  *
diff --git a/drivers/gpu/drm/i915/intel_wopcm.c b/drivers/gpu/drm/i915/intel_wopcm.c
index 322fb9eeb880..c66b3c173ed6 100644
--- a/drivers/gpu/drm/i915/intel_wopcm.c
+++ b/drivers/gpu/drm/i915/intel_wopcm.c
@@ -70,7 +70,7 @@ static inline struct drm_i915_private *wopcm_to_i915(struct intel_wopcm *wopcm)
 }
 
 /**
- * intel_wopcm_init_early() - Early initialization of the WOPCM.
+ * intel_wopcm_init_early - Early initialization of the WOPCM.
  * @wopcm: pointer to intel_wopcm.
  *
  * Setup the size of WOPCM which will be used by later on WOPCM partitioning.
@@ -217,7 +217,7 @@ static bool __wopcm_regs_writable(struct intel_uncore *uncore)
 }
 
 /**
- * intel_wopcm_init() - Initialize the WOPCM structure.
+ * intel_wopcm_init - Initialize the WOPCM structure.
  * @wopcm: pointer to intel_wopcm.
  *
  * This function will partition WOPCM space based on GuC and HuC firmware sizes
-- 
2.37.3

Re: [Intel-gfx] [PATCH v3 27/37] docs: gpu: i915.rst: gt: add more kernel-doc markups

[Rodrigo Vivi]

On Fri, Sep 09, 2022 at 09:34:34AM +0200, Mauro Carvalho Chehab wrote:
> There are several documented GT kAPI that aren't currently part
> of the docs. Add them, as this allows identifying issues with
> badly-formatted tags.
>

In i915's commits we usually add a version history here
to indicate what changed from the previous submission,
something like

v2: re-organizing the blocks to group gtt stuff.

that helps reviewers to know if their change requested was
addressed or not.

but anyways:

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

> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
> 
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v3 00/37] at: https://lore.kernel.org/all/cover.1662708705.git.mchehab@kernel.org/
> 
>  Documentation/gpu/i915.rst | 40 +++++++++++++++++++++++++++++++++++++-
>  1 file changed, 39 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 2ad7941a79f2..b668f36fb0a3 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -149,7 +149,6 @@ Misc display functions
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/skl_scaler.c
>  
> -
>  Plane Configuration
>  -------------------
>  
> @@ -308,6 +307,45 @@ Multicast/Replicated (MCR) Registers
>  .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_mcr.c
>     :internal:
>  
> +GT engine
> +---------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_types.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_cs.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_pm.c
> +
> +Graphics Translation Tables
> +---------------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.h
> +
> +Other GT functionality
> +----------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_context.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gsc.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_migrate.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_mocs.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rc6.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_reset.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rps_types.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rps.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_sseu.c
> +
>  Memory Management and Command Submission
>  ========================================
>  
> -- 
> 2.37.3
> 

Re: [Intel-gfx] [PATCH v3 32/37] docs: gpu: i915.rst: add the remaining kernel-doc markup files

[Rodrigo Vivi]

On Fri, Sep 09, 2022 at 09:34:39AM +0200, Mauro Carvalho Chehab wrote:
> There are other files with kernel-doc markups:
> 
> 	$ git grep -l "/\*\*" $(git ls-files|grep drivers/gpu/drm/i915/) >kernel-doc-files
> 	$ for i in $(cat kernel-doc-files); do if [ "$(git grep $i Documentation/)" == "" ]; then echo "$i"; fi; done >aaa
> 
> Add them to i915.rst as well.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>

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

> ---
> 
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v3 00/37] at: https://lore.kernel.org/all/cover.1662708705.git.mchehab@kernel.org/
> 
>  Documentation/gpu/i915.rst | 85 +++++++++++++++++++++++++++++++++++++-
>  1 file changed, 83 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 545fe630557a..7f5cd01ed398 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -13,6 +13,11 @@ Core Driver Infrastructure
>  This section covers core driver infrastructure used by both the display
>  and the GEM parts of the driver.
>  
> +Core driver
> +-----------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_driver.c
> +
>  Runtime Power Management
>  ------------------------
>  
> @@ -29,6 +34,8 @@ Runtime Power Management
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/intel_pm.c
>  
> +.. kernel-doc:: drivers/gpu/drm/i915/intel_wakeref.h
> +
>  Interrupt Handling
>  ------------------
>  
> @@ -44,8 +51,25 @@ Interrupt Handling
>  .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
>     :functions: intel_runtime_pm_enable_interrupts
>  
> -Intel GVT-g Guest Support(vGPU)
> --------------------------------
> +Memory Handling
> +---------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_resource.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_resource.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_mm.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/intel_memory_region.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_memcpy.c
> +
> +Intel GVT-g Guest Support (vGPU)
> +--------------------------------
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c
>     :doc: Intel GVT-g guest support
> @@ -109,6 +133,55 @@ Workarounds
>  .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c
>     :doc: Hardware workarounds
>  
> +Scatterlist handling
> +--------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_scatterlist.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_scatterlist.c
> +
> +i915 request
> +------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_request.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_request.c
> +
> +Others
> +------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_ioc32.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_gpu_error.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_active.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_deps.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_deps.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/intel_device_info.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_params.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_sw_fence_work.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_syncmap.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/intel_pcode.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_reg_defs.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.h
> +
> +
> +Protected Xe Path (PXP)
> +-----------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_irq.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_tee.c
> +
>  Display Hardware Handling
>  =========================
>  
> @@ -615,6 +688,12 @@ Protected Objects
>  Table Manager (TTM)
>  -------------------
>  
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_ttm_buddy_manager.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_ttm_buddy_manager.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/intel_region_ttm.c
> +
>  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.c
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.h
> @@ -624,6 +703,8 @@ Table Manager (TTM)
>  Graphics Execution Manager (GEM)
>  --------------------------------
>  
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_gem.c
> +
>  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_create.c
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_domain.c
> -- 
> 2.37.3
> 

Re: [PATCH v3 35/37] drm/i915: add descriptions for some RPM macros at intel_gt_pm.h

[Rodrigo Vivi]

On Fri, Sep 09, 2022 at 09:34:42AM +0200, Mauro Carvalho Chehab wrote:
> The intel_gt_pm.h file contains some convenient macros to be used
> in GT code in order to get/put runtime PM references and for
> checking them.
> 
> Add descriptions based on the ones at intel_wakeref.h and
> intel_runtime_pm.c.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>

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

> ---
> 
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v3 00/37] at: https://lore.kernel.org/all/cover.1662708705.git.mchehab@kernel.org/
> 
>  Documentation/gpu/i915.rst            |  2 ++
>  drivers/gpu/drm/i915/gt/intel_gt_pm.h | 51 +++++++++++++++++++++++++++
>  2 files changed, 53 insertions(+)
> 
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 7f5cd01ed398..59c532fe0332 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -446,6 +446,8 @@ Graphics Translation Tables
>  Other GT functionality
>  ----------------------
>  
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_pm.h
> +
>  .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_context.h
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gsc.h
> diff --git a/drivers/gpu/drm/i915/gt/intel_gt_pm.h b/drivers/gpu/drm/i915/gt/intel_gt_pm.h
> index 6c9a46452364..7847e15d102e 100644
> --- a/drivers/gpu/drm/i915/gt/intel_gt_pm.h
> +++ b/drivers/gpu/drm/i915/gt/intel_gt_pm.h
> @@ -11,21 +11,57 @@
>  #include "intel_gt_types.h"
>  #include "intel_wakeref.h"
>  
> +/**
> + * intel_gt_pm_is_awake: Query whether the runtime PM is awake held
> + *
> + * @gt: pointer to the graphics engine
> + *
> + * Returns: true if a runtime pm reference is currently held and the GT is
> + * awake.
> + */
>  static inline bool intel_gt_pm_is_awake(const struct intel_gt *gt)
>  {
>  	return intel_wakeref_is_active(&gt->wakeref);
>  }
>  
> +/**
> + * intel_gt_pm_get: grab a runtime PM reference ensuring that GT is powered up
> + * @gt: pointer to the graphics engine
> + *
> + * Any runtime pm reference obtained by this function must have a symmetric
> + * call to intel_gt_pm_put() to release the reference again.
> + *
> + * Note that this is allowed to fail, in which case the runtime-pm wakeref
> + * will be released and the acquisition unwound.
> + */
>  static inline void intel_gt_pm_get(struct intel_gt *gt)
>  {
>  	intel_wakeref_get(&gt->wakeref);
>  }
>  
> +/**
> + * __intel_gt_pm_get: Acquire the runtime PM reference again
> + * @gt: pointer to the graphics engine which contains the wakeref
> + *
> + * Increment the PM reference counter, only valid if it is already held by
> + * the caller.
> + *
> + * See intel_gt_pm_get().
> + */
>  static inline void __intel_gt_pm_get(struct intel_gt *gt)
>  {
>  	__intel_wakeref_get(&gt->wakeref);
>  }
>  
> +/**
> + * intel_gt_pm_get_if_awake: Acquire the runtime PM reference if active
> + * @gt: pointer to the graphics engine which contains the PM reference
> + *
> + * Acquire a hold on the PM reference, but only if the GT is already
> + * active.
> + *
> + * Returns: true if the wakeref was acquired, false otherwise.
> + */
>  static inline bool intel_gt_pm_get_if_awake(struct intel_gt *gt)
>  {
>  	return intel_wakeref_get_if_active(&gt->wakeref);
> @@ -36,6 +72,14 @@ static inline void intel_gt_pm_might_get(struct intel_gt *gt)
>  	intel_wakeref_might_get(&gt->wakeref);
>  }
>  
> +/**
> + * intel_gt_pm_put: Release the runtime PM reference
> + * @gt: pointer to the graphics engine which contains the PM reference
> + *
> + * Release our hold on the runtime PM for GT.
> + *
> + * It might power down the GT right away if this is the last reference.
> + */
>  static inline void intel_gt_pm_put(struct intel_gt *gt)
>  {
>  	intel_wakeref_put(&gt->wakeref);
> @@ -51,6 +95,13 @@ static inline void intel_gt_pm_might_put(struct intel_gt *gt)
>  	intel_wakeref_might_put(&gt->wakeref);
>  }
>  
> +/**
> + * with_intel_gt_pm - get a GT reference ensuring that GT is powered up,
> + *	run some code and then put the reference away.
> + *
> + * @gt: pointer to the gt
> + * @tmp: pointer to a temporary wakeref.
> + */
>  #define with_intel_gt_pm(gt, tmp) \
>  	for (tmp = 1, intel_gt_pm_get(gt); tmp; \
>  	     intel_gt_pm_put(gt), tmp = 0)
> -- 
> 2.37.3
> 

Re: [PATCH v3 37/37] drm/i915: be consistent with kernel-doc function declaration

[Rodrigo Vivi]

On Fri, Sep 09, 2022 at 09:34:44AM +0200, Mauro Carvalho Chehab wrote:
> Currently, 91% of kernel-doc function declarations don't have
> parenthesis on it. Let's be consistent inside the driver by
> removing the parenthesis from the other ones.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>

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

> ---
> 
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v3 00/37] at: https://lore.kernel.org/all/cover.1662708705.git.mchehab@kernel.org/
> 
>  drivers/gpu/drm/i915/display/intel_atomic.c    |  2 +-
>  drivers/gpu/drm/i915/display/intel_audio.c     |  4 ++--
>  drivers/gpu/drm/i915/display/intel_crtc.c      |  4 ++--
>  drivers/gpu/drm/i915/display/intel_dmc.c       | 10 +++++-----
>  drivers/gpu/drm/i915/display/intel_dsb.c       | 10 +++++-----
>  drivers/gpu/drm/i915/display/intel_lpe_audio.c |  8 ++++----
>  drivers/gpu/drm/i915/gt/intel_engine_cs.c      | 10 +++++-----
>  drivers/gpu/drm/i915/gt/uc/intel_guc.c         | 10 +++++-----
>  drivers/gpu/drm/i915/gt/uc/intel_guc.h         |  2 +-
>  drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c     |  4 ++--
>  drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c      |  2 +-
>  drivers/gpu/drm/i915/gt/uc/intel_guc_slpc.c    |  8 ++++----
>  drivers/gpu/drm/i915/gt/uc/intel_huc.c         |  4 ++--
>  drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c      |  2 +-
>  drivers/gpu/drm/i915/gt/uc/intel_uc_fw.h       |  2 +-
>  drivers/gpu/drm/i915/i915_cmd_parser.c         |  8 ++++----
>  drivers/gpu/drm/i915/i915_reg_defs.h           | 12 ++++++------
>  drivers/gpu/drm/i915/intel_wopcm.c             |  4 ++--
>  18 files changed, 53 insertions(+), 53 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/display/intel_atomic.c b/drivers/gpu/drm/i915/display/intel_atomic.c
> index 18f0a5ae3bac..9b604a720ff0 100644
> --- a/drivers/gpu/drm/i915/display/intel_atomic.c
> +++ b/drivers/gpu/drm/i915/display/intel_atomic.c
> @@ -373,7 +373,7 @@ static void intel_atomic_setup_scaler(struct intel_crtc_scaler_state *scaler_sta
>  }
>  
>  /**
> - * intel_atomic_setup_scalers() - setup scalers for crtc per staged requests
> + * intel_atomic_setup_scalers - setup scalers for crtc per staged requests
>   * @dev_priv: i915 device
>   * @intel_crtc: intel crtc
>   * @crtc_state: incoming crtc_state to validate and setup scalers
> diff --git a/drivers/gpu/drm/i915/display/intel_audio.c b/drivers/gpu/drm/i915/display/intel_audio.c
> index aacbc6da84ef..667fe9a8ff8e 100644
> --- a/drivers/gpu/drm/i915/display/intel_audio.c
> +++ b/drivers/gpu/drm/i915/display/intel_audio.c
> @@ -1385,7 +1385,7 @@ static void i915_audio_component_cleanup(struct drm_i915_private *dev_priv)
>  }
>  
>  /**
> - * intel_audio_init() - Initialize the audio driver either using
> + * intel_audio_init - Initialize the audio driver either using
>   * component framework or using lpe audio bridge
>   * @dev_priv: the i915 drm device private data
>   *
> @@ -1397,7 +1397,7 @@ void intel_audio_init(struct drm_i915_private *dev_priv)
>  }
>  
>  /**
> - * intel_audio_deinit() - deinitialize the audio driver
> + * intel_audio_deinit - deinitialize the audio driver
>   * @dev_priv: the i915 drm device private data
>   *
>   */
> diff --git a/drivers/gpu/drm/i915/display/intel_crtc.c b/drivers/gpu/drm/i915/display/intel_crtc.c
> index 6792a9056f46..507d7aec7b1c 100644
> --- a/drivers/gpu/drm/i915/display/intel_crtc.c
> +++ b/drivers/gpu/drm/i915/display/intel_crtc.c
> @@ -463,7 +463,7 @@ static int intel_mode_vblank_start(const struct drm_display_mode *mode)
>  }
>  
>  /**
> - * intel_pipe_update_start() - start update of a set of display registers
> + * intel_pipe_update_start - start update of a set of display registers
>   * @new_crtc_state: the new crtc state
>   *
>   * Mark the start of an update to pipe registers that should be updated
> @@ -617,7 +617,7 @@ static void dbg_vblank_evade(struct intel_crtc *crtc, ktime_t end) {}
>  #endif
>  
>  /**
> - * intel_pipe_update_end() - end update of a set of display registers
> + * intel_pipe_update_end - end update of a set of display registers
>   * @new_crtc_state: the new crtc state
>   *
>   * Mark the end of an update started with intel_pipe_update_start(). This
> diff --git a/drivers/gpu/drm/i915/display/intel_dmc.c b/drivers/gpu/drm/i915/display/intel_dmc.c
> index e52ecc0738a6..2024884688f6 100644
> --- a/drivers/gpu/drm/i915/display/intel_dmc.c
> +++ b/drivers/gpu/drm/i915/display/intel_dmc.c
> @@ -408,7 +408,7 @@ static void pipedmc_clock_gating_wa(struct drm_i915_private *i915, bool enable)
>  }
>  
>  /**
> - * intel_dmc_load_program() - write the firmware from memory to register.
> + * intel_dmc_load_program - write the firmware from memory to register.
>   * @dev_priv: i915 drm device.
>   *
>   * DMC firmware is read from a .bin file and kept in internal memory one time.
> @@ -876,7 +876,7 @@ static void dmc_load_work_fn(struct work_struct *work)
>  }
>  
>  /**
> - * intel_dmc_ucode_init() - initialize the firmware loading.
> + * intel_dmc_ucode_init - initialize the firmware loading.
>   * @dev_priv: i915 drm device.
>   *
>   * This function is called at the time of loading the display driver to read
> @@ -973,7 +973,7 @@ void intel_dmc_ucode_init(struct drm_i915_private *dev_priv)
>  }
>  
>  /**
> - * intel_dmc_ucode_suspend() - prepare DMC firmware before system suspend
> + * intel_dmc_ucode_suspend - prepare DMC firmware before system suspend
>   * @dev_priv: i915 drm device
>   *
>   * Prepare the DMC firmware before entering system suspend. This includes
> @@ -993,7 +993,7 @@ void intel_dmc_ucode_suspend(struct drm_i915_private *dev_priv)
>  }
>  
>  /**
> - * intel_dmc_ucode_resume() - init DMC firmware during system resume
> + * intel_dmc_ucode_resume - init DMC firmware during system resume
>   * @dev_priv: i915 drm device
>   *
>   * Reinitialize the DMC firmware during system resume, reacquiring any
> @@ -1013,7 +1013,7 @@ void intel_dmc_ucode_resume(struct drm_i915_private *dev_priv)
>  }
>  
>  /**
> - * intel_dmc_ucode_fini() - unload the DMC firmware.
> + * intel_dmc_ucode_fini - unload the DMC firmware.
>   * @dev_priv: i915 drm device.
>   *
>   * Firmmware unloading includes freeing the internal memory and reset the
> diff --git a/drivers/gpu/drm/i915/display/intel_dsb.c b/drivers/gpu/drm/i915/display/intel_dsb.c
> index c4affcb216fd..2ce406f62d40 100644
> --- a/drivers/gpu/drm/i915/display/intel_dsb.c
> +++ b/drivers/gpu/drm/i915/display/intel_dsb.c
> @@ -80,7 +80,7 @@ static bool intel_dsb_disable_engine(struct drm_i915_private *i915,
>  }
>  
>  /**
> - * intel_dsb_indexed_reg_write() -Write to the DSB context for auto
> + * intel_dsb_indexed_reg_write -Write to the DSB context for auto
>   * increment register.
>   * @crtc_state: intel_crtc_state structure
>   * @reg: register address.
> @@ -158,7 +158,7 @@ void intel_dsb_indexed_reg_write(const struct intel_crtc_state *crtc_state,
>  }
>  
>  /**
> - * intel_dsb_reg_write() -Write to the DSB context for normal
> + * intel_dsb_reg_write -Write to the DSB context for normal
>   * register.
>   * @crtc_state: intel_crtc_state structure
>   * @reg: register address.
> @@ -197,7 +197,7 @@ void intel_dsb_reg_write(const struct intel_crtc_state *crtc_state,
>  }
>  
>  /**
> - * intel_dsb_commit() - Trigger workload execution of DSB.
> + * intel_dsb_commit - Trigger workload execution of DSB.
>   * @crtc_state: intel_crtc_state structure
>   *
>   * This function is used to do actual write to hardware using DSB.
> @@ -254,7 +254,7 @@ void intel_dsb_commit(const struct intel_crtc_state *crtc_state)
>  }
>  
>  /**
> - * intel_dsb_prepare() - Allocate, pin and map the DSB command buffer.
> + * intel_dsb_prepare - Allocate, pin and map the DSB command buffer.
>   * @crtc_state: intel_crtc_state structure to prepare associated dsb instance.
>   *
>   * This function prepare the command buffer which is used to store dsb
> @@ -316,7 +316,7 @@ void intel_dsb_prepare(struct intel_crtc_state *crtc_state)
>  }
>  
>  /**
> - * intel_dsb_cleanup() - To cleanup DSB context.
> + * intel_dsb_cleanup - To cleanup DSB context.
>   * @crtc_state: intel_crtc_state structure to cleanup associated dsb instance.
>   *
>   * This function cleanup the DSB context by unpinning and releasing
> diff --git a/drivers/gpu/drm/i915/display/intel_lpe_audio.c b/drivers/gpu/drm/i915/display/intel_lpe_audio.c
> index dca6003ccac8..078a14e991a0 100644
> --- a/drivers/gpu/drm/i915/display/intel_lpe_audio.c
> +++ b/drivers/gpu/drm/i915/display/intel_lpe_audio.c
> @@ -250,7 +250,7 @@ static int lpe_audio_setup(struct drm_i915_private *dev_priv)
>  }
>  
>  /**
> - * intel_lpe_audio_irq_handler() - forwards the LPE audio irq
> + * intel_lpe_audio_irq_handler - forwards the LPE audio irq
>   * @dev_priv: the i915 drm device private data
>   *
>   * the LPE Audio irq is forwarded to the irq handler registered by LPE audio
> @@ -270,7 +270,7 @@ void intel_lpe_audio_irq_handler(struct drm_i915_private *dev_priv)
>  }
>  
>  /**
> - * intel_lpe_audio_init() - detect and setup the bridge between HDMI LPE Audio
> + * intel_lpe_audio_init - detect and setup the bridge between HDMI LPE Audio
>   * driver and i915
>   * @dev_priv: the i915 drm device private data
>   *
> @@ -291,7 +291,7 @@ int intel_lpe_audio_init(struct drm_i915_private *dev_priv)
>  }
>  
>  /**
> - * intel_lpe_audio_teardown() - destroy the bridge between HDMI LPE
> + * intel_lpe_audio_teardown - destroy the bridge between HDMI LPE
>   * audio driver and i915
>   * @dev_priv: the i915 drm device private data
>   *
> @@ -311,7 +311,7 @@ void intel_lpe_audio_teardown(struct drm_i915_private *dev_priv)
>  }
>  
>  /**
> - * intel_lpe_audio_notify() - notify lpe audio event
> + * intel_lpe_audio_notify - notify lpe audio event
>   * audio driver and i915
>   * @dev_priv: the i915 drm device private data
>   * @pipe: pipe
> diff --git a/drivers/gpu/drm/i915/gt/intel_engine_cs.c b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> index da9cd41c45f1..0ac813422809 100644
> --- a/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> +++ b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> @@ -247,7 +247,7 @@ static const struct engine_info intel_engines[] = {
>  };
>  
>  /**
> - * intel_engine_context_size() - return the size of the context for an engine
> + * intel_engine_context_size - return the size of the context for an engine
>   * @gt: the gt
>   * @class: engine class
>   *
> @@ -576,7 +576,7 @@ static void intel_setup_engine_capabilities(struct intel_gt *gt)
>  }
>  
>  /**
> - * intel_engines_release() - free the resources allocated for Command Streamers
> + * intel_engines_release - free the resources allocated for Command Streamers
>   * @gt: pointer to struct intel_gt
>   */
>  void intel_engines_release(struct intel_gt *gt)
> @@ -846,7 +846,7 @@ static void setup_logical_ids(struct intel_gt *gt, u8 *logical_ids, u8 class)
>  }
>  
>  /**
> - * intel_engines_init_mmio() - allocate and prepare the Engine Command Streamers
> + * intel_engines_init_mmio - allocate and prepare the Engine Command Streamers
>   * @gt: pointer to struct intel_gt
>   *
>   * Return: non-zero if the initialization failed.
> @@ -1631,7 +1631,7 @@ void __intel_engine_flush_submission(struct intel_engine_cs *engine, bool sync)
>  }
>  
>  /**
> - * intel_engine_is_idle() - Report if the engine has finished process all work
> + * intel_engine_is_idle - Report if the engine has finished process all work
>   * @engine: the intel_engine_cs
>   *
>   * Return true if there are no requests pending, nothing left to be submitted
> @@ -2203,7 +2203,7 @@ void intel_engine_dump(struct intel_engine_cs *engine,
>  }
>  
>  /**
> - * intel_engine_get_busy_time() - Return current accumulated engine busyness
> + * intel_engine_get_busy_time - Return current accumulated engine busyness
>   * @engine: engine to report on
>   * @now: monotonic timestamp of sampling
>   *
> diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc.c b/drivers/gpu/drm/i915/gt/uc/intel_guc.c
> index 24451d000a6a..d969005a857c 100644
> --- a/drivers/gpu/drm/i915/gt/uc/intel_guc.c
> +++ b/drivers/gpu/drm/i915/gt/uc/intel_guc.c
> @@ -599,7 +599,7 @@ int intel_guc_to_host_process_recv_msg(struct intel_guc *guc,
>  }
>  
>  /**
> - * intel_guc_auth_huc() - Send action to GuC to authenticate HuC ucode
> + * intel_guc_auth_huc - Send action to GuC to authenticate HuC ucode
>   * @guc: intel_guc structure
>   * @rsa_offset: rsa offset w.r.t ggtt base of huc vma
>   *
> @@ -620,7 +620,7 @@ int intel_guc_auth_huc(struct intel_guc *guc, u32 rsa_offset)
>  }
>  
>  /**
> - * intel_guc_suspend() - notify GuC entering suspend state
> + * intel_guc_suspend - notify GuC entering suspend state
>   * @guc:	the guc
>   */
>  int intel_guc_suspend(struct intel_guc *guc)
> @@ -657,7 +657,7 @@ int intel_guc_suspend(struct intel_guc *guc)
>  }
>  
>  /**
> - * intel_guc_resume() - notify GuC resuming from suspend state
> + * intel_guc_resume - notify GuC resuming from suspend state
>   * @guc:	the guc
>   */
>  int intel_guc_resume(struct intel_guc *guc)
> @@ -706,7 +706,7 @@ int intel_guc_resume(struct intel_guc *guc)
>   */
>  
>  /**
> - * intel_guc_allocate_vma() - Allocate a GGTT VMA for GuC usage
> + * intel_guc_allocate_vma - Allocate a GGTT VMA for GuC usage
>   * @guc:	the guc
>   * @size:	size of area to allocate (both virtual space and memory)
>   *
> @@ -756,7 +756,7 @@ struct i915_vma *intel_guc_allocate_vma(struct intel_guc *guc, u32 size)
>  }
>  
>  /**
> - * intel_guc_allocate_and_map_vma() - Allocate and map VMA for GuC usage
> + * intel_guc_allocate_and_map_vma - Allocate and map VMA for GuC usage
>   * @guc:	the guc
>   * @size:	size of area to allocate (both virtual space and memory)
>   * @out_vma:	return variable for the allocated vma pointer
> diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc.h b/drivers/gpu/drm/i915/gt/uc/intel_guc.h
> index 804133df1ac9..04b0cecf12bd 100644
> --- a/drivers/gpu/drm/i915/gt/uc/intel_guc.h
> +++ b/drivers/gpu/drm/i915/gt/uc/intel_guc.h
> @@ -325,7 +325,7 @@ static inline void intel_guc_to_host_event_handler(struct intel_guc *guc)
>  #define GUC_GGTT_TOP	0xFEE00000
>  
>  /**
> - * intel_guc_ggtt_offset() - Get and validate the GGTT offset of @vma
> + * intel_guc_ggtt_offset - Get and validate the GGTT offset of @vma
>   * @guc: intel_guc structure.
>   * @vma: i915 graphics virtual memory area.
>   *
> diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c b/drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c
> index 74cbe8eaf531..77204382cc44 100644
> --- a/drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c
> +++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c
> @@ -786,7 +786,7 @@ static void __guc_ads_init(struct intel_guc *guc)
>  }
>  
>  /**
> - * intel_guc_ads_create() - allocates and initializes GuC ADS.
> + * intel_guc_ads_create - allocates and initializes GuC ADS.
>   * @guc: intel_guc struct
>   *
>   * GuC needs memory block (Additional Data Struct), where it will store
> @@ -871,7 +871,7 @@ static void guc_ads_private_data_reset(struct intel_guc *guc)
>  }
>  
>  /**
> - * intel_guc_ads_reset() - prepares GuC Additional Data Struct for reuse
> + * intel_guc_ads_reset - prepares GuC Additional Data Struct for reuse
>   * @guc: intel_guc struct
>   *
>   * GuC stores some data in ADS, which might be stale after a reset.
> diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c b/drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c
> index a0372735cddb..bcdc37e6d9c9 100644
> --- a/drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c
> +++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c
> @@ -151,7 +151,7 @@ static int guc_wait_ucode(struct intel_uncore *uncore)
>  }
>  
>  /**
> - * intel_guc_fw_upload() - load GuC uCode to device
> + * intel_guc_fw_upload - load GuC uCode to device
>   * @guc: intel_guc structure
>   *
>   * Called from intel_uc_init_hw() during driver load, resume from sleep and
> diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc_slpc.c b/drivers/gpu/drm/i915/gt/uc/intel_guc_slpc.c
> index fdd895f73f9f..288db5ada139 100644
> --- a/drivers/gpu/drm/i915/gt/uc/intel_guc_slpc.c
> +++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_slpc.c
> @@ -381,7 +381,7 @@ static void slpc_shared_data_reset(struct slpc_shared_data *data)
>  }
>  
>  /**
> - * intel_guc_slpc_set_max_freq() - Set max frequency limit for SLPC.
> + * intel_guc_slpc_set_max_freq - Set max frequency limit for SLPC.
>   * @slpc: pointer to intel_guc_slpc.
>   * @val: frequency (MHz)
>   *
> @@ -418,7 +418,7 @@ int intel_guc_slpc_set_max_freq(struct intel_guc_slpc *slpc, u32 val)
>  }
>  
>  /**
> - * intel_guc_slpc_get_max_freq() - Get max frequency limit for SLPC.
> + * intel_guc_slpc_get_max_freq - Get max frequency limit for SLPC.
>   * @slpc: pointer to intel_guc_slpc.
>   * @val: pointer to val which will hold max frequency (MHz)
>   *
> @@ -445,7 +445,7 @@ int intel_guc_slpc_get_max_freq(struct intel_guc_slpc *slpc, u32 *val)
>  }
>  
>  /**
> - * intel_guc_slpc_set_min_freq() - Set min frequency limit for SLPC.
> + * intel_guc_slpc_set_min_freq - Set min frequency limit for SLPC.
>   * @slpc: pointer to intel_guc_slpc.
>   * @val: frequency (MHz)
>   *
> @@ -498,7 +498,7 @@ int intel_guc_slpc_set_min_freq(struct intel_guc_slpc *slpc, u32 val)
>  }
>  
>  /**
> - * intel_guc_slpc_get_min_freq() - Get min frequency limit for SLPC.
> + * intel_guc_slpc_get_min_freq - Get min frequency limit for SLPC.
>   * @slpc: pointer to intel_guc_slpc.
>   * @val: pointer to val which will hold min frequency (MHz)
>   *
> diff --git a/drivers/gpu/drm/i915/gt/uc/intel_huc.c b/drivers/gpu/drm/i915/gt/uc/intel_huc.c
> index 3bb8838e325a..127f7b952646 100644
> --- a/drivers/gpu/drm/i915/gt/uc/intel_huc.c
> +++ b/drivers/gpu/drm/i915/gt/uc/intel_huc.c
> @@ -126,7 +126,7 @@ void intel_huc_fini(struct intel_huc *huc)
>  }
>  
>  /**
> - * intel_huc_auth() - Authenticate HuC uCode
> + * intel_huc_auth - Authenticate HuC uCode
>   * @huc: intel_huc structure
>   *
>   * Called after HuC and GuC firmware loading during intel_uc_init_hw().
> @@ -194,7 +194,7 @@ static bool huc_is_authenticated(struct intel_huc *huc)
>  }
>  
>  /**
> - * intel_huc_check_status() - check HuC status
> + * intel_huc_check_status - check HuC status
>   * @huc: intel_huc structure
>   *
>   * This function reads status register to verify if HuC
> diff --git a/drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c b/drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c
> index 9d6ab1e01639..1fb05b45a8d2 100644
> --- a/drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c
> +++ b/drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c
> @@ -8,7 +8,7 @@
>  #include "i915_drv.h"
>  
>  /**
> - * intel_huc_fw_upload() - load HuC uCode to device via DMA transfer
> + * intel_huc_fw_upload - load HuC uCode to device via DMA transfer
>   * @huc: intel_huc structure
>   *
>   * Called from intel_uc_init_hw() during driver load, resume from sleep and
> diff --git a/drivers/gpu/drm/i915/gt/uc/intel_uc_fw.h b/drivers/gpu/drm/i915/gt/uc/intel_uc_fw.h
> index cb586f7df270..b14c82e17a6c 100644
> --- a/drivers/gpu/drm/i915/gt/uc/intel_uc_fw.h
> +++ b/drivers/gpu/drm/i915/gt/uc/intel_uc_fw.h
> @@ -250,7 +250,7 @@ static inline u32 __intel_uc_fw_get_upload_size(struct intel_uc_fw *uc_fw)
>  }
>  
>  /**
> - * intel_uc_fw_get_upload_size() - Get size of firmware needed to be uploaded.
> + * intel_uc_fw_get_upload_size - Get size of firmware needed to be uploaded.
>   * @uc_fw: uC firmware.
>   *
>   * Get the size of the firmware and header that will be uploaded to WOPCM.
> diff --git a/drivers/gpu/drm/i915/i915_cmd_parser.c b/drivers/gpu/drm/i915/i915_cmd_parser.c
> index f93e6122f247..1929aff97fee 100644
> --- a/drivers/gpu/drm/i915/i915_cmd_parser.c
> +++ b/drivers/gpu/drm/i915/i915_cmd_parser.c
> @@ -945,7 +945,7 @@ static void fini_hash_table(struct intel_engine_cs *engine)
>  }
>  
>  /**
> - * intel_engine_init_cmd_parser() - set cmd parser related fields for an engine
> + * intel_engine_init_cmd_parser - set cmd parser related fields for an engine
>   * @engine: the engine to initialize
>   *
>   * Optionally initializes fields related to batch buffer command parsing in the
> @@ -1059,7 +1059,7 @@ int intel_engine_init_cmd_parser(struct intel_engine_cs *engine)
>  }
>  
>  /**
> - * intel_engine_cleanup_cmd_parser() - clean up cmd parser related fields
> + * intel_engine_cleanup_cmd_parser - clean up cmd parser related fields
>   * @engine: the engine to clean up
>   *
>   * Releases any resources related to command parsing that may have been
> @@ -1422,7 +1422,7 @@ static unsigned long *alloc_whitelist(u32 batch_length)
>  #define LENGTH_BIAS 2
>  
>  /**
> - * intel_engine_cmd_parser() - parse a batch buffer for privilege violations
> + * intel_engine_cmd_parser - parse a batch buffer for privilege violations
>   * @engine: the engine on which the batch is to execute
>   * @batch: the batch buffer in question
>   * @batch_offset: byte offset in the batch at which execution starts
> @@ -1578,7 +1578,7 @@ int intel_engine_cmd_parser(struct intel_engine_cs *engine,
>  }
>  
>  /**
> - * i915_cmd_parser_get_version() - get the cmd parser version number
> + * i915_cmd_parser_get_version - get the cmd parser version number
>   * @dev_priv: i915 device private
>   *
>   * The cmd parser maintains a simple increasing integer version number suitable
> diff --git a/drivers/gpu/drm/i915/i915_reg_defs.h b/drivers/gpu/drm/i915/i915_reg_defs.h
> index 8f486f77609f..ce859aedfd01 100644
> --- a/drivers/gpu/drm/i915/i915_reg_defs.h
> +++ b/drivers/gpu/drm/i915/i915_reg_defs.h
> @@ -10,7 +10,7 @@
>  #include <linux/bits.h>
>  
>  /**
> - * REG_BIT() - Prepare a u32 bit value
> + * REG_BIT - Prepare a u32 bit value
>   * @__n: 0-based bit number
>   *
>   * Local wrapper for BIT() to force u32, with compile time checks.
> @@ -23,7 +23,7 @@
>  				 ((__n) < 0 || (__n) > 31))))
>  
>  /**
> - * REG_GENMASK() - Prepare a continuous u32 bitmask
> + * REG_GENMASK - Prepare a continuous u32 bitmask
>   * @__high: 0-based high bit
>   * @__low: 0-based low bit
>   *
> @@ -38,7 +38,7 @@
>  				 ((__low) < 0 || (__high) > 31 || (__low) > (__high)))))
>  
>  /**
> - * REG_GENMASK64() - Prepare a continuous u64 bitmask
> + * REG_GENMASK64 - Prepare a continuous u64 bitmask
>   * @__high: 0-based high bit
>   * @__low: 0-based low bit
>   *
> @@ -58,7 +58,7 @@
>  #define IS_POWER_OF_2(__x)		((__x) && (((__x) & ((__x) - 1)) == 0))
>  
>  /**
> - * REG_FIELD_PREP() - Prepare a u32 bitfield value
> + * REG_FIELD_PREP - Prepare a u32 bitfield value
>   * @__mask: shifted mask defining the field's length and position
>   * @__val: value to put in the field
>   *
> @@ -75,7 +75,7 @@
>  	       BUILD_BUG_ON_ZERO(__builtin_choose_expr(__is_constexpr(__val), (~((__mask) >> __bf_shf(__mask)) & (__val)), 0))))
>  
>  /**
> - * REG_FIELD_GET() - Extract a u32 bitfield value
> + * REG_FIELD_GET - Extract a u32 bitfield value
>   * @__mask: shifted mask defining the field's length and position
>   * @__val: value to extract the bitfield value from
>   *
> @@ -87,7 +87,7 @@
>  #define REG_FIELD_GET(__mask, __val)	((u32)FIELD_GET(__mask, __val))
>  
>  /**
> - * REG_FIELD_GET64() - Extract a u64 bitfield value
> + * REG_FIELD_GET64 - Extract a u64 bitfield value
>   * @__mask: shifted mask defining the field's length and position
>   * @__val: value to extract the bitfield value from
>   *
> diff --git a/drivers/gpu/drm/i915/intel_wopcm.c b/drivers/gpu/drm/i915/intel_wopcm.c
> index 322fb9eeb880..c66b3c173ed6 100644
> --- a/drivers/gpu/drm/i915/intel_wopcm.c
> +++ b/drivers/gpu/drm/i915/intel_wopcm.c
> @@ -70,7 +70,7 @@ static inline struct drm_i915_private *wopcm_to_i915(struct intel_wopcm *wopcm)
>  }
>  
>  /**
> - * intel_wopcm_init_early() - Early initialization of the WOPCM.
> + * intel_wopcm_init_early - Early initialization of the WOPCM.
>   * @wopcm: pointer to intel_wopcm.
>   *
>   * Setup the size of WOPCM which will be used by later on WOPCM partitioning.
> @@ -217,7 +217,7 @@ static bool __wopcm_regs_writable(struct intel_uncore *uncore)
>  }
>  
>  /**
> - * intel_wopcm_init() - Initialize the WOPCM structure.
> + * intel_wopcm_init - Initialize the WOPCM structure.
>   * @wopcm: pointer to intel_wopcm.
>   *
>   * This function will partition WOPCM space based on GuC and HuC firmware sizes
> -- 
> 2.37.3
> 

Re: [PATCH v3 17/37] drm/i915: i915_gem_wait.c: fix a kernel-doc markup

[Andi Shyti]

Hi Mauro,

On Fri, Sep 09, 2022 at 09:34:24AM +0200, Mauro Carvalho Chehab wrote:
> The return codes for i915_gem_wait_ioctl() have identation issues,
> and will be displayed on a very confusing way. Use lists to improve
> its output.
> 
> Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>

Reviewed-by: Andi Shyti <andi.shyti@linux.intel.com>

Andi

> ---
> 
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v3 00/37] at: https://lore.kernel.org/all/cover.1662708705.git.mchehab@kernel.org/
> 
>  drivers/gpu/drm/i915/gem/i915_gem_wait.c | 24 +++++++++++++-----------
>  1 file changed, 13 insertions(+), 11 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/gem/i915_gem_wait.c b/drivers/gpu/drm/i915/gem/i915_gem_wait.c
> index 4a33ad2d122b..1fd5cff552ed 100644
> --- a/drivers/gpu/drm/i915/gem/i915_gem_wait.c
> +++ b/drivers/gpu/drm/i915/gem/i915_gem_wait.c
> @@ -210,23 +210,25 @@ static unsigned long to_wait_timeout(s64 timeout_ns)
>   * @data: ioctl data blob
>   * @file: drm file pointer
>   *
> - * Returns 0 if successful, else an error is returned with the remaining time in
> - * the timeout parameter.
> - *  -ETIME: object is still busy after timeout
> - *  -ERESTARTSYS: signal interrupted the wait
> - *  -ENONENT: object doesn't exist
> - * Also possible, but rare:
> - *  -EAGAIN: incomplete, restart syscall
> - *  -ENOMEM: damn
> - *  -ENODEV: Internal IRQ fail
> - *  -E?: The add request failed
> - *
>   * The wait ioctl with a timeout of 0 reimplements the busy ioctl. With any
>   * non-zero timeout parameter the wait ioctl will wait for the given number of
>   * nanoseconds on an object becoming unbusy. Since the wait itself does so
>   * without holding struct_mutex the object may become re-busied before this
>   * function completes. A similar but shorter * race condition exists in the busy
>   * ioctl
> + *
> + * Returns:
> + * 0 if successful, else an error is returned with the remaining time in
> + * the timeout parameter.
> + * * -ETIME: object is still busy after timeout
> + * * -ERESTARTSYS: signal interrupted the wait
> + * * -ENONENT: object doesn't exist
> + *
> + * Also possible, but rare:
> + * * -EAGAIN: incomplete, restart syscall
> + * * -ENOMEM: damn
> + * * -ENODEV: Internal IRQ fail
> + * * -E?: The add request failed
>   */
>  int
>  i915_gem_wait_ioctl(struct drm_device *dev, void *data, struct drm_file *file)
> -- 
> 2.37.3

Re: [PATCH v3 19/37] drm/i915: stop using kernel-doc markups for something else

[Andi Shyti]

Hi Mauro,

On Fri, Sep 09, 2022 at 09:34:26AM +0200, Mauro Carvalho Chehab wrote:
> There are some occurrences of "/**" that aren't actually part of
> a kernel-doc markup. Replace them by "/*", in order to make easier
> to identify what i915 files contain kernel-doc markups.
> 
> Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>

nice cleanup!

Reviewed-by: Andi Shyti <andi.shyti@linux.intel.com>

Thanks,
Andi

> ---
> 
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v3 00/37] at: https://lore.kernel.org/all/cover.1662708705.git.mchehab@kernel.org/
> 
>  drivers/gpu/drm/i915/display/dvo_ch7017.c     | 26 +++----
>  drivers/gpu/drm/i915/display/dvo_ch7xxx.c     |  6 +-
>  .../drm/i915/display/intel_display_types.h    |  2 +-
>  drivers/gpu/drm/i915/display/intel_dvo_dev.h  |  6 +-
>  drivers/gpu/drm/i915/display/intel_sdvo.c     |  4 +-
>  drivers/gpu/drm/i915/display/intel_tv.c       |  2 +-
>  drivers/gpu/drm/i915/gt/intel_context_types.h | 69 +++++++++----------
>  drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h  |  2 +-
>  drivers/gpu/drm/i915/gt/intel_gt_types.h      | 12 ++--
>  drivers/gpu/drm/i915/gt/intel_reset_types.h   |  4 +-
>  .../gpu/drm/i915/gt/intel_timeline_types.h    |  6 +-
>  .../drm/i915/gt/shaders/clear_kernel/hsw.asm  |  4 +-
>  .../drm/i915/gt/shaders/clear_kernel/ivb.asm  |  4 +-
>  drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h | 10 +--
>  drivers/gpu/drm/i915/i915_drm_client.h        |  2 +-
>  drivers/gpu/drm/i915/i915_drv.h               | 24 +++----
>  drivers/gpu/drm/i915/i915_file_private.h      |  8 +--
>  drivers/gpu/drm/i915/i915_gpu_error.h         |  4 +-
>  drivers/gpu/drm/i915/i915_pmu.h               | 32 ++++-----
>  drivers/gpu/drm/i915/intel_uncore.h           |  4 +-
>  20 files changed, 115 insertions(+), 116 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/display/dvo_ch7017.c b/drivers/gpu/drm/i915/display/dvo_ch7017.c
> index 0589994dde11..581e29ab77e4 100644
> --- a/drivers/gpu/drm/i915/display/dvo_ch7017.c
> +++ b/drivers/gpu/drm/i915/display/dvo_ch7017.c
> @@ -55,13 +55,13 @@
>  #define CH7017_TEST_PATTERN		0x48
>  
>  #define CH7017_POWER_MANAGEMENT		0x49
> -/** Enables the TV output path. */
> +/* Enables the TV output path. */
>  #define CH7017_TV_EN			(1 << 0)
>  #define CH7017_DAC0_POWER_DOWN		(1 << 1)
>  #define CH7017_DAC1_POWER_DOWN		(1 << 2)
>  #define CH7017_DAC2_POWER_DOWN		(1 << 3)
>  #define CH7017_DAC3_POWER_DOWN		(1 << 4)
> -/** Powers down the TV out block, and DAC0-3 */
> +/* Powers down the TV out block, and DAC0-3 */
>  #define CH7017_TV_POWER_DOWN_EN		(1 << 5)
>  
>  #define CH7017_VERSION_ID		0x4a
> @@ -84,26 +84,26 @@
>  #define CH7017_UP_SCALER_HORIZONTAL_INC_1	0x5e
>  
>  #define CH7017_HORIZONTAL_ACTIVE_PIXEL_INPUT	0x5f
> -/**< Low bits of horizontal active pixel input */
> +/* Low bits of horizontal active pixel input */
>  
>  #define CH7017_ACTIVE_INPUT_LINE_OUTPUT	0x60
> -/** High bits of horizontal active pixel input */
> +/* High bits of horizontal active pixel input */
>  #define CH7017_LVDS_HAP_INPUT_MASK	(0x7 << 0)
> -/** High bits of vertical active line output */
> +/* High bits of vertical active line output */
>  #define CH7017_LVDS_VAL_HIGH_MASK	(0x7 << 3)
>  
>  #define CH7017_VERTICAL_ACTIVE_LINE_OUTPUT	0x61
> -/**< Low bits of vertical active line output */
> +/* Low bits of vertical active line output */
>  
>  #define CH7017_HORIZONTAL_ACTIVE_PIXEL_OUTPUT	0x62
> -/**< Low bits of horizontal active pixel output */
> +/* Low bits of horizontal active pixel output */
>  
>  #define CH7017_LVDS_POWER_DOWN		0x63
> -/** High bits of horizontal active pixel output */
> +/* High bits of horizontal active pixel output */
>  #define CH7017_LVDS_HAP_HIGH_MASK	(0x7 << 0)
> -/** Enables the LVDS power down state transition */
> +/* Enables the LVDS power down state transition */
>  #define CH7017_LVDS_POWER_DOWN_EN	(1 << 6)
> -/** Enables the LVDS upscaler */
> +/* Enables the LVDS upscaler */
>  #define CH7017_LVDS_UPSCALER_EN		(1 << 7)
>  #define CH7017_LVDS_POWER_DOWN_DEFAULT_RESERVED 0x08
>  
> @@ -116,9 +116,9 @@
>  #define CH7017_LVDS_ENCODING_2		0x65
>  
>  #define CH7017_LVDS_PLL_CONTROL		0x66
> -/** Enables the LVDS panel output path */
> +/* Enables the LVDS panel output path */
>  #define CH7017_LVDS_PANEN		(1 << 0)
> -/** Enables the LVDS panel backlight */
> +/* Enables the LVDS panel backlight */
>  #define CH7017_LVDS_BKLEN		(1 << 3)
>  
>  #define CH7017_POWER_SEQUENCING_T1	0x67
> @@ -197,7 +197,7 @@ static bool ch7017_write(struct intel_dvo_device *dvo, u8 addr, u8 val)
>  	return i2c_transfer(dvo->i2c_bus, &msg, 1) == 1;
>  }
>  
> -/** Probes for a CH7017 on the given bus and slave address. */
> +/* Probes for a CH7017 on the given bus and slave address. */
>  static bool ch7017_init(struct intel_dvo_device *dvo,
>  			struct i2c_adapter *adapter)
>  {
> diff --git a/drivers/gpu/drm/i915/display/dvo_ch7xxx.c b/drivers/gpu/drm/i915/display/dvo_ch7xxx.c
> index 54f58ba44b9f..1c1fe1f29675 100644
> --- a/drivers/gpu/drm/i915/display/dvo_ch7xxx.c
> +++ b/drivers/gpu/drm/i915/display/dvo_ch7xxx.c
> @@ -81,7 +81,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
>  #define CH7301_SYNC_RGB_YUV	(1<<0)
>  #define CH7301_SYNC_POL_DVI	(1<<5)
>  
> -/** @file
> +/*
>   * driver for the Chrontel 7xxx DVI chip over DVO.
>   */
>  
> @@ -132,7 +132,7 @@ static char *ch7xxx_get_did(u8 did)
>  	return NULL;
>  }
>  
> -/** Reads an 8 bit register */
> +/* Reads an 8 bit register */
>  static bool ch7xxx_readb(struct intel_dvo_device *dvo, int addr, u8 *ch)
>  {
>  	struct ch7xxx_priv *ch7xxx = dvo->dev_priv;
> @@ -170,7 +170,7 @@ static bool ch7xxx_readb(struct intel_dvo_device *dvo, int addr, u8 *ch)
>  	return false;
>  }
>  
> -/** Writes an 8 bit register */
> +/* Writes an 8 bit register */
>  static bool ch7xxx_writeb(struct intel_dvo_device *dvo, int addr, u8 ch)
>  {
>  	struct ch7xxx_priv *ch7xxx = dvo->dev_priv;
> diff --git a/drivers/gpu/drm/i915/display/intel_display_types.h b/drivers/gpu/drm/i915/display/intel_display_types.h
> index 3b7945aad22a..e46027d2a3c7 100644
> --- a/drivers/gpu/drm/i915/display/intel_display_types.h
> +++ b/drivers/gpu/drm/i915/display/intel_display_types.h
> @@ -1006,7 +1006,7 @@ struct intel_crtc_state {
>  		enum drm_scaling_filter scaling_filter;
>  	} hw;
>  
> -	/**
> +	/*
>  	 * quirks - bitfield with hw state readout quirks
>  	 *
>  	 * For various reasons the hw state readout code might not be able to
> diff --git a/drivers/gpu/drm/i915/display/intel_dvo_dev.h b/drivers/gpu/drm/i915/display/intel_dvo_dev.h
> index d96c3cc46e50..45d47209c327 100644
> --- a/drivers/gpu/drm/i915/display/intel_dvo_dev.h
> +++ b/drivers/gpu/drm/i915/display/intel_dvo_dev.h
> @@ -110,7 +110,7 @@ struct intel_dvo_dev_ops {
>  	 */
>  	bool (*get_hw_state)(struct intel_dvo_device *dev);
>  
> -	/**
> +	/*
>  	 * Query the device for the modes it provides.
>  	 *
>  	 * This function may also update MonInfo, mm_width, and mm_height.
> @@ -119,12 +119,12 @@ struct intel_dvo_dev_ops {
>  	 */
>  	struct drm_display_mode *(*get_modes)(struct intel_dvo_device *dvo);
>  
> -	/**
> +	/*
>  	 * Clean up driver-specific bits of the output
>  	 */
>  	void (*destroy) (struct intel_dvo_device *dvo);
>  
> -	/**
> +	/*
>  	 * Debugging hook to dump device registers to log file
>  	 */
>  	void (*dump_regs)(struct intel_dvo_device *dvo);
> diff --git a/drivers/gpu/drm/i915/display/intel_sdvo.c b/drivers/gpu/drm/i915/display/intel_sdvo.c
> index f5b744bef18f..87ff910dce05 100644
> --- a/drivers/gpu/drm/i915/display/intel_sdvo.c
> +++ b/drivers/gpu/drm/i915/display/intel_sdvo.c
> @@ -162,7 +162,7 @@ struct intel_sdvo_connector {
>  	/* this is to get the range of margin.*/
>  	u32 max_hscan, max_vscan;
>  
> -	/**
> +	/*
>  	 * This is set if we treat the device as HDMI, instead of DVI.
>  	 */
>  	bool is_hdmi;
> @@ -280,7 +280,7 @@ static bool intel_sdvo_read_byte(struct intel_sdvo *intel_sdvo, u8 addr, u8 *ch)
>  
>  #define SDVO_CMD_NAME_ENTRY(cmd_) { .cmd = SDVO_CMD_ ## cmd_, .name = #cmd_ }
>  
> -/** Mapping of command numbers to names, for debug output */
> +/* Mapping of command numbers to names, for debug output */
>  static const struct {
>  	u8 cmd;
>  	const char *name;
> diff --git a/drivers/gpu/drm/i915/display/intel_tv.c b/drivers/gpu/drm/i915/display/intel_tv.c
> index 9379f3463344..2507ab1ceda6 100644
> --- a/drivers/gpu/drm/i915/display/intel_tv.c
> +++ b/drivers/gpu/drm/i915/display/intel_tv.c
> @@ -26,7 +26,7 @@
>   *
>   */
>  
> -/** @file
> +/*
>   * Integrated TV-out support for the 915GM and 945GM.
>   */
>  
> diff --git a/drivers/gpu/drm/i915/gt/intel_context_types.h b/drivers/gpu/drm/i915/gt/intel_context_types.h
> index 04eacae1aca5..1be2aad18f2a 100644
> --- a/drivers/gpu/drm/i915/gt/intel_context_types.h
> +++ b/drivers/gpu/drm/i915/gt/intel_context_types.h
> @@ -128,7 +128,6 @@ struct intel_context {
>  	struct {
>  		u64 timeout_us;
>  	} watchdog;
> -
>  	u32 *lrc_reg_state;
>  	union {
>  		struct {
> @@ -139,7 +138,7 @@ struct intel_context {
>  	} lrc;
>  	u32 tag; /* cookie passed to HW to track this context on submission */
>  
> -	/** stats: Context GPU engine busyness tracking. */
> +	/* stats: Context GPU engine busyness tracking. */
>  	struct intel_context_stats {
>  		u64 active;
>  
> @@ -158,7 +157,7 @@ struct intel_context {
>  	atomic_t pin_count;
>  	struct mutex pin_mutex; /* guards pinning and associated on-gpuing */
>  
> -	/**
> +	/*
>  	 * active: Active tracker for the rq activity (inc. external) on this
>  	 * intel_context object.
>  	 */
> @@ -166,10 +165,10 @@ struct intel_context {
>  
>  	const struct intel_context_ops *ops;
>  
> -	/** sseu: Control eu/slice partitioning */
> +	/* sseu: Control eu/slice partitioning */
>  	struct intel_sseu sseu;
>  
> -	/**
> +	/*
>  	 * pinned_contexts_link: List link for the engine's pinned contexts.
>  	 * This is only used if this is a perma-pinned kernel context and
>  	 * the list is assumed to only be manipulated during driver load
> @@ -180,9 +179,9 @@ struct intel_context {
>  	u8 wa_bb_page; /* if set, page num reserved for context workarounds */
>  
>  	struct {
> -		/** @lock: protects everything in guc_state */
> +		/* @lock: protects everything in guc_state */
>  		spinlock_t lock;
> -		/**
> +		/*
>  		 * @sched_state: scheduling state of this context using GuC
>  		 * submission
>  		 */
> @@ -192,18 +191,18 @@ struct intel_context {
>  		 * being fenced until a GuC operation completes
>  		 */
>  		struct list_head fences;
> -		/**
> +		/*
>  		 * @blocked: fence used to signal when the blocking of a
>  		 * context's submissions is complete.
>  		 */
>  		struct i915_sw_fence blocked;
> -		/** @number_committed_requests: number of committed requests */
> +		/* @number_committed_requests: number of committed requests */
>  		int number_committed_requests;
> -		/** @requests: list of active requests on this context */
> +		/* @requests: list of active requests on this context */
>  		struct list_head requests;
> -		/** @prio: the context's current guc priority */
> +		/* @prio: the context's current guc priority */
>  		u8 prio;
> -		/**
> +		/*
>  		 * @prio_count: a counter of the number requests in flight in
>  		 * each priority bucket
>  		 */
> @@ -211,82 +210,82 @@ struct intel_context {
>  	} guc_state;
>  
>  	struct {
> -		/**
> +		/*
>  		 * @id: handle which is used to uniquely identify this context
>  		 * with the GuC, protected by guc->submission_state.lock
>  		 */
>  		u16 id;
> -		/**
> +		/*
>  		 * @ref: the number of references to the guc_id, when
>  		 * transitioning in and out of zero protected by
>  		 * guc->submission_state.lock
>  		 */
>  		atomic_t ref;
> -		/**
> +		/*
>  		 * @link: in guc->guc_id_list when the guc_id has no refs but is
>  		 * still valid, protected by guc->submission_state.lock
>  		 */
>  		struct list_head link;
>  	} guc_id;
>  
> -	/**
> +	/*
>  	 * @destroyed_link: link in guc->submission_state.destroyed_contexts, in
>  	 * list when context is pending to be destroyed (deregistered with the
>  	 * GuC), protected by guc->submission_state.lock
>  	 */
>  	struct list_head destroyed_link;
>  
> -	/** @parallel: sub-structure for parallel submission members */
> +	/* @parallel: sub-structure for parallel submission members */
>  	struct {
>  		union {
> -			/**
> +			/*
>  			 * @child_list: parent's list of children
>  			 * contexts, no protection as immutable after context
>  			 * creation
>  			 */
>  			struct list_head child_list;
> -			/**
> +			/*
>  			 * @child_link: child's link into parent's list of
>  			 * children
>  			 */
>  			struct list_head child_link;
>  		};
> -		/** @parent: pointer to parent if child */
> +		/* @parent: pointer to parent if child */
>  		struct intel_context *parent;
> -		/**
> +		/*
>  		 * @last_rq: last request submitted on a parallel context, used
>  		 * to insert submit fences between requests in the parallel
>  		 * context
>  		 */
>  		struct i915_request *last_rq;
> -		/**
> +		/*
>  		 * @fence_context: fence context composite fence when doing
>  		 * parallel submission
>  		 */
>  		u64 fence_context;
> -		/**
> +		/*
>  		 * @seqno: seqno for composite fence when doing parallel
>  		 * submission
>  		 */
>  		u32 seqno;
> -		/** @number_children: number of children if parent */
> +		/* @number_children: number of children if parent */
>  		u8 number_children;
> -		/** @child_index: index into child_list if child */
> +		/* @child_index: index into child_list if child */
>  		u8 child_index;
> -		/** @guc: GuC specific members for parallel submission */
> +		/* @guc: GuC specific members for parallel submission */
>  		struct {
> -			/** @wqi_head: cached head pointer in work queue */
> +			/* @wqi_head: cached head pointer in work queue */
>  			u16 wqi_head;
> -			/** @wqi_tail: cached tail pointer in work queue */
> +			/* @wqi_tail: cached tail pointer in work queue */
>  			u16 wqi_tail;
> -			/** @wq_head: pointer to the actual head in work queue */
> +			/* @wq_head: pointer to the actual head in work queue */
>  			u32 *wq_head;
> -			/** @wq_tail: pointer to the actual head in work queue */
> +			/* @wq_tail: pointer to the actual head in work queue */
>  			u32 *wq_tail;
> -			/** @wq_status: pointer to the status in work queue */
> +			/* @wq_status: pointer to the status in work queue */
>  			u32 *wq_status;
>  
> -			/**
> +			/*
>  			 * @parent_page: page in context state (ce->state) used
>  			 * by parent for work queue, process descriptor
>  			 */
> @@ -295,18 +294,18 @@ struct intel_context {
>  	} parallel;
>  
>  #ifdef CONFIG_DRM_I915_SELFTEST
> -	/**
> +	/*
>  	 * @drop_schedule_enable: Force drop of schedule enable G2H for selftest
>  	 */
>  	bool drop_schedule_enable;
>  
> -	/**
> +	/*
>  	 * @drop_schedule_disable: Force drop of schedule disable G2H for
>  	 * selftest
>  	 */
>  	bool drop_schedule_disable;
>  
> -	/**
> +	/*
>  	 * @drop_deregister: Force drop of deregister G2H for selftest
>  	 */
>  	bool drop_deregister;
> diff --git a/drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h b/drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h
> index 25340be5ecf0..230e846151a8 100644
> --- a/drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h
> +++ b/drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h
> @@ -26,7 +26,7 @@ struct i915_fence_reg {
>  	atomic_t pin_count;
>  	struct i915_active active;
>  	int id;
> -	/**
> +	/*
>  	 * Whether the tiling parameters for the currently
>  	 * associated fence register have changed. Note that
>  	 * for the purposes of tracking tiling changes we also
> diff --git a/drivers/gpu/drm/i915/gt/intel_gt_types.h b/drivers/gpu/drm/i915/gt/intel_gt_types.h
> index 4d56f7d5a3be..c66e3d803666 100644
> --- a/drivers/gpu/drm/i915/gt/intel_gt_types.h
> +++ b/drivers/gpu/drm/i915/gt/intel_gt_types.h
> @@ -114,7 +114,7 @@ struct intel_gt {
>  	} timelines;
>  
>  	struct intel_gt_requests {
> -		/**
> +		/*
>  		 * We leave the user IRQ off as much as possible,
>  		 * but this means that requests will finish and never
>  		 * be retired once the system goes idle. Set a timer to
> @@ -138,7 +138,7 @@ struct intel_gt {
>  	ktime_t last_init_time;
>  	struct intel_reset reset;
>  
> -	/**
> +	/*
>  	 * Is the GPU currently considered idle, or busy executing
>  	 * userspace requests? Whilst idle, we allow runtime power
>  	 * management to power down the hardware and display clocks.
> @@ -164,12 +164,12 @@ struct intel_gt {
>  	struct {
>  		bool active;
>  
> -		/**
> +		/*
>  		 * @lock: Lock protecting the below fields.
>  		 */
>  		seqcount_mutex_t lock;
>  
> -		/**
> +		/*
>  		 * @total: Total time this engine was busy.
>  		 *
>  		 * Accumulated time not counting the most recent block in cases
> @@ -177,7 +177,7 @@ struct intel_gt {
>  		 */
>  		ktime_t total;
>  
> -		/**
> +		/*
>  		 * @start: Timestamp of the last idle to active transition.
>  		 *
>  		 * Idle is defined as active == 0, active is active > 0.
> @@ -243,7 +243,7 @@ struct intel_gt {
>  
>  		unsigned long mslice_mask;
>  
> -		/** @hwconfig: hardware configuration data */
> +		/* @hwconfig: hardware configuration data */
>  		struct intel_hwconfig hwconfig;
>  	} info;
>  
> diff --git a/drivers/gpu/drm/i915/gt/intel_reset_types.h b/drivers/gpu/drm/i915/gt/intel_reset_types.h
> index 9312b29f5a97..4ef21186e6d5 100644
> --- a/drivers/gpu/drm/i915/gt/intel_reset_types.h
> +++ b/drivers/gpu/drm/i915/gt/intel_reset_types.h
> @@ -11,7 +11,7 @@
>  #include <linux/srcu.h>
>  
>  struct intel_reset {
> -	/**
> +	/*
>  	 * flags: Control various stages of the GPU reset
>  	 *
>  	 * #I915_RESET_BACKOFF - When we start a global reset, we need to
> @@ -49,7 +49,7 @@ struct intel_reset {
>  
>  	struct mutex mutex; /* serialises wedging/unwedging */
>  
> -	/**
> +	/*
>  	 * Waitqueue to signal when the reset has completed. Used by clients
>  	 * that wait for dev_priv->mm.wedged to settle.
>  	 */
> diff --git a/drivers/gpu/drm/i915/gt/intel_timeline_types.h b/drivers/gpu/drm/i915/gt/intel_timeline_types.h
> index 74e67dbf89c5..ae5f859d72c0 100644
> --- a/drivers/gpu/drm/i915/gt/intel_timeline_types.h
> +++ b/drivers/gpu/drm/i915/gt/intel_timeline_types.h
> @@ -50,7 +50,7 @@ struct intel_timeline {
>  
>  	bool has_initial_breadcrumb;
>  
> -	/**
> +	/*
>  	 * List of breadcrumbs associated with GPU requests currently
>  	 * outstanding.
>  	 */
> @@ -66,10 +66,10 @@ struct intel_timeline {
>  
>  	struct i915_active active;
>  
> -	/** A chain of completed timelines ready for early retirement. */
> +	/* A chain of completed timelines ready for early retirement. */
>  	struct intel_timeline *retire;
>  
> -	/**
> +	/*
>  	 * We track the most recent seqno that we wait on in every context so
>  	 * that we only have to emit a new await and dependency on a more
>  	 * recent sync point. As the contexts may be executed out-of-order, we
> diff --git a/drivers/gpu/drm/i915/gt/shaders/clear_kernel/hsw.asm b/drivers/gpu/drm/i915/gt/shaders/clear_kernel/hsw.asm
> index 5fdf384bb621..88d2dbbf981e 100644
> --- a/drivers/gpu/drm/i915/gt/shaders/clear_kernel/hsw.asm
> +++ b/drivers/gpu/drm/i915/gt/shaders/clear_kernel/hsw.asm
> @@ -14,7 +14,7 @@
>  /* Store designated "clear GRF" value */
>  mov(1)          f0.1<1>UW       g1.2<0,1,0>UW                   { align1 1N };
>  
> -/**
> +/*
>   * Curbe Format
>   *
>   * DW 1.0 - Block Offset to write Render Cache
> @@ -40,7 +40,7 @@ add(1)          g1.2<1>UD       g1.2<0,1,0>UD   0x00000001UD    { align1 1N }; /
>  cmp.z.f0.0(1)   null<1>UD       g1.3<0,1,0>UD   0x00000000UD    { align1 1N };
>  (+f0.0) jmpi(1) 352D                                            { align1 WE_all 1N };
>  
> -/**
> +/*
>   * State Register has info on where this thread is running
>   *	IVB: sr0.0 :: [15:13]: MBZ, 12: HSID (Half-Slice ID), [11:8]EUID, [2:0] ThreadSlotID
>   *	HSW: sr0.0 :: 15: MBZ, [14:13]: SliceID, 12: HSID (Half-Slice ID), [11:8]EUID, [2:0] ThreadSlotID
> diff --git a/drivers/gpu/drm/i915/gt/shaders/clear_kernel/ivb.asm b/drivers/gpu/drm/i915/gt/shaders/clear_kernel/ivb.asm
> index 97c7ac9e3854..4d7c5f1981ba 100644
> --- a/drivers/gpu/drm/i915/gt/shaders/clear_kernel/ivb.asm
> +++ b/drivers/gpu/drm/i915/gt/shaders/clear_kernel/ivb.asm
> @@ -14,7 +14,7 @@
>  /* Store designated "clear GRF" value */
>  mov(1)          f0.1<1>UW       g1.2<0,1,0>UW                   { align1 1N };
>  
> -/**
> +/*
>   * Curbe Format
>   *
>   * DW 1.0 - Block Offset to write Render Cache
> @@ -40,7 +40,7 @@ add(1)          g1.2<1>UD       g1.2<0,1,0>UD   0x00000001UD    { align1 1N }; /
>  cmp.z.f0.0(1)   null<1>UD       g1.3<0,1,0>UD   0x00000000UD    { align1 1N };
>  (+f0.0) jmpi(1) 44D                                             { align1 WE_all 1N };
>  
> -/**
> +/*
>   * State Register has info on where this thread is running
>   *	IVB: sr0.0 :: [15:13]: MBZ, 12: HSID (Half-Slice ID), [11:8]EUID, [2:0] ThreadSlotID
>   *	HSW: sr0.0 :: 15: MBZ, [14:13]: SliceID, 12: HSID (Half-Slice ID), [11:8]EUID, [2:0] ThreadSlotID
> 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 58f93226b1c1..d8a7659079f5 100644
> --- a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> +++ b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> @@ -168,12 +168,12 @@ struct __guc_capture_ads_cache {
>   * Internal context of the intel_guc_capture module.
>   */
>  struct intel_guc_state_capture {
> -	/**
> +	/*
>  	 * @reglists: static table of register lists used for error-capture state.
>  	 */
>  	const struct __guc_mmio_reg_descr_group *reglists;
>  
> -	/**
> +	/*
>  	 * @extlists: allocated table of steered register lists used for error-capture state.
>  	 *
>  	 * NOTE: steered registers have multiple instances depending on the HW configuration
> @@ -181,7 +181,7 @@ struct intel_guc_state_capture {
>  	 */
>  	struct __guc_mmio_reg_descr_group *extlists;
>  
> -	/**
> +	/*
>  	 * @ads_cache: cached register lists that is ADS format ready
>  	 */
>  	struct __guc_capture_ads_cache ads_cache[GUC_CAPTURE_LIST_INDEX_MAX]
> @@ -189,7 +189,7 @@ struct intel_guc_state_capture {
>  						[GUC_MAX_ENGINE_CLASSES];
>  	void *ads_null_cache;
>  
> -	/**
> +	/*
>  	 * @cachelist: Pool of pre-allocated nodes for error capture output
>  	 *
>  	 * We need this pool of pre-allocated nodes because we cannot
> @@ -204,7 +204,7 @@ struct intel_guc_state_capture {
>  #define PREALLOC_NODES_DEFAULT_NUMREGS 64
>  	int max_mmio_per_node;
>  
> -	/**
> +	/*
>  	 * @outlist: Pool of pre-allocated nodes for error capture output
>  	 *
>  	 * A linked list of parsed GuC error-capture output data before
> diff --git a/drivers/gpu/drm/i915/i915_drm_client.h b/drivers/gpu/drm/i915/i915_drm_client.h
> index 69496af996d9..c722e3c18694 100644
> --- a/drivers/gpu/drm/i915/i915_drm_client.h
> +++ b/drivers/gpu/drm/i915/i915_drm_client.h
> @@ -34,7 +34,7 @@ struct i915_drm_client {
>  
>  	struct i915_drm_clients *clients;
>  
> -	/**
> +	/*
>  	 * @past_runtime: Accumulation of pphwsp runtimes from closed contexts.
>  	 */
>  	atomic64_t past_runtime[I915_LAST_UABI_ENGINE_CLASS + 1];
> diff --git a/drivers/gpu/drm/i915/i915_drv.h b/drivers/gpu/drm/i915/i915_drv.h
> index 76aad81c014b..519e8e8ace45 100644
> --- a/drivers/gpu/drm/i915/i915_drv.h
> +++ b/drivers/gpu/drm/i915/i915_drv.h
> @@ -113,37 +113,37 @@ struct i915_gem_mm {
>  	 * support stolen.
>  	 */
>  	struct intel_memory_region *stolen_region;
> -	/** Memory allocator for GTT stolen memory */
> +	/* Memory allocator for GTT stolen memory */
>  	struct drm_mm stolen;
> -	/** Protects the usage of the GTT stolen memory allocator. This is
> +	/* Protects the usage of the GTT stolen memory allocator. This is
>  	 * always the inner lock when overlapping with struct_mutex. */
>  	struct mutex stolen_lock;
>  
>  	/* Protects bound_list/unbound_list and #drm_i915_gem_object.mm.link */
>  	spinlock_t obj_lock;
>  
> -	/**
> +	/*
>  	 * List of objects which are purgeable.
>  	 */
>  	struct list_head purge_list;
>  
> -	/**
> +	/*
>  	 * List of objects which have allocated pages and are shrinkable.
>  	 */
>  	struct list_head shrink_list;
>  
> -	/**
> +	/*
>  	 * List of objects which are pending destruction.
>  	 */
>  	struct llist_head free_list;
>  	struct work_struct free_work;
> -	/**
> +	/*
>  	 * Count of objects pending destructions. Used to skip needlessly
>  	 * waiting on an RCU barrier if no objects are waiting to be freed.
>  	 */
>  	atomic_t free_count;
>  
> -	/**
> +	/*
>  	 * tmpfs instance used for shmem backed objects
>  	 */
>  	struct vfsmount *gemfs;
> @@ -155,7 +155,7 @@ struct i915_gem_mm {
>  	struct shrinker shrinker;
>  
>  #ifdef CONFIG_MMU_NOTIFIER
> -	/**
> +	/*
>  	 * notifier_lock for mmu notifiers, memory may not be allocated
>  	 * while holding this lock.
>  	 */
> @@ -209,7 +209,7 @@ struct drm_i915_private {
>  	struct intel_runtime_info __runtime; /* Use RUNTIME_INFO() to access. */
>  	struct intel_driver_caps caps;
>  
> -	/**
> +	/*
>  	 * Data Stolen Memory - aka "i915 stolen memory" gives us the start and
>  	 * end of stolen which we can optionally use to create GEM objects
>  	 * backed by stolen memory. Note that stolen_usable_size tells us
> @@ -217,7 +217,7 @@ struct drm_i915_private {
>  	 * some portion of it is in fact reserved for use by hardware functions.
>  	 */
>  	struct resource dsm;
> -	/**
> +	/*
>  	 * Reseved portion of Data Stolen Memory
>  	 */
>  	struct resource dsm_reserved;
> @@ -258,7 +258,7 @@ struct drm_i915_private {
>  	struct mutex sb_lock;
>  	struct pm_qos_request sb_qos;
>  
> -	/** Cached value of IMR to avoid reads in updating the bitfield */
> +	/* Cached value of IMR to avoid reads in updating the bitfield */
>  	union {
>  		u32 irq_mask;
>  		u32 de_irq_mask[I915_MAX_PIPES];
> @@ -274,7 +274,7 @@ struct drm_i915_private {
>  	unsigned int hpll_freq;
>  	unsigned int czclk_freq;
>  
> -	/**
> +	/*
>  	 * wq - Driver workqueue for GEM.
>  	 *
>  	 * NOTE: Work items scheduled here are not allowed to grab any modeset
> diff --git a/drivers/gpu/drm/i915/i915_file_private.h b/drivers/gpu/drm/i915/i915_file_private.h
> index f42877869692..282e0c280224 100644
> --- a/drivers/gpu/drm/i915/i915_file_private.h
> +++ b/drivers/gpu/drm/i915/i915_file_private.h
> @@ -22,7 +22,7 @@ struct drm_i915_file_private {
>  		struct rcu_head rcu;
>  	};
>  
> -	/** @proto_context_lock: Guards all struct i915_gem_proto_context
> +	/* @proto_context_lock: Guards all struct i915_gem_proto_context
>  	 * operations
>  	 *
>  	 * This not only guards @proto_context_xa, but is always held
> @@ -33,7 +33,7 @@ struct drm_i915_file_private {
>  	 */
>  	struct mutex proto_context_lock;
>  
> -	/** @proto_context_xa: xarray of struct i915_gem_proto_context
> +	/* @proto_context_xa: xarray of struct i915_gem_proto_context
>  	 *
>  	 * Historically, the context uAPI allowed for two methods of
>  	 * setting context parameters: SET_CONTEXT_PARAM and
> @@ -77,7 +77,7 @@ struct drm_i915_file_private {
>  	 */
>  	struct xarray proto_context_xa;
>  
> -	/** @context_xa: xarray of fully created i915_gem_context
> +	/* @context_xa: xarray of fully created i915_gem_context
>  	 *
>  	 * Write access to this xarray is guarded by @proto_context_lock.
>  	 * Otherwise, writers may race with finalize_create_context_locked().
> @@ -101,7 +101,7 @@ struct drm_i915_file_private {
>  #define   I915_CLIENT_FAST_HANG_JIFFIES (60 * HZ)
>  #define I915_CLIENT_SCORE_CONTEXT_BAN   3
>  #define I915_CLIENT_SCORE_BANNED	9
> -	/** ban_score: Accumulated score of all ctx bans and fast hangs. */
> +	/* ban_score: Accumulated score of all ctx bans and fast hangs. */
>  	atomic_t ban_score;
>  	unsigned long hang_timestamp;
>  
> diff --git a/drivers/gpu/drm/i915/i915_gpu_error.h b/drivers/gpu/drm/i915/i915_gpu_error.h
> index efc75cc2ffdb..4e395a9e4c11 100644
> --- a/drivers/gpu/drm/i915/i915_gpu_error.h
> +++ b/drivers/gpu/drm/i915/i915_gpu_error.h
> @@ -224,10 +224,10 @@ struct i915_gpu_error {
>  
>  	atomic_t pending_fb_pin;
>  
> -	/** Number of times the device has been reset (global) */
> +	/* Number of times the device has been reset (global) */
>  	atomic_t reset_count;
>  
> -	/** Number of times an engine has been reset */
> +	/* Number of times an engine has been reset */
>  	atomic_t reset_engine_count[I915_NUM_ENGINES];
>  };
>  
> diff --git a/drivers/gpu/drm/i915/i915_pmu.h b/drivers/gpu/drm/i915/i915_pmu.h
> index c30f43319a78..9fdb50376995 100644
> --- a/drivers/gpu/drm/i915/i915_pmu.h
> +++ b/drivers/gpu/drm/i915/i915_pmu.h
> @@ -52,34 +52,34 @@ struct i915_pmu_sample {
>  };
>  
>  struct i915_pmu {
> -	/**
> +	/*
>  	 * @cpuhp: Struct used for CPU hotplug handling.
>  	 */
>  	struct {
>  		struct hlist_node node;
>  		unsigned int cpu;
>  	} cpuhp;
> -	/**
> +	/*
>  	 * @base: PMU base.
>  	 */
>  	struct pmu base;
> -	/**
> +	/*
>  	 * @closed: i915 is unregistering.
>  	 */
>  	bool closed;
> -	/**
> +	/*
>  	 * @name: Name as registered with perf core.
>  	 */
>  	const char *name;
> -	/**
> +	/*
>  	 * @lock: Lock protecting enable mask and ref count handling.
>  	 */
>  	spinlock_t lock;
> -	/**
> +	/*
>  	 * @timer: Timer for internal i915 PMU sampling.
>  	 */
>  	struct hrtimer timer;
> -	/**
> +	/*
>  	 * @enable: Bitmask of specific enabled events.
>  	 *
>  	 * For some events we need to track their state and do some internal
> @@ -92,14 +92,14 @@ struct i915_pmu {
>  	 */
>  	u32 enable;
>  
> -	/**
> +	/*
>  	 * @timer_last:
>  	 *
>  	 * Timestmap of the previous timer invocation.
>  	 */
>  	ktime_t timer_last;
>  
> -	/**
> +	/*
>  	 * @enable_count: Reference counts for the enabled events.
>  	 *
>  	 * Array indices are mapped in the same way as bits in the @enable field
> @@ -107,11 +107,11 @@ struct i915_pmu {
>  	 * are using the PMU API.
>  	 */
>  	unsigned int enable_count[I915_PMU_MASK_BITS];
> -	/**
> +	/*
>  	 * @timer_enabled: Should the internal sampling timer be running.
>  	 */
>  	bool timer_enabled;
> -	/**
> +	/*
>  	 * @sample: Current and previous (raw) counters for sampling events.
>  	 *
>  	 * These counters are updated from the i915 PMU sampling timer.
> @@ -120,11 +120,11 @@ struct i915_pmu {
>  	 * struct intel_engine_cs.
>  	 */
>  	struct i915_pmu_sample sample[__I915_NUM_PMU_SAMPLERS];
> -	/**
> +	/*
>  	 * @sleep_last: Last time GT parked for RC6 estimation.
>  	 */
>  	ktime_t sleep_last;
> -	/**
> +	/*
>  	 * @irq_count: Number of interrupts
>  	 *
>  	 * Intentionally unsigned long to avoid atomics or heuristics on 32bit.
> @@ -132,15 +132,15 @@ struct i915_pmu {
>  	 * occasional wraparound easily. It's 32bit after all.
>  	 */
>  	unsigned long irq_count;
> -	/**
> +	/*
>  	 * @events_attr_group: Device events attribute group.
>  	 */
>  	struct attribute_group events_attr_group;
> -	/**
> +	/*
>  	 * @i915_attr: Memory block holding device attributes.
>  	 */
>  	void *i915_attr;
> -	/**
> +	/*
>  	 * @pmu_attr: Memory block holding device attributes.
>  	 */
>  	void *pmu_attr;
> diff --git a/drivers/gpu/drm/i915/intel_uncore.h b/drivers/gpu/drm/i915/intel_uncore.h
> index b1fa912a65e7..5f896fbf3064 100644
> --- a/drivers/gpu/drm/i915/intel_uncore.h
> +++ b/drivers/gpu/drm/i915/intel_uncore.h
> @@ -39,7 +39,7 @@ struct intel_uncore;
>  struct intel_gt;
>  
>  struct intel_uncore_mmio_debug {
> -	spinlock_t lock; /** lock is also taken in irq contexts. */
> +	spinlock_t lock; /* lock is also taken in irq contexts. */
>  	int unclaimed_mmio_check;
>  	int saved_mmio_check;
>  	u32 suspend_count;
> @@ -133,7 +133,7 @@ struct intel_uncore {
>  	struct intel_gt *gt;
>  	struct intel_runtime_pm *rpm;
>  
> -	spinlock_t lock; /** lock is also taken in irq contexts. */
> +	spinlock_t lock; /* lock is also taken in irq contexts. */
>  
>  	unsigned int flags;
>  #define UNCORE_HAS_FORCEWAKE		BIT(0)
> -- 
> 2.37.3

Re: [PATCH v3 33/37] drm/i915 i915_gem_object_types.h: document struct i915_lut_handle

[Andi Shyti]

Hi Mauro,

On Fri, Sep 09, 2022 at 09:34:40AM +0200, Mauro Carvalho Chehab wrote:
> commit d1b48c1e7184 ("drm/i915: Replace execbuf vma ht with an idr")
> added a rbtree list to allow searching for obj/ctx.
> 
> Document it.
> 
> Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
> 
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v3 00/37] at: https://lore.kernel.org/all/cover.1662708705.git.mchehab@kernel.org/
> 
>  drivers/gpu/drm/i915/gem/i915_gem_object_types.h | 12 +++++++++---
>  1 file changed, 9 insertions(+), 3 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/gem/i915_gem_object_types.h b/drivers/gpu/drm/i915/gem/i915_gem_object_types.h
> index 9f6b14ec189a..35746cf268ea 100644
> --- a/drivers/gpu/drm/i915/gem/i915_gem_object_types.h
> +++ b/drivers/gpu/drm/i915/gem/i915_gem_object_types.h
> @@ -21,9 +21,15 @@ struct drm_i915_gem_object;
>  struct intel_fronbuffer;
>  struct intel_memory_region;
>  
> -/*
> - * struct i915_lut_handle tracks the fast lookups from handle to vma used
> - * for execbuf. Although we use a radixtree for that mapping, in order to
> +/**
> + * struct i915_lut_handle - tracks the fast lookups from handle to vma used
> + * for execbuf.
> + *

just to be picky: do we or don't we want this extra space here? I
think that besides our personal taste it's important to have a
coherent style.

I would r-b it anyway if I didn't look the next patch.

Andi

> + * @obj_link: link to the object associated with the @handle.
> + * @ctx: context associated with the @handle.
> + * @handle: a rbtree handle to lookup context for specific obj/vma.
> + *
> + * Although we use a radixtree for that mapping, in order to
>   * remove them as the object or context is closed, we need a secondary list
>   * and a translation entry (i915_lut_handle).
>   */
> -- 
> 2.37.3

Re: [PATCH v3 35/37] drm/i915: add descriptions for some RPM macros at intel_gt_pm.h

[Andi Shyti]

Hi Mauro,

[...]

> +/**
> + * intel_gt_pm_is_awake: Query whether the runtime PM is awake held
> + *
> + * @gt: pointer to the graphics engine

...

> +/**
> + * intel_gt_pm_get: grab a runtime PM reference ensuring that GT is powered up
> + * @gt: pointer to the graphics engine

...

> +/**
> + * __intel_gt_pm_get: Acquire the runtime PM reference again
> + * @gt: pointer to the graphics engine which contains the wakeref

...

> +/**
> + * intel_gt_pm_get_if_awake: Acquire the runtime PM reference if active
> + * @gt: pointer to the graphics engine which contains the PM reference

...

> +/**
> + * intel_gt_pm_put: Release the runtime PM reference
> + * @gt: pointer to the graphics engine which contains the PM reference

...

> +/**
> + * with_intel_gt_pm - get a GT reference ensuring that GT is powered up,
> + *	run some code and then put the reference away.
> + *
> + * @gt: pointer to the gt

as you can see sometimes you put that extra blank line and
sometimes not... can we please stick to one style?

Thanks,
Andi

Re: [PATCH v3 19/37] drm/i915: stop using kernel-doc markups for something else

[Matt Roper]

On Fri, Sep 09, 2022 at 09:34:26AM +0200, Mauro Carvalho Chehab wrote:
> There are some occurrences of "/**" that aren't actually part of
> a kernel-doc markup. Replace them by "/*", in order to make easier
> to identify what i915 files contain kernel-doc markups.
> 
> Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
> 
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v3 00/37] at: https://lore.kernel.org/all/cover.1662708705.git.mchehab@kernel.org/
> 
>  drivers/gpu/drm/i915/display/dvo_ch7017.c     | 26 +++----
>  drivers/gpu/drm/i915/display/dvo_ch7xxx.c     |  6 +-
>  .../drm/i915/display/intel_display_types.h    |  2 +-
>  drivers/gpu/drm/i915/display/intel_dvo_dev.h  |  6 +-
>  drivers/gpu/drm/i915/display/intel_sdvo.c     |  4 +-
>  drivers/gpu/drm/i915/display/intel_tv.c       |  2 +-
>  drivers/gpu/drm/i915/gt/intel_context_types.h | 69 +++++++++----------
>  drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h  |  2 +-
>  drivers/gpu/drm/i915/gt/intel_gt_types.h      | 12 ++--
>  drivers/gpu/drm/i915/gt/intel_reset_types.h   |  4 +-
>  .../gpu/drm/i915/gt/intel_timeline_types.h    |  6 +-
>  .../drm/i915/gt/shaders/clear_kernel/hsw.asm  |  4 +-
>  .../drm/i915/gt/shaders/clear_kernel/ivb.asm  |  4 +-
>  drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h | 10 +--
>  drivers/gpu/drm/i915/i915_drm_client.h        |  2 +-
>  drivers/gpu/drm/i915/i915_drv.h               | 24 +++----
>  drivers/gpu/drm/i915/i915_file_private.h      |  8 +--
>  drivers/gpu/drm/i915/i915_gpu_error.h         |  4 +-
>  drivers/gpu/drm/i915/i915_pmu.h               | 32 ++++-----
>  drivers/gpu/drm/i915/intel_uncore.h           |  4 +-
>  20 files changed, 115 insertions(+), 116 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/display/dvo_ch7017.c b/drivers/gpu/drm/i915/display/dvo_ch7017.c
> index 0589994dde11..581e29ab77e4 100644
> --- a/drivers/gpu/drm/i915/display/dvo_ch7017.c
> +++ b/drivers/gpu/drm/i915/display/dvo_ch7017.c
> @@ -55,13 +55,13 @@
>  #define CH7017_TEST_PATTERN		0x48
>  
>  #define CH7017_POWER_MANAGEMENT		0x49
> -/** Enables the TV output path. */
> +/* Enables the TV output path. */
>  #define CH7017_TV_EN			(1 << 0)
>  #define CH7017_DAC0_POWER_DOWN		(1 << 1)
>  #define CH7017_DAC1_POWER_DOWN		(1 << 2)
>  #define CH7017_DAC2_POWER_DOWN		(1 << 3)
>  #define CH7017_DAC3_POWER_DOWN		(1 << 4)
> -/** Powers down the TV out block, and DAC0-3 */
> +/* Powers down the TV out block, and DAC0-3 */
>  #define CH7017_TV_POWER_DOWN_EN		(1 << 5)
>  
>  #define CH7017_VERSION_ID		0x4a
> @@ -84,26 +84,26 @@
>  #define CH7017_UP_SCALER_HORIZONTAL_INC_1	0x5e
>  
>  #define CH7017_HORIZONTAL_ACTIVE_PIXEL_INPUT	0x5f
> -/**< Low bits of horizontal active pixel input */
> +/* Low bits of horizontal active pixel input */
>  
>  #define CH7017_ACTIVE_INPUT_LINE_OUTPUT	0x60
> -/** High bits of horizontal active pixel input */
> +/* High bits of horizontal active pixel input */
>  #define CH7017_LVDS_HAP_INPUT_MASK	(0x7 << 0)
> -/** High bits of vertical active line output */
> +/* High bits of vertical active line output */
>  #define CH7017_LVDS_VAL_HIGH_MASK	(0x7 << 3)
>  
>  #define CH7017_VERTICAL_ACTIVE_LINE_OUTPUT	0x61
> -/**< Low bits of vertical active line output */
> +/* Low bits of vertical active line output */
>  
>  #define CH7017_HORIZONTAL_ACTIVE_PIXEL_OUTPUT	0x62
> -/**< Low bits of horizontal active pixel output */
> +/* Low bits of horizontal active pixel output */
>  
>  #define CH7017_LVDS_POWER_DOWN		0x63
> -/** High bits of horizontal active pixel output */
> +/* High bits of horizontal active pixel output */
>  #define CH7017_LVDS_HAP_HIGH_MASK	(0x7 << 0)
> -/** Enables the LVDS power down state transition */
> +/* Enables the LVDS power down state transition */
>  #define CH7017_LVDS_POWER_DOWN_EN	(1 << 6)
> -/** Enables the LVDS upscaler */
> +/* Enables the LVDS upscaler */
>  #define CH7017_LVDS_UPSCALER_EN		(1 << 7)
>  #define CH7017_LVDS_POWER_DOWN_DEFAULT_RESERVED 0x08
>  
> @@ -116,9 +116,9 @@
>  #define CH7017_LVDS_ENCODING_2		0x65
>  
>  #define CH7017_LVDS_PLL_CONTROL		0x66
> -/** Enables the LVDS panel output path */
> +/* Enables the LVDS panel output path */
>  #define CH7017_LVDS_PANEN		(1 << 0)
> -/** Enables the LVDS panel backlight */
> +/* Enables the LVDS panel backlight */
>  #define CH7017_LVDS_BKLEN		(1 << 3)
>  
>  #define CH7017_POWER_SEQUENCING_T1	0x67
> @@ -197,7 +197,7 @@ static bool ch7017_write(struct intel_dvo_device *dvo, u8 addr, u8 val)
>  	return i2c_transfer(dvo->i2c_bus, &msg, 1) == 1;
>  }
>  
> -/** Probes for a CH7017 on the given bus and slave address. */
> +/* Probes for a CH7017 on the given bus and slave address. */
>  static bool ch7017_init(struct intel_dvo_device *dvo,
>  			struct i2c_adapter *adapter)
>  {
> diff --git a/drivers/gpu/drm/i915/display/dvo_ch7xxx.c b/drivers/gpu/drm/i915/display/dvo_ch7xxx.c
> index 54f58ba44b9f..1c1fe1f29675 100644
> --- a/drivers/gpu/drm/i915/display/dvo_ch7xxx.c
> +++ b/drivers/gpu/drm/i915/display/dvo_ch7xxx.c
> @@ -81,7 +81,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
>  #define CH7301_SYNC_RGB_YUV	(1<<0)
>  #define CH7301_SYNC_POL_DVI	(1<<5)
>  
> -/** @file
> +/*
>   * driver for the Chrontel 7xxx DVI chip over DVO.
>   */
>  
> @@ -132,7 +132,7 @@ static char *ch7xxx_get_did(u8 did)
>  	return NULL;
>  }
>  
> -/** Reads an 8 bit register */
> +/* Reads an 8 bit register */
>  static bool ch7xxx_readb(struct intel_dvo_device *dvo, int addr, u8 *ch)
>  {
>  	struct ch7xxx_priv *ch7xxx = dvo->dev_priv;
> @@ -170,7 +170,7 @@ static bool ch7xxx_readb(struct intel_dvo_device *dvo, int addr, u8 *ch)
>  	return false;
>  }
>  
> -/** Writes an 8 bit register */
> +/* Writes an 8 bit register */
>  static bool ch7xxx_writeb(struct intel_dvo_device *dvo, int addr, u8 ch)
>  {
>  	struct ch7xxx_priv *ch7xxx = dvo->dev_priv;
> diff --git a/drivers/gpu/drm/i915/display/intel_display_types.h b/drivers/gpu/drm/i915/display/intel_display_types.h
> index 3b7945aad22a..e46027d2a3c7 100644
> --- a/drivers/gpu/drm/i915/display/intel_display_types.h
> +++ b/drivers/gpu/drm/i915/display/intel_display_types.h
> @@ -1006,7 +1006,7 @@ struct intel_crtc_state {
>  		enum drm_scaling_filter scaling_filter;
>  	} hw;
>  
> -	/**
> +	/*
>  	 * quirks - bitfield with hw state readout quirks
>  	 *
>  	 * For various reasons the hw state readout code might not be able to
> diff --git a/drivers/gpu/drm/i915/display/intel_dvo_dev.h b/drivers/gpu/drm/i915/display/intel_dvo_dev.h
> index d96c3cc46e50..45d47209c327 100644
> --- a/drivers/gpu/drm/i915/display/intel_dvo_dev.h
> +++ b/drivers/gpu/drm/i915/display/intel_dvo_dev.h
> @@ -110,7 +110,7 @@ struct intel_dvo_dev_ops {
>  	 */
>  	bool (*get_hw_state)(struct intel_dvo_device *dev);
>  
> -	/**
> +	/*
>  	 * Query the device for the modes it provides.
>  	 *
>  	 * This function may also update MonInfo, mm_width, and mm_height.
> @@ -119,12 +119,12 @@ struct intel_dvo_dev_ops {
>  	 */
>  	struct drm_display_mode *(*get_modes)(struct intel_dvo_device *dvo);
>  
> -	/**
> +	/*
>  	 * Clean up driver-specific bits of the output
>  	 */
>  	void (*destroy) (struct intel_dvo_device *dvo);
>  
> -	/**
> +	/*
>  	 * Debugging hook to dump device registers to log file
>  	 */
>  	void (*dump_regs)(struct intel_dvo_device *dvo);
> diff --git a/drivers/gpu/drm/i915/display/intel_sdvo.c b/drivers/gpu/drm/i915/display/intel_sdvo.c
> index f5b744bef18f..87ff910dce05 100644
> --- a/drivers/gpu/drm/i915/display/intel_sdvo.c
> +++ b/drivers/gpu/drm/i915/display/intel_sdvo.c
> @@ -162,7 +162,7 @@ struct intel_sdvo_connector {
>  	/* this is to get the range of margin.*/
>  	u32 max_hscan, max_vscan;
>  
> -	/**
> +	/*
>  	 * This is set if we treat the device as HDMI, instead of DVI.
>  	 */
>  	bool is_hdmi;
> @@ -280,7 +280,7 @@ static bool intel_sdvo_read_byte(struct intel_sdvo *intel_sdvo, u8 addr, u8 *ch)
>  
>  #define SDVO_CMD_NAME_ENTRY(cmd_) { .cmd = SDVO_CMD_ ## cmd_, .name = #cmd_ }
>  
> -/** Mapping of command numbers to names, for debug output */
> +/* Mapping of command numbers to names, for debug output */
>  static const struct {
>  	u8 cmd;
>  	const char *name;
> diff --git a/drivers/gpu/drm/i915/display/intel_tv.c b/drivers/gpu/drm/i915/display/intel_tv.c
> index 9379f3463344..2507ab1ceda6 100644
> --- a/drivers/gpu/drm/i915/display/intel_tv.c
> +++ b/drivers/gpu/drm/i915/display/intel_tv.c
> @@ -26,7 +26,7 @@
>   *
>   */
>  
> -/** @file
> +/*
>   * Integrated TV-out support for the 915GM and 945GM.
>   */
>  
> diff --git a/drivers/gpu/drm/i915/gt/intel_context_types.h b/drivers/gpu/drm/i915/gt/intel_context_types.h
> index 04eacae1aca5..1be2aad18f2a 100644
> --- a/drivers/gpu/drm/i915/gt/intel_context_types.h
> +++ b/drivers/gpu/drm/i915/gt/intel_context_types.h

Several of the comments in this file do appear to be kerneldoc (in fact
kerneldoc that was specifically requested during code review at
https://patchwork.freedesktop.org/patch/448456/#comment_804252) and this
file is included from Documentation/gpu/i915.rst, so I think some of
these changes might be moving in the wrong direction.  Should we instead
focus on fixing up the comments that aren't quite formatted properly?


Matt

> @@ -128,7 +128,6 @@ struct intel_context {
>  	struct {
>  		u64 timeout_us;
>  	} watchdog;
> -
>  	u32 *lrc_reg_state;
>  	union {
>  		struct {
> @@ -139,7 +138,7 @@ struct intel_context {
>  	} lrc;
>  	u32 tag; /* cookie passed to HW to track this context on submission */
>  
> -	/** stats: Context GPU engine busyness tracking. */
> +	/* stats: Context GPU engine busyness tracking. */
>  	struct intel_context_stats {
>  		u64 active;
>  
> @@ -158,7 +157,7 @@ struct intel_context {
>  	atomic_t pin_count;
>  	struct mutex pin_mutex; /* guards pinning and associated on-gpuing */
>  
> -	/**
> +	/*
>  	 * active: Active tracker for the rq activity (inc. external) on this
>  	 * intel_context object.
>  	 */
> @@ -166,10 +165,10 @@ struct intel_context {
>  
>  	const struct intel_context_ops *ops;
>  
> -	/** sseu: Control eu/slice partitioning */
> +	/* sseu: Control eu/slice partitioning */
>  	struct intel_sseu sseu;
>  
> -	/**
> +	/*
>  	 * pinned_contexts_link: List link for the engine's pinned contexts.
>  	 * This is only used if this is a perma-pinned kernel context and
>  	 * the list is assumed to only be manipulated during driver load
> @@ -180,9 +179,9 @@ struct intel_context {
>  	u8 wa_bb_page; /* if set, page num reserved for context workarounds */
>  
>  	struct {
> -		/** @lock: protects everything in guc_state */
> +		/* @lock: protects everything in guc_state */
>  		spinlock_t lock;
> -		/**
> +		/*
>  		 * @sched_state: scheduling state of this context using GuC
>  		 * submission
>  		 */
> @@ -192,18 +191,18 @@ struct intel_context {
>  		 * being fenced until a GuC operation completes
>  		 */
>  		struct list_head fences;
> -		/**
> +		/*
>  		 * @blocked: fence used to signal when the blocking of a
>  		 * context's submissions is complete.
>  		 */
>  		struct i915_sw_fence blocked;
> -		/** @number_committed_requests: number of committed requests */
> +		/* @number_committed_requests: number of committed requests */
>  		int number_committed_requests;
> -		/** @requests: list of active requests on this context */
> +		/* @requests: list of active requests on this context */
>  		struct list_head requests;
> -		/** @prio: the context's current guc priority */
> +		/* @prio: the context's current guc priority */
>  		u8 prio;
> -		/**
> +		/*
>  		 * @prio_count: a counter of the number requests in flight in
>  		 * each priority bucket
>  		 */
> @@ -211,82 +210,82 @@ struct intel_context {
>  	} guc_state;
>  
>  	struct {
> -		/**
> +		/*
>  		 * @id: handle which is used to uniquely identify this context
>  		 * with the GuC, protected by guc->submission_state.lock
>  		 */
>  		u16 id;
> -		/**
> +		/*
>  		 * @ref: the number of references to the guc_id, when
>  		 * transitioning in and out of zero protected by
>  		 * guc->submission_state.lock
>  		 */
>  		atomic_t ref;
> -		/**
> +		/*
>  		 * @link: in guc->guc_id_list when the guc_id has no refs but is
>  		 * still valid, protected by guc->submission_state.lock
>  		 */
>  		struct list_head link;
>  	} guc_id;
>  
> -	/**
> +	/*
>  	 * @destroyed_link: link in guc->submission_state.destroyed_contexts, in
>  	 * list when context is pending to be destroyed (deregistered with the
>  	 * GuC), protected by guc->submission_state.lock
>  	 */
>  	struct list_head destroyed_link;
>  
> -	/** @parallel: sub-structure for parallel submission members */
> +	/* @parallel: sub-structure for parallel submission members */
>  	struct {
>  		union {
> -			/**
> +			/*
>  			 * @child_list: parent's list of children
>  			 * contexts, no protection as immutable after context
>  			 * creation
>  			 */
>  			struct list_head child_list;
> -			/**
> +			/*
>  			 * @child_link: child's link into parent's list of
>  			 * children
>  			 */
>  			struct list_head child_link;
>  		};
> -		/** @parent: pointer to parent if child */
> +		/* @parent: pointer to parent if child */
>  		struct intel_context *parent;
> -		/**
> +		/*
>  		 * @last_rq: last request submitted on a parallel context, used
>  		 * to insert submit fences between requests in the parallel
>  		 * context
>  		 */
>  		struct i915_request *last_rq;
> -		/**
> +		/*
>  		 * @fence_context: fence context composite fence when doing
>  		 * parallel submission
>  		 */
>  		u64 fence_context;
> -		/**
> +		/*
>  		 * @seqno: seqno for composite fence when doing parallel
>  		 * submission
>  		 */
>  		u32 seqno;
> -		/** @number_children: number of children if parent */
> +		/* @number_children: number of children if parent */
>  		u8 number_children;
> -		/** @child_index: index into child_list if child */
> +		/* @child_index: index into child_list if child */
>  		u8 child_index;
> -		/** @guc: GuC specific members for parallel submission */
> +		/* @guc: GuC specific members for parallel submission */
>  		struct {
> -			/** @wqi_head: cached head pointer in work queue */
> +			/* @wqi_head: cached head pointer in work queue */
>  			u16 wqi_head;
> -			/** @wqi_tail: cached tail pointer in work queue */
> +			/* @wqi_tail: cached tail pointer in work queue */
>  			u16 wqi_tail;
> -			/** @wq_head: pointer to the actual head in work queue */
> +			/* @wq_head: pointer to the actual head in work queue */
>  			u32 *wq_head;
> -			/** @wq_tail: pointer to the actual head in work queue */
> +			/* @wq_tail: pointer to the actual head in work queue */
>  			u32 *wq_tail;
> -			/** @wq_status: pointer to the status in work queue */
> +			/* @wq_status: pointer to the status in work queue */
>  			u32 *wq_status;
>  
> -			/**
> +			/*
>  			 * @parent_page: page in context state (ce->state) used
>  			 * by parent for work queue, process descriptor
>  			 */
> @@ -295,18 +294,18 @@ struct intel_context {
>  	} parallel;
>  
>  #ifdef CONFIG_DRM_I915_SELFTEST
> -	/**
> +	/*
>  	 * @drop_schedule_enable: Force drop of schedule enable G2H for selftest
>  	 */
>  	bool drop_schedule_enable;
>  
> -	/**
> +	/*
>  	 * @drop_schedule_disable: Force drop of schedule disable G2H for
>  	 * selftest
>  	 */
>  	bool drop_schedule_disable;
>  
> -	/**
> +	/*
>  	 * @drop_deregister: Force drop of deregister G2H for selftest
>  	 */
>  	bool drop_deregister;
> diff --git a/drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h b/drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h
> index 25340be5ecf0..230e846151a8 100644
> --- a/drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h
> +++ b/drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h
> @@ -26,7 +26,7 @@ struct i915_fence_reg {
>  	atomic_t pin_count;
>  	struct i915_active active;
>  	int id;
> -	/**
> +	/*
>  	 * Whether the tiling parameters for the currently
>  	 * associated fence register have changed. Note that
>  	 * for the purposes of tracking tiling changes we also
> diff --git a/drivers/gpu/drm/i915/gt/intel_gt_types.h b/drivers/gpu/drm/i915/gt/intel_gt_types.h
> index 4d56f7d5a3be..c66e3d803666 100644
> --- a/drivers/gpu/drm/i915/gt/intel_gt_types.h
> +++ b/drivers/gpu/drm/i915/gt/intel_gt_types.h
> @@ -114,7 +114,7 @@ struct intel_gt {
>  	} timelines;
>  
>  	struct intel_gt_requests {
> -		/**
> +		/*
>  		 * We leave the user IRQ off as much as possible,
>  		 * but this means that requests will finish and never
>  		 * be retired once the system goes idle. Set a timer to
> @@ -138,7 +138,7 @@ struct intel_gt {
>  	ktime_t last_init_time;
>  	struct intel_reset reset;
>  
> -	/**
> +	/*
>  	 * Is the GPU currently considered idle, or busy executing
>  	 * userspace requests? Whilst idle, we allow runtime power
>  	 * management to power down the hardware and display clocks.
> @@ -164,12 +164,12 @@ struct intel_gt {
>  	struct {
>  		bool active;
>  
> -		/**
> +		/*
>  		 * @lock: Lock protecting the below fields.
>  		 */
>  		seqcount_mutex_t lock;
>  
> -		/**
> +		/*
>  		 * @total: Total time this engine was busy.
>  		 *
>  		 * Accumulated time not counting the most recent block in cases
> @@ -177,7 +177,7 @@ struct intel_gt {
>  		 */
>  		ktime_t total;
>  
> -		/**
> +		/*
>  		 * @start: Timestamp of the last idle to active transition.
>  		 *
>  		 * Idle is defined as active == 0, active is active > 0.
> @@ -243,7 +243,7 @@ struct intel_gt {
>  
>  		unsigned long mslice_mask;
>  
> -		/** @hwconfig: hardware configuration data */
> +		/* @hwconfig: hardware configuration data */
>  		struct intel_hwconfig hwconfig;
>  	} info;
>  
> diff --git a/drivers/gpu/drm/i915/gt/intel_reset_types.h b/drivers/gpu/drm/i915/gt/intel_reset_types.h
> index 9312b29f5a97..4ef21186e6d5 100644
> --- a/drivers/gpu/drm/i915/gt/intel_reset_types.h
> +++ b/drivers/gpu/drm/i915/gt/intel_reset_types.h
> @@ -11,7 +11,7 @@
>  #include <linux/srcu.h>
>  
>  struct intel_reset {
> -	/**
> +	/*
>  	 * flags: Control various stages of the GPU reset
>  	 *
>  	 * #I915_RESET_BACKOFF - When we start a global reset, we need to
> @@ -49,7 +49,7 @@ struct intel_reset {
>  
>  	struct mutex mutex; /* serialises wedging/unwedging */
>  
> -	/**
> +	/*
>  	 * Waitqueue to signal when the reset has completed. Used by clients
>  	 * that wait for dev_priv->mm.wedged to settle.
>  	 */
> diff --git a/drivers/gpu/drm/i915/gt/intel_timeline_types.h b/drivers/gpu/drm/i915/gt/intel_timeline_types.h
> index 74e67dbf89c5..ae5f859d72c0 100644
> --- a/drivers/gpu/drm/i915/gt/intel_timeline_types.h
> +++ b/drivers/gpu/drm/i915/gt/intel_timeline_types.h
> @@ -50,7 +50,7 @@ struct intel_timeline {
>  
>  	bool has_initial_breadcrumb;
>  
> -	/**
> +	/*
>  	 * List of breadcrumbs associated with GPU requests currently
>  	 * outstanding.
>  	 */
> @@ -66,10 +66,10 @@ struct intel_timeline {
>  
>  	struct i915_active active;
>  
> -	/** A chain of completed timelines ready for early retirement. */
> +	/* A chain of completed timelines ready for early retirement. */
>  	struct intel_timeline *retire;
>  
> -	/**
> +	/*
>  	 * We track the most recent seqno that we wait on in every context so
>  	 * that we only have to emit a new await and dependency on a more
>  	 * recent sync point. As the contexts may be executed out-of-order, we
> diff --git a/drivers/gpu/drm/i915/gt/shaders/clear_kernel/hsw.asm b/drivers/gpu/drm/i915/gt/shaders/clear_kernel/hsw.asm
> index 5fdf384bb621..88d2dbbf981e 100644
> --- a/drivers/gpu/drm/i915/gt/shaders/clear_kernel/hsw.asm
> +++ b/drivers/gpu/drm/i915/gt/shaders/clear_kernel/hsw.asm
> @@ -14,7 +14,7 @@
>  /* Store designated "clear GRF" value */
>  mov(1)          f0.1<1>UW       g1.2<0,1,0>UW                   { align1 1N };
>  
> -/**
> +/*
>   * Curbe Format
>   *
>   * DW 1.0 - Block Offset to write Render Cache
> @@ -40,7 +40,7 @@ add(1)          g1.2<1>UD       g1.2<0,1,0>UD   0x00000001UD    { align1 1N }; /
>  cmp.z.f0.0(1)   null<1>UD       g1.3<0,1,0>UD   0x00000000UD    { align1 1N };
>  (+f0.0) jmpi(1) 352D                                            { align1 WE_all 1N };
>  
> -/**
> +/*
>   * State Register has info on where this thread is running
>   *	IVB: sr0.0 :: [15:13]: MBZ, 12: HSID (Half-Slice ID), [11:8]EUID, [2:0] ThreadSlotID
>   *	HSW: sr0.0 :: 15: MBZ, [14:13]: SliceID, 12: HSID (Half-Slice ID), [11:8]EUID, [2:0] ThreadSlotID
> diff --git a/drivers/gpu/drm/i915/gt/shaders/clear_kernel/ivb.asm b/drivers/gpu/drm/i915/gt/shaders/clear_kernel/ivb.asm
> index 97c7ac9e3854..4d7c5f1981ba 100644
> --- a/drivers/gpu/drm/i915/gt/shaders/clear_kernel/ivb.asm
> +++ b/drivers/gpu/drm/i915/gt/shaders/clear_kernel/ivb.asm
> @@ -14,7 +14,7 @@
>  /* Store designated "clear GRF" value */
>  mov(1)          f0.1<1>UW       g1.2<0,1,0>UW                   { align1 1N };
>  
> -/**
> +/*
>   * Curbe Format
>   *
>   * DW 1.0 - Block Offset to write Render Cache
> @@ -40,7 +40,7 @@ add(1)          g1.2<1>UD       g1.2<0,1,0>UD   0x00000001UD    { align1 1N }; /
>  cmp.z.f0.0(1)   null<1>UD       g1.3<0,1,0>UD   0x00000000UD    { align1 1N };
>  (+f0.0) jmpi(1) 44D                                             { align1 WE_all 1N };
>  
> -/**
> +/*
>   * State Register has info on where this thread is running
>   *	IVB: sr0.0 :: [15:13]: MBZ, 12: HSID (Half-Slice ID), [11:8]EUID, [2:0] ThreadSlotID
>   *	HSW: sr0.0 :: 15: MBZ, [14:13]: SliceID, 12: HSID (Half-Slice ID), [11:8]EUID, [2:0] ThreadSlotID
> 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 58f93226b1c1..d8a7659079f5 100644
> --- a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> +++ b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> @@ -168,12 +168,12 @@ struct __guc_capture_ads_cache {
>   * Internal context of the intel_guc_capture module.
>   */
>  struct intel_guc_state_capture {
> -	/**
> +	/*
>  	 * @reglists: static table of register lists used for error-capture state.
>  	 */
>  	const struct __guc_mmio_reg_descr_group *reglists;
>  
> -	/**
> +	/*
>  	 * @extlists: allocated table of steered register lists used for error-capture state.
>  	 *
>  	 * NOTE: steered registers have multiple instances depending on the HW configuration
> @@ -181,7 +181,7 @@ struct intel_guc_state_capture {
>  	 */
>  	struct __guc_mmio_reg_descr_group *extlists;
>  
> -	/**
> +	/*
>  	 * @ads_cache: cached register lists that is ADS format ready
>  	 */
>  	struct __guc_capture_ads_cache ads_cache[GUC_CAPTURE_LIST_INDEX_MAX]
> @@ -189,7 +189,7 @@ struct intel_guc_state_capture {
>  						[GUC_MAX_ENGINE_CLASSES];
>  	void *ads_null_cache;
>  
> -	/**
> +	/*
>  	 * @cachelist: Pool of pre-allocated nodes for error capture output
>  	 *
>  	 * We need this pool of pre-allocated nodes because we cannot
> @@ -204,7 +204,7 @@ struct intel_guc_state_capture {
>  #define PREALLOC_NODES_DEFAULT_NUMREGS 64
>  	int max_mmio_per_node;
>  
> -	/**
> +	/*
>  	 * @outlist: Pool of pre-allocated nodes for error capture output
>  	 *
>  	 * A linked list of parsed GuC error-capture output data before
> diff --git a/drivers/gpu/drm/i915/i915_drm_client.h b/drivers/gpu/drm/i915/i915_drm_client.h
> index 69496af996d9..c722e3c18694 100644
> --- a/drivers/gpu/drm/i915/i915_drm_client.h
> +++ b/drivers/gpu/drm/i915/i915_drm_client.h
> @@ -34,7 +34,7 @@ struct i915_drm_client {
>  
>  	struct i915_drm_clients *clients;
>  
> -	/**
> +	/*
>  	 * @past_runtime: Accumulation of pphwsp runtimes from closed contexts.
>  	 */
>  	atomic64_t past_runtime[I915_LAST_UABI_ENGINE_CLASS + 1];
> diff --git a/drivers/gpu/drm/i915/i915_drv.h b/drivers/gpu/drm/i915/i915_drv.h
> index 76aad81c014b..519e8e8ace45 100644
> --- a/drivers/gpu/drm/i915/i915_drv.h
> +++ b/drivers/gpu/drm/i915/i915_drv.h
> @@ -113,37 +113,37 @@ struct i915_gem_mm {
>  	 * support stolen.
>  	 */
>  	struct intel_memory_region *stolen_region;
> -	/** Memory allocator for GTT stolen memory */
> +	/* Memory allocator for GTT stolen memory */
>  	struct drm_mm stolen;
> -	/** Protects the usage of the GTT stolen memory allocator. This is
> +	/* Protects the usage of the GTT stolen memory allocator. This is
>  	 * always the inner lock when overlapping with struct_mutex. */
>  	struct mutex stolen_lock;
>  
>  	/* Protects bound_list/unbound_list and #drm_i915_gem_object.mm.link */
>  	spinlock_t obj_lock;
>  
> -	/**
> +	/*
>  	 * List of objects which are purgeable.
>  	 */
>  	struct list_head purge_list;
>  
> -	/**
> +	/*
>  	 * List of objects which have allocated pages and are shrinkable.
>  	 */
>  	struct list_head shrink_list;
>  
> -	/**
> +	/*
>  	 * List of objects which are pending destruction.
>  	 */
>  	struct llist_head free_list;
>  	struct work_struct free_work;
> -	/**
> +	/*
>  	 * Count of objects pending destructions. Used to skip needlessly
>  	 * waiting on an RCU barrier if no objects are waiting to be freed.
>  	 */
>  	atomic_t free_count;
>  
> -	/**
> +	/*
>  	 * tmpfs instance used for shmem backed objects
>  	 */
>  	struct vfsmount *gemfs;
> @@ -155,7 +155,7 @@ struct i915_gem_mm {
>  	struct shrinker shrinker;
>  
>  #ifdef CONFIG_MMU_NOTIFIER
> -	/**
> +	/*
>  	 * notifier_lock for mmu notifiers, memory may not be allocated
>  	 * while holding this lock.
>  	 */
> @@ -209,7 +209,7 @@ struct drm_i915_private {
>  	struct intel_runtime_info __runtime; /* Use RUNTIME_INFO() to access. */
>  	struct intel_driver_caps caps;
>  
> -	/**
> +	/*
>  	 * Data Stolen Memory - aka "i915 stolen memory" gives us the start and
>  	 * end of stolen which we can optionally use to create GEM objects
>  	 * backed by stolen memory. Note that stolen_usable_size tells us
> @@ -217,7 +217,7 @@ struct drm_i915_private {
>  	 * some portion of it is in fact reserved for use by hardware functions.
>  	 */
>  	struct resource dsm;
> -	/**
> +	/*
>  	 * Reseved portion of Data Stolen Memory
>  	 */
>  	struct resource dsm_reserved;
> @@ -258,7 +258,7 @@ struct drm_i915_private {
>  	struct mutex sb_lock;
>  	struct pm_qos_request sb_qos;
>  
> -	/** Cached value of IMR to avoid reads in updating the bitfield */
> +	/* Cached value of IMR to avoid reads in updating the bitfield */
>  	union {
>  		u32 irq_mask;
>  		u32 de_irq_mask[I915_MAX_PIPES];
> @@ -274,7 +274,7 @@ struct drm_i915_private {
>  	unsigned int hpll_freq;
>  	unsigned int czclk_freq;
>  
> -	/**
> +	/*
>  	 * wq - Driver workqueue for GEM.
>  	 *
>  	 * NOTE: Work items scheduled here are not allowed to grab any modeset
> diff --git a/drivers/gpu/drm/i915/i915_file_private.h b/drivers/gpu/drm/i915/i915_file_private.h
> index f42877869692..282e0c280224 100644
> --- a/drivers/gpu/drm/i915/i915_file_private.h
> +++ b/drivers/gpu/drm/i915/i915_file_private.h
> @@ -22,7 +22,7 @@ struct drm_i915_file_private {
>  		struct rcu_head rcu;
>  	};
>  
> -	/** @proto_context_lock: Guards all struct i915_gem_proto_context
> +	/* @proto_context_lock: Guards all struct i915_gem_proto_context
>  	 * operations
>  	 *
>  	 * This not only guards @proto_context_xa, but is always held
> @@ -33,7 +33,7 @@ struct drm_i915_file_private {
>  	 */
>  	struct mutex proto_context_lock;
>  
> -	/** @proto_context_xa: xarray of struct i915_gem_proto_context
> +	/* @proto_context_xa: xarray of struct i915_gem_proto_context
>  	 *
>  	 * Historically, the context uAPI allowed for two methods of
>  	 * setting context parameters: SET_CONTEXT_PARAM and
> @@ -77,7 +77,7 @@ struct drm_i915_file_private {
>  	 */
>  	struct xarray proto_context_xa;
>  
> -	/** @context_xa: xarray of fully created i915_gem_context
> +	/* @context_xa: xarray of fully created i915_gem_context
>  	 *
>  	 * Write access to this xarray is guarded by @proto_context_lock.
>  	 * Otherwise, writers may race with finalize_create_context_locked().
> @@ -101,7 +101,7 @@ struct drm_i915_file_private {
>  #define   I915_CLIENT_FAST_HANG_JIFFIES (60 * HZ)
>  #define I915_CLIENT_SCORE_CONTEXT_BAN   3
>  #define I915_CLIENT_SCORE_BANNED	9
> -	/** ban_score: Accumulated score of all ctx bans and fast hangs. */
> +	/* ban_score: Accumulated score of all ctx bans and fast hangs. */
>  	atomic_t ban_score;
>  	unsigned long hang_timestamp;
>  
> diff --git a/drivers/gpu/drm/i915/i915_gpu_error.h b/drivers/gpu/drm/i915/i915_gpu_error.h
> index efc75cc2ffdb..4e395a9e4c11 100644
> --- a/drivers/gpu/drm/i915/i915_gpu_error.h
> +++ b/drivers/gpu/drm/i915/i915_gpu_error.h
> @@ -224,10 +224,10 @@ struct i915_gpu_error {
>  
>  	atomic_t pending_fb_pin;
>  
> -	/** Number of times the device has been reset (global) */
> +	/* Number of times the device has been reset (global) */
>  	atomic_t reset_count;
>  
> -	/** Number of times an engine has been reset */
> +	/* Number of times an engine has been reset */
>  	atomic_t reset_engine_count[I915_NUM_ENGINES];
>  };
>  
> diff --git a/drivers/gpu/drm/i915/i915_pmu.h b/drivers/gpu/drm/i915/i915_pmu.h
> index c30f43319a78..9fdb50376995 100644
> --- a/drivers/gpu/drm/i915/i915_pmu.h
> +++ b/drivers/gpu/drm/i915/i915_pmu.h
> @@ -52,34 +52,34 @@ struct i915_pmu_sample {
>  };
>  
>  struct i915_pmu {
> -	/**
> +	/*
>  	 * @cpuhp: Struct used for CPU hotplug handling.
>  	 */
>  	struct {
>  		struct hlist_node node;
>  		unsigned int cpu;
>  	} cpuhp;
> -	/**
> +	/*
>  	 * @base: PMU base.
>  	 */
>  	struct pmu base;
> -	/**
> +	/*
>  	 * @closed: i915 is unregistering.
>  	 */
>  	bool closed;
> -	/**
> +	/*
>  	 * @name: Name as registered with perf core.
>  	 */
>  	const char *name;
> -	/**
> +	/*
>  	 * @lock: Lock protecting enable mask and ref count handling.
>  	 */
>  	spinlock_t lock;
> -	/**
> +	/*
>  	 * @timer: Timer for internal i915 PMU sampling.
>  	 */
>  	struct hrtimer timer;
> -	/**
> +	/*
>  	 * @enable: Bitmask of specific enabled events.
>  	 *
>  	 * For some events we need to track their state and do some internal
> @@ -92,14 +92,14 @@ struct i915_pmu {
>  	 */
>  	u32 enable;
>  
> -	/**
> +	/*
>  	 * @timer_last:
>  	 *
>  	 * Timestmap of the previous timer invocation.
>  	 */
>  	ktime_t timer_last;
>  
> -	/**
> +	/*
>  	 * @enable_count: Reference counts for the enabled events.
>  	 *
>  	 * Array indices are mapped in the same way as bits in the @enable field
> @@ -107,11 +107,11 @@ struct i915_pmu {
>  	 * are using the PMU API.
>  	 */
>  	unsigned int enable_count[I915_PMU_MASK_BITS];
> -	/**
> +	/*
>  	 * @timer_enabled: Should the internal sampling timer be running.
>  	 */
>  	bool timer_enabled;
> -	/**
> +	/*
>  	 * @sample: Current and previous (raw) counters for sampling events.
>  	 *
>  	 * These counters are updated from the i915 PMU sampling timer.
> @@ -120,11 +120,11 @@ struct i915_pmu {
>  	 * struct intel_engine_cs.
>  	 */
>  	struct i915_pmu_sample sample[__I915_NUM_PMU_SAMPLERS];
> -	/**
> +	/*
>  	 * @sleep_last: Last time GT parked for RC6 estimation.
>  	 */
>  	ktime_t sleep_last;
> -	/**
> +	/*
>  	 * @irq_count: Number of interrupts
>  	 *
>  	 * Intentionally unsigned long to avoid atomics or heuristics on 32bit.
> @@ -132,15 +132,15 @@ struct i915_pmu {
>  	 * occasional wraparound easily. It's 32bit after all.
>  	 */
>  	unsigned long irq_count;
> -	/**
> +	/*
>  	 * @events_attr_group: Device events attribute group.
>  	 */
>  	struct attribute_group events_attr_group;
> -	/**
> +	/*
>  	 * @i915_attr: Memory block holding device attributes.
>  	 */
>  	void *i915_attr;
> -	/**
> +	/*
>  	 * @pmu_attr: Memory block holding device attributes.
>  	 */
>  	void *pmu_attr;
> diff --git a/drivers/gpu/drm/i915/intel_uncore.h b/drivers/gpu/drm/i915/intel_uncore.h
> index b1fa912a65e7..5f896fbf3064 100644
> --- a/drivers/gpu/drm/i915/intel_uncore.h
> +++ b/drivers/gpu/drm/i915/intel_uncore.h
> @@ -39,7 +39,7 @@ struct intel_uncore;
>  struct intel_gt;
>  
>  struct intel_uncore_mmio_debug {
> -	spinlock_t lock; /** lock is also taken in irq contexts. */
> +	spinlock_t lock; /* lock is also taken in irq contexts. */
>  	int unclaimed_mmio_check;
>  	int saved_mmio_check;
>  	u32 suspend_count;
> @@ -133,7 +133,7 @@ struct intel_uncore {
>  	struct intel_gt *gt;
>  	struct intel_runtime_pm *rpm;
>  
> -	spinlock_t lock; /** lock is also taken in irq contexts. */
> +	spinlock_t lock; /* lock is also taken in irq contexts. */
>  
>  	unsigned int flags;
>  #define UNCORE_HAS_FORCEWAKE		BIT(0)
> -- 
> 2.37.3
> 

-- 
Matt Roper
Graphics Software Engineer
VTT-OSGC Platform Enablement
Intel Corporation

Re: [PATCH v3 19/37] drm/i915: stop using kernel-doc markups for something else

[Mauro Carvalho Chehab]

Hi Matt,

Em Mon, 12 Sep 2022 08:09:57 -0700
Matt Roper <matthew.d.roper@intel.com> escreveu:

> > --- a/drivers/gpu/drm/i915/gt/intel_context_types.h
> > +++ b/drivers/gpu/drm/i915/gt/intel_context_types.h  
> 
> Several of the comments in this file do appear to be kerneldoc (in fact
> kerneldoc that was specifically requested during code review at
> https://patchwork.freedesktop.org/patch/448456/#comment_804252) and this
> file is included from Documentation/gpu/i915.rst, so I think some of
> these changes might be moving in the wrong direction.  Should we instead
> focus on fixing up the comments that aren't quite formatted properly?

Those *appear* to be kernel-doc markups, but they aren't, because
the structs themselves are not properly marked. See, for instance
struct intel_context.

scripts/kerneldoc will *only* consider what's there as a proper
comment if you add:

	/**
	 * struct intel_context - describes an i915 context
	 * <add a proper description for it>
	 */
	struct intel_context {
		union {
			/** @ref: a kernel object reference */
	                struct kref ref; /* no kref_get_unless_zero()! */
			/** @rcu: a rcu header */
	                struct rcu_head rcu;
	        };
		...
	}

Describing all fields inside the struct. Just placing
	/** something */
on some random places in the middle doesn't make it a kernel-doc.

If you actually run kernel-doc in Werror mode:

	./scripts/kernel-doc -Werror -sphinx-version 2.4.4 drivers/gpu/drm/i915/gt/intel_context_types.h | echo "ERROR!"
	ERROR!
	drivers/gpu/drm/i915/gt/intel_context_types.h:1: warning: no structured comments found
	1 warnings as Errors

you'll see that this is currently broken.

Thanks,
Mauro

Re: [PATCH v3 19/37] drm/i915: stop using kernel-doc markups for something else

[Matt Roper]

On Mon, Sep 12, 2022 at 06:47:56PM +0200, Mauro Carvalho Chehab wrote:
> Hi Matt,
> 
> Em Mon, 12 Sep 2022 08:09:57 -0700
> Matt Roper <matthew.d.roper@intel.com> escreveu:
> 
> > > --- a/drivers/gpu/drm/i915/gt/intel_context_types.h
> > > +++ b/drivers/gpu/drm/i915/gt/intel_context_types.h  
> > 
> > Several of the comments in this file do appear to be kerneldoc (in fact
> > kerneldoc that was specifically requested during code review at
> > https://patchwork.freedesktop.org/patch/448456/#comment_804252) and this
> > file is included from Documentation/gpu/i915.rst, so I think some of
> > these changes might be moving in the wrong direction.  Should we instead
> > focus on fixing up the comments that aren't quite formatted properly?
> 
> Those *appear* to be kernel-doc markups, but they aren't, because
> the structs themselves are not properly marked. See, for instance
> struct intel_context.
> 
> scripts/kerneldoc will *only* consider what's there as a proper
> comment if you add:
> 
> 	/**
> 	 * struct intel_context - describes an i915 context
> 	 * <add a proper description for it>
> 	 */
> 	struct intel_context {
> 		union {
> 			/** @ref: a kernel object reference */
> 	                struct kref ref; /* no kref_get_unless_zero()! */
> 			/** @rcu: a rcu header */
> 	                struct rcu_head rcu;
> 	        };
> 		...
> 	}
> 
> Describing all fields inside the struct. Just placing
> 	/** something */
> on some random places in the middle doesn't make it a kernel-doc.

Right, what we have today is incomplete/incorrect.  But I think we
should be fixing that by adding the missing documentation on the
structure, rather than giving up and removing the kerneldoc.  The end
goal should be to have proper generated documentation, not just silence
the warnings while leaving the actual output incomplete.


Matt

> 
> If you actually run kernel-doc in Werror mode:
> 
> 	./scripts/kernel-doc -Werror -sphinx-version 2.4.4 drivers/gpu/drm/i915/gt/intel_context_types.h | echo "ERROR!"
> 	ERROR!
> 	drivers/gpu/drm/i915/gt/intel_context_types.h:1: warning: no structured comments found
> 	1 warnings as Errors
> 
> you'll see that this is currently broken.
> 
> Thanks,
> Mauro

-- 
Matt Roper
Graphics Software Engineer
VTT-OSGC Platform Enablement
Intel Corporation

Re: [Intel-gfx] [PATCH v3 02/37] drm/i915: display: fix kernel-doc markup warnings

[Gwan-gyeong Mun]

Looks good to me.

Reviewed-by: Gwan-gyeong Mun <gwan-gyeong.mun@intel.com>

On 9/9/22 10:34 AM, Mauro Carvalho Chehab wrote:
> There are a couple of issues at i915 display kernel-doc markups:
> 
> 	drivers/gpu/drm/i915/display/intel_display_debugfs.c:2238: warning: Function parameter or member 'intel_connector' not described in 'intel_connector_debugfs_add'
> 	drivers/gpu/drm/i915/display/intel_display_debugfs.c:2238: warning: Excess function parameter 'connector' description in 'intel_connector_debugfs_add'
> 	drivers/gpu/drm/i915/display/intel_display_power.c:700: warning: expecting prototype for intel_display_power_put_async(). Prototype was for __intel_display_power_put_async() instead
> 	drivers/gpu/drm/i915/display/intel_tc.c:807: warning: Function parameter or member 'work' not described in 'intel_tc_port_disconnect_phy_work'
> 	drivers/gpu/drm/i915/display/intel_tc.c:807: warning: Excess function parameter 'dig_port' description in 'intel_tc_port_disconnect_phy_work'
> 
> Those are due to wrong parameter of function name. Address them.
> 
> Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
> 
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v3 00/37] at: https://lore.kernel.org/all/cover.1662708705.git.mchehab@kernel.org/
> 
>   drivers/gpu/drm/i915/display/intel_display_debugfs.c | 2 +-
>   drivers/gpu/drm/i915/display/intel_display_power.c   | 2 +-
>   drivers/gpu/drm/i915/display/intel_tc.c              | 2 +-
>   3 files changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/display/intel_display_debugfs.c b/drivers/gpu/drm/i915/display/intel_display_debugfs.c
> index 5dc364e9db49..e8433aa50905 100644
> --- a/drivers/gpu/drm/i915/display/intel_display_debugfs.c
> +++ b/drivers/gpu/drm/i915/display/intel_display_debugfs.c
> @@ -2232,7 +2232,7 @@ DEFINE_SHOW_ATTRIBUTE(i915_current_bpc);
>   
>   /**
>    * intel_connector_debugfs_add - add i915 specific connector debugfs files
> - * @connector: pointer to a registered drm_connector
> + * @intel_connector: pointer to a registered drm_connector
>    *
>    * Cleanup will be done by drm_connector_unregister() through a call to
>    * drm_debugfs_connector_remove().
> diff --git a/drivers/gpu/drm/i915/display/intel_display_power.c b/drivers/gpu/drm/i915/display/intel_display_power.c
> index 1af1705d730d..b080d65d4461 100644
> --- a/drivers/gpu/drm/i915/display/intel_display_power.c
> +++ b/drivers/gpu/drm/i915/display/intel_display_power.c
> @@ -686,7 +686,7 @@ intel_display_power_put_async_work(struct work_struct *work)
>   }
>   
>   /**
> - * intel_display_power_put_async - release a power domain reference asynchronously
> + * __intel_display_power_put_async - release a power domain reference asynchronously
>    * @i915: i915 device instance
>    * @domain: power domain to reference
>    * @wakeref: wakeref acquired for the reference that is being released
> diff --git a/drivers/gpu/drm/i915/display/intel_tc.c b/drivers/gpu/drm/i915/display/intel_tc.c
> index e5af955b5600..10cda362537e 100644
> --- a/drivers/gpu/drm/i915/display/intel_tc.c
> +++ b/drivers/gpu/drm/i915/display/intel_tc.c
> @@ -797,7 +797,7 @@ void intel_tc_port_lock(struct intel_digital_port *dig_port)
>   
>   /**
>    * intel_tc_port_disconnect_phy_work: disconnect TypeC PHY from display port
> - * @dig_port: digital port
> + * @work: workqueue struct
>    *
>    * Disconnect the given digital port from its TypeC PHY (handing back the
>    * control of the PHY to the TypeC subsystem). This will happen in a delayed

Re: [Intel-gfx] [PATCH v3 01/37] drm/i915: fix kernel-doc trivial warnings on i915/*.[ch] files

[Gwan-gyeong Mun]

On 9/9/22 10:34 AM, Mauro Carvalho Chehab wrote:
> There are several trivial warnings there, due to trivial things:
> 	- lack of function name at the kerneldoc markup;
> 	- renamed functions;
> 	- wrong parameter syntax.
> 
> Fix such warnings:
> 	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'
> 	drivers/gpu/drm/i915/i915_gem.c:443: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> 	 * Reads data from the object referenced by handle.
> 	drivers/gpu/drm/i915/i915_gem.c:532: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> 	 * This is the fast pwrite path, where we copy the data directly from the
> 	drivers/gpu/drm/i915/i915_gem.c:717: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> 	 * Writes data to the object referenced by handle.
> 	drivers/gpu/drm/i915/i915_gem.c:802: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> 	 * Called when user space has done writes to this buffer
> 	drivers/gpu/drm/i915/i915_pmu.h:22: warning: cannot understand function prototype: 'enum i915_pmu_tracked_events '
> 	drivers/gpu/drm/i915/i915_pmu.h:33: warning: cannot understand function prototype: 'enum '
> 	drivers/gpu/drm/i915/i915_pmu.h:42: 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.
> 	drivers/gpu/drm/i915/i915_request.h:177: 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:473: 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.
> 	drivers/gpu/drm/i915/i915_scatterlist.c:63: warning: Function parameter or member 'size' not described in 'i915_refct_sgt_init'
> 	drivers/gpu/drm/i915/i915_scatterlist.h:153: warning: Incorrect use of kernel-doc format:          * release() - Free the memory of the struct i915_refct_sgt
> 	drivers/gpu/drm/i915/i915_scatterlist.h:157: warning: Function parameter or member 'release' not described in 'i915_refct_sgt_ops'
> 	drivers/gpu/drm/i915/i915_scatterlist.h:180: warning: Function parameter or member 'rsgt' not described in 'i915_refct_sgt_put'
> 	drivers/gpu/drm/i915/i915_scatterlist.h:191: warning: Function parameter or member 'rsgt' not described in 'i915_refct_sgt_get'
> 	drivers/gpu/drm/i915/i915_scatterlist.h:207: warning: Function parameter or member 'rsgt' not described in '__i915_refct_sgt_init'
> 	drivers/gpu/drm/i915/i915_utils.h:291: warning: Function parameter or member 'OP' not described in '__wait_for'
> 	drivers/gpu/drm/i915/i915_utils.h:291: warning: Function parameter or member 'COND' not described in '__wait_for'
> 	drivers/gpu/drm/i915/i915_utils.h:291: warning: Function parameter or member 'US' not described in '__wait_for'
> 	drivers/gpu/drm/i915/i915_utils.h:291: warning: Function parameter or member 'Wmin' not described in '__wait_for'
> 	drivers/gpu/drm/i915/i915_utils.h:291: warning: Function parameter or member 'Wmax' not described in '__wait_for'
> 	drivers/gpu/drm/i915/i915_vma_resource.h:88: warning: Incorrect use of kernel-doc format:          * struct i915_vma_bindinfo - Information needed for async bind
> 	drivers/gpu/drm/i915/i915_vma_resource.h:123: warning: Function parameter or member 'bi' not described in 'i915_vma_resource'
> 
> Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
> 
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v3 00/37] at: https://lore.kernel.org/all/cover.1662708705.git.mchehab@kernel.org/
> 
>   drivers/gpu/drm/i915/i915_active.h       | 14 +++++++-------
>   drivers/gpu/drm/i915/i915_gem.c          | 10 ++++++----
>   drivers/gpu/drm/i915/i915_pmu.h          |  6 +++---
>   drivers/gpu/drm/i915/i915_request.h      |  4 ++--
>   drivers/gpu/drm/i915/i915_scatterlist.c  |  2 +-
>   drivers/gpu/drm/i915/i915_scatterlist.h  | 10 +++++-----
>   drivers/gpu/drm/i915/i915_utils.h        |  2 +-
>   drivers/gpu/drm/i915/i915_vma_resource.h |  2 +-
>   8 files changed, 26 insertions(+), 24 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
> diff --git a/drivers/gpu/drm/i915/i915_gem.c b/drivers/gpu/drm/i915/i915_gem.c
> index bae857d5221d..f68fa0732363 100644
> --- a/drivers/gpu/drm/i915/i915_gem.c
> +++ b/drivers/gpu/drm/i915/i915_gem.c
> @@ -439,7 +439,7 @@ i915_gem_gtt_pread(struct drm_i915_gem_object *obj,
>   }
>   
>   /**
> - * Reads data from the object referenced by handle.
> + * i915_gem_pread_ioctl - Reads data from the object referenced by handle.
>    * @dev: drm device pointer
>    * @data: ioctl data blob
>    * @file: drm file pointer
> @@ -528,7 +528,8 @@ ggtt_write(struct io_mapping *mapping,
>   }
>   
>   /**
> - * This is the fast pwrite path, where we copy the data directly from the
> + * i915_gem_gtt_pwrite_fast - This is the fast pwrite path, where we copy
> + *	the data directly from the
>    * user into the GTT, uncached.
>    * @obj: i915 GEM object
>    * @args: pwrite arguments structure
> @@ -713,7 +714,7 @@ i915_gem_shmem_pwrite(struct drm_i915_gem_object *obj,
>   }
>   
>   /**
> - * Writes data to the object referenced by handle.
> + * i915_gem_pwrite_ioctl - Writes data to the object referenced by handle.
>    * @dev: drm device
>    * @data: ioctl data blob
>    * @file: drm file
> @@ -798,7 +799,8 @@ i915_gem_pwrite_ioctl(struct drm_device *dev, void *data,
>   }
>   
>   /**
> - * Called when user space has done writes to this buffer
> + * i915_gem_sw_finish_ioctl - Called when user space has done writes to
> + *	this buffer
As per this link[1], the brief description does not have a limitation to 
match the indentation when explained over multiple lines, unlike 
function parameters.

[1] 
https://docs.kernel.org/doc-guide/kernel-doc.html#function-documentation

Therefore if you look at the function brief description over several 
lines in i915 and drm,

One of the drm apis, drm_gem_lock_reservations(), is used without 
indentation in the form below,
/**
  * drm_gem_lock_reservations - Sets up the ww context and acquires
  * the lock on an array of GEM objects.

In i915_perf.c, indentation is set as follows.

/**
  * gen8_append_oa_reports - Copies all buffered OA reports into
  *			    userspace read() buffer.

...

/**
  * gen7_append_oa_reports - Copies all buffered OA reports into
  *			    userspace read() buffer.

If there is no problem when using the same form as 
gen8_append_oa_reports when generating kernel-doc, it seems to be 
indented to match the existing i915 style. However, if there is a 
problem, I think you need to remove the indented part of the i915 code 
like the drm apis.

except i915_gem_sw_finish_ioctl  i915_gem_gtt_pwrite_fast parts, the 
rest of the parts look good to me.

Reviewed-by: Gwan-gyeong Mun <gwan-gyeong.mun@intel.com>
>    * @dev: drm device
>    * @data: ioctl data blob
>    * @file: drm file
> 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.
> diff --git a/drivers/gpu/drm/i915/i915_request.h b/drivers/gpu/drm/i915/i915_request.h
> index 47041ec68df8..66d6dee98525 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
> @@ -468,7 +468,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)
> diff --git a/drivers/gpu/drm/i915/i915_scatterlist.c b/drivers/gpu/drm/i915/i915_scatterlist.c
> index dcc081874ec8..f664c1ce02cf 100644
> --- a/drivers/gpu/drm/i915/i915_scatterlist.c
> +++ b/drivers/gpu/drm/i915/i915_scatterlist.c
> @@ -56,7 +56,7 @@ static const struct i915_refct_sgt_ops rsgt_ops = {
>   /**
>    * i915_refct_sgt_init - Initialize a struct i915_refct_sgt with default ops
>    * @rsgt: The struct i915_refct_sgt to initialize.
> - * size: The size of the underlying memory buffer.
> + * @size: The size of the underlying memory buffer.
>    */
>   void i915_refct_sgt_init(struct i915_refct_sgt *rsgt, size_t size)
>   {
> diff --git a/drivers/gpu/drm/i915/i915_scatterlist.h b/drivers/gpu/drm/i915/i915_scatterlist.h
> index 9ddb3e743a3e..79b70ae2e766 100644
> --- a/drivers/gpu/drm/i915/i915_scatterlist.h
> +++ b/drivers/gpu/drm/i915/i915_scatterlist.h
> @@ -149,7 +149,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
> +	 * @release: Free the memory of the struct i915_refct_sgt
>   	 * @ref: struct kref that is embedded in the struct i915_refct_sgt
>   	 */
>   	void (*release)(struct kref *ref);
> @@ -159,7 +159,7 @@ struct i915_refct_sgt_ops {
>    * struct i915_refct_sgt - A refcounted scatter-gather table
>    * @kref: struct kref for refcounting
>    * @table: struct sg_table holding the scatter-gather table itself. Note that
> - * @table->sgl = NULL can be used to determine whether a scatter-gather table
> + * @table->sgl == NULL can be used to determine whether a scatter-gather table
>    * is present or not.
>    * @size: The size in bytes of the underlying memory buffer
>    * @ops: The operations structure.
> @@ -173,7 +173,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)
>   {
> @@ -183,7 +183,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)
> @@ -195,7 +195,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.
> diff --git a/drivers/gpu/drm/i915/i915_utils.h b/drivers/gpu/drm/i915/i915_utils.h
> index 6c14d13364bf..85994298a74e 100644
> --- a/drivers/gpu/drm/i915/i915_utils.h
> +++ b/drivers/gpu/drm/i915/i915_utils.h
> @@ -256,7 +256,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
> diff --git a/drivers/gpu/drm/i915/i915_vma_resource.h b/drivers/gpu/drm/i915/i915_vma_resource.h
> index 06923d1816e7..e155f6f7af6f 100644
> --- a/drivers/gpu/drm/i915/i915_vma_resource.h
> +++ b/drivers/gpu/drm/i915/i915_vma_resource.h
> @@ -85,7 +85,7 @@ struct i915_vma_resource {
>   	intel_wakeref_t wakeref;
>   
>   	/**
> -	 * struct i915_vma_bindinfo - Information needed for async bind
> +	 * @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

Re: [Intel-gfx] [PATCH v3 19/37] drm/i915: stop using kernel-doc markups for something else

[Mauro Carvalho Chehab]

Em Mon, 12 Sep 2022 10:19:04 -0700
Matt Roper <matthew.d.roper@intel.com> escreveu:

> > Those *appear* to be kernel-doc markups, but they aren't, because
> > the structs themselves are not properly marked. See, for instance
> > struct intel_context.
> > 
> > scripts/kerneldoc will *only* consider what's there as a proper
> > comment if you add:
> > 
> > 	/**
> > 	 * struct intel_context - describes an i915 context
> > 	 * <add a proper description for it>
> > 	 */
> > 	struct intel_context {
> > 		union {
> > 			/** @ref: a kernel object reference */
> > 	                struct kref ref; /* no kref_get_unless_zero()! */
> > 			/** @rcu: a rcu header */
> > 	                struct rcu_head rcu;
> > 	        };
> > 		...
> > 	}
> > 
> > Describing all fields inside the struct. Just placing
> > 	/** something */
> > on some random places in the middle doesn't make it a kernel-doc.  
> 
> Right, what we have today is incomplete/incorrect.  But I think we
> should be fixing that by adding the missing documentation on the
> structure, rather than giving up and removing the kerneldoc.  The end
> goal should be to have proper generated documentation, not just silence
> the warnings while leaving the actual output incomplete.

The end goal is to have *real* kernel-doc markups, not fake ones.
We're aiming towards there, where the first step is to get rid of the
ones that just pretend to be kernel-doc without really being validated
in order to check if they produce a valid content.

See, what we have so far are just comments. Some examples from this
patch:

	/** Powers down the TV out block, and DAC0-3 */
	 #define CH7017_TV_POWER_DOWN_EN		(1 << 5)

Currently, kernel-doc doesn't have any markup for not-function defines.

What we do to document this at kernel-doc is to either:

1. convert to an enum;
2. embed it inside some struct (or function) definition.

Other examples: this is not a Kernel-doc markup:

	/** @file
	  * driver for the Chrontel 7xxx DVI chip over DVO.
	  */

Neither this:

	/**
 	 * active: Active tracker for the rq activity (inc. external) on this
 	 * intel_context object.
 	 */
 
In summary, what happens is that those "/**" tags removed on this patch are
just pretending to be Kernel-doc, but they aren't anything. See, when a newbie
starts programming in C code, without having a compiler, lots of syntax
issues will happen. When they try to compile their code, hundreds or errors
and warnings happen. That's basically what it is happening here.

See, the very basic syntax thing is missing: just like a C file requires
that all codes to be inside functions, a kernel-doc field description 
requires a kernel-doc markup for the struct/function/enum/union that
contains it.

-

Now, I fully agree that the end goal is to have proper kernel-doc markups.

Adding those require a lot of archaeological work, looking at the git
commits which introduced the changes. Patch 34/37, for instance, does
that for struct drm_i915_gem_object:

	https://lists.freedesktop.org/archives/intel-gfx/2022-September/305736.html

See, besides adding a real Kernel-doc markup for the struct:

	+/**
	+ * struct drm_i915_gem_object - describes an i915 GEM object
	+ */
	 struct drm_i915_gem_object {

It had to fix several sintax and semantic mistakes:

Typos:

	/**
-	 * @shared_resv_from: The object shares the resv from this vm.
+	 * @shares_resv_from: The object shares the resv from this vm.
 	 */

Invalid kernel-doc markups:

	 	/**
	-	 * @mem_flags - Mutable placement-related flags
	+	 * @mem_flags: Mutable placement-related flags

Kernel markups that miss that they're on an embedded struct inside
the main one (thus those are also invalid kernel-doc markups):

                /**
-                * @shrink_pin: Prevents the pages from being made visible to
+                * @mm.shrink_pin: Prevents the pages from being made visible to


Etc.

Thanks,
Mauro

Re: [Intel-gfx] [PATCH v3 01/37] drm/i915: fix kernel-doc trivial warnings on i915/*.[ch] files

[Mauro Carvalho Chehab]

Em Fri, 16 Sep 2022 17:03:27 +0300
Gwan-gyeong Mun <gwan-gyeong.mun@intel.com> escreveu:

> >   /**
> > - * Called when user space has done writes to this buffer
> > + * i915_gem_sw_finish_ioctl - Called when user space has done writes to
> > + *		this buffer  
> As per this link[1], the brief description does not have a limitation to 
> match the indentation when explained over multiple lines, unlike 
> function parameters.
> 
> [1] 
> https://docs.kernel.org/doc-guide/kernel-doc.html#function-documentation
> 
> Therefore if you look at the function brief description over several 
> lines in i915 and drm,
> 
> One of the drm apis, drm_gem_lock_reservations(), is used without 
> indentation in the form below,
> /**
>   * drm_gem_lock_reservations - Sets up the ww context and acquires
>   * the lock on an array of GEM objects.
> 
> In i915_perf.c, indentation is set as follows.
> 
> /**
>   * gen8_append_oa_reports - Copies all buffered OA reports into
>   *			    userspace read() buffer.
> 
> ...
> 
> /**
>   * gen7_append_oa_reports - Copies all buffered OA reports into
>   *			    userspace read() buffer.
> 
> If there is no problem when using the same form as 
> gen8_append_oa_reports when generating kernel-doc, it seems to be 
> indented to match the existing i915 style. However, if there is a 
> problem, I think you need to remove the indented part of the i915 code 
> like the drm apis.
> 
> except i915_gem_sw_finish_ioctl  i915_gem_gtt_pwrite_fast parts, the 
> rest of the parts look good to me.

There's no rule about either indent or not. IMO, it makes easier for
humans to read when indent is used.

Yet, I'd say that, right now, 50% of multi-line comments within the
kernel has indent. So, it is more like a matter of personal developer's
preference at the moment.

> 
> Reviewed-by: Gwan-gyeong Mun <gwan-gyeong.mun@intel.com>

Thanks,
Mauro

Re: [Intel-gfx] [PATCH v3 27/37] docs: gpu: i915.rst: gt: add more kernel-doc markups

[Mauro Carvalho Chehab]

Em Fri, 9 Sep 2022 05:06:46 -0400
Rodrigo Vivi <rodrigo.vivi@intel.com> escreveu:

> On Fri, Sep 09, 2022 at 09:34:34AM +0200, Mauro Carvalho Chehab wrote:
> > There are several documented GT kAPI that aren't currently part
> > of the docs. Add them, as this allows identifying issues with
> > badly-formatted tags.
> >  
> 
> In i915's commits we usually add a version history here
> to indicate what changed from the previous submission,
> something like
> 
> v2: re-organizing the blocks to group gtt stuff.

Placing patch versioning at the email's detailed explanation is
actually a violation of the Kernel coding style. See:

	https://www.kernel.org/doc/html/latest/process/submitting-patches.html#the-canonical-patch-format

	"The explanation body will be committed to the permanent source changelog, 
	 so should make sense to a competent reader who has long since forgotten 
	 the immediate details of the discussion that might have led to this patch."

Such versions should either go at the cover letter - which is the usual
convention on big series, or after "---", as explained at the same
document:

	"The --- marker line serves the essential purpose of marking for patch
	 handling tools where the changelog message ends.

	 ...

	Other comments relevant only to the moment or the maintainer, not suitable
	for the permanent changelog, should also go here. A good example of such 
	comments might be patch changelogs which describe what has changed between
	the v1 and v2 version of the patch."


> 
> that helps reviewers to know if their change requested was
> addressed or not.

True. Next time, I'll add a version at the cover letter.

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

Thank you!
Mauro