STRUCT DRM_I915_QUERY(9)

✨ NAME ✨

Okay bestie, meet struct drm_i915_query(9) — straight out of the Kernel API Manual. Its whole main-character job is to supply an array of struct drm_i915_query_item for the kernel to fill out. That’s the vibe. 💅

---

🦋 SYNOPSIS 🦋

       struct drm_i915_query {
           __u32 num_items;
           __u32 flags;
           __u64 items_ptr;
        };

---

🎀 Members 🎀

• num_items — the number of elements in the items_ptr array. Literally the count, no cap.
• flags — unused for now. Must be cleared to zero. Like, actually zero — not “zero-ish.” 🫶
• items_ptr — pointer to an array of struct drm_i915_query_item. The number of array elements is num_items. That’s the whole thing.

---

💅 Description 💅

So this is generally a two-step process for each struct drm_i915_query_item in the array:

1. Call the DRM_IOCTL_I915_QUERY, giving it our array of struct drm_i915_query_item, with drm_i915_query_item.length set to zero. The kernel will then fill in the size, in bytes, which tells userspace how much 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 drm_i915_query_item.length 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. 🎀

---

👑 SEE ALSO 👑

The whole squad, gathered for your reading pleasure:

• Kernel file ./tools/perf/trace/beauty/include/uapi/drm/i915_drm.h
• uevents generated by i915 on its device node(9)
• struct i915_user_extension(9)
• enum drm_i915_gem_engine_class(9)
• struct i915_engine_class_instance(9)
• perf_events exposed by i915 through /sys/bus/event_sources/drivers/i915(9)
• struct drm_i915_getparam(9)
• drm_i915_getparam_t(9)
• struct drm_i915_gem_mmap_offset(9)
• struct drm_i915_gem_set_domain(9)
• struct drm_i915_gem_exec_fence(9)
• struct drm_i915_gem_execbuffer_ext_timeline_fences(9)
• struct drm_i915_gem_execbuffer2(9)
• struct drm_i915_gem_caching(9)
• struct drm_i915_gem_context_create_ext(9)
• struct drm_i915_gem_context_param(9)
• Virtual Engine uAPI(9)
• struct i915_context_engines_parallel_submit(9)
• Context Engine Map uAPI(9)
• struct drm_i915_gem_context_create_ext_setparam(9)
• struct drm_i915_gem_vm_control(9)
• struct drm_i915_gem_userptr(9)
• struct drm_i915_perf_oa_config(9)
• struct drm_i915_query_item(9)
• struct drm_i915_query_topology_info(9)
• Engine Discovery uAPI(9)
• struct drm_i915_engine_info(9)
• struct drm_i915_query_engine_info(9)
• struct drm_i915_query_perf_config(9)
• enum drm_i915_gem_memory_class(9)
• struct drm_i915_gem_memory_class_instance(9)
• struct drm_i915_memory_region_info(9)
• struct drm_i915_query_memory_regions(9)
• struct drm_i915_query_guc_submission_version(9)
• GuC HWCONFIG blob uAPI(9)
• struct drm_i915_gem_create_ext(9)
• struct drm_i915_gem_create_ext_memory_regions(9)
• struct drm_i915_gem_create_ext_protected_content(9)
• struct drm_i915_gem_create_ext_set_pat(9)

---

Source/version cutie: ./tools/perf/trace/beauty/incl... — dropped October 2026. struct drm_i915_query(9) is signing off, mwah 💖🦋