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 ;-)
---
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.
Jiapeng Chong (3):
drm/i915/gvt: Fix kernel-doc for intel_gvt_switch_mmio()
drm/i915/gvt: Fix kernel-doc for intel_vgpu_default_mmio_write
drm/i915/gvt: Fix kernel-doc for intel_vgpu_*_resource()
Mauro Carvalho Chehab (36):
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
Documentation/gpu/i915.rst | 288 ++++++++++++++++++
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 +-
.../drm/i915/display/intel_display_debugfs.c | 2 +-
.../drm/i915/display/intel_display_power.c | 2 +-
.../drm/i915/display/intel_display_types.h | 2 +-
.../drm/i915/display/intel_dp_link_training.c | 2 +
drivers/gpu/drm/i915/display/intel_dvo_dev.h | 6 +-
drivers/gpu/drm/i915/display/intel_fb.c | 2 +-
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 | 63 ++--
drivers/gpu/drm/i915/gt/intel_engine_cs.c | 4 +-
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 | 62 ++++
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_fwif.h | 2 +-
.../gpu/drm/i915/gt/uc/intel_guc_hwconfig.c | 5 +-
drivers/gpu/drm/i915/gvt/aperture_gm.c | 4 +-
drivers/gpu/drm/i915/gvt/cfg_space.c | 2 +-
drivers/gpu/drm/i915/gvt/dmabuf.h | 2 +-
drivers/gpu/drm/i915/gvt/handlers.c | 2 +-
drivers/gpu/drm/i915/gvt/mmio_context.c | 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_deps.c | 4 +-
drivers/gpu/drm/i915/i915_drm_client.h | 2 +-
drivers/gpu/drm/i915/i915_drv.h | 30 +-
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_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 +-
68 files changed, 795 insertions(+), 327 deletions(-)
--
2.36.1
Fix those kernel-doc warnings:
drivers/gpu/drm/i915/intel_region_ttm.c:199: warning: Function parameter or member 'offset' not described in 'intel_region_ttm_resource_alloc'
drivers/gpu/drm/i915/i915_vma_resource.h:123: warning: Function parameter or member 'wakeref' not described in 'i915_vma_resource'
drivers/gpu/drm/i915/i915_vma.c:1703: warning: Function parameter or member 'vma' not described in 'i915_vma_destroy_locked'
drivers/gpu/drm/i915/i915_vma.c:751: warning: Function parameter or member 'ww' not described in 'i915_vma_insert'
drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:159: warning: Function parameter or member 'gt' not described in 'intel_gt_fini_hwconfig'
drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:146: warning: Function parameter or member 'gt' not described in 'intel_gt_init_hwconfig'
drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:113: warning: expecting prototype for intel_guc_hwconfig_init(). Prototype was for guc_hwconfig_init() instead
drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:113: warning: Function parameter or member 'gt' not described in 'guc_hwconfig_init'
drivers/gpu/drm/i915/gt/intel_engine_types.h:276: warning: Function parameter or member 'preempt_hang' not described in 'intel_engine_execlists'
That are due undocumented parameters.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
drivers/gpu/drm/i915/gt/intel_engine_types.h | 1 +
drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c | 5 ++++-
drivers/gpu/drm/i915/i915_vma.c | 2 ++
drivers/gpu/drm/i915/i915_vma_resource.h | 1 +
drivers/gpu/drm/i915/intel_region_ttm.c | 3 ++-
5 files changed, 10 insertions(+), 2 deletions(-)
diff --git a/drivers/gpu/drm/i915/gt/intel_engine_types.h b/drivers/gpu/drm/i915/gt/intel_engine_types.h
index 633a7e5dba3b..7c5ad9071fe7 100644
--- a/drivers/gpu/drm/i915/gt/intel_engine_types.h
+++ b/drivers/gpu/drm/i915/gt/intel_engine_types.h
@@ -271,6 +271,7 @@ struct intel_engine_execlists {
*/
u8 csb_head;
+ /* private: Used only in selftests */
I915_SELFTEST_DECLARE(struct st_preempt_hang preempt_hang;)
};
diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c b/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
index 4781fccc2687..76f7447302a6 100644
--- a/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
+++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
@@ -103,7 +103,8 @@ static bool has_table(struct drm_i915_private *i915)
}
/**
- * intel_guc_hwconfig_init - Initialize the HWConfig
+ * guc_hwconfig_init - Initialize the HWConfig
+ * @gt: GT structure
*
* Retrieve the HWConfig table from the GuC and save it locally.
* It can then be queried on demand by other users later on.
@@ -138,6 +139,7 @@ static int guc_hwconfig_init(struct intel_gt *gt)
/**
* intel_gt_init_hwconfig - Initialize the HWConfig if available
+ * @gt: GT structure
*
* Retrieve the HWConfig table if available on the current platform.
*/
@@ -151,6 +153,7 @@ int intel_gt_init_hwconfig(struct intel_gt *gt)
/**
* intel_gt_fini_hwconfig - Finalize the HWConfig
+ * @gt: GT structure
*
* Free up the memory allocation holding the table.
*/
diff --git a/drivers/gpu/drm/i915/i915_vma.c b/drivers/gpu/drm/i915/i915_vma.c
index ef3b04c7e153..ddf348c597b0 100644
--- a/drivers/gpu/drm/i915/i915_vma.c
+++ b/drivers/gpu/drm/i915/i915_vma.c
@@ -733,6 +733,7 @@ bool i915_gem_valid_gtt_space(struct i915_vma *vma, unsigned long color)
/**
* i915_vma_insert - finds a slot for the vma in its address space
* @vma: the vma
+ * @ww: An optional struct i915_gem_ww_ctx
* @size: requested size in bytes (can be larger than the VMA)
* @alignment: required alignment
* @flags: mask of PIN_* flags to use
@@ -1675,6 +1676,7 @@ static void release_references(struct i915_vma *vma, struct intel_gt *gt,
/**
* i915_vma_destroy_locked - Remove all weak reference to the vma and put
* the initial reference.
+ * @vma: VMA to destroy
*
* This function should be called when it's decided the vma isn't needed
* anymore. The caller must assure that it doesn't race with another lookup
diff --git a/drivers/gpu/drm/i915/i915_vma_resource.h b/drivers/gpu/drm/i915/i915_vma_resource.h
index 14a0327b2080..a15271d96b7e 100644
--- a/drivers/gpu/drm/i915/i915_vma_resource.h
+++ b/drivers/gpu/drm/i915/i915_vma_resource.h
@@ -49,6 +49,7 @@ struct i915_page_sizes {
* @__subtree_last: Interval tree private member.
* @vm: non-refcounted pointer to the vm. This is for internal use only and
* this member is cleared after vm_resource unbind.
+ * @wakeref: wakeref used for runtime PM reference.
* @mr: The memory region of the object pointed to by the vma.
* @ops: Pointer to the 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 6873808a7015..471a70c50b2c 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.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
Documentation/gpu/i915.rst | 41 ++++++++++++++++++++++++++++++++++++++
1 file changed, 41 insertions(+)
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 70f2f4826eba..3ee121a0ea62 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.36.1
Both intel_runtime_pm.h and intel_pm.c contains kAPI for
runtime PM. So, add them to the documentation.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
Documentation/gpu/i915.rst | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 3ee121a0ea62..c32409c03d32 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.36.1
This is a large struct used to describe gem objects. It is
currently partially documented. Finish its documentation, filling
the gaps from git logs.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
.../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 ceed0d220ce3..8c09e493590d 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 | \
@@ -343,15 +398,21 @@ struct drm_i915_gem_object {
#define I915_BO_PROTECTED BIT(9)
#define I915_BO_WAS_BOUND_BIT 10
/**
- * @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.
*
@@ -400,7 +461,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
@@ -423,7 +484,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.
@@ -509,23 +570,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.
@@ -536,7 +603,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.
*
@@ -548,13 +615,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.
@@ -572,94 +639,143 @@ 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;
} 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.36.1
This file is licensed with MIT license. Change its license text
to use SPDX.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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.36.1
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().
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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.36.1
There are several trivial warnings there, due to trivial things:
- lack of function name at the kerneldoc markup;
- undocumented structs with kernel-doc markups;
- wrong parameter syntax.
Fix such warnings:
drivers/gpu/drm/i915/gt/intel_context.h:107: warning: Function parameter or member 'ce' not described in 'intel_context_lock_pinned'
drivers/gpu/drm/i915/gt/intel_context.h:122: warning: Function parameter or member 'ce' not described in 'intel_context_is_pinned'
drivers/gpu/drm/i915/gt/intel_context.h:141: warning: Function parameter or member 'ce' not described in 'intel_context_unlock_pinned'
drivers/gpu/drm/i915/gt/intel_gtt.h:510: warning: Function parameter or member 'vm' not described in 'i915_vm_resv_put'
drivers/gpu/drm/i915/gt/intel_gtt.h:510: warning: Excess function parameter 'resv' description in 'i915_vm_resv_put'
drivers/gpu/drm/i915/gt/intel_gtt.h:615: warning: Function parameter or member 'i915' not described in 'i915_ggtt_mark_pte_lost'
drivers/gpu/drm/i915/gt/intel_gtt.h:615: warning: Function parameter or member 'val' not described in 'i915_ggtt_mark_pte_lost'
drivers/gpu/drm/i915/gt/intel_rps.c:2343: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* Tells the intel_ips driver that the i915 driver is now loaded, if
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'size' not described in '__guc_capture_bufstate'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'data' not described in '__guc_capture_bufstate'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'rd' not described in '__guc_capture_bufstate'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'wr' not described in '__guc_capture_bufstate'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'link' not described in '__guc_capture_parsed_output'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'is_partial' not described in '__guc_capture_parsed_output'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'eng_class' not described in '__guc_capture_parsed_output'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'eng_inst' not described in '__guc_capture_parsed_output'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'guc_id' not described in '__guc_capture_parsed_output'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'lrca' not described in '__guc_capture_parsed_output'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'reginfo' not described in '__guc_capture_parsed_output'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:63: warning: wrong kernel-doc identifier on line:
* struct guc_debug_capture_list_header / struct guc_debug_capture_list
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:81: warning: wrong kernel-doc identifier on line:
* struct __guc_mmio_reg_descr / struct __guc_mmio_reg_descr_group
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:106: warning: wrong kernel-doc identifier on line:
* struct guc_state_capture_header_t / struct guc_state_capture_t /
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'is_valid' not described in '__guc_capture_ads_cache'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'ptr' not described in '__guc_capture_ads_cache'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'size' not described in '__guc_capture_ads_cache'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'status' not described in '__guc_capture_ads_cache'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:217: warning: Function parameter or member 'ads_null_cache' not described in 'intel_guc_state_capture'
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:217: warning: Function parameter or member 'max_mmio_per_node' not described in 'intel_guc_state_capture'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'marker' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'read_ptr' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'write_ptr' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'size' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'sampled_write_ptr' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'wrap_offset' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'flush_to_file' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'buffer_full_cnt' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'reserved' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'flags' not described in 'guc_log_buffer_state'
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'version' not described in 'guc_log_buffer_state'
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
drivers/gpu/drm/i915/gt/intel_context.h | 6 +++---
drivers/gpu/drm/i915/gt/intel_engine_cs.c | 4 ++--
drivers/gpu/drm/i915/gt/intel_gtt.h | 6 +++---
drivers/gpu/drm/i915/gt/intel_rps.c | 4 ++--
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h | 14 +++++++-------
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h | 2 +-
6 files changed, 18 insertions(+), 18 deletions(-)
diff --git a/drivers/gpu/drm/i915/gt/intel_context.h b/drivers/gpu/drm/i915/gt/intel_context.h
index 8e2d70630c49..91c092d5deae 100644
--- a/drivers/gpu/drm/i915/gt/intel_context.h
+++ b/drivers/gpu/drm/i915/gt/intel_context.h
@@ -96,7 +96,7 @@ void intel_context_bind_parent_child(struct intel_context *parent,
/**
* intel_context_lock_pinned - Stablises the 'pinned' status of the HW context
- * @ce - the context
+ * @ce: the context
*
* Acquire a lock on the pinned status of the HW context, such that the context
* can neither be bound to the GPU or unbound whilst the lock is held, i.e.
@@ -110,7 +110,7 @@ static inline int intel_context_lock_pinned(struct intel_context *ce)
/**
* intel_context_is_pinned - Reports the 'pinned' status
- * @ce - the context
+ * @ce: the context
*
* While in use by the GPU, the context, along with its ring and page
* tables is pinned into memory and the GTT.
@@ -132,7 +132,7 @@ static inline void intel_context_cancel_request(struct intel_context *ce,
/**
* intel_context_unlock_pinned - Releases the earlier locking of 'pinned' status
- * @ce - the context
+ * @ce: the context
*
* Releases the lock earlier acquired by intel_context_unlock_pinned().
*/
diff --git a/drivers/gpu/drm/i915/gt/intel_engine_cs.c b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
index 37fa813af766..da225f5db2a4 100644
--- a/drivers/gpu/drm/i915/gt/intel_engine_cs.c
+++ b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
@@ -1197,7 +1197,7 @@ create_kernel_context(struct intel_engine_cs *engine)
}
/**
- * intel_engines_init_common - initialize cengine state which might require hw access
+ * engine_init_common - initialize cengine state which might require hw access
* @engine: Engine to initialize.
*
* Initializes @engine@ structure members shared between legacy and execlists
@@ -1278,7 +1278,7 @@ int intel_engines_init(struct intel_gt *gt)
}
/**
- * intel_engines_cleanup_common - cleans up the engine state created by
+ * intel_engine_cleanup_common - cleans up the engine state created by
* the common initiailizers.
* @engine: Engine to cleanup.
*
diff --git a/drivers/gpu/drm/i915/gt/intel_gtt.h b/drivers/gpu/drm/i915/gt/intel_gtt.h
index e639434e97fd..fca8eedee1d8 100644
--- a/drivers/gpu/drm/i915/gt/intel_gtt.h
+++ b/drivers/gpu/drm/i915/gt/intel_gtt.h
@@ -503,7 +503,7 @@ static inline void i915_vm_put(struct i915_address_space *vm)
/**
* i915_vm_resv_put - Release a reference on the vm's reservation lock
- * @resv: Pointer to a reservation lock obtained from i915_vm_resv_get()
+ * @vm: The vm whose reservation lock was obtained from i915_vm_resv_get()
*/
static inline void i915_vm_resv_put(struct i915_address_space *vm)
{
@@ -604,8 +604,8 @@ void i915_ggtt_resume(struct i915_ggtt *ggtt);
/**
* i915_ggtt_mark_pte_lost - Mark ggtt ptes as lost or clear such a marking
- * @i915 The device private.
- * @val whether the ptes should be marked as lost.
+ * @i915: The device private.
+ * @val: whether the ptes should be marked as lost.
*
* In some cases pte content is retained across suspend, but typically lost
* across hibernate. Typically they should be marked as lost on
diff --git a/drivers/gpu/drm/i915/gt/intel_rps.c b/drivers/gpu/drm/i915/gt/intel_rps.c
index fb3f57ee450b..8aefc427e06e 100644
--- a/drivers/gpu/drm/i915/gt/intel_rps.c
+++ b/drivers/gpu/drm/i915/gt/intel_rps.c
@@ -2339,8 +2339,8 @@ bool rps_read_mask_mmio(struct intel_rps *rps,
static struct drm_i915_private __rcu *ips_mchdev;
/**
- * Tells the intel_ips driver that the i915 driver is now loaded, if
- * IPS got loaded first.
+ * ips_ping_for_i915_load - Tells the intel_ips driver that the i915 driver
+ * is now loaded, if IPS got loaded first.
*
* This awkward dance is so that neither module has to depend on the
* other in order for IPS to do the appropriate communication of
diff --git a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
index 3624abfd22d1..58f93226b1c1 100644
--- a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
+++ b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
@@ -12,7 +12,7 @@
struct intel_guc;
struct file;
-/**
+/*
* struct __guc_capture_bufstate
*
* Book-keeping structure used to track read and write pointers
@@ -26,7 +26,7 @@ struct __guc_capture_bufstate {
u32 wr;
};
-/**
+/*
* struct __guc_capture_parsed_output - extracted error capture node
*
* A single unit of extracted error-capture output data grouped together
@@ -58,7 +58,7 @@ struct __guc_capture_parsed_output {
#define GCAP_PARSED_REGLIST_INDEX_ENGINST BIT(GUC_CAPTURE_LIST_TYPE_ENGINE_INSTANCE)
};
-/**
+/*
* struct guc_debug_capture_list_header / struct guc_debug_capture_list
*
* As part of ADS registration, these header structures (followed by
@@ -76,7 +76,7 @@ struct guc_debug_capture_list {
struct guc_mmio_reg regs[0];
} __packed;
-/**
+/*
* struct __guc_mmio_reg_descr / struct __guc_mmio_reg_descr_group
*
* intel_guc_capture module uses these structures to maintain static
@@ -101,7 +101,7 @@ struct __guc_mmio_reg_descr_group {
struct __guc_mmio_reg_descr *extlist; /* only used for steered registers */
};
-/**
+/*
* struct guc_state_capture_header_t / struct guc_state_capture_t /
* guc_state_capture_group_header_t / guc_state_capture_group_t
*
@@ -148,7 +148,7 @@ struct guc_state_capture_group_t {
struct guc_state_capture_t capture_entries[0];
} __packed;
-/**
+/*
* struct __guc_capture_ads_cache
*
* A structure to cache register lists that were populated and registered
@@ -162,7 +162,7 @@ struct __guc_capture_ads_cache {
int status;
};
-/**
+/*
* struct intel_guc_state_capture
*
* Internal context of the intel_guc_capture module.
diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h b/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h
index b3c9a9327f76..237019e98ede 100644
--- a/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h
+++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h
@@ -360,7 +360,7 @@ enum guc_log_buffer_type {
GUC_MAX_LOG_BUFFER
};
-/**
+/*
* struct guc_log_buffer_state - GuC log buffer state
*
* Below state structure is used for coordination of retrieval of GuC firmware
--
2.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
Documentation/gpu/i915.rst | 38 ++++++++++++++++++++++++++++++++++++++
1 file changed, 38 insertions(+)
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index c32409c03d32..974754586be8 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -615,6 +615,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.36.1
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")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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 32e92651ef7c..7790f97b26db 100644
--- a/drivers/gpu/drm/i915/i915_gpu_error.c
+++ b/drivers/gpu/drm/i915/i915_gpu_error.c
@@ -2096,7 +2096,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.36.1
From: Jiapeng Chong <[email protected]>
Fix the following W=1 kernel warnings:
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.
Reported-by: Abaci Robot <[email protected]>
Signed-off-by: Jiapeng Chong <[email protected]>
Acked-by: Zhenyu Wang <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
drivers/gpu/drm/i915/gvt/mmio_context.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/gpu/drm/i915/gvt/mmio_context.c b/drivers/gpu/drm/i915/gvt/mmio_context.c
index c85bafe7539e..1c6e941c9666 100644
--- a/drivers/gpu/drm/i915/gvt/mmio_context.c
+++ b/drivers/gpu/drm/i915/gvt/mmio_context.c
@@ -546,7 +546,7 @@ static void switch_mmio(struct intel_vgpu *pre,
}
/**
- * intel_gvt_switch_render_mmio - switch mmio context of specific engine
+ * intel_gvt_switch_mmio - switch mmio context of specific engine
* @pre: the last vGPU that own the engine
* @next: the vGPU to switch to
* @engine: the engine
--
2.36.1
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 <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
Documentation/gpu/i915.rst | 43 +++++++++++++++++++++++++++++++++++++-
1 file changed, 42 insertions(+), 1 deletion(-)
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 2ad7941a79f2..afd8c0e3c689 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,48 @@ 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
+
+GT context
+----------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_context.h
+
+Graphics Translation Tables
+---------------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt.c
+
+Other GT functionality
+----------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gsc.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.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.36.1
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 <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
Documentation/gpu/i915.rst | 87 ++++++++++++++++++++++++++++++++++++++
1 file changed, 87 insertions(+)
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 974754586be8..6bb50edc6d79 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,10 @@ Runtime Power Management
.. kernel-doc:: drivers/gpu/drm/i915/intel_pm.c
+.. kernel-doc:: drivers/gpu/drm/i915/intel_wakeref.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_active.h
+
Interrupt Handling
------------------
@@ -44,6 +53,28 @@ Interrupt Handling
.. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
:functions: intel_runtime_pm_enable_interrupts
+Error handling
+--------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_gpu_error.c
+
+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)
-------------------------------
@@ -109,6 +140,54 @@ Workarounds
.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c
:doc: Hardware workarounds
+32-bits compatible ioctl Logic
+------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_ioc32.c
+
+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
+
+Ancillary routines
+------------------
+
+.. 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
+
+
+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
=========================
@@ -618,6 +697,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
@@ -627,6 +712,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.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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 27c55027387a..fa5a678018d9 100644
--- a/drivers/gpu/drm/i915/i915_vma_resource.c
+++ b/drivers/gpu/drm/i915/i915_vma_resource.c
@@ -283,7 +283,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,
@@ -367,7 +367,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.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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 | 63 +++++++++----------
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 | 30 ++++-----
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 0da9b208d56e..100715d4c2fb 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 19122bc6d2ab..7925f5ffaa68 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 d2d75d9c0c8d..351515db4ef5 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,75 +210,75 @@ 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: head pointer in work queue */
+ /* @wqi_head: head pointer in work queue */
u16 wqi_head;
- /** @wqi_tail: tail pointer in work queue */
+ /* @wqi_tail: tail pointer in work queue */
u16 wqi_tail;
- /**
+ /*
* @parent_page: page in context state (ce->state) used
* by parent for work queue, process descriptor
*/
@@ -288,18 +287,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 df708802889d..905f547094ca 100644
--- a/drivers/gpu/drm/i915/gt/intel_gt_types.h
+++ b/drivers/gpu/drm/i915/gt/intel_gt_types.h
@@ -93,7 +93,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
@@ -117,7 +117,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.
@@ -143,12 +143,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
@@ -156,7 +156,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.
@@ -222,7 +222,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 d25647be25d1..91a3aa49e918 100644
--- a/drivers/gpu/drm/i915/i915_drv.h
+++ b/drivers/gpu/drm/i915/i915_drv.h
@@ -224,37 +224,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 delayed_work 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;
@@ -266,7 +266,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.
*/
@@ -384,7 +384,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
@@ -392,7 +392,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;
@@ -421,11 +421,11 @@ struct drm_i915_private {
struct intel_gmbus *gmbus[GMBUS_NUM_PINS];
- /** gmbus_mutex protects against concurrent usage of the single hw gmbus
+ /* gmbus_mutex protects against concurrent usage of the single hw gmbus
* controller on different i2c buses. */
struct mutex gmbus_mutex;
- /**
+ /*
* Base address of where the gmbus and gpio blocks are located (either
* on PCH or on SoC for platforms without PCH).
*/
@@ -454,7 +454,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];
@@ -503,7 +503,7 @@ struct drm_i915_private {
struct intel_global_obj obj;
} dbuf;
- /**
+ /*
* wq - Driver workqueue for GEM.
*
* NOTE: Work items scheduled here are not allowed to grab any modeset
@@ -554,7 +554,7 @@ struct drm_i915_private {
/* Kernel Modesetting */
- /**
+ /*
* dpll and cdclk state is protected by connection_mutex
* dpll.lock serializes intel_{prepare,enable,disable}_shared_dpll.
* Must be global rather than per dpll, because on some platforms plls
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 55a143b92d10..112a646c78ed 100644
--- a/drivers/gpu/drm/i915/i915_gpu_error.h
+++ b/drivers/gpu/drm/i915/i915_gpu_error.h
@@ -207,10 +207,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.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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.36.1
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
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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 dad3a6054335..a0fc6d356588 100644
--- a/drivers/gpu/drm/i915/gvt/cfg_space.c
+++ b/drivers/gpu/drm/i915/gvt/cfg_space.c
@@ -243,7 +243,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.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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 6c3954479047..1e35eb01742b 100644
--- a/drivers/gpu/drm/i915/display/intel_display_debugfs.c
+++ b/drivers/gpu/drm/i915/display/intel_display_debugfs.c
@@ -2229,7 +2229,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 589af257edeb..fd6b71160a06 100644
--- a/drivers/gpu/drm/i915/display/intel_display_power.c
+++ b/drivers/gpu/drm/i915/display/intel_display_power.c
@@ -685,7 +685,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 6773840f6cc7..7ce0cbe0de05 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.36.1
This file is licensed with MIT license. Change its license text
to use SPDX.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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 9feaf1a589f3..23a269fcf6ca 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.36.1
From: Jiapeng Chong <[email protected]>
Fix the following W=1 kernel warnings:
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.
Reported-by: Abaci Robot <[email protected]>
Signed-off-by: Jiapeng Chong <[email protected]>
Acked-by: Zhenyu Wang <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
drivers/gpu/drm/i915/gvt/handlers.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/gpu/drm/i915/gvt/handlers.c b/drivers/gpu/drm/i915/gvt/handlers.c
index beea5895e499..9c8dde079cb4 100644
--- a/drivers/gpu/drm/i915/gvt/handlers.c
+++ b/drivers/gpu/drm/i915/gvt/handlers.c
@@ -3052,7 +3052,7 @@ int intel_vgpu_default_mmio_read(struct intel_vgpu *vgpu, unsigned int offset,
}
/**
- * intel_t_default_mmio_write - default MMIO write handler
+ * intel_vgpu_default_mmio_write() - default MMIO write handler
* @vgpu: a vGPU
* @offset: access offset
* @p_data: write data buffer
--
2.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
Documentation/gpu/i915.rst | 22 ++++++++++++++++++++++
1 file changed, 22 insertions(+)
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index afd8c0e3c689..70f2f4826eba 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -596,6 +596,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.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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 1674b0c5802b..49d7841ba979 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 6f0a3ce35567..222608df66df 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.36.1
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'
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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 9aad84059d56..9843831c9b37 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c
+++ b/drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c
@@ -123,8 +123,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.
@@ -188,7 +189,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.36.1
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 <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
Documentation/gpu/i915.rst | 2 +
drivers/gpu/drm/i915/gt/intel_gt_pm.h | 62 +++++++++++++++++++++++++++
2 files changed, 64 insertions(+)
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 6bb50edc6d79..9862d504df4d 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -709,6 +709,8 @@ Table Manager (TTM)
.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_pm.h
+
Graphics Execution Manager (GEM)
--------------------------------
diff --git a/drivers/gpu/drm/i915/gt/intel_gt_pm.h b/drivers/gpu/drm/i915/gt/intel_gt_pm.h
index bc898df7a48c..a8ea6846980a 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(>->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(>->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(>->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(>->wakeref);
@@ -36,6 +72,14 @@ static inline void intel_gt_pm_might_get(struct intel_gt *gt)
intel_wakeref_might_get(>->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(>->wakeref);
@@ -51,10 +95,28 @@ static inline void intel_gt_pm_might_put(struct intel_gt *gt)
intel_wakeref_might_put(>->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)
+/**
+ * intel_gt_pm_wait_for_idle: Wait until the runtime PM reference is idle
+ * @gt: pointer to the graphics engine which contains the PM reference
+ *
+ * Wait for the earlier asynchronous release of the runtime PM reference. Note
+ * this will wait for any third party as well, so make sure you only wait
+ * when you have control over the GT runtime PM and trust no one else is
+ * acquiring it.
+ *
+ * Return: 0 on success, error code if killed.
+ */
static inline int intel_gt_pm_wait_for_idle(struct intel_gt *gt)
{
return intel_wakeref_wait_for_idle(>->wakeref);
--
2.36.1
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'
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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 702e5b89be22..41e83d078a70 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 f63b50b71e10..128fab326bb0 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 b13e4cdea923..0b8bf4be4330 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 c10d68cdc3ca..cae684c40d4f 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 5d8427caa2ba..14a0327b2080 100644
--- a/drivers/gpu/drm/i915/i915_vma_resource.h
+++ b/drivers/gpu/drm/i915/i915_vma_resource.h
@@ -84,7 +84,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.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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 41e83d078a70..0ca4bb08ea78 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.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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 f06babdb3a8c..d3393752b04b 100644
--- a/drivers/gpu/drm/i915/intel_pm.c
+++ b/drivers/gpu/drm/i915/intel_pm.c
@@ -684,18 +684,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
@@ -731,13 +733,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.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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 b191915ab351..fe72c75a9c79 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.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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 0b8bf4be4330..5b5c4eee0f44 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.36.1
Currently, functions inside GuC aren't presented as part of the
GuC documentation.
Add them.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
Documentation/gpu/i915.rst | 3 +++
1 file changed, 3 insertions(+)
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 9862d504df4d..8c21a90d8b5a 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -768,6 +768,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.36.1
The doc markup should not end with ":", as it would generate a
warning on Sphinx while generating the cross-reference tag.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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 ccec4055fde3..b5dd43405355 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_object.c
+++ b/drivers/gpu/drm/i915/gem/i915_gem_object.c
@@ -820,6 +820,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.36.1
commit d1b48c1e7184 ("drm/i915: Replace execbuf vma ht with an idr")
added a rbtree list to allow searching for obj/ctx.
Document it.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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 5cf36a130061..ceed0d220ce3 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.36.1
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.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
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.36.1
On Wed, Jul 13, 2022 at 09:11:49AM +0100, Mauro Carvalho Chehab wrote:
> From: Jiapeng Chong <[email protected]>
>
> Fix the following W=1 kernel warnings:
>
> 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.
>
> Reported-by: Abaci Robot <[email protected]>
> Signed-off-by: Jiapeng Chong <[email protected]>
> Acked-by: Zhenyu Wang <[email protected]>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> drivers/gpu/drm/i915/gvt/mmio_context.c | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/drivers/gpu/drm/i915/gvt/mmio_context.c b/drivers/gpu/drm/i915/gvt/mmio_context.c
> index c85bafe7539e..1c6e941c9666 100644
> --- a/drivers/gpu/drm/i915/gvt/mmio_context.c
> +++ b/drivers/gpu/drm/i915/gvt/mmio_context.c
> @@ -546,7 +546,7 @@ static void switch_mmio(struct intel_vgpu *pre,
> }
>
> /**
> - * intel_gvt_switch_render_mmio - switch mmio context of specific engine
> + * intel_gvt_switch_mmio - switch mmio context of specific engine
> * @pre: the last vGPU that own the engine
> * @next: the vGPU to switch to
> * @engine: the engine
> --
> 2.36.1
>
On Wed, Jul 13, 2022 at 09:11:52AM +0100, 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'
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
functions should change to have "()" or not?
whatever you decide, keep it consistent and feel free to use
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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 702e5b89be22..41e83d078a70 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 f63b50b71e10..128fab326bb0 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 b13e4cdea923..0b8bf4be4330 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 c10d68cdc3ca..cae684c40d4f 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 5d8427caa2ba..14a0327b2080 100644
> --- a/drivers/gpu/drm/i915/i915_vma_resource.h
> +++ b/drivers/gpu/drm/i915/i915_vma_resource.h
> @@ -84,7 +84,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.36.1
>
On Wed, Jul 13, 2022 at 05:54:44PM -0400, Rodrigo Vivi wrote:
> On Wed, Jul 13, 2022 at 09:11:49AM +0100, Mauro Carvalho Chehab wrote:
> > From: Jiapeng Chong <[email protected]>
> >
> > Fix the following W=1 kernel warnings:
> >
> > 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.
> >
> > Reported-by: Abaci Robot <[email protected]>
> > Signed-off-by: Jiapeng Chong <[email protected]>
> > Acked-by: Zhenyu Wang <[email protected]>
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
>
> Reviewed-by: Rodrigo Vivi <[email protected]>
I actually changed my mind after seeing that in most cases you use "()"
for the functions and you didn't use for this case...
which one should we pick for consistency?
>
> > ---
> >
> > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> > See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
> >
> > drivers/gpu/drm/i915/gvt/mmio_context.c | 2 +-
> > 1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > diff --git a/drivers/gpu/drm/i915/gvt/mmio_context.c b/drivers/gpu/drm/i915/gvt/mmio_context.c
> > index c85bafe7539e..1c6e941c9666 100644
> > --- a/drivers/gpu/drm/i915/gvt/mmio_context.c
> > +++ b/drivers/gpu/drm/i915/gvt/mmio_context.c
> > @@ -546,7 +546,7 @@ static void switch_mmio(struct intel_vgpu *pre,
> > }
> >
> > /**
> > - * intel_gvt_switch_render_mmio - switch mmio context of specific engine
> > + * intel_gvt_switch_mmio - switch mmio context of specific engine
> > * @pre: the last vGPU that own the engine
> > * @next: the vGPU to switch to
> > * @engine: the engine
> > --
> > 2.36.1
> >
On Wed, Jul 13, 2022 at 09:11:50AM +0100, Mauro Carvalho Chehab wrote:
> From: Jiapeng Chong <[email protected]>
>
> Fix the following W=1 kernel warnings:
>
> 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.
>
> Reported-by: Abaci Robot <[email protected]>
> Signed-off-by: Jiapeng Chong <[email protected]>
> Acked-by: Zhenyu Wang <[email protected]>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> drivers/gpu/drm/i915/gvt/handlers.c | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/drivers/gpu/drm/i915/gvt/handlers.c b/drivers/gpu/drm/i915/gvt/handlers.c
> index beea5895e499..9c8dde079cb4 100644
> --- a/drivers/gpu/drm/i915/gvt/handlers.c
> +++ b/drivers/gpu/drm/i915/gvt/handlers.c
> @@ -3052,7 +3052,7 @@ int intel_vgpu_default_mmio_read(struct intel_vgpu *vgpu, unsigned int offset,
> }
>
> /**
> - * intel_t_default_mmio_write - default MMIO write handler
> + * intel_vgpu_default_mmio_write() - default MMIO write handler
> * @vgpu: a vGPU
> * @offset: access offset
> * @p_data: write data buffer
> --
> 2.36.1
>
On Wed, Jul 13, 2022 at 09:11:57AM +0100, Mauro Carvalho Chehab wrote:
> 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().
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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.36.1
>
On Wed, Jul 13, 2022 at 09:11:55AM +0100, Mauro Carvalho Chehab wrote:
> 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
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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 dad3a6054335..a0fc6d356588 100644
> --- a/drivers/gpu/drm/i915/gvt/cfg_space.c
> +++ b/drivers/gpu/drm/i915/gvt/cfg_space.c
> @@ -243,7 +243,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.36.1
>
On Wed, Jul 13, 2022 at 09:11:53AM +0100, 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.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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 6c3954479047..1e35eb01742b 100644
> --- a/drivers/gpu/drm/i915/display/intel_display_debugfs.c
> +++ b/drivers/gpu/drm/i915/display/intel_display_debugfs.c
> @@ -2229,7 +2229,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 589af257edeb..fd6b71160a06 100644
> --- a/drivers/gpu/drm/i915/display/intel_display_power.c
> +++ b/drivers/gpu/drm/i915/display/intel_display_power.c
> @@ -685,7 +685,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
oh, we are really using __ prefix for non-static functions?! o.O
anyway, with that ditto "()" consistency,
Reviewed-by: Rodrigo Vivi <[email protected]>
> * @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 6773840f6cc7..7ce0cbe0de05 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.36.1
>
On Wed, Jul 13, 2022 at 09:11:54AM +0100, Mauro Carvalho Chehab wrote:
> There are several trivial warnings there, due to trivial things:
> - lack of function name at the kerneldoc markup;
> - undocumented structs with kernel-doc markups;
> - wrong parameter syntax.
>
> Fix such warnings:
>
> drivers/gpu/drm/i915/gt/intel_context.h:107: warning: Function parameter or member 'ce' not described in 'intel_context_lock_pinned'
> drivers/gpu/drm/i915/gt/intel_context.h:122: warning: Function parameter or member 'ce' not described in 'intel_context_is_pinned'
> drivers/gpu/drm/i915/gt/intel_context.h:141: warning: Function parameter or member 'ce' not described in 'intel_context_unlock_pinned'
> drivers/gpu/drm/i915/gt/intel_gtt.h:510: warning: Function parameter or member 'vm' not described in 'i915_vm_resv_put'
> drivers/gpu/drm/i915/gt/intel_gtt.h:510: warning: Excess function parameter 'resv' description in 'i915_vm_resv_put'
> drivers/gpu/drm/i915/gt/intel_gtt.h:615: warning: Function parameter or member 'i915' not described in 'i915_ggtt_mark_pte_lost'
> drivers/gpu/drm/i915/gt/intel_gtt.h:615: warning: Function parameter or member 'val' not described in 'i915_ggtt_mark_pte_lost'
> drivers/gpu/drm/i915/gt/intel_rps.c:2343: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> * Tells the intel_ips driver that the i915 driver is now loaded, if
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'size' not described in '__guc_capture_bufstate'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'data' not described in '__guc_capture_bufstate'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'rd' not described in '__guc_capture_bufstate'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'wr' not described in '__guc_capture_bufstate'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'link' not described in '__guc_capture_parsed_output'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'is_partial' not described in '__guc_capture_parsed_output'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'eng_class' not described in '__guc_capture_parsed_output'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'eng_inst' not described in '__guc_capture_parsed_output'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'guc_id' not described in '__guc_capture_parsed_output'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'lrca' not described in '__guc_capture_parsed_output'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'reginfo' not described in '__guc_capture_parsed_output'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:63: warning: wrong kernel-doc identifier on line:
> * struct guc_debug_capture_list_header / struct guc_debug_capture_list
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:81: warning: wrong kernel-doc identifier on line:
> * struct __guc_mmio_reg_descr / struct __guc_mmio_reg_descr_group
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:106: warning: wrong kernel-doc identifier on line:
> * struct guc_state_capture_header_t / struct guc_state_capture_t /
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'is_valid' not described in '__guc_capture_ads_cache'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'ptr' not described in '__guc_capture_ads_cache'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'size' not described in '__guc_capture_ads_cache'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'status' not described in '__guc_capture_ads_cache'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:217: warning: Function parameter or member 'ads_null_cache' not described in 'intel_guc_state_capture'
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:217: warning: Function parameter or member 'max_mmio_per_node' not described in 'intel_guc_state_capture'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'marker' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'read_ptr' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'write_ptr' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'size' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'sampled_write_ptr' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'wrap_offset' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'flush_to_file' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'buffer_full_cnt' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'reserved' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'flags' not described in 'guc_log_buffer_state'
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'version' not described in 'guc_log_buffer_state'
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> drivers/gpu/drm/i915/gt/intel_context.h | 6 +++---
> drivers/gpu/drm/i915/gt/intel_engine_cs.c | 4 ++--
> drivers/gpu/drm/i915/gt/intel_gtt.h | 6 +++---
> drivers/gpu/drm/i915/gt/intel_rps.c | 4 ++--
> drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h | 14 +++++++-------
> drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h | 2 +-
> 6 files changed, 18 insertions(+), 18 deletions(-)
>
> diff --git a/drivers/gpu/drm/i915/gt/intel_context.h b/drivers/gpu/drm/i915/gt/intel_context.h
> index 8e2d70630c49..91c092d5deae 100644
> --- a/drivers/gpu/drm/i915/gt/intel_context.h
> +++ b/drivers/gpu/drm/i915/gt/intel_context.h
> @@ -96,7 +96,7 @@ void intel_context_bind_parent_child(struct intel_context *parent,
>
> /**
> * intel_context_lock_pinned - Stablises the 'pinned' status of the HW context
> - * @ce - the context
> + * @ce: the context
> *
> * Acquire a lock on the pinned status of the HW context, such that the context
> * can neither be bound to the GPU or unbound whilst the lock is held, i.e.
> @@ -110,7 +110,7 @@ static inline int intel_context_lock_pinned(struct intel_context *ce)
>
> /**
> * intel_context_is_pinned - Reports the 'pinned' status
> - * @ce - the context
> + * @ce: the context
> *
> * While in use by the GPU, the context, along with its ring and page
> * tables is pinned into memory and the GTT.
> @@ -132,7 +132,7 @@ static inline void intel_context_cancel_request(struct intel_context *ce,
>
> /**
> * intel_context_unlock_pinned - Releases the earlier locking of 'pinned' status
> - * @ce - the context
> + * @ce: the context
> *
> * Releases the lock earlier acquired by intel_context_unlock_pinned().
> */
> diff --git a/drivers/gpu/drm/i915/gt/intel_engine_cs.c b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> index 37fa813af766..da225f5db2a4 100644
> --- a/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> +++ b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> @@ -1197,7 +1197,7 @@ create_kernel_context(struct intel_engine_cs *engine)
> }
>
> /**
> - * intel_engines_init_common - initialize cengine state which might require hw access
> + * engine_init_common - initialize cengine state which might require hw access
> * @engine: Engine to initialize.
> *
> * Initializes @engine@ structure members shared between legacy and execlists
> @@ -1278,7 +1278,7 @@ int intel_engines_init(struct intel_gt *gt)
> }
>
> /**
> - * intel_engines_cleanup_common - cleans up the engine state created by
> + * intel_engine_cleanup_common - cleans up the engine state created by
> * the common initiailizers.
> * @engine: Engine to cleanup.
> *
> diff --git a/drivers/gpu/drm/i915/gt/intel_gtt.h b/drivers/gpu/drm/i915/gt/intel_gtt.h
> index e639434e97fd..fca8eedee1d8 100644
> --- a/drivers/gpu/drm/i915/gt/intel_gtt.h
> +++ b/drivers/gpu/drm/i915/gt/intel_gtt.h
> @@ -503,7 +503,7 @@ static inline void i915_vm_put(struct i915_address_space *vm)
>
> /**
> * i915_vm_resv_put - Release a reference on the vm's reservation lock
> - * @resv: Pointer to a reservation lock obtained from i915_vm_resv_get()
> + * @vm: The vm whose reservation lock was obtained from i915_vm_resv_get()
> */
> static inline void i915_vm_resv_put(struct i915_address_space *vm)
> {
> @@ -604,8 +604,8 @@ void i915_ggtt_resume(struct i915_ggtt *ggtt);
>
> /**
> * i915_ggtt_mark_pte_lost - Mark ggtt ptes as lost or clear such a marking
> - * @i915 The device private.
> - * @val whether the ptes should be marked as lost.
> + * @i915: The device private.
> + * @val: whether the ptes should be marked as lost.
> *
> * In some cases pte content is retained across suspend, but typically lost
> * across hibernate. Typically they should be marked as lost on
> diff --git a/drivers/gpu/drm/i915/gt/intel_rps.c b/drivers/gpu/drm/i915/gt/intel_rps.c
> index fb3f57ee450b..8aefc427e06e 100644
> --- a/drivers/gpu/drm/i915/gt/intel_rps.c
> +++ b/drivers/gpu/drm/i915/gt/intel_rps.c
> @@ -2339,8 +2339,8 @@ bool rps_read_mask_mmio(struct intel_rps *rps,
> static struct drm_i915_private __rcu *ips_mchdev;
>
> /**
> - * Tells the intel_ips driver that the i915 driver is now loaded, if
> - * IPS got loaded first.
> + * ips_ping_for_i915_load - Tells the intel_ips driver that the i915 driver
> + * is now loaded, if IPS got loaded first.
> *
> * This awkward dance is so that neither module has to depend on the
> * other in order for IPS to do the appropriate communication of
> diff --git a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> index 3624abfd22d1..58f93226b1c1 100644
> --- a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> +++ b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> @@ -12,7 +12,7 @@
> struct intel_guc;
> struct file;
>
> -/**
> +/*
> * struct __guc_capture_bufstate
> *
> * Book-keeping structure used to track read and write pointers
> @@ -26,7 +26,7 @@ struct __guc_capture_bufstate {
> u32 wr;
> };
>
> -/**
> +/*
> * struct __guc_capture_parsed_output - extracted error capture node
> *
> * A single unit of extracted error-capture output data grouped together
> @@ -58,7 +58,7 @@ struct __guc_capture_parsed_output {
> #define GCAP_PARSED_REGLIST_INDEX_ENGINST BIT(GUC_CAPTURE_LIST_TYPE_ENGINE_INSTANCE)
> };
>
> -/**
> +/*
> * struct guc_debug_capture_list_header / struct guc_debug_capture_list
> *
> * As part of ADS registration, these header structures (followed by
> @@ -76,7 +76,7 @@ struct guc_debug_capture_list {
> struct guc_mmio_reg regs[0];
> } __packed;
>
> -/**
> +/*
> * struct __guc_mmio_reg_descr / struct __guc_mmio_reg_descr_group
> *
> * intel_guc_capture module uses these structures to maintain static
> @@ -101,7 +101,7 @@ struct __guc_mmio_reg_descr_group {
> struct __guc_mmio_reg_descr *extlist; /* only used for steered registers */
> };
>
> -/**
> +/*
> * struct guc_state_capture_header_t / struct guc_state_capture_t /
> * guc_state_capture_group_header_t / guc_state_capture_group_t
> *
> @@ -148,7 +148,7 @@ struct guc_state_capture_group_t {
> struct guc_state_capture_t capture_entries[0];
> } __packed;
>
> -/**
> +/*
> * struct __guc_capture_ads_cache
and many more here... :/
Hopefully this great work on the docs will make these ugly
"exported" "__" prefixes visible and we will fix them
Reviewed-by: Rodrigo Vivi <[email protected]>
> *
> * A structure to cache register lists that were populated and registered
> @@ -162,7 +162,7 @@ struct __guc_capture_ads_cache {
> int status;
> };
>
> -/**
> +/*
> * struct intel_guc_state_capture
> *
> * Internal context of the intel_guc_capture module.
> diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h b/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h
> index b3c9a9327f76..237019e98ede 100644
> --- a/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h
> +++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h
> @@ -360,7 +360,7 @@ enum guc_log_buffer_type {
> GUC_MAX_LOG_BUFFER
> };
>
> -/**
> +/*
> * struct guc_log_buffer_state - GuC log buffer state
> *
> * Below state structure is used for coordination of retrieval of GuC firmware
> --
> 2.36.1
>
On 2022.07.13 09:11:55 +0100, Mauro Carvalho Chehab wrote:
> 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
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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 dad3a6054335..a0fc6d356588 100644
> --- a/drivers/gpu/drm/i915/gvt/cfg_space.c
> +++ b/drivers/gpu/drm/i915/gvt/cfg_space.c
> @@ -243,7 +243,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.
> --
Acked-by: Zhenyu Wang <[email protected]>
Thanks! I'll put in queue with other gvt fixes.
On Wed, 13 Jul 2022 18:00:59 -0400
Rodrigo Vivi <[email protected]> wrote:
> On Wed, Jul 13, 2022 at 05:54:44PM -0400, Rodrigo Vivi wrote:
> > On Wed, Jul 13, 2022 at 09:11:49AM +0100, Mauro Carvalho Chehab wrote:
> > > From: Jiapeng Chong <[email protected]>
> > >
> > > Fix the following W=1 kernel warnings:
> > >
> > > 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.
> > >
> > > Reported-by: Abaci Robot <[email protected]>
> > > Signed-off-by: Jiapeng Chong <[email protected]>
> > > Acked-by: Zhenyu Wang <[email protected]>
> > > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> >
> > Reviewed-by: Rodrigo Vivi <[email protected]>
>
> I actually changed my mind after seeing that in most cases you use "()"
> for the functions and you didn't use for this case...
The documentation build system handles both ways equally, and there's
no consensus kernel-wide about what would be the preferred way[1].
Also, at the html (or pdf) output, they'll all look the same. So, no
difference in practice at the produced documentation.
[1] The current count (using drm-tip 2022y-07m-12d-21h-47m-27s) as basis,
is:
$ git ls-files|xargs grep -Pzo "\/\*\*\n \* [_a-zA-Z0-9]+ -" |wc -l
36680
$ git ls-files|xargs grep -Pzo "\/\*\*\n \* [_a-zA-Z0-9]+\s*\(\) -" |wc -l
12068
So, 48748 documented functions, being ~25% with parenthesis,
and ~75% without it.
Under drivers/gpu, the numbers are:
$ git ls-files|grep drivers/gpu/|xargs grep -Pzo "\/\*\*\n \* [_a-zA-Z0-9]+\s*\(\) -" |wc -l
480
mchehab@sal /new_devel/v4l/tmp $ git ls-files|grep drivers/gpu/|xargs grep -Pzo "\/\*\*\n \* [_a-zA-Z0-9]+ -" |wc -l
4046
> which one should we pick for consistency?
Yeah, it is nicer to use the same way everywhere. Btw, on media, I was
enforcing one way at the beginning, but I ended giving up doing that
as it was too many efforts for too little. Nowadays, half of media
function declarations have parenthesis, half doesn't.
Anyway, this is what we have at i915 driver, before this series:
$ grep -Pzo "\/\*\*\n \* [_a-zA-Z0-9]+\s*\(\) -" $(find drivers/gpu/drm/i915 -type f)|wc -l
53
$ grep -Pzo "\/\*\*\n \* [_a-zA-Z0-9]+ -" $(find drivers/gpu/drm/i915 -type f)|wc -l
542
This series include 3 functions with "()" (on patches 1 and 3, both
authored by Jiapeng, and 11 functions without it on my own patches.
I'll change those two patches to remove the "()" for consistency.
I guess I'll add a patch at the end changing the other 53 functions
to drop "()".
Regards,
Mauro
On Wed, 13 Jul 2022 18:05:06 -0400
Rodrigo Vivi <[email protected]> wrote:
> On Wed, Jul 13, 2022 at 09:11:53AM +0100, 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.
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > ---
> >
> > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> > See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
> >
> > 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 6c3954479047..1e35eb01742b 100644
> > --- a/drivers/gpu/drm/i915/display/intel_display_debugfs.c
> > +++ b/drivers/gpu/drm/i915/display/intel_display_debugfs.c
> > @@ -2229,7 +2229,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 589af257edeb..fd6b71160a06 100644
> > --- a/drivers/gpu/drm/i915/display/intel_display_power.c
> > +++ b/drivers/gpu/drm/i915/display/intel_display_power.c
> > @@ -685,7 +685,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
>
> oh, we are really using __ prefix for non-static functions?! o.O
Yeah... Btw, this is actually a common practice to have __ prefix on
non-static and even on exported functions. Usually, the __ variant
assumes that a spinlock/mutex were already taken previously.
However, that's not the case here, as it starts holding a mutex.
In this specific case, the __ variant is called by an inline
function on a different way, depending if
CONFIG_DRM_I915_DEBUG_RUNTIME_PM is true. On such case, it passes
the runtime PM wakeref, otherwise it passes a -1.
Funny enough, intel_display_power_put() ifdef is inside the C
file, using a different implementation:
#if IS_ENABLED(CONFIG_DRM_I915_DEBUG_RUNTIME_PM)
...
void intel_display_power_put(struct drm_i915_private *dev_priv,
enum intel_display_power_domain domain,
intel_wakeref_t wakeref)
...
#else
...
void intel_display_power_put_unchecked(struct drm_i915_private *dev_priv,
enum intel_display_power_domain domain)
...
#endif
For consistency, I would use the same solution for both, probably
at the C file, and avoiding use a __ prefix for the async put version.
> anyway, with that ditto "()" consistency,
>
> Reviewed-by: Rodrigo Vivi <[email protected]>
Thanks!
Btw, I'm removing "()" from patches 1-3 (both at descriptions and
internally), keeping your R-B on them too.
Regards,
Mauro
On Wed, 13 Jul 2022 18:07:44 -0400
Rodrigo Vivi <[email protected]> wrote:
> On Wed, Jul 13, 2022 at 09:11:54AM +0100, Mauro Carvalho Chehab wrote:
> > There are several trivial warnings there, due to trivial things:
> > - lack of function name at the kerneldoc markup;
> > - undocumented structs with kernel-doc markups;
> > - wrong parameter syntax.
> >
> > Fix such warnings:
> >
> > drivers/gpu/drm/i915/gt/intel_context.h:107: warning: Function parameter or member 'ce' not described in 'intel_context_lock_pinned'
> > drivers/gpu/drm/i915/gt/intel_context.h:122: warning: Function parameter or member 'ce' not described in 'intel_context_is_pinned'
> > drivers/gpu/drm/i915/gt/intel_context.h:141: warning: Function parameter or member 'ce' not described in 'intel_context_unlock_pinned'
> > drivers/gpu/drm/i915/gt/intel_gtt.h:510: warning: Function parameter or member 'vm' not described in 'i915_vm_resv_put'
> > drivers/gpu/drm/i915/gt/intel_gtt.h:510: warning: Excess function parameter 'resv' description in 'i915_vm_resv_put'
> > drivers/gpu/drm/i915/gt/intel_gtt.h:615: warning: Function parameter or member 'i915' not described in 'i915_ggtt_mark_pte_lost'
> > drivers/gpu/drm/i915/gt/intel_gtt.h:615: warning: Function parameter or member 'val' not described in 'i915_ggtt_mark_pte_lost'
> > drivers/gpu/drm/i915/gt/intel_rps.c:2343: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> > * Tells the intel_ips driver that the i915 driver is now loaded, if
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'size' not described in '__guc_capture_bufstate'
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'data' not described in '__guc_capture_bufstate'
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'rd' not described in '__guc_capture_bufstate'
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:28: warning: Function parameter or member 'wr' not described in '__guc_capture_bufstate'
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'link' not described in '__guc_capture_parsed_output'
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'is_partial' not described in '__guc_capture_parsed_output'
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'eng_class' not described in '__guc_capture_parsed_output'
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'eng_inst' not described in '__guc_capture_parsed_output'
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'guc_id' not described in '__guc_capture_parsed_output'
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'lrca' not described in '__guc_capture_parsed_output'
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:60: warning: Function parameter or member 'reginfo' not described in '__guc_capture_parsed_output'
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:63: warning: wrong kernel-doc identifier on line:
> > * struct guc_debug_capture_list_header / struct guc_debug_capture_list
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:81: warning: wrong kernel-doc identifier on line:
> > * struct __guc_mmio_reg_descr / struct __guc_mmio_reg_descr_group
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:106: warning: wrong kernel-doc identifier on line:
> > * struct guc_state_capture_header_t / struct guc_state_capture_t /
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'is_valid' not described in '__guc_capture_ads_cache'
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'ptr' not described in '__guc_capture_ads_cache'
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'size' not described in '__guc_capture_ads_cache'
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:164: warning: Function parameter or member 'status' not described in '__guc_capture_ads_cache'
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:217: warning: Function parameter or member 'ads_null_cache' not described in 'intel_guc_state_capture'
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h:217: warning: Function parameter or member 'max_mmio_per_node' not described in 'intel_guc_state_capture'
> > drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'marker' not described in 'guc_log_buffer_state'
> > drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'read_ptr' not described in 'guc_log_buffer_state'
> > drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'write_ptr' not described in 'guc_log_buffer_state'
> > drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'size' not described in 'guc_log_buffer_state'
> > drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'sampled_write_ptr' not described in 'guc_log_buffer_state'
> > drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'wrap_offset' not described in 'guc_log_buffer_state'
> > drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'flush_to_file' not described in 'guc_log_buffer_state'
> > drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'buffer_full_cnt' not described in 'guc_log_buffer_state'
> > drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'reserved' not described in 'guc_log_buffer_state'
> > drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'flags' not described in 'guc_log_buffer_state'
> > drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h:401: warning: Function parameter or member 'version' not described in 'guc_log_buffer_state'
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > ---
> >
> > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> > See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
> >
> > drivers/gpu/drm/i915/gt/intel_context.h | 6 +++---
> > drivers/gpu/drm/i915/gt/intel_engine_cs.c | 4 ++--
> > drivers/gpu/drm/i915/gt/intel_gtt.h | 6 +++---
> > drivers/gpu/drm/i915/gt/intel_rps.c | 4 ++--
> > drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h | 14 +++++++-------
> > drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h | 2 +-
> > 6 files changed, 18 insertions(+), 18 deletions(-)
> >
> > diff --git a/drivers/gpu/drm/i915/gt/intel_context.h b/drivers/gpu/drm/i915/gt/intel_context.h
> > index 8e2d70630c49..91c092d5deae 100644
> > --- a/drivers/gpu/drm/i915/gt/intel_context.h
> > +++ b/drivers/gpu/drm/i915/gt/intel_context.h
> > @@ -96,7 +96,7 @@ void intel_context_bind_parent_child(struct intel_context *parent,
> >
> > /**
> > * intel_context_lock_pinned - Stablises the 'pinned' status of the HW context
> > - * @ce - the context
> > + * @ce: the context
> > *
> > * Acquire a lock on the pinned status of the HW context, such that the context
> > * can neither be bound to the GPU or unbound whilst the lock is held, i.e.
> > @@ -110,7 +110,7 @@ static inline int intel_context_lock_pinned(struct intel_context *ce)
> >
> > /**
> > * intel_context_is_pinned - Reports the 'pinned' status
> > - * @ce - the context
> > + * @ce: the context
> > *
> > * While in use by the GPU, the context, along with its ring and page
> > * tables is pinned into memory and the GTT.
> > @@ -132,7 +132,7 @@ static inline void intel_context_cancel_request(struct intel_context *ce,
> >
> > /**
> > * intel_context_unlock_pinned - Releases the earlier locking of 'pinned' status
> > - * @ce - the context
> > + * @ce: the context
> > *
> > * Releases the lock earlier acquired by intel_context_unlock_pinned().
> > */
> > diff --git a/drivers/gpu/drm/i915/gt/intel_engine_cs.c b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> > index 37fa813af766..da225f5db2a4 100644
> > --- a/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> > +++ b/drivers/gpu/drm/i915/gt/intel_engine_cs.c
> > @@ -1197,7 +1197,7 @@ create_kernel_context(struct intel_engine_cs *engine)
> > }
> >
> > /**
> > - * intel_engines_init_common - initialize cengine state which might require hw access
> > + * engine_init_common - initialize cengine state which might require hw access
> > * @engine: Engine to initialize.
> > *
> > * Initializes @engine@ structure members shared between legacy and execlists
> > @@ -1278,7 +1278,7 @@ int intel_engines_init(struct intel_gt *gt)
> > }
> >
> > /**
> > - * intel_engines_cleanup_common - cleans up the engine state created by
> > + * intel_engine_cleanup_common - cleans up the engine state created by
> > * the common initiailizers.
> > * @engine: Engine to cleanup.
> > *
> > diff --git a/drivers/gpu/drm/i915/gt/intel_gtt.h b/drivers/gpu/drm/i915/gt/intel_gtt.h
> > index e639434e97fd..fca8eedee1d8 100644
> > --- a/drivers/gpu/drm/i915/gt/intel_gtt.h
> > +++ b/drivers/gpu/drm/i915/gt/intel_gtt.h
> > @@ -503,7 +503,7 @@ static inline void i915_vm_put(struct i915_address_space *vm)
> >
> > /**
> > * i915_vm_resv_put - Release a reference on the vm's reservation lock
> > - * @resv: Pointer to a reservation lock obtained from i915_vm_resv_get()
> > + * @vm: The vm whose reservation lock was obtained from i915_vm_resv_get()
> > */
> > static inline void i915_vm_resv_put(struct i915_address_space *vm)
> > {
> > @@ -604,8 +604,8 @@ void i915_ggtt_resume(struct i915_ggtt *ggtt);
> >
> > /**
> > * i915_ggtt_mark_pte_lost - Mark ggtt ptes as lost or clear such a marking
> > - * @i915 The device private.
> > - * @val whether the ptes should be marked as lost.
> > + * @i915: The device private.
> > + * @val: whether the ptes should be marked as lost.
> > *
> > * In some cases pte content is retained across suspend, but typically lost
> > * across hibernate. Typically they should be marked as lost on
> > diff --git a/drivers/gpu/drm/i915/gt/intel_rps.c b/drivers/gpu/drm/i915/gt/intel_rps.c
> > index fb3f57ee450b..8aefc427e06e 100644
> > --- a/drivers/gpu/drm/i915/gt/intel_rps.c
> > +++ b/drivers/gpu/drm/i915/gt/intel_rps.c
> > @@ -2339,8 +2339,8 @@ bool rps_read_mask_mmio(struct intel_rps *rps,
> > static struct drm_i915_private __rcu *ips_mchdev;
> >
> > /**
> > - * Tells the intel_ips driver that the i915 driver is now loaded, if
> > - * IPS got loaded first.
> > + * ips_ping_for_i915_load - Tells the intel_ips driver that the i915 driver
> > + * is now loaded, if IPS got loaded first.
> > *
> > * This awkward dance is so that neither module has to depend on the
> > * other in order for IPS to do the appropriate communication of
> > diff --git a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> > index 3624abfd22d1..58f93226b1c1 100644
> > --- a/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> > +++ b/drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h
> > @@ -12,7 +12,7 @@
> > struct intel_guc;
> > struct file;
> >
> > -/**
> > +/*
> > * struct __guc_capture_bufstate
> > *
> > * Book-keeping structure used to track read and write pointers
> > @@ -26,7 +26,7 @@ struct __guc_capture_bufstate {
> > u32 wr;
> > };
> >
> > -/**
> > +/*
> > * struct __guc_capture_parsed_output - extracted error capture node
> > *
> > * A single unit of extracted error-capture output data grouped together
> > @@ -58,7 +58,7 @@ struct __guc_capture_parsed_output {
> > #define GCAP_PARSED_REGLIST_INDEX_ENGINST BIT(GUC_CAPTURE_LIST_TYPE_ENGINE_INSTANCE)
> > };
> >
> > -/**
> > +/*
> > * struct guc_debug_capture_list_header / struct guc_debug_capture_list
> > *
> > * As part of ADS registration, these header structures (followed by
> > @@ -76,7 +76,7 @@ struct guc_debug_capture_list {
> > struct guc_mmio_reg regs[0];
> > } __packed;
> >
> > -/**
> > +/*
> > * struct __guc_mmio_reg_descr / struct __guc_mmio_reg_descr_group
> > *
> > * intel_guc_capture module uses these structures to maintain static
> > @@ -101,7 +101,7 @@ struct __guc_mmio_reg_descr_group {
> > struct __guc_mmio_reg_descr *extlist; /* only used for steered registers */
> > };
> >
> > -/**
> > +/*
> > * struct guc_state_capture_header_t / struct guc_state_capture_t /
> > * guc_state_capture_group_header_t / guc_state_capture_group_t
> > *
> > @@ -148,7 +148,7 @@ struct guc_state_capture_group_t {
> > struct guc_state_capture_t capture_entries[0];
> > } __packed;
> >
> > -/**
> > +/*
> > * struct __guc_capture_ads_cache
>
> and many more here... :/
> Hopefully this great work on the docs will make these ugly
> "exported" "__" prefixes visible and we will fix them
Yeah, while I can see why __function would be ok on some cases
(like for lock/unlock variants and on some special macros like the ones
that use THIS_MODULE), I can't see any reason why struct/enum/union
would ever need to have __ prefixes on it ;-)
> Reviewed-by: Rodrigo Vivi <[email protected]>
Thanks!
Regards,
Mauro
On Wed, Jul 13, 2022 at 09:12:08AM +0100, 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.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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.36.1
>
On Wed, Jul 13, 2022 at 09:12:15AM +0100, Mauro Carvalho Chehab wrote:
> 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.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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 0b8bf4be4330..5b5c4eee0f44 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.36.1
>
On Wed, Jul 13, 2022 at 09:12:13AM +0100, Mauro Carvalho Chehab wrote:
> 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.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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 27c55027387a..fa5a678018d9 100644
> --- a/drivers/gpu/drm/i915/i915_vma_resource.c
> +++ b/drivers/gpu/drm/i915/i915_vma_resource.c
> @@ -283,7 +283,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,
> @@ -367,7 +367,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.36.1
>
On Wed, Jul 13, 2022 at 09:12:02AM +0100, Mauro Carvalho Chehab wrote:
> Fix those kernel-doc warnings:
> drivers/gpu/drm/i915/intel_region_ttm.c:199: warning: Function parameter or member 'offset' not described in 'intel_region_ttm_resource_alloc'
> drivers/gpu/drm/i915/i915_vma_resource.h:123: warning: Function parameter or member 'wakeref' not described in 'i915_vma_resource'
> drivers/gpu/drm/i915/i915_vma.c:1703: warning: Function parameter or member 'vma' not described in 'i915_vma_destroy_locked'
> drivers/gpu/drm/i915/i915_vma.c:751: warning: Function parameter or member 'ww' not described in 'i915_vma_insert'
> drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:159: warning: Function parameter or member 'gt' not described in 'intel_gt_fini_hwconfig'
> drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:146: warning: Function parameter or member 'gt' not described in 'intel_gt_init_hwconfig'
> drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:113: warning: expecting prototype for intel_guc_hwconfig_init(). Prototype was for guc_hwconfig_init() instead
> drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c:113: warning: Function parameter or member 'gt' not described in 'guc_hwconfig_init'
> drivers/gpu/drm/i915/gt/intel_engine_types.h:276: warning: Function parameter or member 'preempt_hang' not described in 'intel_engine_execlists'
>
> That are due undocumented parameters.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> drivers/gpu/drm/i915/gt/intel_engine_types.h | 1 +
> drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c | 5 ++++-
> drivers/gpu/drm/i915/i915_vma.c | 2 ++
> drivers/gpu/drm/i915/i915_vma_resource.h | 1 +
> drivers/gpu/drm/i915/intel_region_ttm.c | 3 ++-
> 5 files changed, 10 insertions(+), 2 deletions(-)
>
> diff --git a/drivers/gpu/drm/i915/gt/intel_engine_types.h b/drivers/gpu/drm/i915/gt/intel_engine_types.h
> index 633a7e5dba3b..7c5ad9071fe7 100644
> --- a/drivers/gpu/drm/i915/gt/intel_engine_types.h
> +++ b/drivers/gpu/drm/i915/gt/intel_engine_types.h
> @@ -271,6 +271,7 @@ struct intel_engine_execlists {
> */
> u8 csb_head;
>
> + /* private: Used only in selftests */
> I915_SELFTEST_DECLARE(struct st_preempt_hang preempt_hang;)
> };
>
> diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c b/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
> index 4781fccc2687..76f7447302a6 100644
> --- a/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
> +++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
> @@ -103,7 +103,8 @@ static bool has_table(struct drm_i915_private *i915)
> }
>
> /**
> - * intel_guc_hwconfig_init - Initialize the HWConfig
> + * guc_hwconfig_init - Initialize the HWConfig
> + * @gt: GT structure
> *
> * Retrieve the HWConfig table from the GuC and save it locally.
> * It can then be queried on demand by other users later on.
> @@ -138,6 +139,7 @@ static int guc_hwconfig_init(struct intel_gt *gt)
>
> /**
> * intel_gt_init_hwconfig - Initialize the HWConfig if available
> + * @gt: GT structure
> *
> * Retrieve the HWConfig table if available on the current platform.
> */
> @@ -151,6 +153,7 @@ int intel_gt_init_hwconfig(struct intel_gt *gt)
>
> /**
> * intel_gt_fini_hwconfig - Finalize the HWConfig
> + * @gt: GT structure
> *
> * Free up the memory allocation holding the table.
> */
> diff --git a/drivers/gpu/drm/i915/i915_vma.c b/drivers/gpu/drm/i915/i915_vma.c
> index ef3b04c7e153..ddf348c597b0 100644
> --- a/drivers/gpu/drm/i915/i915_vma.c
> +++ b/drivers/gpu/drm/i915/i915_vma.c
> @@ -733,6 +733,7 @@ bool i915_gem_valid_gtt_space(struct i915_vma *vma, unsigned long color)
> /**
> * i915_vma_insert - finds a slot for the vma in its address space
> * @vma: the vma
> + * @ww: An optional struct i915_gem_ww_ctx
> * @size: requested size in bytes (can be larger than the VMA)
> * @alignment: required alignment
> * @flags: mask of PIN_* flags to use
> @@ -1675,6 +1676,7 @@ static void release_references(struct i915_vma *vma, struct intel_gt *gt,
> /**
> * i915_vma_destroy_locked - Remove all weak reference to the vma and put
> * the initial reference.
> + * @vma: VMA to destroy
> *
> * This function should be called when it's decided the vma isn't needed
> * anymore. The caller must assure that it doesn't race with another lookup
> diff --git a/drivers/gpu/drm/i915/i915_vma_resource.h b/drivers/gpu/drm/i915/i915_vma_resource.h
> index 14a0327b2080..a15271d96b7e 100644
> --- a/drivers/gpu/drm/i915/i915_vma_resource.h
> +++ b/drivers/gpu/drm/i915/i915_vma_resource.h
> @@ -49,6 +49,7 @@ struct i915_page_sizes {
> * @__subtree_last: Interval tree private member.
> * @vm: non-refcounted pointer to the vm. This is for internal use only and
> * this member is cleared after vm_resource unbind.
> + * @wakeref: wakeref used for runtime PM reference.
> * @mr: The memory region of the object pointed to by the vma.
> * @ops: Pointer to the 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 6873808a7015..471a70c50b2c 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.36.1
>
On Wed, Jul 13, 2022 at 09:12:11AM +0100, Mauro Carvalho Chehab wrote:
> This file is licensed with MIT license. Change its license text
> to use SPDX.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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.36.1
>
On Wed, Jul 13, 2022 at 09:12:16AM +0100, Mauro Carvalho Chehab wrote:
> 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.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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.36.1
>
On Wed, Jul 13, 2022 at 09:12:14AM +0100, Mauro Carvalho Chehab wrote:
> 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.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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 41e83d078a70..0ca4bb08ea78 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.36.1
>
On Wed, Jul 13, 2022 at 09:12:09AM +0100, Mauro Carvalho Chehab wrote:
> The doc markup should not end with ":", as it would generate a
> warning on Sphinx while generating the cross-reference tag.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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.36.1
>
On Wed, Jul 13, 2022 at 09:12:10AM +0100, 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.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
\o/
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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 | 63 +++++++++----------
> 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 | 30 ++++-----
> 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 0da9b208d56e..100715d4c2fb 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 19122bc6d2ab..7925f5ffaa68 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 d2d75d9c0c8d..351515db4ef5 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,75 +210,75 @@ 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: head pointer in work queue */
> + /* @wqi_head: head pointer in work queue */
> u16 wqi_head;
> - /** @wqi_tail: tail pointer in work queue */
> + /* @wqi_tail: tail pointer in work queue */
> u16 wqi_tail;
> - /**
> + /*
> * @parent_page: page in context state (ce->state) used
> * by parent for work queue, process descriptor
> */
> @@ -288,18 +287,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 df708802889d..905f547094ca 100644
> --- a/drivers/gpu/drm/i915/gt/intel_gt_types.h
> +++ b/drivers/gpu/drm/i915/gt/intel_gt_types.h
> @@ -93,7 +93,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
> @@ -117,7 +117,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.
> @@ -143,12 +143,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
> @@ -156,7 +156,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.
> @@ -222,7 +222,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 d25647be25d1..91a3aa49e918 100644
> --- a/drivers/gpu/drm/i915/i915_drv.h
> +++ b/drivers/gpu/drm/i915/i915_drv.h
> @@ -224,37 +224,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 delayed_work 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;
> @@ -266,7 +266,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.
> */
> @@ -384,7 +384,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
> @@ -392,7 +392,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;
> @@ -421,11 +421,11 @@ struct drm_i915_private {
>
> struct intel_gmbus *gmbus[GMBUS_NUM_PINS];
>
> - /** gmbus_mutex protects against concurrent usage of the single hw gmbus
> + /* gmbus_mutex protects against concurrent usage of the single hw gmbus
> * controller on different i2c buses. */
> struct mutex gmbus_mutex;
>
> - /**
> + /*
> * Base address of where the gmbus and gpio blocks are located (either
> * on PCH or on SoC for platforms without PCH).
> */
> @@ -454,7 +454,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];
> @@ -503,7 +503,7 @@ struct drm_i915_private {
> struct intel_global_obj obj;
> } dbuf;
>
> - /**
> + /*
> * wq - Driver workqueue for GEM.
> *
> * NOTE: Work items scheduled here are not allowed to grab any modeset
> @@ -554,7 +554,7 @@ struct drm_i915_private {
>
> /* Kernel Modesetting */
>
> - /**
> + /*
> * dpll and cdclk state is protected by connection_mutex
> * dpll.lock serializes intel_{prepare,enable,disable}_shared_dpll.
> * Must be global rather than per dpll, because on some platforms plls
> 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 55a143b92d10..112a646c78ed 100644
> --- a/drivers/gpu/drm/i915/i915_gpu_error.h
> +++ b/drivers/gpu/drm/i915/i915_gpu_error.h
> @@ -207,10 +207,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.36.1
>
On Wed, Jul 13, 2022 at 09:12:12AM +0100, Mauro Carvalho Chehab wrote:
> This file is licensed with MIT license. Change its license text
> to use SPDX.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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.36.1
>
On Fri, 2022-07-15 at 17:35 -0400, Rodrigo Vivi wrote:
> On Wed, Jul 13, 2022 at 09:12:12AM +0100, Mauro Carvalho Chehab wrote:
> > This file is licensed with MIT license. Change its license text
> > to use SPDX.
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
>
> Reviewed-by: Rodrigo Vivi <[email protected]>
Not exactly the MIT license as it's missing "or copyright holders"
>
> > ---
> >
> > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> > See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
> >
> > 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
Missing "Authors or copyright holders"
> > 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.36.1
> >
On Wed, Jul 13, 2022 at 09:12:04AM +0100, Mauro Carvalho Chehab wrote:
> 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.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Just trying to understand as well on why in a few you had chosen ```foo```
and here **foo**. why?
anyway, not a blocker:
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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 b191915ab351..fe72c75a9c79 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.36.1
>
On Wed, Jul 13, 2022 at 09:12:01AM +0100, Mauro Carvalho Chehab wrote:
> 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")
Why the fix here and not in the i915_vma_destroy_locked one?
That was also a new introduction. Should we bother with the Fixes
anyway since there were many broken already? And if we do, shouldn't
we add to the others?
But anyway, just trying to understand the differences and reasons,
because the patch is correct:
Reviewed-by: Rodrigo Vivi <[email protected]>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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 32e92651ef7c..7790f97b26db 100644
> --- a/drivers/gpu/drm/i915/i915_gpu_error.c
> +++ b/drivers/gpu/drm/i915/i915_gpu_error.c
> @@ -2096,7 +2096,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.36.1
>
On Fri, 15 Jul 2022 15:16:05 -0700
Joe Perches <[email protected]> wrote:
> On Fri, 2022-07-15 at 17:35 -0400, Rodrigo Vivi wrote:
> > On Wed, Jul 13, 2022 at 09:12:12AM +0100, Mauro Carvalho Chehab wrote:
> > > This file is licensed with MIT license. Change its license text
> > > to use SPDX.
> > >
> > > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> >
> > Reviewed-by: Rodrigo Vivi <[email protected]>
>
> Not exactly the MIT license as it's missing "or copyright holders"
Text is not identical, but the license is... see below:
> >
> > > ---
> > >
> > > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> > > See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
> > >
> > > 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 license itself is here. It is standard MIT license. The original
text for the above paragraph is clearer about that:
"The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software."
The "next paragraph", mentioned on this variant:
> > > -
> > > -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
>
> Missing "Authors or copyright holders"
Is actually a disclaimer's note, and not the license itself, informing that
there's no warranties provide by author(s).
With SPDX, this will point to LICENSES/preferred/MIT with has a paragraph
that fits to the same purpose: it excludes any express or implied
warranties.
Btw, the Kernel itself had this at COPYING by the time this was added
and before SPDX, which was there when this code was added. This is
part of the GPL text:
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
So, I can't see any changes here: with or without this patch, there's
no warranties from the ones that wrote the code - nor for any
copyright holders - as the Kernel as a hole is released under GPL.
Also, LICENSES/preferred/MIT define that MIT license text is:
MIT License
Copyright (c) <year> <copyright holders>
In this specific case, "Copyright © 2006 Dave Airlie", which is both
the author and the copyright holder that is part of MIT, so the text
meaning is identical with either "AUTHOR" or "AUTHORS OR COPYRIGHT
HOLDERS" is used.
So, I can't see any difference from legal standpoint.
Regards,
Mauro
On Wed, Jul 13, 2022 at 09:12:06AM +0100, Mauro Carvalho Chehab wrote:
> 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.
my first reaction was: "do we really need those new empty ( ) blocks?"
Then I read this ;)
Reviewed-by: Rodrigo Vivi <[email protected]>
>
> Change the ascii artwork to be on code-blocks, starting all
> lines at the same characters and not ending with a backslash.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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 f06babdb3a8c..d3393752b04b 100644
> --- a/drivers/gpu/drm/i915/intel_pm.c
> +++ b/drivers/gpu/drm/i915/intel_pm.c
> @@ -684,18 +684,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
> @@ -731,13 +733,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.36.1
>
On Wed, Jul 13, 2022 at 09:12:18AM +0100, 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.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> Documentation/gpu/i915.rst | 43 +++++++++++++++++++++++++++++++++++++-
> 1 file changed, 42 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 2ad7941a79f2..afd8c0e3c689 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,48 @@ 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
> +
> +GT context
> +----------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_context.h
why does the context deserves a separated section and the
many others below no?
> +
> +Graphics Translation Tables
> +---------------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt.c
> +
> +Other GT functionality
> +----------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gsc.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.h
Why aren't these gtt ones in the above block? why only
having the global gtt there?
> +
> +.. 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.36.1
>
On Wed, Jul 13, 2022 at 09:12:25AM +0100, Mauro Carvalho Chehab wrote:
> This is a large struct used to describe gem objects. It is
> currently partially documented. Finish its documentation, filling
> the gaps from git logs.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> .../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 ceed0d220ce3..8c09e493590d 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 | \
> @@ -343,15 +398,21 @@ struct drm_i915_gem_object {
> #define I915_BO_PROTECTED BIT(9)
> #define I915_BO_WAS_BOUND_BIT 10
> /**
> - * @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.
> *
> @@ -400,7 +461,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
> @@ -423,7 +484,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.
> @@ -509,23 +570,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.
> @@ -536,7 +603,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.
> *
> @@ -548,13 +615,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.
> @@ -572,94 +639,143 @@ 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;
> } 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.36.1
>
On Wed, Jul 13, 2022 at 09:12:03AM +0100, Mauro Carvalho Chehab wrote:
> 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.
cool, I didn't know that
Reviewed-by: Rodrigo Vivi <[email protected]>
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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 9feaf1a589f3..23a269fcf6ca 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.36.1
>
On Wed, Jul 13, 2022 at 09:12:07AM +0100, Mauro Carvalho Chehab wrote:
> 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.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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.36.1
>
On Wed, Jul 13, 2022 at 09:12:27AM +0100, Mauro Carvalho Chehab wrote:
> Currently, functions inside GuC aren't presented as part of the
> GuC documentation.
>
> Add them.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
could be squashed to the other guc patch, but anyways:
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> Documentation/gpu/i915.rst | 3 +++
> 1 file changed, 3 insertions(+)
>
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 9862d504df4d..8c21a90d8b5a 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -768,6 +768,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.36.1
>
On Wed, Jul 13, 2022 at 09:12:21AM +0100, Mauro Carvalho Chehab wrote:
> Both intel_runtime_pm.h and intel_pm.c contains kAPI for
> runtime PM. So, add them to the documentation.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> Documentation/gpu/i915.rst | 4 ++++
> 1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 3ee121a0ea62..c32409c03d32 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.36.1
>
On Wed, Jul 13, 2022 at 09:12:24AM +0100, 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.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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 5cf36a130061..ceed0d220ce3 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.36.1
>
On Wed, Jul 13, 2022 at 09:12:19AM +0100, Mauro Carvalho Chehab wrote:
> 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.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> Documentation/gpu/i915.rst | 22 ++++++++++++++++++++++
> 1 file changed, 22 insertions(+)
>
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index afd8c0e3c689..70f2f4826eba 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -596,6 +596,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.36.1
>
On Wed, Jul 13, 2022 at 09:12:26AM +0100, 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 <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> Documentation/gpu/i915.rst | 2 +
> drivers/gpu/drm/i915/gt/intel_gt_pm.h | 62 +++++++++++++++++++++++++++
> 2 files changed, 64 insertions(+)
>
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 6bb50edc6d79..9862d504df4d 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -709,6 +709,8 @@ Table Manager (TTM)
>
> .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c
>
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_pm.h
I don't believe this is the right placement for this.
the rest lgtm
> +
> Graphics Execution Manager (GEM)
> --------------------------------
>
> diff --git a/drivers/gpu/drm/i915/gt/intel_gt_pm.h b/drivers/gpu/drm/i915/gt/intel_gt_pm.h
> index bc898df7a48c..a8ea6846980a 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(>->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(>->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(>->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(>->wakeref);
> @@ -36,6 +72,14 @@ static inline void intel_gt_pm_might_get(struct intel_gt *gt)
> intel_wakeref_might_get(>->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(>->wakeref);
> @@ -51,10 +95,28 @@ static inline void intel_gt_pm_might_put(struct intel_gt *gt)
> intel_wakeref_might_put(>->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)
>
> +/**
> + * intel_gt_pm_wait_for_idle: Wait until the runtime PM reference is idle
> + * @gt: pointer to the graphics engine which contains the PM reference
> + *
> + * Wait for the earlier asynchronous release of the runtime PM reference. Note
> + * this will wait for any third party as well, so make sure you only wait
> + * when you have control over the GT runtime PM and trust no one else is
> + * acquiring it.
> + *
> + * Return: 0 on success, error code if killed.
> + */
> static inline int intel_gt_pm_wait_for_idle(struct intel_gt *gt)
> {
> return intel_wakeref_wait_for_idle(>->wakeref);
> --
> 2.36.1
>
On Wed, Jul 13, 2022 at 09:12:22AM +0100, Mauro Carvalho Chehab wrote:
> 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.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> Documentation/gpu/i915.rst | 38 ++++++++++++++++++++++++++++++++++++++
> 1 file changed, 38 insertions(+)
>
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index c32409c03d32..974754586be8 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -615,6 +615,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.36.1
>
On Wed, Jul 13, 2022 at 09:12:23AM +0100, 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 <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> Documentation/gpu/i915.rst | 87 ++++++++++++++++++++++++++++++++++++++
> 1 file changed, 87 insertions(+)
>
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 974754586be8..6bb50edc6d79 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,10 @@ Runtime Power Management
>
> .. kernel-doc:: drivers/gpu/drm/i915/intel_pm.c
>
> +.. kernel-doc:: drivers/gpu/drm/i915/intel_wakeref.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_active.h
not sure if this belongs to this group...
> +
> Interrupt Handling
> ------------------
>
> @@ -44,6 +53,28 @@ Interrupt Handling
> .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
> :functions: intel_runtime_pm_enable_interrupts
>
> +Error handling
> +--------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_gpu_error.c
not sure if this gt hang stuff deserves a separated section
alone and if the name is the best one....
> +
> +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)
^ missing space
> -------------------------------
>
> @@ -109,6 +140,54 @@ Workarounds
> .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c
> :doc: Hardware workarounds
>
> +32-bits compatible ioctl Logic
> +------------------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_ioc32.c
> +
> +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
> +
> +Ancillary routines
maybe simply have an "Others" section and put everything
that has only one item like the gpu hang one?
> +------------------
> +
> +.. 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
> +
> +
> +PXP
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
> =========================
>
> @@ -618,6 +697,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
> @@ -627,6 +712,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
in many cases I see only the .h or only the .c... why is that?
wouldn't be better already put both in all the cases?
> --
> 2.36.1
>
On Wed, Jul 13, 2022 at 09:12:20AM +0100, Mauro Carvalho Chehab wrote:
> 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.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
I haven't checked if these would be all the files, but the approach
looks reasonable to me.
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> Documentation/gpu/i915.rst | 41 ++++++++++++++++++++++++++++++++++++++
> 1 file changed, 41 insertions(+)
>
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 70f2f4826eba..3ee121a0ea62 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.36.1
>
On Wed, Jul 13, 2022 at 09:12:17AM +0100, Mauro Carvalho Chehab wrote:
> 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.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
same here, not checked if these would be all the files, but it is reasonable
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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.36.1
>
On Wed, Jul 13, 2022 at 09:11:59AM +0100, Mauro Carvalho Chehab wrote:
> 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'
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Rodrigo Vivi <[email protected]>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
>
> 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 9aad84059d56..9843831c9b37 100644
> --- a/drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c
> +++ b/drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c
> @@ -123,8 +123,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.
> @@ -188,7 +189,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.36.1
>
On Tue, 9 Aug 2022 05:51:39 -0400
Rodrigo Vivi <[email protected]> wrote:
> On Wed, Jul 13, 2022 at 09:12:03AM +0100, Mauro Carvalho Chehab wrote:
> > 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.
>
> cool, I didn't know that
Yeah, you can use almost all Sphinx tags inside a kernel-doc markup,
taking some care with indents and not conflicting with the things
that kernel-doc itself parses.
The same is also valid for uAPI stuff inside Documentation/ABI.
Regards,
Mauro
>
> Reviewed-by: Rodrigo Vivi <[email protected]>
>
>
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > ---
> >
> > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> > See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
> >
> > 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 9feaf1a589f3..23a269fcf6ca 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.36.1
> >
On Tue, 9 Aug 2022 06:12:06 -0400
Rodrigo Vivi <[email protected]> wrote:
> On Wed, Jul 13, 2022 at 09:12:26AM +0100, 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 <[email protected]>
> > ---
> >
> > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> > See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
> >
> > Documentation/gpu/i915.rst | 2 +
> > drivers/gpu/drm/i915/gt/intel_gt_pm.h | 62 +++++++++++++++++++++++++++
> > 2 files changed, 64 insertions(+)
> >
> > diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> > index 6bb50edc6d79..9862d504df4d 100644
> > --- a/Documentation/gpu/i915.rst
> > +++ b/Documentation/gpu/i915.rst
> > @@ -709,6 +709,8 @@ Table Manager (TTM)
> >
> > .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c
> >
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_pm.h
>
> I don't believe this is the right placement for this.
I'll add it then at:
Other GT functionality
Section.
Regards,
Mauro
>
> the rest lgtm
>
> > +
> > Graphics Execution Manager (GEM)
> > --------------------------------
> >
> > diff --git a/drivers/gpu/drm/i915/gt/intel_gt_pm.h b/drivers/gpu/drm/i915/gt/intel_gt_pm.h
> > index bc898df7a48c..a8ea6846980a 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(>->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(>->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(>->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(>->wakeref);
> > @@ -36,6 +72,14 @@ static inline void intel_gt_pm_might_get(struct intel_gt *gt)
> > intel_wakeref_might_get(>->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(>->wakeref);
> > @@ -51,10 +95,28 @@ static inline void intel_gt_pm_might_put(struct intel_gt *gt)
> > intel_wakeref_might_put(>->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)
> >
> > +/**
> > + * intel_gt_pm_wait_for_idle: Wait until the runtime PM reference is idle
> > + * @gt: pointer to the graphics engine which contains the PM reference
> > + *
> > + * Wait for the earlier asynchronous release of the runtime PM reference. Note
> > + * this will wait for any third party as well, so make sure you only wait
> > + * when you have control over the GT runtime PM and trust no one else is
> > + * acquiring it.
> > + *
> > + * Return: 0 on success, error code if killed.
> > + */
> > static inline int intel_gt_pm_wait_for_idle(struct intel_gt *gt)
> > {
> > return intel_wakeref_wait_for_idle(>->wakeref);
> > --
> > 2.36.1
> >
On Tue, 9 Aug 2022 06:20:57 -0400
Rodrigo Vivi <[email protected]> wrote:
> On Wed, Jul 13, 2022 at 09:12:23AM +0100, 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 <[email protected]>
> > ---
> >
> > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> > See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
> >
> > Documentation/gpu/i915.rst | 87 ++++++++++++++++++++++++++++++++++++++
> > 1 file changed, 87 insertions(+)
> >
> > diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> > index 974754586be8..6bb50edc6d79 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,10 @@ Runtime Power Management
> >
> > .. kernel-doc:: drivers/gpu/drm/i915/intel_pm.c
> >
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_wakeref.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_active.h
>
> not sure if this belongs to this group...
>
> > +
> > Interrupt Handling
> > ------------------
> >
> > @@ -44,6 +53,28 @@ Interrupt Handling
> > .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
> > :functions: intel_runtime_pm_enable_interrupts
> >
> > +Error handling
> > +--------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_gpu_error.c
>
> not sure if this gt hang stuff deserves a separated section
> alone and if the name is the best one....
>
> > +
> > +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)
>
> ^ missing space
>
> > -------------------------------
> >
> > @@ -109,6 +140,54 @@ Workarounds
> > .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c
> > :doc: Hardware workarounds
> >
> > +32-bits compatible ioctl Logic
> > +------------------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_ioc32.c
> > +
> > +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
> > +
> > +Ancillary routines
>
> maybe simply have an "Others" section and put everything
> that has only one item like the gpu hang one?
OK!
>
> > +------------------
> > +
> > +.. 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
> > +
> > +
> > +PXP
>
> 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
> > =========================
> >
> > @@ -618,6 +697,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
> > @@ -627,6 +712,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
>
> in many cases I see only the .h or only the .c... why is that?
> wouldn't be better already put both in all the cases?
No. Adding kernel-doc files that doesn't contain any markups
will produce warnings.
We're working hard upstream to have a zero-warnings policy for
documentation.
Regards,
Mauro
On Fri, 15 Jul 2022 17:40:25 -0400
Rodrigo Vivi <[email protected]> wrote:
> On Wed, Jul 13, 2022 at 09:12:04AM +0100, Mauro Carvalho Chehab wrote:
> > 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.
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
>
> Just trying to understand as well on why in a few you had chosen ```foo```
> and here **foo**. why?
>
No particular reason. I'll use ``foo`` here too, keeping your reviewed-by.
> anyway, not a blocker:
>
> Reviewed-by: Rodrigo Vivi <[email protected]>
>
>
>
> > ---
> >
> > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> > See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
> >
> > 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 b191915ab351..fe72c75a9c79 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.36.1
> >
On Tue, 9 Aug 2022 05:55:10 -0400
Rodrigo Vivi <[email protected]> wrote:
> On Wed, Jul 13, 2022 at 09:12:06AM +0100, Mauro Carvalho Chehab wrote:
> > 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.
>
> my first reaction was: "do we really need those new empty ( ) blocks?"
>
> Then I read this ;)
Yeah, it is tricky to get it right, due to kernel-doc + Sphinx here.
Also, I bet that this would be needed even for ReST files with
C code on it, as it is likely the C domain encoding at Sphinx that
handles continuation lines with "\" at the end...
>
> Reviewed-by: Rodrigo Vivi <[email protected]>
>
> >
> > Change the ascii artwork to be on code-blocks, starting all
> > lines at the same characters and not ending with a backslash.
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > ---
> >
> > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> > See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
> >
> > 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 f06babdb3a8c..d3393752b04b 100644
> > --- a/drivers/gpu/drm/i915/intel_pm.c
> > +++ b/drivers/gpu/drm/i915/intel_pm.c
> > @@ -684,18 +684,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
> > @@ -731,13 +733,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.36.1
> >
On Tue, 9 Aug 2022 06:01:53 -0400
Rodrigo Vivi <[email protected]> wrote:
> On Wed, Jul 13, 2022 at 09:12:18AM +0100, 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.
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > ---
> >
> > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> > See [PATCH v2 00/39] at: https://lore.kernel.org/all/[email protected]/
> >
> > Documentation/gpu/i915.rst | 43 +++++++++++++++++++++++++++++++++++++-
> > 1 file changed, 42 insertions(+), 1 deletion(-)
> >
> > diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> > index 2ad7941a79f2..afd8c0e3c689 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,48 @@ 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
> > +
> > +GT context
> > +----------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_context.h
>
> why does the context deserves a separated section and the
> many others below no?
Good question. The patches adding stuff to i915.rst are the
hardest ones to produce, in the sense that it is not easy to have
a common criteria about when creating or not a new section.
I tried to follow the same as other things for the same type, but
it is hard to classify.
The main point is that they should be somewhere there, in order to start
producing errors when building the docs. Reorganizing those markups should
be easily done once all files with kernel-docs gets added there.
Anyway, I'll keep this under:
Other GT functionality
Section. We can shift things later on as needed.
> > +
> > +Graphics Translation Tables
> > +---------------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt.c
> > +
> > +Other GT functionality
> > +----------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gsc.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.h
>
> Why aren't these gtt ones in the above block? why only
> having the global gtt there?
Makes sense. I'll place GTT together with GGTT.
>
> > +
> > +.. 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.36.1
> >