[Intel-xe] [PATCH v2 4/5] drm/xe: Document usage of struct drm_xe_device_query

[Francois Dugast]

Explain how to use struct drm_xe_device_query, in particular the behavior
for size.

Reported-by: Oded Gabbay <ogabbay at kernel.org>
Link: https://lists.freedesktop.org/archives/intel-xe/2023-May/004704.html
Signed-off-by: Francois Dugast <francois.dugast at intel.com>
---
 include/uapi/drm/xe_drm.h | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/include/uapi/drm/xe_drm.h b/include/uapi/drm/xe_drm.h
index 2eea80bf0e06..e29399de148c 100644
--- a/include/uapi/drm/xe_drm.h
+++ b/include/uapi/drm/xe_drm.h
@@ -120,7 +120,10 @@ struct xe_user_extension {
 #define XE_MEM_REGION_CLASS_VRAM	1
 
 struct drm_xe_query_mem_usage {
+	/** @num_params: number of memory regions returned in regions */
 	__u32 num_regions;
+
+	/** @pad: MBZ */
 	__u32 pad;
 
 	struct drm_xe_query_mem_region {
@@ -136,7 +139,10 @@ struct drm_xe_query_mem_usage {
 };
 
 struct drm_xe_query_config {
+	/** @num_params: number of parameters returned in info */
 	__u32 num_params;
+
+	/** @pad: MBZ */
 	__u32 pad;
 
 #define XE_QUERY_CONFIG_REV_AND_DEVICE_ID	0
@@ -149,11 +155,15 @@ struct drm_xe_query_config {
 #define XE_QUERY_CONFIG_MEM_REGION_COUNT	5
 #define XE_QUERY_CONFIG_MAX_ENGINE_PRIORITY	6
 #define XE_QUERY_CONFIG_NUM_PARAM		XE_QUERY_CONFIG_MAX_ENGINE_PRIORITY + 1
+	/** @info: array containing the config info below  */
 	__u64 info[];
 };
 
 struct drm_xe_query_gts {
+	/** @num_gt: number of GTs returned in gts */
 	__u32 num_gt;
+
+	/** @pad: MBZ */
 	__u32 pad;
 
 	/*
@@ -193,6 +203,23 @@ struct drm_xe_query_topology_mask {
 	__u8 mask[];
 };
 
+/**
+ * struct drm_xe_device_query - main structure to query device information
+ *
+ * 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.
+ *
+ * A typical usage from user space is:
+ * - create a struct drm_xe_device_query with size = 0 and query = one of
+ *   the types DRM_XE_DEVICE_QUERY_*, for example DRM_XE_DEVICE_QUERY_ENGINES
+ * - call DRM_IOCTL_XE_DEVICE_QUERY
+ * - create a pointer to a query struct matching the query type selected
+ *   previously, for example struct drm_xe_engine_class_instance *
+ * - allocate memory of the size returned in drm_xe_device_query
+ * - call DRM_IOCTL_XE_DEVICE_QUERY
+ * - read the queried information in data
+ */
 struct drm_xe_device_query {
 	/** @extensions: Pointer to the first extension struct, if any */
 	__u64 extensions;
-- 
2.34.1