Add a note about the two-step process. Suggested-by: Daniel Vetter <dan...@ffwll.ch> Signed-off-by: Matthew Auld <matthew.a...@intel.com> Cc: Joonas Lahtinen <joonas.lahti...@linux.intel.com> Cc: Jordan Justen <jordan.l.jus...@intel.com> Cc: Daniel Vetter <daniel.vet...@intel.com> Cc: Kenneth Graunke <kenn...@whitecape.org> Cc: Jason Ekstrand <ja...@jlekstrand.net> Cc: Dave Airlie <airl...@gmail.com> Cc: dri-de...@lists.freedesktop.org Cc: mesa-...@lists.freedesktop.org --- include/uapi/drm/i915_drm.h | 57 ++++++++++++++++++++++++++++++------- 1 file changed, 46 insertions(+), 11 deletions(-)
diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h index d9c954a5a456..ef36f1a0adde 100644 --- a/include/uapi/drm/i915_drm.h +++ b/include/uapi/drm/i915_drm.h @@ -2210,14 +2210,23 @@ struct drm_i915_perf_oa_config { __u64 flex_regs_ptr; }; +/** + * struct drm_i915_query_item - An individual query for the kernel to process. + * + * The behaviour is determined by the @query_id. Note that exactly what + * @data_ptr is also depends on the specific @query_id. + */ struct drm_i915_query_item { + /** @query_id: The id for this query */ __u64 query_id; #define DRM_I915_QUERY_TOPOLOGY_INFO 1 #define DRM_I915_QUERY_ENGINE_INFO 2 #define DRM_I915_QUERY_PERF_CONFIG 3 /* Must be kept compact -- no holes and well documented */ - /* + /** + * @length: + * * When set to zero by userspace, this is filled with the size of the * data to be written at the data_ptr pointer. The kernel sets this * value to a negative value to signal an error on a particular query @@ -2225,21 +2234,26 @@ struct drm_i915_query_item { */ __s32 length; - /* + /** + * @flags: + * * When query_id == DRM_I915_QUERY_TOPOLOGY_INFO, must be 0. * * When query_id == DRM_I915_QUERY_PERF_CONFIG, must be one of the - * following : - * - DRM_I915_QUERY_PERF_CONFIG_LIST - * - DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID - * - DRM_I915_QUERY_PERF_CONFIG_FOR_UUID + * following: + * + * - DRM_I915_QUERY_PERF_CONFIG_LIST + * - DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID + * - DRM_I915_QUERY_PERF_CONFIG_FOR_UUID */ __u32 flags; #define DRM_I915_QUERY_PERF_CONFIG_LIST 1 #define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID 2 #define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID 3 - /* + /** + * @data_ptr: + * * Data will be written at the location pointed by data_ptr when the * value of length matches the length of the data to be written by the * kernel. @@ -2247,16 +2261,37 @@ struct drm_i915_query_item { __u64 data_ptr; }; +/** + * struct drm_i915_query - Supply an array of drm_i915_query_item for the kernel + * to fill out. + * + * Note that this is generally a two step process for each drm_i915_query_item + * in the array: + * + * 1.) Call the DRM_IOCTL_I915_QUERY, giving it our array of + * drm_i915_query_item, with drm_i915_query_item.size set to zero. The + * kernel will then fill in the size, in bytes, which tells userspace how + * memory it needs to allocate for the blob(say for an array of + * properties). + * + * 2.) Next we call DRM_IOCTL_I915_QUERY again, this time with the + * drm_i915_query_item.data_ptr equal to our newly allocated blob. Note + * that the i915_query_item.size should still be the same as what the + * kernel previously set. At this point the kernel can fill in the blob. + * + */ struct drm_i915_query { + /** @num_items: The number of elements in the @items_ptr array */ __u32 num_items; - /* - * Unused for now. Must be cleared to zero. + /** + * @flags: Unused for now. Must be cleared to zero. */ __u32 flags; - /* - * This points to an array of num_items drm_i915_query_item structures. + /** + * @items_ptr: This points to an array of num_items drm_i915_query_item + * structures. */ __u64 items_ptr; }; -- 2.26.3 _______________________________________________ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx