STRUCT DRM_XE_DEVICE_QUERY(9)

📦 version 7.3.1, in nixpkgs unstable

💜 struct drm_xe_device_query(9)

okay bestie, welcome to the struct drm_xe_device_query(9) era — this is a page from the Kernel API Manual and it's literally the input of &DRM_IOCTL_XE_DEVICE_QUERY, aka the main character structure you use to query device information 🎀

✨ SYNOPSIS ✨

struct drm_xe_device_query {
    __u64 extensions;
  #define DRM_XE_DEVICE_QUERY_ENGINES             0;
  #define DRM_XE_DEVICE_QUERY_MEM_REGIONS         1;
  #define DRM_XE_DEVICE_QUERY_CONFIG              2;
  #define DRM_XE_DEVICE_QUERY_GT_LIST             3;
  #define DRM_XE_DEVICE_QUERY_HWCONFIG            4;
  #define DRM_XE_DEVICE_QUERY_GT_TOPOLOGY         5;
  #define DRM_XE_DEVICE_QUERY_ENGINE_CYCLES       6;
  #define DRM_XE_DEVICE_QUERY_UC_FW_VERSION       7;
  #define DRM_XE_DEVICE_QUERY_OA_UNITS            8;
  #define DRM_XE_DEVICE_QUERY_PXP_STATUS          9;
  #define DRM_XE_DEVICE_QUERY_EU_STALL            10;
    __u32 query;
    __u32 size;
    __u64 data;
    __u64 reserved[2];
 };

🌸 Members 🌸

  • extensions — pointer to the first extension struct, if any ✨
  • query — the type of data you wanna query 👀
  • size — size of the queried data 📏
  • data — the queried data gets placed here 💌
  • reserved — reserved, hands off 🙈

🦋 Description 🦋

So here's the vibe: you pick the type of data you want to query from among DRM_XE_DEVICE_QUERY_* and you set that value in the query member. That's what tells the driver which kind of structure to hand you back in data, out of the struct drm_xe_query_* fam 💅

The query can be:

  • DRM_XE_DEVICE_QUERY_ENGINES
  • DRM_XE_DEVICE_QUERY_MEM_REGIONS
  • DRM_XE_DEVICE_QUERY_CONFIG
  • DRM_XE_DEVICE_QUERY_GT_LIST
  • DRM_XE_DEVICE_QUERY_HWCONFIG — query type to retrieve the hardware configuration of the device, like info on slices, memory, caches, and so on. It's provided as a table of key / value attributes 🔥
  • DRM_XE_DEVICE_QUERY_GT_TOPOLOGY
  • DRM_XE_DEVICE_QUERY_ENGINE_CYCLES
  • DRM_XE_DEVICE_QUERY_UC_FW_VERSION
  • DRM_XE_DEVICE_QUERY_OA_UNITS
  • DRM_XE_DEVICE_QUERY_PXP_STATUS
  • DRM_XE_DEVICE_QUERY_EU_STALL

Now the size lore, because this is the part that actually matters 🫶

  • If size is set to 0, the driver fills it in with the required size for the requested type of data to query ✨
  • If size is equal to the required size, the queried information gets copied into data 💖
  • If size is set to a value that is different from 0 and different from the required size, the IOCTL call returns -EINVAL 💀
bestie the two-pass thing is real: ask with size = 0, get the size back, then ask again with real memory. do not skip step one, i'm begging 😭

Like, for example, the following code snippet lets you retrieve and print information about the device engines with DRM_XE_DEVICE_QUERY_ENGINES:

