[igt-dev] [PATCH v2 09/64] drm-uapi/xe: Make constant comments visible in kernel doc
Francois Dugast
francois.dugast at intel.com
Fri Nov 3 14:43:04 UTC 2023
Align with commit ("Make constant comments visible in kernel doc")
Signed-off-by: Francois Dugast <francois.dugast at intel.com>
---
include/drm-uapi/xe_drm.h | 272 +++++++++++++++++++++-----------------
1 file changed, 154 insertions(+), 118 deletions(-)
diff --git a/include/drm-uapi/xe_drm.h b/include/drm-uapi/xe_drm.h
index 9dc40898c..1ec16ab24 100644
--- a/include/drm-uapi/xe_drm.h
+++ b/include/drm-uapi/xe_drm.h
@@ -126,23 +126,40 @@ struct xe_user_extension {
#define DRM_IOCTL_XE_WAIT_USER_FENCE DRM_IOWR(DRM_COMMAND_BASE + DRM_XE_WAIT_USER_FENCE, struct drm_xe_wait_user_fence)
#define DRM_IOCTL_XE_VM_MADVISE DRM_IOW(DRM_COMMAND_BASE + DRM_XE_VM_MADVISE, struct drm_xe_vm_madvise)
-/** struct drm_xe_engine_class_instance - instance of an engine class */
+/**
+ * struct drm_xe_engine_class_instance - instance of an engine class
+ *
+ * The @engine_class can be:
+ * - %DRM_XE_ENGINE_CLASS_RENDER
+ * - %DRM_XE_ENGINE_CLASS_COPY
+ * - %DRM_XE_ENGINE_CLASS_VIDEO_DECODE
+ * - %DRM_XE_ENGINE_CLASS_VIDEO_ENHANCE
+ * - %DRM_XE_ENGINE_CLASS_COMPUTE
+ * - %DRM_XE_ENGINE_CLASS_VM_BIND_ASYNC - Kernel only class (not actual
+ * hardware engine class) used for creating ordered queues of
+ * asynchronous VM bind operations.
+ * - %DRM_XE_ENGINE_CLASS_VM_BIND_SYNC - Kernel only class (not actual
+ * synchronous VM bind operations.
+ *
+ */
struct drm_xe_engine_class_instance {
#define DRM_XE_ENGINE_CLASS_RENDER 0
#define DRM_XE_ENGINE_CLASS_COPY 1
#define DRM_XE_ENGINE_CLASS_VIDEO_DECODE 2
#define DRM_XE_ENGINE_CLASS_VIDEO_ENHANCE 3
#define DRM_XE_ENGINE_CLASS_COMPUTE 4
- /*
- * Kernel only classes (not actual hardware engine class). Used for
- * creating ordered queues of VM bind operations.
- */
#define DRM_XE_ENGINE_CLASS_VM_BIND_ASYNC 5
#define DRM_XE_ENGINE_CLASS_VM_BIND_SYNC 6
+ /**
+ * @engine_class: Class of this instance among possible
+ * DRM_XE_ENGINE_CLASS_*
+ */
__u16 engine_class;
-
+ /** @engine_instance: Engine instance */
__u16 engine_instance;
+ /** @gt_id: GT ID the instance is associated with */
__u16 gt_id;
+ /** @rsvd: Reserved */
__u16 rsvd;
};
@@ -313,44 +330,36 @@ struct drm_xe_query_mem_usage {
* If a query is made with a struct drm_xe_device_query where .query
* is equal to DRM_XE_DEVICE_QUERY_CONFIG, then the reply uses
* struct drm_xe_query_config in .data.
+ *
+ * The index in @info can be:
+ * - %DRM_XE_QUERY_CONFIG_REV_AND_DEVICE_ID - Device ID (lower 16 bits)
+ * and the device revision (next 8 bits)
+ * - %DRM_XE_QUERY_CONFIG_FLAGS - Flags describing the device
+ * configuration, see list below
+ *
+ * - %DRM_XE_QUERY_CONFIG_FLAGS_HAS_VRAM - Flag is set if the device
+ * has usable VRAM
+ * - %DRM_XE_QUERY_CONFIG_MIN_ALIGNMENT - Minimal memory alignment
+ * required by this device, typically SZ_4K or SZ_64K
+ * - %DRM_XE_QUERY_CONFIG_VA_BITS - Maximum bits of a virtual address
+ * - %DRM_XE_QUERY_CONFIG_GT_COUNT - Total number of GTs for the entire
+ * device
+ * - %DRM_XE_QUERY_CONFIG_MEM_REGION_COUNT - Total number of accessible
+ * memory regions
+ * - %DRM_XE_QUERY_CONFIG_MAX_EXEC_QUEUE_PRIORITY - Value of the highest
+ * available exec queue priority
*/
struct drm_xe_query_config {
/** @pad: MBZ */
__u32 pad;
- /*
- * Device ID (lower 16 bits) and the device revision (next
- * 8 bits)
- */
#define DRM_XE_QUERY_CONFIG_REV_AND_DEVICE_ID 0
- /*
- * Flags describing the device configuration, see list below
- */
#define DRM_XE_QUERY_CONFIG_FLAGS 1
- /*
- * Flag is set if the device has usable VRAM
- */
#define DRM_XE_QUERY_CONFIG_FLAGS_HAS_VRAM (0x1 << 0)
- /*
- * Minimal memory alignment required by this device,
- * typically SZ_4K or SZ_64K
- */
#define DRM_XE_QUERY_CONFIG_MIN_ALIGNMENT 2
- /*
- * Maximum bits of a virtual address
- */
#define DRM_XE_QUERY_CONFIG_VA_BITS 3
- /*
- * Total number of GTs for the entire device
- */
#define DRM_XE_QUERY_CONFIG_GT_COUNT 4
- /*
- * Total number of accessible memory regions
- */
#define DRM_XE_QUERY_CONFIG_MEM_REGION_COUNT 5
- /*
- * Value of the highest available exec queue priority
- */
#define DRM_XE_QUERY_CONFIG_MAX_EXEC_QUEUE_PRIORITY 6
/** @info: array of elements containing the config info */
__u64 info[];
@@ -363,6 +372,7 @@ struct drm_xe_query_config {
* existing GT individual descriptions.
* Graphics Technology (GT) is a subset of a GPU/tile that is responsible for
* implementing graphics and/or media operations.
+ *
*/
struct drm_xe_query_gt {
#define DRM_XE_QUERY_GT_TYPE_MAIN 0
@@ -420,34 +430,31 @@ struct drm_xe_query_gt_list {
* If a query is made with a struct drm_xe_device_query where .query
* is equal to DRM_XE_DEVICE_QUERY_GT_TOPOLOGY, then the reply uses
* struct drm_xe_query_topology_mask in .data.
+ *
+ * The @type can be:
+ * - %DRM_XE_TOPO_DSS_GEOMETRY - To query the mask of Dual Sub Slices
+ * (DSS) available for geometry operations. For example a query response
+ * containing the following in mask:
+ * ``DSS_GEOMETRY ff ff ff ff 00 00 00 00``
+ * means 32 DSS are available for geometry.
+ * - %DRM_XE_TOPO_DSS_COMPUTE - To query the mask of Dual Sub Slices
+ * (DSS) available for compute operations. For example a query response
+ * containing the following in mask:
+ * ``DSS_COMPUTE ff ff ff ff 00 00 00 00``
+ * means 32 DSS are available for compute.
+ * - %DRM_XE_TOPO_EU_PER_DSS - To query the mask of Execution Units (EU)
+ * available per Dual Sub Slices (DSS). For example a query response
+ * containing the following in mask:
+ * ``EU_PER_DSS ff ff 00 00 00 00 00 00``
+ * means each DSS has 16 EU.
+ *
*/
struct drm_xe_query_topology_mask {
/** @gt_id: GT ID the mask is associated with */
__u16 gt_id;
- /*
- * To query the mask of Dual Sub Slices (DSS) available for geometry
- * operations. For example a query response containing the following
- * in mask:
- * DSS_GEOMETRY ff ff ff ff 00 00 00 00
- * means 32 DSS are available for geometry.
- */
#define DRM_XE_TOPO_DSS_GEOMETRY (1 << 0)
- /*
- * To query the mask of Dual Sub Slices (DSS) available for compute
- * operations. For example a query response containing the following
- * in mask:
- * DSS_COMPUTE ff ff ff ff 00 00 00 00
- * means 32 DSS are available for compute.
- */
#define DRM_XE_TOPO_DSS_COMPUTE (1 << 1)
- /*
- * To query the mask of Execution Units (EU) available per Dual Sub
- * Slices (DSS). For example a query response containing the following
- * in mask:
- * EU_PER_DSS ff ff 00 00 00 00 00 00
- * means each DSS has 16 EU.
- */
#define DRM_XE_TOPO_EU_PER_DSS (1 << 2)
/** @type: type of mask */
__u16 type;
@@ -486,13 +493,13 @@ struct drm_xe_query_uc_fw_version {
/** @reserved: Reserved */
__u16 reserved;
- /* @major_ver: major uc fw version */
+ /** @major_ver: major uc fw version */
__u32 major_ver;
- /* @minor_ver: minor uc fw version */
+ /** @minor_ver: minor uc fw version */
__u32 minor_ver;
- /* @patch_ver: patch uc fw version */
+ /** @patch_ver: patch uc fw version */
__u32 patch_ver;
- /* @branch_ver: branch uc fw version */
+ /** @branch_ver: branch uc fw version */
__u32 branch_ver;
/** @pad2: MBZ */
@@ -509,6 +516,19 @@ struct drm_xe_query_uc_fw_version {
* and sets the value in the query member. This determines the type of
* the structure provided by the driver in data, among struct drm_xe_query_*.
*
+ * The @query can be:
+ * - %DRM_XE_DEVICE_QUERY_ENGINES
+ * - %DRM_XE_DEVICE_QUERY_MEM_USAGE
+ * - %DRM_XE_DEVICE_QUERY_CONFIG
+ * - %DRM_XE_DEVICE_QUERY_GT_LIST - Query type to retrieve the hardware
+ * configuration of the device such as information on slices, memory,
+ * caches, and so on. It is provided as a table of key / value
+ * attributes.
+ * - %DRM_XE_DEVICE_QUERY_HWCONFIG
+ * - %DRM_XE_DEVICE_QUERY_GT_TOPOLOGY
+ * - %DRM_XE_DEVICE_QUERY_ENGINE_CYCLES
+ * - %DRM_XE_DEVICE_QUERY_UC_FW_VERSION
+ *
* If size is set to 0, the driver fills it with the required size for
* the requested type of data to query. If size is equal to the required
* size, the queried information is copied into data. If size is set to
@@ -551,11 +571,6 @@ struct drm_xe_device_query {
#define DRM_XE_DEVICE_QUERY_MEM_USAGE 1
#define DRM_XE_DEVICE_QUERY_CONFIG 2
#define DRM_XE_DEVICE_QUERY_GT_LIST 3
- /*
- * Query type to retrieve the hardware configuration of the device
- * such as information on slices, memory, caches, and so on. It is
- * provided as a table of attributes (key / value).
- */
#define DRM_XE_DEVICE_QUERY_HWCONFIG 4
#define DRM_XE_DEVICE_QUERY_GT_TOPOLOGY 5
#define DRM_XE_DEVICE_QUERY_ENGINE_CYCLES 6
@@ -573,6 +588,29 @@ struct drm_xe_device_query {
__u64 reserved[2];
};
+/**
+ * struct drm_xe_gem_create - structure for gem creation
+ *
+ * The @flags can be:
+ * - %DRM_XE_GEM_CREATE_FLAG_DEFER_BACKING
+ * - %DRM_XE_GEM_CREATE_FLAG_SCANOUT
+ * - %DRM_XE_GEM_CREATE_FLAG_NEEDS_VISIBLE_VRAM - When using VRAM as a
+ * possible placement, ensure that the corresponding VRAM allocation
+ * will always use the CPU accessible part of VRAM. This is important
+ * for small-bar systems (on full-bar systems this gets turned into a
+ * noop).
+ * Note1: System memory can be used as an extra placement if the kernel
+ * should spill the allocation to system memory, if space can't be made
+ * available in the CPU accessible part of VRAM (giving the same
+ * behaviour as the i915 interface, see
+ * I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS).
+ * Note2: For clear-color CCS surfaces the kernel needs to read the
+ * clear-color value stored in the buffer, and on discrete platforms we
+ * need to use VRAM for display surfaces, therefore the kernel requires
+ * setting this flag for such objects, otherwise an error is thrown on
+ * small-bar systems.
+ *
+ */
struct drm_xe_gem_create {
/** @extensions: Pointer to the first extension struct, if any */
__u64 extensions;
@@ -586,21 +624,6 @@ struct drm_xe_gem_create {
#define DRM_XE_GEM_CREATE_FLAG_DEFER_BACKING (0x1 << 24)
#define DRM_XE_GEM_CREATE_FLAG_SCANOUT (0x1 << 25)
-/*
- * When using VRAM as a possible placement, ensure that the corresponding VRAM
- * allocation will always use the CPU accessible part of VRAM. This is important
- * for small-bar systems (on full-bar systems this gets turned into a noop).
- *
- * Note: System memory can be used as an extra placement if the kernel should
- * spill the allocation to system memory, if space can't be made available in
- * the CPU accessible part of VRAM (giving the same behaviour as the i915
- * interface, see I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS).
- *
- * Note: For clear-color CCS surfaces the kernel needs to read the clear-color
- * value stored in the buffer, and on discrete platforms we need to use VRAM for
- * display surfaces, therefore the kernel requires setting this flag for such
- * objects, otherwise an error is thrown on small-bar systems.
- */
#define DRM_XE_GEM_CREATE_FLAG_NEEDS_VISIBLE_VRAM (0x1 << 26)
/**
* @flags: Flags, currently a mask of memory instances of where BO can
@@ -697,6 +720,30 @@ struct drm_xe_vm_destroy {
__u64 reserved[2];
};
+/**
+ * struct drm_xe_vm_bind_op - run bind operations
+ *
+ * The @op can be:
+ * - %DRM_XE_VM_BIND_OP_MAP
+ * - %DRM_XE_VM_BIND_OP_UNMAP
+ * - %DRM_XE_VM_BIND_OP_MAP_USERPTR
+ * - %DRM_XE_VM_BIND_OP_UNMAP_ALL
+ * - %DRM_XE_VM_BIND_OP_PREFETCH
+ *
+ * and the @flags can be:
+ * - %DRM_XE_VM_BIND_FLAG_READONLY
+ * - %DRM_XE_VM_BIND_FLAG_ASYNC
+ * - %DRM_XE_VM_BIND_FLAG_IMMEDIATE - Valid on a faulting VM only, do the
+ * MAP operation immediately rather than deferring the MAP to the page
+ * fault handler.
+ * - %DRM_XE_VM_BIND_FLAG_NULL - When the NULL flag is set, the page
+ * tables are setup with a special bit which indicates writes are
+ * dropped and all reads return zero. In the future, the NULL flags
+ * will only be valid for DRM_XE_VM_BIND_OP_MAP operations, the BO
+ * handle MBZ, and the BO offset MBZ. This flag is intended to
+ * implement VK sparse bindings.
+ *
+ */
struct drm_xe_vm_bind_op {
/** @extensions: Pointer to the first extension struct, if any */
__u64 extensions;
@@ -744,23 +791,12 @@ struct drm_xe_vm_bind_op {
#define DRM_XE_VM_BIND_FLAG_READONLY (0x1 << 0)
#define DRM_XE_VM_BIND_FLAG_ASYNC (0x1 << 1)
- /*
- * Valid on a faulting VM only, do the MAP operation immediately rather
- * than deferring the MAP to the page fault handler.
- */
#define DRM_XE_VM_BIND_FLAG_IMMEDIATE (0x1 << 2)
- /*
- * When the NULL flag is set, the page tables are setup with a special
- * bit which indicates writes are dropped and all reads return zero. In
- * the future, the NULL flags will only be valid for DRM_XE_VM_BIND_OP_MAP
- * operations, the BO handle MBZ, and the BO offset MBZ. This flag is
- * intended to implement VK sparse bindings.
- */
#define DRM_XE_VM_BIND_FLAG_NULL (0x1 << 3)
/** @flags: Bind flags */
__u32 flags;
- /** @mem_region: Memory region to prefetch VMA to, instance not a mask */
+ /** @region: Memory region to prefetch VMA to, instance not a mask */
__u32 region;
/** @reserved: Reserved */
@@ -1046,6 +1082,35 @@ struct drm_xe_wait_user_fence {
__u64 reserved[2];
};
+/**
+ * struct drm_xe_vm_madvise - give advice about use of memory
+ *
+ * The @property can be:
+ * - %DRM_XE_VM_MADVISE_PREFERRED_MEM_CLASS - Setting the preferred
+ * location will trigger a migrate of the VMA backing store to new
+ * location if the backing store is already allocated.
+ * For DRM_XE_VM_MADVISE_PREFERRED_MEM_CLASS usage, see enum
+ * drm_xe_memory_class.
+ * - %DRM_XE_VM_MADVISE_PREFERRED_GT
+ * - %DRM_XE_VM_MADVISE_PREFERRED_MEM_CLASS_GT - In this case lower 32 bits
+ * are mem class, upper 32 are GT. Combination provides a single IOCTL
+ * plus migrate VMA to preferred location.
+ * - %DRM_XE_VM_MADVISE_CPU_ATOMIC - The CPU will do atomic memory
+ * operations to this VMA. Must be set on some devices for atomics to
+ * behave correctly.
+ * - %DRM_XE_VM_MADVISE_DEVICE_ATOMIC - The device will do atomic memory
+ * operations to this VMA. Must be set on some devices for atomics to
+ * behave correctly.
+ * - %DRM_XE_VM_MADVISE_PRIORITY - Priority WRT to eviction (moving from
+ * preferred memory location due to memory pressure). The lower the
+ * priority, the more likely to be evicted.
+ *
+ * - %DRM_XE_VMA_PRIORITY_LOW
+ * - %DRM_XE_VMA_PRIORITY_NORMAL - Default
+ * - %DRM_XE_VMA_PRIORITY_HIGH - Must be user with elevated privileges
+ * - %DRM_XE_VM_MADVISE_PIN - Pin the VMA in memory, must be user with
+ * elevated privileges
+ */
struct drm_xe_vm_madvise {
/** @extensions: Pointer to the first extension struct, if any */
__u64 extensions;
@@ -1062,44 +1127,15 @@ struct drm_xe_vm_madvise {
/** @addr: Address of the VMA to operation on */
__u64 addr;
- /*
- * Setting the preferred location will trigger a migrate of the VMA
- * backing store to new location if the backing store is already
- * allocated.
- *
- * For DRM_XE_VM_MADVISE_PREFERRED_MEM_CLASS usage, see enum
- * drm_xe_memory_class.
- */
#define DRM_XE_VM_MADVISE_PREFERRED_MEM_CLASS 0
#define DRM_XE_VM_MADVISE_PREFERRED_GT 1
- /*
- * In this case lower 32 bits are mem class, upper 32 are GT.
- * Combination provides a single IOCTL plus migrate VMA to preferred
- * location.
- */
#define DRM_XE_VM_MADVISE_PREFERRED_MEM_CLASS_GT 2
- /*
- * The CPU will do atomic memory operations to this VMA. Must be set on
- * some devices for atomics to behave correctly.
- */
#define DRM_XE_VM_MADVISE_CPU_ATOMIC 3
- /*
- * The device will do atomic memory operations to this VMA. Must be set
- * on some devices for atomics to behave correctly.
- */
#define DRM_XE_VM_MADVISE_DEVICE_ATOMIC 4
- /*
- * Priority WRT to eviction (moving from preferred memory location due
- * to memory pressure). The lower the priority, the more likely to be
- * evicted.
- */
#define DRM_XE_VM_MADVISE_PRIORITY 5
#define DRM_XE_VMA_PRIORITY_LOW 0
- /* Default */
#define DRM_XE_VMA_PRIORITY_NORMAL 1
- /* Must be user with elevated privileges */
#define DRM_XE_VMA_PRIORITY_HIGH 2
- /* Pin the VMA in memory, must be user with elevated privileges */
#define DRM_XE_VM_MADVISE_PIN 6
/** @property: property to set */
__u32 property;
--
2.34.1
More information about the igt-dev
mailing list