drm/xe/uapi: add some kernel-doc for region query

Since we need to extend this, we should also take the time to add some
basic kernel-doc here for the existing bits. Note that this is all still
subject to change when upstreaming.

Also convert XE_MEM_REGION_CLASS_* into an enum, so we can more easily
create links to it from other parts of the uapi.

Suggested-by: Gwan-gyeong Mun <gwan-gyeong.mun@intel.com>
Signed-off-by: Matthew Auld <matthew.auld@intel.com>
Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Cc: Thomas Hellström <thomas.hellstrom@linux.intel.com>
Cc: Lucas De Marchi <lucas.demarchi@intel.com>
Cc: José Roberto de Souza <jose.souza@intel.com>
Cc: Filip Hazubski <filip.hazubski@intel.com>
Cc: Carl Zhang <carl.zhang@intel.com>
Cc: Effie Yu <effie.yu@intel.com>
Reviewed-by: Gwan-gyeong Mun <gwan-gyeong.mun@intel.com>
Signed-off-by: Rodrigo Vivi <rodrigo.vivi@intel.com>

1 files changed, 71 insertions, 15 deletions

diff --git a/include/uapi/drm/xe_drm.h b/include/uapi/drm/xe_drm.h
index fef5e26aad2a..0808b21de29a 100644
--- a/include/uapi/drm/xe_drm.h
+++ b/include/uapi/drm/xe_drm.h
@@ -118,8 +118,71 @@ 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)
 
-#define XE_MEM_REGION_CLASS_SYSMEM	0
-#define XE_MEM_REGION_CLASS_VRAM	1
+/**
+ * enum drm_xe_memory_class - Supported memory classes.
+ */
+enum drm_xe_memory_class {
+	/** @XE_MEM_REGION_CLASS_SYSMEM: Represents system memory. */
+	XE_MEM_REGION_CLASS_SYSMEM = 0,
+	/**
+	 * @XE_MEM_REGION_CLASS_VRAM: On discrete platforms, this
+	 * represents the memory that is local to the device, which we
+	 * call VRAM. Not valid on integrated platforms.
+	 */
+	XE_MEM_REGION_CLASS_VRAM
+};
+
+/**
+ * struct drm_xe_query_mem_region - Describes some region as known to
+ * the driver.
+ */
+struct drm_xe_query_mem_region {
+	/**
+	 * @mem_class: The memory class describing this region.
+	 *
+	 * See enum drm_xe_memory_class for supported values.
+	 */
+	__u16 mem_class;
+	/**
+	 * @instance: The instance for this region.
+	 *
+	 * The @mem_class and @instance taken together will always give
+	 * a unique pair.
+	 */
+	__u16 instance;
+	/** @pad: MBZ */
+	__u32 pad;
+	/**
+	 * @min_page_size: Min page-size in bytes for this region.
+	 *
+	 * When the kernel allocates memory for this region, the
+	 * underlying pages will be at least @min_page_size in size.
+	 *
+	 * Important note: When userspace allocates a GTT address which
+	 * can point to memory allocated from this region, it must also
+	 * respect this minimum alignment. This is enforced by the
+	 * kernel.
+	 */
+	__u32 min_page_size;
+	/**
+	 * @max_page_size: Max page-size in bytes for this region.
+	 */
+	__u32 max_page_size;
+	/**
+	 * @total_size: The usable size in bytes for this region.
+	 */
+	__u64 total_size;
+	/**
+	 * @used: Estimate of the memory used in bytes for this region.
+	 *
+	 * Requires CAP_PERFMON or CAP_SYS_ADMIN to get reliable
+	 * accounting.  Without this the value here will always equal
+	 * zero.
+	 */
+	__u64 used;
+	/** @reserved: MBZ */
+	__u64 reserved[8];
+};
 
 /**
  * struct drm_xe_query_mem_usage - describe memory regions and usage
@@ -129,22 +192,12 @@ struct xe_user_extension {
  * struct drm_xe_query_mem_usage in .data.
  */
 struct drm_xe_query_mem_usage {
-	/** @num_params: number of memory regions returned in regions */
+	/** @num_regions: number of memory regions returned in @regions */
 	__u32 num_regions;
-
 	/** @pad: MBZ */
 	__u32 pad;
-
-	struct drm_xe_query_mem_region {
-		__u16 mem_class;
-		__u16 instance;	/* unique ID even among different classes */
-		__u32 pad;
-		__u32 min_page_size;
-		__u32 max_page_size;
-		__u64 total_size;
-		__u64 used;
-		__u64 reserved[8];
-	} regions[];
+	/** @regions: The returned regions for this device */
+	struct drm_xe_query_mem_region regions[];
 };
 
 /**
@@ -888,6 +941,9 @@ struct drm_xe_vm_madvise {
 	 * 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