struct drm_xe_query_engines *engines;
struct drm_xe_device_query query = {
    .extensions = 0,
    .query = DRM_XE_DEVICE_QUERY_ENGINES,
    .size = 0,
    .data = 0,
};
ioctl(fd, DRM_IOCTL_XE_DEVICE_QUERY, query);
engines = malloc(query.size);
query.data = (uintptr_t)engines;
ioctl(fd, DRM_IOCTL_XE_DEVICE_QUERY, query);
for (int i = 0; i < engines->num_engines; i++) {
    printf("Engine d: s0, i,
        engines->engines[i].instance.engine_class ==
            DRM_XE_ENGINE_CLASS_RENDER ? "RENDER":
        engines->engines[i].instance.engine_class ==
            DRM_XE_ENGINE_CLASS_COPY ? "COPY":
        engines->engines[i].instance.engine_class ==
            DRM_XE_ENGINE_CLASS_VIDEO_DECODE ? "VIDEO_DECODE":
        engines->engines[i].instance.engine_class ==
            DRM_XE_ENGINE_CLASS_VIDEO_ENHANCE ? "VIDEO_ENHANCE":
        engines->engines[i].instance.engine_class ==
            DRM_XE_ENGINE_CLASS_COMPUTE ? "COMPUTE":
        "UNKNOWN");
}
free(engines);

🧚 SEE ALSO 🧚

Kernel file ./include/uapi/drm/xe_drm.h, plus the whole iconic extended universe:

  • Xe Device Block Diagram(9)
  • Xe uAPI Overview(9)
  • Xe IOCTL Extensions(9)
  • struct drm_xe_user_extension(9)
  • struct drm_xe_ext_set_property(9)
  • struct drm_xe_engine_class_instance(9)
  • struct drm_xe_engine(9)
  • struct drm_xe_query_engines(9)
  • enum drm_xe_memory_class(9)
  • struct drm_xe_mem_region(9)
  • struct drm_xe_query_mem_regions(9)
  • struct drm_xe_query_config(9)
  • struct drm_xe_gt(9)
  • struct drm_xe_query_gt_list(9)
  • struct drm_xe_query_topology_mask(9)
  • struct drm_xe_query_engine_cycles(9)
  • struct drm_xe_query_uc_fw_version(9)
  • struct drm_xe_query_pxp_status(9)
  • struct drm_xe_gem_create(9)
  • struct drm_xe_gem_mmap_offset(9)
  • struct drm_xe_vm_create(9)
  • struct drm_xe_vm_destroy(9)
  • struct drm_xe_vm_bind_op(9)
  • struct drm_xe_vm_bind(9)
  • struct drm_xe_vm_get_property(9)
  • struct drm_xe_exec_queue_create(9)
  • struct drm_xe_exec_queue_destroy(9)
  • struct drm_xe_exec_queue_get_property(9)
  • struct drm_xe_sync(9)
  • struct drm_xe_exec(9)
  • struct drm_xe_wait_user_fence(9)
  • enum drm_xe_observation_type(9)
  • enum drm_xe_observation_op(9)
  • struct drm_xe_observation_param(9)
  • enum drm_xe_observation_ioctls(9)
  • enum drm_xe_oa_unit_type(9)
  • struct drm_xe_oa_unit(9)
  • struct drm_xe_query_oa_units(9)
  • enum drm_xe_oa_format_type(9)
  • enum drm_xe_oa_property_id(9)
  • struct drm_xe_oa_config(9)
  • struct drm_xe_oa_stream_status(9)
  • struct drm_xe_oa_stream_info(9)
  • enum drm_xe_pxp_session_type(9)
  • enum drm_xe_eu_stall_property_id(9)
  • struct drm_xe_query_eu_stall(9)
  • struct drm_xe_madvise(9)
  • struct drm_xe_mem_range_attr(9)
  • struct drm_xe_vm_query_mem_range_attr(9)
  • struct drm_xe_exec_queue_set_property(9)
  • Xe DRM RAS(9)
  • enum drm_xe_ras_error_severity(9)
  • enum drm_xe_ras_error_component(9)

and that's the whole page, bestie 🫶 this one lives at ./include/uapi/drm, dated October 2026, and it's filed under struct drm_xe_device_query(9) — go forth and query, you absolute icon 👑💅

📦 where this page comes from