There are several kernel-doc markups along the i915 driver that aren't part
of the i915.rst file, nor are included on any other file under Documentation.
Maybe due to that, there are several kernel-doc markups that report problems
when checked with scripts/kernel-doc. More than that, some of them also
have problems when actually integrated at the building system, as reported
by Sphinx.
Along the issues we have:
- renamed symbols where the prototype doesn't match the kernel-doc name;
- some markups doesn't have the symbol name on it;
- typos when defining parameter;
- some parameters are missing;
- some ascii artwork aren't properly displayed after parsed by Sphinx;
- some other tags produce bad results and warnings after parsed by html build;
- some "/**" patterns exist on places that aren't kernel-doc markups.
This series, against drm-tip, fix all the above issues and all all such files to
i915.rst. This way, it will be easier to avoid other problems to be introduced.
While here, I also added SPDX on two display files. Besides being the current
way to indicate the license, it also makes easier to find all files with kernel-doc
markups, as all it is needed is to search for "/**" at i915 files to know what of
them have embedded documentation.
PS.: my end goal here is to ensure that the TLB patch series I'm about to
send will be properly documented. For that to happen, let's first fix all
warnings when building the documentation ;-)
---
v3:
- Dropped patches with issues already fixed;
- Addressed Rodrigo's comments.
v2:
- Added 3 already-existing patches form other PRs addressing some of the
issues. The subjects were renamed, in order to describe what they're
doing.
- Fixed checkpatch warnings;
- Added 4 additional patches at the end, documenting some structs
at i915_gem_object_types.h and intel_gt_pm.h, plus adding
intel-guc.c internal functions to the generated documentation.
Mauro Carvalho Chehab (37):
drm/i915: fix kernel-doc trivial warnings on i915/*.[ch] files
drm/i915: display: fix kernel-doc markup warnings
drm/i915: gt: fix some Kernel-doc issues
drm/i915: gvt: fix kernel-doc trivial warnings
drm/i915: gem: fix some Kernel-doc issues
drm/i915: intel_wakeref.h: fix some kernel-doc markups
drm/i915: i915_gem_ttm: fix a kernel-doc markup
drm/i915: i915_gem_ttm_pm.c: fix kernel-doc markups
drm/i915: gem: add kernel-doc description for some function parameters
drm/i915: i915_gpu_error.c: document dump_flags
drm/i915: document kernel-doc trivial issues
drm/i915: intel_dp_link_training.c: fix kernel-doc markup
drm/i915: intel_fb: fix a kernel-doc issue with Sphinx
drm/i915: skl_scaler: fix return value kernel-doc markup
drm/i915: intel_pm.c: fix some ascii artwork at kernel-doc
drm/i915: i915_gem_region.h: fix i915_gem_apply_to_region_ops doc
drm/i915: i915_gem_wait.c: fix a kernel-doc markup
drm/i915: fix i915_gem_ttm_move.c DOC: markup
drm/i915: stop using kernel-doc markups for something else
drm/i915: dvo_ch7xxx.c: use SPDX header
drm/i915: dvo_sil164.c: use SPDX header
drm/i915: i915_vma_resource.c: fix some kernel-doc markups
drm/i915: i915_gem.c fix a kernel-doc issue
drm/i915: i915_scatterlist.h: fix some kernel-doc markups
drm/i915: i915_deps: use a shorter title markup
docs: gpu: i915.rst: display: add kernel-doc markups
docs: gpu: i915.rst: gt: add more kernel-doc markups
docs: gpu: i915.rst: GuC: add more kernel-doc markups
docs: gpu: i915.rst: GVT: add more kernel-doc markups
docs: gpu: i915.rst: PM: add more kernel-doc markups
docs: gpu: i915.rst: GEM/TTM: add more kernel-doc markups
docs: gpu: i915.rst: add the remaining kernel-doc markup files
drm/i915 i915_gem_object_types.h: document struct i915_lut_handle
drm/i915: document struct drm_i915_gem_object
drm/i915: add descriptions for some RPM macros at intel_gt_pm.h
drm/i915: add GuC functions to the documentation
drm/i915: be consistent with kernel-doc function declaration
Documentation/gpu/i915.rst | 283 +++++++++++++++++-
drivers/gpu/drm/i915/display/dvo_ch7017.c | 26 +-
drivers/gpu/drm/i915/display/dvo_ch7xxx.c | 39 +--
drivers/gpu/drm/i915/display/dvo_sil164.c | 32 +-
drivers/gpu/drm/i915/display/intel_atomic.c | 2 +-
drivers/gpu/drm/i915/display/intel_audio.c | 4 +-
drivers/gpu/drm/i915/display/intel_crtc.c | 4 +-
.../drm/i915/display/intel_display_debugfs.c | 2 +-
.../drm/i915/display/intel_display_power.c | 2 +-
.../drm/i915/display/intel_display_types.h | 2 +-
drivers/gpu/drm/i915/display/intel_dmc.c | 10 +-
.../drm/i915/display/intel_dp_link_training.c | 2 +
drivers/gpu/drm/i915/display/intel_dsb.c | 10 +-
drivers/gpu/drm/i915/display/intel_dvo_dev.h | 6 +-
drivers/gpu/drm/i915/display/intel_fb.c | 2 +-
.../gpu/drm/i915/display/intel_lpe_audio.c | 8 +-
drivers/gpu/drm/i915/display/intel_sdvo.c | 4 +-
drivers/gpu/drm/i915/display/intel_tc.c | 2 +-
drivers/gpu/drm/i915/display/intel_tv.c | 2 +-
drivers/gpu/drm/i915/display/skl_scaler.c | 6 +-
drivers/gpu/drm/i915/gem/i915_gem_create.c | 8 +-
drivers/gpu/drm/i915/gem/i915_gem_domain.c | 17 +-
drivers/gpu/drm/i915/gem/i915_gem_object.c | 2 +
drivers/gpu/drm/i915/gem/i915_gem_object.h | 2 +-
.../gpu/drm/i915/gem/i915_gem_object_types.h | 212 ++++++++++---
drivers/gpu/drm/i915/gem/i915_gem_region.h | 8 +-
drivers/gpu/drm/i915/gem/i915_gem_ttm.c | 2 +
drivers/gpu/drm/i915/gem/i915_gem_ttm.h | 1 +
drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c | 4 +-
drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c | 8 +-
drivers/gpu/drm/i915/gem/i915_gem_wait.c | 26 +-
drivers/gpu/drm/i915/gt/intel_context.h | 6 +-
drivers/gpu/drm/i915/gt/intel_context_types.h | 69 +++--
drivers/gpu/drm/i915/gt/intel_engine_cs.c | 14 +-
drivers/gpu/drm/i915/gt/intel_engine_types.h | 1 +
drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h | 2 +-
drivers/gpu/drm/i915/gt/intel_gt_pm.h | 51 ++++
drivers/gpu/drm/i915/gt/intel_gt_types.h | 12 +-
drivers/gpu/drm/i915/gt/intel_gtt.h | 6 +-
drivers/gpu/drm/i915/gt/intel_reset_types.h | 4 +-
drivers/gpu/drm/i915/gt/intel_rps.c | 4 +-
.../gpu/drm/i915/gt/intel_timeline_types.h | 6 +-
.../drm/i915/gt/shaders/clear_kernel/hsw.asm | 4 +-
.../drm/i915/gt/shaders/clear_kernel/ivb.asm | 4 +-
drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h | 24 +-
drivers/gpu/drm/i915/gt/uc/intel_guc.c | 10 +-
drivers/gpu/drm/i915/gt/uc/intel_guc.h | 2 +-
drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c | 4 +-
drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c | 2 +-
drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h | 2 +-
.../gpu/drm/i915/gt/uc/intel_guc_hwconfig.c | 5 +-
drivers/gpu/drm/i915/gt/uc/intel_guc_slpc.c | 8 +-
drivers/gpu/drm/i915/gt/uc/intel_huc.c | 4 +-
drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c | 2 +-
drivers/gpu/drm/i915/gt/uc/intel_uc_fw.h | 2 +-
drivers/gpu/drm/i915/gvt/cfg_space.c | 2 +-
drivers/gpu/drm/i915/gvt/dmabuf.h | 2 +-
drivers/gpu/drm/i915/gvt/page_track.c | 2 +-
drivers/gpu/drm/i915/gvt/vgpu.c | 6 +-
drivers/gpu/drm/i915/i915_active.h | 14 +-
drivers/gpu/drm/i915/i915_cmd_parser.c | 8 +-
drivers/gpu/drm/i915/i915_deps.c | 4 +-
drivers/gpu/drm/i915/i915_drm_client.h | 2 +-
drivers/gpu/drm/i915/i915_drv.h | 24 +-
drivers/gpu/drm/i915/i915_file_private.h | 8 +-
drivers/gpu/drm/i915/i915_gem.c | 12 +-
drivers/gpu/drm/i915/i915_gpu_error.c | 3 +-
drivers/gpu/drm/i915/i915_gpu_error.h | 4 +-
drivers/gpu/drm/i915/i915_pmu.h | 38 +--
drivers/gpu/drm/i915/i915_reg_defs.h | 12 +-
drivers/gpu/drm/i915/i915_request.h | 4 +-
drivers/gpu/drm/i915/i915_scatterlist.c | 2 +-
drivers/gpu/drm/i915/i915_scatterlist.h | 12 +-
drivers/gpu/drm/i915/i915_utils.h | 2 +-
drivers/gpu/drm/i915/i915_vma.c | 2 +
drivers/gpu/drm/i915/i915_vma_resource.c | 4 +-
drivers/gpu/drm/i915/i915_vma_resource.h | 3 +-
drivers/gpu/drm/i915/intel_pm.c | 33 +-
drivers/gpu/drm/i915/intel_region_ttm.c | 3 +-
drivers/gpu/drm/i915/intel_uncore.h | 4 +-
drivers/gpu/drm/i915/intel_wakeref.h | 4 +-
drivers/gpu/drm/i915/intel_wopcm.c | 4 +-
82 files changed, 826 insertions(+), 378 deletions(-)
--
2.37.3
The doc markup should not end with ":", as it would generate a
warning on Sphinx while generating the cross-reference tag.
Reviewed-by: Rodrigo Vivi <[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 v3 00/37] 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.37.3
There are some parameters missing at the kernel-doc markups on
some gem files. Some of those are trivial enough to be added.
Document them.
Reviewed-by: Nirmoy Das <[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 v3 00/37] 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 85482a04d158..35637e2f51f3 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_object.c
+++ b/drivers/gpu/drm/i915/gem/i915_gem_object.c
@@ -815,6 +815,8 @@ int i915_gem_object_wait_moving_fence(struct drm_i915_gem_object *obj,
* in an unknown_state. This means that userspace must NEVER be allowed to touch
* the pages, with either the GPU or CPU.
*
+ * @obj: The object to check its state.
+ *
* ONLY valid to be called after ensuring that all kernel fences have signalled
* (in particular the fence for moving/clearing the object).
*/
diff --git a/drivers/gpu/drm/i915/gem/i915_gem_ttm.h b/drivers/gpu/drm/i915/gem/i915_gem_ttm.h
index e4842b4296fc..64151f40098f 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_ttm.h
+++ b/drivers/gpu/drm/i915/gem/i915_gem_ttm.h
@@ -30,6 +30,7 @@ void i915_ttm_bo_destroy(struct ttm_buffer_object *bo);
/**
* i915_ttm_to_gem - Convert a struct ttm_buffer_object to an embedding
* struct drm_i915_gem_object.
+ * @bo: The ttm buffer object.
*
* Return: Pointer to the embedding struct ttm_buffer_object, or NULL
* if the object was not an i915 ttm object.
diff --git a/drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c b/drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c
index 9a7e50534b84..56217d324a9b 100644
--- a/drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c
+++ b/drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c
@@ -237,6 +237,7 @@ static struct dma_fence *i915_ttm_accel_move(struct ttm_buffer_object *bo,
* @_src_iter: Storage space for the source kmap iterator.
* @dst_iter: Pointer to the destination kmap iterator.
* @src_iter: Pointer to the source kmap iterator.
+ * @num_pages: Number of pages to copy or to be cleared.
* @clear: Whether to clear instead of copy.
* @src_rsgt: Refcounted scatter-gather list of source memory.
* @dst_rsgt: Refcounted scatter-gather list of destination memory.
@@ -541,6 +542,7 @@ __i915_ttm_move(struct ttm_buffer_object *bo,
* i915_ttm_move - The TTM move callback used by i915.
* @bo: The buffer object.
* @evict: Whether this is an eviction.
+ * @ctx: Pointer to a struct ttm_operation_ctx
* @dst_mem: The destination ttm resource.
* @hop: If we need multihop, what temporary memory type to move to.
*
--
2.37.3
The kernel-doc markup for i915_gem_apply_to_region_ops() has some
issues:
1. The field should be marked as @process_obj;
2. The callback parameters aren't document properly, as sphinx
will consider them to be placed at the wrong place.
Fix (1) and change the way the parameters are described, using
a list, in order for it to be properly parsed during documentation
build time.
Reviewed-by: Rodrigo Vivi <[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 v3 00/37] 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.37.3
Some functions seem to have been renamed without updating the kernel-doc
markup causing warnings. Also, struct intel_vgpu_dmabuf_obj is not
properly documented, but has a kerneld-doc markup.
Fix those warnings:
drivers/gpu/drm/i915/gvt/aperture_gm.c:308: warning: expecting prototype for inte_gvt_free_vgpu_resource(). Prototype was for intel_vgpu_free_resource() instead
drivers/gpu/drm/i915/gvt/aperture_gm.c:344: warning: expecting prototype for intel_alloc_vgpu_resource(). Prototype was for intel_vgpu_alloc_resource() instead
drivers/gpu/drm/i915/gvt/cfg_space.c:257: warning: expecting prototype for intel_vgpu_emulate_cfg_read(). Prototype was for intel_vgpu_emulate_cfg_write() instead
drivers/gpu/drm/i915/gvt/dmabuf.h:61: warning: Function parameter or member 'vgpu' not described in 'intel_vgpu_dmabuf_obj'
drivers/gpu/drm/i915/gvt/dmabuf.h:61: warning: Function parameter or member 'info' not described in 'intel_vgpu_dmabuf_obj'
drivers/gpu/drm/i915/gvt/dmabuf.h:61: warning: Function parameter or member 'dmabuf_id' not described in 'intel_vgpu_dmabuf_obj'
drivers/gpu/drm/i915/gvt/dmabuf.h:61: warning: Function parameter or member 'kref' not described in 'intel_vgpu_dmabuf_obj'
drivers/gpu/drm/i915/gvt/dmabuf.h:61: warning: Function parameter or member 'initref' not described in 'intel_vgpu_dmabuf_obj'
drivers/gpu/drm/i915/gvt/dmabuf.h:61: warning: Function parameter or member 'list' not described in 'intel_vgpu_dmabuf_obj'
drivers/gpu/drm/i915/gvt/handlers.c:3066: warning: expecting prototype for intel_t_default_mmio_write(). Prototype was for intel_vgpu_default_mmio_write() instead
drivers/gpu/drm/i915/gvt/mmio_context.c:560: warning: expecting prototype for intel_gvt_switch_render_mmio(). Prototype was for intel_gvt_switch_mmio() instead
drivers/gpu/drm/i915/gvt/page_track.c:131: warning: expecting prototype for intel_vgpu_enable_page_track(). Prototype was for intel_vgpu_disable_page_track() instead
drivers/gpu/drm/i915/gvt/vgpu.c:215: warning: expecting prototype for intel_gvt_active_vgpu(). Prototype was for intel_gvt_activate_vgpu() instead
drivers/gpu/drm/i915/gvt/vgpu.c:230: warning: expecting prototype for intel_gvt_deactive_vgpu(). Prototype was for intel_gvt_deactivate_vgpu() instead
drivers/gpu/drm/i915/gvt/vgpu.c:358: warning: expecting prototype for intel_gvt_destroy_vgpu(). Prototype was for intel_gvt_destroy_idle_vgpu() instead
Reviewed-by: Rodrigo Vivi <[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 v3 00/37] 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 eef3bba8a41b..bff63babacd5 100644
--- a/drivers/gpu/drm/i915/gvt/cfg_space.c
+++ b/drivers/gpu/drm/i915/gvt/cfg_space.c
@@ -244,7 +244,7 @@ static void emulate_pci_bar_write(struct intel_vgpu *vgpu, unsigned int offset,
}
/**
- * intel_vgpu_emulate_cfg_read - emulate vGPU configuration space write
+ * intel_vgpu_emulate_cfg_write - emulate vGPU configuration space write
* @vgpu: target vgpu
* @offset: offset
* @p_data: write data ptr
diff --git a/drivers/gpu/drm/i915/gvt/dmabuf.h b/drivers/gpu/drm/i915/gvt/dmabuf.h
index 5f8f03fb1d1b..3dcdb6570eda 100644
--- a/drivers/gpu/drm/i915/gvt/dmabuf.h
+++ b/drivers/gpu/drm/i915/gvt/dmabuf.h
@@ -48,7 +48,7 @@ struct intel_vgpu_fb_info {
struct intel_vgpu_dmabuf_obj *obj;
};
-/**
+/*
* struct intel_vgpu_dmabuf_obj- Intel vGPU device buffer object
*/
struct intel_vgpu_dmabuf_obj {
diff --git a/drivers/gpu/drm/i915/gvt/page_track.c b/drivers/gpu/drm/i915/gvt/page_track.c
index 3375b51c75f1..df34e73cba41 100644
--- a/drivers/gpu/drm/i915/gvt/page_track.c
+++ b/drivers/gpu/drm/i915/gvt/page_track.c
@@ -120,7 +120,7 @@ int intel_vgpu_enable_page_track(struct intel_vgpu *vgpu, unsigned long gfn)
}
/**
- * intel_vgpu_enable_page_track - cancel write-protection on guest page
+ * intel_vgpu_disable_page_track - cancel write-protection on guest page
* @vgpu: a vGPU
* @gfn: the gfn of guest page
*
diff --git a/drivers/gpu/drm/i915/gvt/vgpu.c b/drivers/gpu/drm/i915/gvt/vgpu.c
index 46da19b3225d..8e71cda19995 100644
--- a/drivers/gpu/drm/i915/gvt/vgpu.c
+++ b/drivers/gpu/drm/i915/gvt/vgpu.c
@@ -205,7 +205,7 @@ static void intel_gvt_update_vgpu_types(struct intel_gvt *gvt)
}
/**
- * intel_gvt_active_vgpu - activate a virtual GPU
+ * intel_gvt_activate_vgpu - activate a virtual GPU
* @vgpu: virtual GPU
*
* This function is called when user wants to activate a virtual GPU.
@@ -219,7 +219,7 @@ void intel_gvt_activate_vgpu(struct intel_vgpu *vgpu)
}
/**
- * intel_gvt_deactive_vgpu - deactivate a virtual GPU
+ * intel_gvt_deactivate_vgpu - deactivate a virtual GPU
* @vgpu: virtual GPU
*
* This function is called when user wants to deactivate a virtual GPU.
@@ -348,7 +348,7 @@ struct intel_vgpu *intel_gvt_create_idle_vgpu(struct intel_gvt *gvt)
}
/**
- * intel_gvt_destroy_vgpu - destroy an idle virtual GPU
+ * intel_gvt_destroy_idle_vgpu - destroy an idle virtual GPU
* @vgpu: virtual GPU
*
* This function is called when user wants to destroy an idle virtual GPU.
--
2.37.3
Building docs currently produces this warning:
Documentation/foo/i915:159: ./drivers/gpu/drm/i915/i915_scatterlist.h:73: WARNING: Inline strong start-string without end-string.
That's because @foo evaluates into **foo**, and placing anything
after it without spaces cause Sphinx to warn and do the wrong
thing.. So, replace them by a different Sphinx-compatible tag.
Reviewed-by: Rodrigo Vivi <[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 v3 00/37] 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 79b70ae2e766..ac77f2668544 100644
--- a/drivers/gpu/drm/i915/i915_scatterlist.h
+++ b/drivers/gpu/drm/i915/i915_scatterlist.h
@@ -70,7 +70,7 @@ static inline struct scatterlist *____sg_next(struct scatterlist *sg)
*
* Description:
* If the entry is the last, return NULL; otherwise, step to the next
- * element in the array (@sg@+1). If that's a chain pointer, follow it;
+ * element in the array (``sg@+1``). If that's a chain pointer, follow it;
* otherwise just return the pointer to the current element.
**/
static inline struct scatterlist *__sg_next(struct scatterlist *sg)
--
2.37.3
Prevent this Sphinx warning:
Documentation/foo/i915:728: ./drivers/gpu/drm/i915/i915_gem.c:447: WARNING: Inline emphasis start-string without end-string.
By using @data to identify the data field, as expected by kernel-doc.
Reviewed-by: Rodrigo Vivi <[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 v3 00/37] 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 f68fa0732363..2b5b2be91a24 100644
--- a/drivers/gpu/drm/i915/i915_gem.c
+++ b/drivers/gpu/drm/i915/i915_gem.c
@@ -444,7 +444,7 @@ i915_gem_gtt_pread(struct drm_i915_gem_object *obj,
* @data: ioctl data blob
* @file: drm file pointer
*
- * On error, the contents of *data are undefined.
+ * On error, the contents of @data is undefined.
*/
int
i915_gem_pread_ioctl(struct drm_device *dev, void *data,
--
2.37.3
Two documented functions don't match the kernel-doc comments,
as reported by kernel-doc:
drivers/gpu/drm/i915/intel_wakeref.h:117: warning: expecting prototype for intel_wakeref_get_if_in_use(). Prototype was for intel_wakeref_get_if_active() instead
drivers/gpu/drm/i915/intel_wakeref.h:149: warning: expecting prototype for intel_wakeref_put_flags(). Prototype was for __intel_wakeref_put() instead
Fix them.
Additionally, improve title for intel_wakeref_get_if_active().
Reviewed-by: Rodrigo Vivi <[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 v3 00/37] 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.37.3
We can't use %foo[<something>] as this produces a bad markup.
Use instead, the emphasis markup directly.
Fix this issue:
Documentation/gpu/i915:136: ./drivers/gpu/drm/i915/display/intel_fb.c:280: WARNING: Inline strong start-string without end-string.
Reviewed-by: Rodrigo Vivi <[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 v3 00/37] 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 eefa33c555ac..ba413e38033d 100644
--- a/drivers/gpu/drm/i915/display/intel_fb.c
+++ b/drivers/gpu/drm/i915/display/intel_fb.c
@@ -276,7 +276,7 @@ lookup_format_info(const struct drm_format_info formats[],
* @cmd: FB add command structure
*
* Returns:
- * Returns the format information for @cmd->pixel_format specific to @cmd->modifier[0],
+ * Returns the format information for @cmd->pixel_format specific to ``cmd->modifier[0]``,
* or %NULL if the modifier doesn't override the format.
*/
const struct drm_format_info *
--
2.37.3
Currently, functions inside GuC aren't presented as part of the
GuC documentation.
Add them.
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 v3 00/37] 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 59c532fe0332..b71e9720a1ac 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -759,6 +759,9 @@ GuC
.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.h
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c
+ :internal:
+
.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_actions_slpc_abi.h
.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c
--
2.37.3
This file is licensed with MIT license. Change its license text
to use SPDX.
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 v3 00/37] 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.37.3