<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<body>
<div dir="auto">
<div dir="auto">Reviewed-by: Jason Ekstrand <jason@jlekstrand.net></div><div dir='auto'><br></div>
<div id="aqm-original" style="color: black;">
<div dir="auto">On April 16, 2021 05:37:55 Matthew Auld <matthew.auld@intel.com> wrote:</div>
<div><br></div>
<blockquote type="cite" class="gmail_quote" style="margin: 0 0 0 0.75ex; border-left: 1px solid #808080; padding-left: 0.75ex;">
<div dir="auto">Add a note about the two-step process.</div>
<div dir="auto"><br></div>
<div dir="auto">v2(Tvrtko):</div>
<div dir="auto"> - Also document the other method of just passing in a buffer which is</div>
<div dir="auto"> large enough, which avoids two ioctl calls. Can make sense for</div>
<div dir="auto"> smaller query items.</div>
<div dir="auto"><br></div>
<div dir="auto">Suggested-by: Daniel Vetter <daniel@ffwll.ch></div>
<div dir="auto">Signed-off-by: Matthew Auld <matthew.auld@intel.com></div>
<div dir="auto">Cc: Joonas Lahtinen <joonas.lahtinen@linux.intel.com></div>
<div dir="auto">Cc: Tvrtko Ursulin <tvrtko.ursulin@linux.intel.com></div>
<div dir="auto">Cc: Jordan Justen <jordan.l.justen@intel.com></div>
<div dir="auto">Cc: Daniel Vetter <daniel.vetter@intel.com></div>
<div dir="auto">Cc: Kenneth Graunke <kenneth@whitecape.org></div>
<div dir="auto">Cc: Jason Ekstrand <jason@jlekstrand.net></div>
<div dir="auto">Cc: Dave Airlie <airlied@gmail.com></div>
<div dir="auto">Cc: dri-devel@lists.freedesktop.org</div>
<div dir="auto">Cc: mesa-dev@lists.freedesktop.org</div>
<div dir="auto">Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch></div>
<div dir="auto">---</div>
<div dir="auto"> include/uapi/drm/i915_drm.h | 61 ++++++++++++++++++++++++++++++-------</div>
<div dir="auto"> 1 file changed, 50 insertions(+), 11 deletions(-)</div>
<div dir="auto"><br></div>
<div dir="auto">diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h</div>
<div dir="auto">index d79b51c12ff2..12f375c52317 100644</div>
<div dir="auto">--- a/include/uapi/drm/i915_drm.h</div>
<div dir="auto">+++ b/include/uapi/drm/i915_drm.h</div>
<div dir="auto">@@ -2218,14 +2218,23 @@ struct drm_i915_perf_oa_config {</div>
<div dir="auto"> __u64 flex_regs_ptr;</div>
<div dir="auto"> };</div>
<div dir="auto"> </div>
<div dir="auto">+/**</div>
<div dir="auto">+ * struct drm_i915_query_item - An individual query for the kernel to process.</div>
<div dir="auto">+ *</div>
<div dir="auto">+ * The behaviour is determined by the @query_id. Note that exactly what</div>
<div dir="auto">+ * @data_ptr is also depends on the specific @query_id.</div>
<div dir="auto">+ */</div>
<div dir="auto"> struct drm_i915_query_item {</div>
<div dir="auto">+ /** @query_id: The id for this query */</div>
<div dir="auto"> __u64 query_id;</div>
<div dir="auto"> #define DRM_I915_QUERY_TOPOLOGY_INFO 1</div>
<div dir="auto"> #define DRM_I915_QUERY_ENGINE_INFO 2</div>
<div dir="auto"> #define DRM_I915_QUERY_PERF_CONFIG 3</div>
<div dir="auto"> /* Must be kept compact -- no holes and well documented */</div>
<div dir="auto"> </div>
<div dir="auto">- /*</div>
<div dir="auto">+ /**</div>
<div dir="auto">+ * @length:</div>
<div dir="auto">+ *</div>
<div dir="auto"> * When set to zero by userspace, this is filled with the size of the</div>
<div dir="auto"> * data to be written at the data_ptr pointer. The kernel sets this</div>
<div dir="auto"> * value to a negative value to signal an error on a particular query</div>
<div dir="auto">@@ -2233,21 +2242,26 @@ struct drm_i915_query_item {</div>
<div dir="auto"> */</div>
<div dir="auto"> __s32 length;</div>
<div dir="auto"> </div>
<div dir="auto">- /*</div>
<div dir="auto">+ /**</div>
<div dir="auto">+ * @flags:</div>
<div dir="auto">+ *</div>
<div dir="auto"> * When query_id == DRM_I915_QUERY_TOPOLOGY_INFO, must be 0.</div>
<div dir="auto"> *</div>
<div dir="auto"> * When query_id == DRM_I915_QUERY_PERF_CONFIG, must be one of the</div>
<div dir="auto">- * following :</div>
<div dir="auto">- * - DRM_I915_QUERY_PERF_CONFIG_LIST</div>
<div dir="auto">- * - DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID</div>
<div dir="auto">- * - DRM_I915_QUERY_PERF_CONFIG_FOR_UUID</div>
<div dir="auto">+ * following:</div>
<div dir="auto">+ *</div>
<div dir="auto">+ * - DRM_I915_QUERY_PERF_CONFIG_LIST</div>
<div dir="auto">+ * - DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID</div>
<div dir="auto">+ * - DRM_I915_QUERY_PERF_CONFIG_FOR_UUID</div>
<div dir="auto"> */</div>
<div dir="auto"> __u32 flags;</div>
<div dir="auto"> #define DRM_I915_QUERY_PERF_CONFIG_LIST 1</div>
<div dir="auto"> #define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID 2</div>
<div dir="auto"> #define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID 3</div>
<div dir="auto"> </div>
<div dir="auto">- /*</div>
<div dir="auto">+ /**</div>
<div dir="auto">+ * @data_ptr:</div>
<div dir="auto">+ *</div>
<div dir="auto"> * Data will be written at the location pointed by data_ptr when the</div>
<div dir="auto"> * value of length matches the length of the data to be written by the</div>
<div dir="auto"> * kernel.</div>
<div dir="auto">@@ -2255,16 +2269,41 @@ struct drm_i915_query_item {</div>
<div dir="auto"> __u64 data_ptr;</div>
<div dir="auto"> };</div>
<div dir="auto"> </div>
<div dir="auto">+/**</div>
<div dir="auto">+ * struct drm_i915_query - Supply an array of drm_i915_query_item for the kernel</div>
<div dir="auto">+ * to fill out.</div>
<div dir="auto">+ *</div>
<div dir="auto">+ * Note that this is generally a two step process for each drm_i915_query_item</div>
<div dir="auto">+ * in the array:</div>
<div dir="auto">+ *</div>
<div dir="auto">+ * 1. Call the DRM_IOCTL_I915_QUERY, giving it our array of drm_i915_query_item,</div>
<div dir="auto">+ * with drm_i915_query_item.size set to zero. The kernel will then fill in</div>
<div dir="auto">+ * the size, in bytes, which tells userspace how memory it needs to allocate</div>
<div dir="auto">+ * for the blob(say for an array of properties).</div>
<div dir="auto">+ *</div>
<div dir="auto">+ * 2. Next we call DRM_IOCTL_I915_QUERY again, this time with the</div>
<div dir="auto">+ * drm_i915_query_item.data_ptr equal to our newly allocated blob. Note that</div>
<div dir="auto">+ * the i915_query_item.size should still be the same as what the kernel</div>
<div dir="auto">+ * previously set. At this point the kernel can fill in the blob.</div>
<div dir="auto">+ *</div>
<div dir="auto">+ * Note that for some query items it can make sense for userspace to just pass</div>
<div dir="auto">+ * in a buffer/blob equal to or larger than the required size. In this case only</div>
<div dir="auto">+ * a single ioctl call is needed. For some smaller query items this can work</div>
<div dir="auto">+ * quite well.</div>
<div dir="auto">+ *</div>
<div dir="auto">+ */</div>
<div dir="auto"> struct drm_i915_query {</div>
<div dir="auto">+ /** @num_items: The number of elements in the @items_ptr array */</div>
<div dir="auto"> __u32 num_items;</div>
<div dir="auto"> </div>
<div dir="auto">- /*</div>
<div dir="auto">- * Unused for now. Must be cleared to zero.</div>
<div dir="auto">+ /**</div>
<div dir="auto">+ * @flags: Unused for now. Must be cleared to zero.</div>
<div dir="auto"> */</div>
<div dir="auto"> __u32 flags;</div>
<div dir="auto"> </div>
<div dir="auto">- /*</div>
<div dir="auto">- * This points to an array of num_items drm_i915_query_item structures.</div>
<div dir="auto">+ /**</div>
<div dir="auto">+ * @items_ptr: This points to an array of num_items drm_i915_query_item</div>
<div dir="auto">+ * structures.</div>
<div dir="auto"> */</div>
<div dir="auto"> __u64 items_ptr;</div>
<div dir="auto"> };</div>
<div dir="auto">-- </div>
<div dir="auto">2.26.3</div>
</blockquote>
</div><div dir="auto"><br></div>
</div></body>
</html>