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

[Lucas De Marchi]

On Wed, May 31, 2023 at 03:23:37PM +0000, Francois Dugast wrote:
>Explain how to use struct drm_xe_device_query, in particular the behavior
>for size.

While at it, also add some missing kernel-doc in related structs.

>
>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

looks ok, but may be better as a code snippet?

Lucas De Marchi

>+ */
> struct drm_xe_device_query {
> 	/** @extensions: Pointer to the first extension struct, if any */
> 	__u64 extensions;
>-- 
>2.34.1
>