[PATCH 1/3] drm/amd/kfd: Update documentation to match kernel standards
David.Francis at amd.com
David.Francis at amd.com
Tue Jul 19 14:03:36 UTC 2022
From: David Francis <David.Francis at amd.com>
The kernel documentation system requires things to be just so
in order to incorporate documentation into the sphinx system.
There were some comments in amdkfd which didn't meet that
standard. Tweak them so they do.
Signed-off-by: David Francis <David.Francis at amd.com>
Reviewed-by: Felix Kuehling <Felix.Kuehling at amd.com>
---
drivers/gpu/drm/amd/amdkfd/kfd_flat_memory.c | 27 +++++++++++++---
drivers/gpu/drm/amd/amdkfd/kfd_interrupt.c | 4 +--
include/uapi/linux/kfd_ioctl.h | 33 +++++++++++---------
3 files changed, 43 insertions(+), 21 deletions(-)
diff --git a/drivers/gpu/drm/amd/amdkfd/kfd_flat_memory.c b/drivers/gpu/drm/amd/amdkfd/kfd_flat_memory.c
index 8aebe408c544..075e4c80dd04 100644
--- a/drivers/gpu/drm/amd/amdkfd/kfd_flat_memory.c
+++ b/drivers/gpu/drm/amd/amdkfd/kfd_flat_memory.c
@@ -37,11 +37,14 @@
#include <linux/mman.h>
#include <linux/processor.h>
-/*
+/**
+ * DOC: Memory_Features
+ *
* The primary memory I/O features being added for revisions of gfxip
* beyond 7.0 (Kaveri) are:
*
* Access to ATC/IOMMU mapped memory w/ associated extension of VA to 48b
+ * ----------------------------------------------------------------------
*
* “Flat” shader memory access – These are new shader vector memory
* operations that do not reference a T#/V# so a “pointer” is what is
@@ -55,6 +58,7 @@
*
*
* System Unified Address - SUA
+ * ----------------------------
*
* The standard usage for GPU virtual addresses are that they are mapped by
* a set of page tables we call GPUVM and these page tables are managed by
@@ -72,13 +76,16 @@
* There are three fundamental address modes of operation for a given VMID
* (process) on the GPU:
*
- * HSA64 – 64b pointers and the default address space is ATC
- * HSA32 – 32b pointers and the default address space is ATC
- * GPUVM – 64b pointers and the default address space is GPUVM (driver
- * model mode)
+ * HSA64 – 64b pointers and the default address space is ATC
+ *
+ * HSA32 – 32b pointers and the default address space is ATC
+ *
+ * GPUVM – 64b pointers and the default address space is GPUVM (driver
+ * model mode)
*
*
* HSA64 - ATC/IOMMU 64b
+ * ---------------------
*
* A 64b pointer in the AMD64/IA64 CPU architecture is not fully utilized
* by the CPU so an AMD CPU can only access the high area
@@ -99,6 +106,7 @@
*
*
* 64b to 49b Address conversion
+ * -----------------------------
*
* Note that there are still significant portions of unused regions (holes)
* in the 64b address space even for the GPU. There are several places in
@@ -147,6 +155,7 @@
*
*
* “Spare” aperture (APE1)
+ * -----------------------
*
* We use the GPUVM aperture to differentiate ATC vs. GPUVM, but we also use
* apertures to set the Mtype field for S_LOAD/FLAT_* ops which is input to the
@@ -160,6 +169,7 @@
*
*
* General Aperture definitions and rules
+ * --------------------------------------
*
* An aperture register definition consists of a Base, Limit, Mtype, and
* usually an ATC bit indicating which translation tables that aperture uses.
@@ -187,6 +197,7 @@
*
*
* HSA32 - ATC/IOMMU 32b
+ * ---------------------
*
* For HSA32 mode, the pointers are interpreted as 32 bits and use a single GPR
* instead of two for the S_LOAD and FLAT_* ops. The entire GPUVM space of 40b
@@ -196,6 +207,7 @@
*
*
* GPUVM 64b mode (driver model)
+ * -----------------------------
*
* This mode is related to HSA64 in that the difference really is that
* the default aperture is GPUVM (ATC==0) and not ATC space.
@@ -204,6 +216,7 @@
*
*
* Device Unified Address - DUA
+ * ----------------------------
*
* Device unified address (DUA) is the name of the feature that maps the
* Shared(LDS) memory and Private(Scratch) memory into the overall address
@@ -220,6 +233,7 @@
*
*
* HSA64 Apertures for FLAT_* vector ops
+ * -------------------------------------
*
* For HSA64 SUA mode, the Shared and Private apertures are always placed
* in the hole w/ a limited selection of possible locations. The requests
@@ -231,6 +245,7 @@
*
*
* HSA32 Apertures for FLAT_* vector ops
+ * -------------------------------------
*
* In HSA32 mode, the Private and Shared apertures can be placed anywhere
* in the 32b space except at 0 (Private or Shared Base at zero disables
@@ -239,6 +254,7 @@
*
*
* GPUVM Apertures for FLAT_* vector ops
+ * -------------------------------------
*
* In GPUVM mode, the Shared/Private apertures are specified identically
* to HSA64 mode where they are always in the hole at a limited selection
@@ -246,6 +262,7 @@
*
*
* Aperture Definitions for SUA and DUA
+ * ------------------------------------
*
* The interpretation of the aperture register definitions for a given
* VMID is a function of the “SUA Mode” which is one of HSA64, HSA32, or
diff --git a/drivers/gpu/drm/amd/amdkfd/kfd_interrupt.c b/drivers/gpu/drm/amd/amdkfd/kfd_interrupt.c
index a9466d154395..d53ffff2635a 100644
--- a/drivers/gpu/drm/amd/amdkfd/kfd_interrupt.c
+++ b/drivers/gpu/drm/amd/amdkfd/kfd_interrupt.c
@@ -21,8 +21,8 @@
* OTHER DEALINGS IN THE SOFTWARE.
*/
-/*
- * KFD Interrupts.
+/**
+ * DOC: KFD_Interrupts
*
* AMD GPUs deliver interrupts by pushing an interrupt description onto the
* interrupt ring and then sending an interrupt. KGD receives the interrupt
diff --git a/include/uapi/linux/kfd_ioctl.h b/include/uapi/linux/kfd_ioctl.h
index afd8ff29c74f..248c4b2f85d6 100644
--- a/include/uapi/linux/kfd_ioctl.h
+++ b/include/uapi/linux/kfd_ioctl.h
@@ -367,7 +367,8 @@ struct kfd_ioctl_acquire_vm_args {
#define KFD_IOC_ALLOC_MEM_FLAGS_COHERENT (1 << 26)
#define KFD_IOC_ALLOC_MEM_FLAGS_UNCACHED (1 << 25)
-/* Allocate memory for later SVM (shared virtual memory) mapping.
+/**
+ * struct kfd_ioctl_alloc_memory_of_gpu_args - Allocate memory for later SVM (shared virtual memory) mapping.
*
* @va_addr: virtual address of the memory to be allocated
* all later mappings on all GPUs will use this address
@@ -396,7 +397,8 @@ struct kfd_ioctl_free_memory_of_gpu_args {
__u64 handle; /* to KFD */
};
-/* Map memory to one or more GPUs
+/**
+ * struct kfd_ioctl_map_memory_to_gpu_args - Map memory to one or more GPUs
*
* @handle: memory handle returned by alloc
* @device_ids_array_ptr: array of gpu_ids (__u32 per device)
@@ -544,7 +546,7 @@ enum kfd_criu_op {
};
/**
- * kfd_ioctl_criu_args - Arguments perform CRIU operation
+ * struct kfd_ioctl_criu_args - Arguments perform CRIU operation
* @devices: [in/out] User pointer to memory location for devices information.
* This is an array of type kfd_criu_device_bucket.
* @bos: [in/out] User pointer to memory location for BOs information
@@ -616,7 +618,7 @@ enum kfd_mmio_remap {
#define KFD_IOCTL_SVM_FLAG_GPU_ALWAYS_MAPPED 0x00000040
/**
- * kfd_ioctl_svm_op - SVM ioctl operations
+ * enum kfd_ioctl_svm_op - SVM ioctl operations
*
* @KFD_IOCTL_SVM_OP_SET_ATTR: Modify one or more attributes
* @KFD_IOCTL_SVM_OP_GET_ATTR: Query one or more attributes
@@ -626,7 +628,8 @@ enum kfd_ioctl_svm_op {
KFD_IOCTL_SVM_OP_GET_ATTR
};
-/** kfd_ioctl_svm_location - Enum for preferred and prefetch locations
+/**
+ * enum kfd_ioctl_svm_location - Enum for preferred and prefetch locations
*
* GPU IDs are used to specify GPUs as preferred and prefetch locations.
* Below definitions are used for system memory or for leaving the preferred
@@ -638,7 +641,7 @@ enum kfd_ioctl_svm_location {
};
/**
- * kfd_ioctl_svm_attr_type - SVM attribute types
+ * enum kfd_ioctl_svm_attr_type - SVM attribute types
*
* @KFD_IOCTL_SVM_ATTR_PREFERRED_LOC: gpuid of the preferred location, 0 for
* system memory
@@ -667,7 +670,7 @@ enum kfd_ioctl_svm_attr_type {
};
/**
- * kfd_ioctl_svm_attribute - Attributes as pairs of type and value
+ * struct kfd_ioctl_svm_attribute - Attributes as pairs of type and value
*
* The meaning of the @value depends on the attribute type.
*
@@ -680,14 +683,16 @@ struct kfd_ioctl_svm_attribute {
};
/**
- * kfd_ioctl_svm_args - Arguments for SVM ioctl
+ * struct kfd_ioctl_svm_args - Arguments for SVM ioctl
+ *
+ * @op: specifies the operation to perform (see enum kfd_ioctl_svm_op).
+ * @start_addr: starting virtual address of SVM range
+ * @size: size of SVM range
*
- * @op specifies the operation to perform (see enum
- * @kfd_ioctl_svm_op). @start_addr and @size are common for all
- * operations.
+ * @attrs: a variable number of attributes to set / get
+ * @nattr: the number of attributes.
*
- * A variable number of attributes can be given in @attrs.
- * @nattr specifies the number of attributes. New attributes can be
+ * New attributes can be
* added in the future without breaking the ABI. If unknown attributes
* are given, the function returns -EINVAL.
*
@@ -727,7 +732,7 @@ struct kfd_ioctl_svm_args {
};
/**
- * kfd_ioctl_set_xnack_mode_args - Arguments for set_xnack_mode
+ * struct kfd_ioctl_set_xnack_mode_args - Arguments for set_xnack_mode
*
* @xnack_enabled: [in/out] Whether to enable XNACK mode for this process
*
--
2.25.1
More information about the amd-gfx
mailing list