Reviewed-by: Jason Ekstrand jason@jlekstrand.net
On April 16, 2021 05:37:55 Matthew Auld matthew.auld@intel.com wrote:
Add a note about the two-step process.
v2(Tvrtko):
- Also document the other method of just passing in a buffer which is large enough, which avoids two ioctl calls. Can make sense for smaller query items.
Suggested-by: Daniel Vetter daniel@ffwll.ch Signed-off-by: Matthew Auld matthew.auld@intel.com Cc: Joonas Lahtinen joonas.lahtinen@linux.intel.com Cc: Tvrtko Ursulin tvrtko.ursulin@linux.intel.com Cc: Jordan Justen jordan.l.justen@intel.com Cc: Daniel Vetter daniel.vetter@intel.com Cc: Kenneth Graunke kenneth@whitecape.org Cc: Jason Ekstrand jason@jlekstrand.net Cc: Dave Airlie airlied@gmail.com Cc: dri-devel@lists.freedesktop.org Cc: mesa-dev@lists.freedesktop.org Reviewed-by: Daniel Vetter daniel.vetter@ffwll.ch
include/uapi/drm/i915_drm.h | 61 ++++++++++++++++++++++++++++++------- 1 file changed, 50 insertions(+), 11 deletions(-)
diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h index d79b51c12ff2..12f375c52317 100644 --- a/include/uapi/drm/i915_drm.h +++ b/include/uapi/drm/i915_drm.h @@ -2218,14 +2218,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
@@ -2233,21 +2242,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#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.
@@ -2255,16 +2269,41 @@ 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:
- 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).
- 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.
- Note that for some query items it can make sense for userspace to just pass
- in a buffer/blob equal to or larger than the required size. In this
case only
- a single ioctl call is needed. For some smaller query items this can work
- quite well.
- */
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.
- /*
* 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.};
2.26.3