[PATCH] drm/gpusvm: Fix kernel-doc
Matthew Brost
matthew.brost at intel.com
Fri Mar 7 15:55:13 UTC 2025
On Fri, Mar 07, 2025 at 07:40:28AM -0800, Lucas De Marchi wrote:
> Due to wrong `.. kernel-doc` directive in Documentation/gpu/rfc/gpusvm.rst
> the documentation was actually not parsing anything from
> drivers/gpu/drm/drm_gpusvm.c. This fixes the kernel-doc include and all
> warnings/errors created when doing so.
>
Thanks for fixing this. One nit below.
> Cc: Simona Vetter <simona.vetter at ffwll.ch>
> Cc: Dave Airlie <airlied at redhat.com>
> Cc: Christian König <christian.koenig at amd.com>
> Cc: Matthew Brost <matthew.brost at intel.com>
> Cc: Thomas Hellström <thomas.hellstrom at linux.intel.com>
> Reported-by: Stephen Rothwell <sfr at canb.auug.org.au>
> Closes: https://lore.kernel.org/intel-xe/20250307195239.57abcd2d@canb.auug.org.au/
> Fixes: 99624bdff867 ("drm/gpusvm: Add support for GPU Shared Virtual Memory")
> Signed-off-by: Lucas De Marchi <lucas.demarchi at intel.com>
> ---
> Documentation/gpu/rfc/gpusvm.rst | 15 +++--
> drivers/gpu/drm/drm_gpusvm.c | 138 +++++++++++++++++++++------------------
> 2 files changed, 86 insertions(+), 67 deletions(-)
>
> diff --git a/Documentation/gpu/rfc/gpusvm.rst b/Documentation/gpu/rfc/gpusvm.rst
> index 073e46065d9c6ce7de48aadd7d1cc5e57c0a9e21..bcf66a8137a64404cd559d0cf6cd6cb4548e2098 100644
> --- a/Documentation/gpu/rfc/gpusvm.rst
> +++ b/Documentation/gpu/rfc/gpusvm.rst
> @@ -67,14 +67,19 @@ Agreed upon design principles
> Overview of baseline design
> ===========================
>
> -Baseline design is simple as possible to get a working basline in which can be
> -built upon.
> -
> -.. kernel-doc:: drivers/gpu/drm/xe/drm_gpusvm.c
> +.. kernel-doc:: drivers/gpu/drm/drm_gpusvm.c
> :doc: Overview
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_gpusvm.c
> :doc: Locking
> - :doc: Migrataion
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_gpusvm.c
> + :doc: Migration
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_gpusvm.c
> :doc: Partial Unmapping of Ranges
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_gpusvm.c
> :doc: Examples
>
> Possible future design features
> diff --git a/drivers/gpu/drm/drm_gpusvm.c b/drivers/gpu/drm/drm_gpusvm.c
> index f314f5c4af0f309e899bedace52c3eb9ad82e0ac..d7ec12483554791b513a1587b87071759cb53943 100644
> --- a/drivers/gpu/drm/drm_gpusvm.c
> +++ b/drivers/gpu/drm/drm_gpusvm.c
> @@ -23,54 +23,63 @@
> * DOC: Overview
> *
> * GPU Shared Virtual Memory (GPU SVM) layer for the Direct Rendering Manager (DRM)
> - *
> - * The GPU SVM layer is a component of the DRM framework designed to manage shared
> - * virtual memory between the CPU and GPU. It enables efficient data exchange and
> - * processing for GPU-accelerated applications by allowing memory sharing and
> + * is a component of the DRM framework designed to manage shared virtual memory
> + * between the CPU and GPU. It enables efficient data exchange and processing
> + * for GPU-accelerated applications by allowing memory sharing and
> * synchronization between the CPU's and GPU's virtual address spaces.
> *
> * Key GPU SVM Components:
> - * - Notifiers: Notifiers: Used for tracking memory intervals and notifying the
> - * GPU of changes, notifiers are sized based on a GPU SVM
> - * initialization parameter, with a recommendation of 512M or
> - * larger. They maintain a Red-BlacK tree and a list of ranges that
> - * fall within the notifier interval. Notifiers are tracked within
> - * a GPU SVM Red-BlacK tree and list and are dynamically inserted
> - * or removed as ranges within the interval are created or
> - * destroyed.
> - * - Ranges: Represent memory ranges mapped in a DRM device and managed
> - * by GPU SVM. They are sized based on an array of chunk sizes, which
> - * is a GPU SVM initialization parameter, and the CPU address space.
> - * Upon GPU fault, the largest aligned chunk that fits within the
> - * faulting CPU address space is chosen for the range size. Ranges are
> - * expected to be dynamically allocated on GPU fault and removed on an
> - * MMU notifier UNMAP event. As mentioned above, ranges are tracked in
> - * a notifier's Red-Black tree.
> - * - Operations: Define the interface for driver-specific GPU SVM operations
> - * such as range allocation, notifier allocation, and
> - * invalidations.
> - * - Device Memory Allocations: Embedded structure containing enough information
> - * for GPU SVM to migrate to / from device memory.
> - * - Device Memory Operations: Define the interface for driver-specific device
> - * memory operations release memory, populate pfns,
> - * and copy to / from device memory.
> - *
> - * This layer provides interfaces for allocating, mapping, migrating, and
> - * releasing memory ranges between the CPU and GPU. It handles all core memory
> - * management interactions (DMA mapping, HMM, and migration) and provides
> - * driver-specific virtual functions (vfuncs). This infrastructure is sufficient
> - * to build the expected driver components for an SVM implementation as detailed
> - * below.
> + *
> + * - Notifiers:
> + * Used for tracking memory intervals and notifying the GPU of changes,
> + * notifiers are sized based on a GPU SVM initialization parameter, with a
> + * recommendation of 512M or larger. They maintain a Red-BlacK tree and a
> + * list of ranges that fall within the notifier interval. Notifiers are
> + * tracked within a GPU SVM Red-BlacK tree and list and are dynamically
> + * inserted or removed as ranges within the interval are created or
> + * destroyed.
> + * - Ranges:
> + * Represent memory ranges mapped in a DRM device and managed by GPU SVM.
> + * They are sized based on an array of chunk sizes, which is a GPU SVM
> + * initialization parameter, and the CPU address space. Upon GPU fault,
> + * the largest aligned chunk that fits within the faulting CPU address
> + * space is chosen for the range size. Ranges are expected to be
> + * dynamically allocated on GPU fault and removed on an MMU notifier UNMAP
> + * event. As mentioned above, ranges are tracked in a notifier's Red-Black
> + * tree.
> + *
> + * - Operations:
> + * Define the interface for driver-specific GPU SVM operations such as
> + * range allocation, notifier allocation, and invalidations.
> + *
> + * - Device Memory Allocations:
> + * Embedded structure containing enough information for GPU SVM to migrate
> + * to / from device memory.
> + *
> + * - Device Memory Operations:
> + * Define the interface for driver-specific device memory operations
> + * release memory, populate pfns, and copy to / from device memory.
> + *
> + * This layer provides interfaces for allocating, mapping, migrating, and
> + * releasing memory ranges between the CPU and GPU. It handles all core
> + * memory management interactions (DMA mapping, HMM, and migration) and
> + * provides driver-specific virtual functions (vfuncs). This infrastructure
> + * is sufficient to build the expected driver components for an SVM
> + * implementation as detailed below.
I think you have an extra indentation here.
With this fixed:
Reviewed-by: Matthew Brost <matthew.brost at intel.com>
> *
> * Expected Driver Components:
> - * - GPU page fault handler: Used to create ranges and notifiers based on the
> - * fault address, optionally migrate the range to
> - * device memory, and create GPU bindings.
> - * - Garbage collector: Used to unmap and destroy GPU bindings for ranges.
> - * Ranges are expected to be added to the garbage collector
> - * upon a MMU_NOTIFY_UNMAP event in notifier callback.
> - * - Notifier callback: Used to invalidate and DMA unmap GPU bindings for
> - * ranges.
> + *
> + * - GPU page fault handler:
> + * Used to create ranges and notifiers based on the fault address,
> + * optionally migrate the range to device memory, and create GPU bindings.
> + *
> + * - Garbage collector:
> + * Used to unmap and destroy GPU bindings for ranges. Ranges are expected
> + * to be added to the garbage collector upon a MMU_NOTIFY_UNMAP event in
> + * notifier callback.
> + *
> + * - Notifier callback:
> + * Used to invalidate and DMA unmap GPU bindings for ranges.
> */
>
> /**
> @@ -83,9 +92,9 @@
> * range RB tree and list, as well as the range's DMA mappings and sequence
> * number. GPU SVM manages all necessary locking and unlocking operations,
> * except for the recheck range's pages being valid
> - * (drm_gpusvm_range_pages_valid) when the driver is committing GPU bindings. This
> - * lock corresponds to the 'driver->update' lock mentioned in the HMM
> - * documentation (TODO: Link). Future revisions may transition from a GPU SVM
> + * (drm_gpusvm_range_pages_valid) when the driver is committing GPU bindings.
> + * This lock corresponds to the ``driver->update`` lock mentioned in
> + * Documentation/mm/hmm.rst. Future revisions may transition from a GPU SVM
> * global lock to a per-notifier lock if finer-grained locking is deemed
> * necessary.
> *
> @@ -102,11 +111,11 @@
> * DOC: Migration
> *
> * The migration support is quite simple, allowing migration between RAM and
> - * device memory at the range granularity. For example, GPU SVM currently does not
> - * support mixing RAM and device memory pages within a range. This means that upon GPU
> - * fault, the entire range can be migrated to device memory, and upon CPU fault, the
> - * entire range is migrated to RAM. Mixed RAM and device memory storage within a range
> - * could be added in the future if required.
> + * device memory at the range granularity. For example, GPU SVM currently does
> + * not support mixing RAM and device memory pages within a range. This means
> + * that upon GPU fault, the entire range can be migrated to device memory, and
> + * upon CPU fault, the entire range is migrated to RAM. Mixed RAM and device
> + * memory storage within a range could be added in the future if required.
> *
> * The reasoning for only supporting range granularity is as follows: it
> * simplifies the implementation, and range sizes are driver-defined and should
> @@ -119,11 +128,11 @@
> * Partial unmapping of ranges (e.g., 1M out of 2M is unmapped by CPU resulting
> * in MMU_NOTIFY_UNMAP event) presents several challenges, with the main one
> * being that a subset of the range still has CPU and GPU mappings. If the
> - * backing store for the range is in device memory, a subset of the backing store has
> - * references. One option would be to split the range and device memory backing store,
> - * but the implementation for this would be quite complicated. Given that
> - * partial unmappings are rare and driver-defined range sizes are relatively
> - * small, GPU SVM does not support splitting of ranges.
> + * backing store for the range is in device memory, a subset of the backing
> + * store has references. One option would be to split the range and device
> + * memory backing store, but the implementation for this would be quite
> + * complicated. Given that partial unmappings are rare and driver-defined range
> + * sizes are relatively small, GPU SVM does not support splitting of ranges.
> *
> * With no support for range splitting, upon partial unmapping of a range, the
> * driver is expected to invalidate and destroy the entire range. If the range
> @@ -144,6 +153,8 @@
> *
> * 1) GPU page fault handler
> *
> + * .. code-block:: c
> + *
> * int driver_bind_range(struct drm_gpusvm *gpusvm, struct drm_gpusvm_range *range)
> * {
> * int err = 0;
> @@ -208,7 +219,9 @@
> * return err;
> * }
> *
> - * 2) Garbage Collector.
> + * 2) Garbage Collector
> + *
> + * .. code-block:: c
> *
> * void __driver_garbage_collector(struct drm_gpusvm *gpusvm,
> * struct drm_gpusvm_range *range)
> @@ -231,7 +244,9 @@
> * __driver_garbage_collector(gpusvm, range);
> * }
> *
> - * 3) Notifier callback.
> + * 3) Notifier callback
> + *
> + * .. code-block:: c
> *
> * void driver_invalidation(struct drm_gpusvm *gpusvm,
> * struct drm_gpusvm_notifier *notifier,
> @@ -499,7 +514,7 @@ drm_gpusvm_notifier_invalidate(struct mmu_interval_notifier *mni,
> return true;
> }
>
> -/**
> +/*
> * drm_gpusvm_notifier_ops - MMU interval notifier operations for GPU SVM
> */
> static const struct mmu_interval_notifier_ops drm_gpusvm_notifier_ops = {
> @@ -2055,7 +2070,6 @@ static int __drm_gpusvm_migrate_to_ram(struct vm_area_struct *vas,
>
> /**
> * drm_gpusvm_range_evict - Evict GPU SVM range
> - * @pagemap: Pointer to the GPU SVM structure
> * @range: Pointer to the GPU SVM range to be removed
> *
> * This function evicts the specified GPU SVM range. This function will not
> @@ -2146,8 +2160,8 @@ static vm_fault_t drm_gpusvm_migrate_to_ram(struct vm_fault *vmf)
> return err ? VM_FAULT_SIGBUS : 0;
> }
>
> -/**
> - * drm_gpusvm_pagemap_ops() - Device page map operations for GPU SVM
> +/*
> + * drm_gpusvm_pagemap_ops - Device page map operations for GPU SVM
> */
> static const struct dev_pagemap_ops drm_gpusvm_pagemap_ops = {
> .page_free = drm_gpusvm_page_free,
>
> ---
> base-commit: 2c4fba1d065427efba4aaed5f80f4664c9f4a729
> change-id: 20250307-fix-svm-kerneldoc-8a4051e25d44
>
> Best regards,
> --
> Lucas De Marchi <lucas.demarchi at intel.com>
More information about the dri-devel
mailing list