[Intel-xe] [PATCH v4 2/5] drm/xe/uapi: add some kernel-doc for region query

[Matthew Auld]

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 at intel.com>
Signed-off-by: Matthew Auld <matthew.auld at intel.com>
Cc: Maarten Lankhorst <maarten.lankhorst at linux.intel.com>
Cc: Thomas Hellström <thomas.hellstrom at linux.intel.com>
Cc: Lucas De Marchi <lucas.demarchi at intel.com>
Cc: José Roberto de Souza <jose.souza at intel.com>
Cc: Filip Hazubski <filip.hazubski at intel.com>
Cc: Carl Zhang <carl.zhang at intel.com>
Cc: Effie Yu <effie.yu at intel.com>
Reviewed-by: Gwan-gyeong Mun <gwan-gyeong.mun at intel.com>
---
 include/uapi/drm/xe_drm.h | 74 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 70 insertions(+), 4 deletions(-)

diff --git a/include/uapi/drm/xe_drm.h b/include/uapi/drm/xe_drm.h
index b0b80aae3ee8..8cb3324221f2 100644
--- a/include/uapi/drm/xe_drm.h
+++ b/include/uapi/drm/xe_drm.h
@@ -154,21 +154,84 @@ struct drm_xe_engine_class_instance {
 	__u16 gt_id;
 };
 
-#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_usage - The region info query enumerates all regions
+ * known to the driver by filling in an array of struct drm_xe_query_mem_region
+ * structures.
+ */
 struct drm_xe_query_mem_usage {
+	/**
+	 * @num_regions: Number of supported memory regions for this device.
+	 *
+	 * The @regions will contain @num_regions entries.
+	 */
 	__u32 num_regions;
+	/** @pad: MBZ */
 	__u32 pad;
-
+	/**
+	 * 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;
-		__u16 instance;	/* unique ID even among different classes */
+		/**
+		 * @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
+		 * the @total_size.
+		 */
 		__u64 used;
+		/** @reserved: MBZ */
 		__u64 reserved[8];
 	} regions[];
 };
@@ -760,6 +823,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
-- 
2.39.2