STRUCT DRM_XE_EXEC_QUEUE_CREATE(9)

💅 struct drm_xe_exec_queue_create 💅

okay so this is a page from the Kernel API Manual, bestie — sit down, hydrate, and let's get into it. 🫶

✨ NAME ✨

struct drm_xe_exec_queue_create — the input struct for &DRM_IOCTL_XE_EXEC_QUEUE_CREATE. that's it, that's the whole vibe check. 💖

🎀 SYNOPSIS 🎀

struct drm_xe_exec_queue_create {
  #define DRM_XE_EXEC_QUEUE_EXTENSION_SET_PROPERTY                0;
  #define DRM_XE_EXEC_QUEUE_SET_PROPERTY_PRIORITY               0;
  #define DRM_XE_EXEC_QUEUE_SET_PROPERTY_TIMESLICE              1;
  #define DRM_XE_EXEC_QUEUE_SET_PROPERTY_PXP_TYPE               2;
  #define DRM_XE_EXEC_QUEUE_SET_HANG_REPLAY_STATE               3;
  #define DRM_XE_EXEC_QUEUE_SET_PROPERTY_MULTI_GROUP            4;
  #define DRM_XE_MULTI_GROUP_CREATE                           (1ull <<
 63);
  #define DRM_XE_EXEC_QUEUE_SET_PROPERTY_MULTI_QUEUE_PRIORITY   5;
  #define DRM_XE_EXEC_QUEUE_SET_DISABLE_STATE_CACHE_PERF_FIX    6;
    __u64 extensions;
    __u16 width;
    __u16 num_placements;
    __u32 vm_id;
  #define DRM_XE_EXEC_QUEUE_LOW_LATENCY_HINT      (1 << 0);
    __u32 flags;
    __u32 exec_queue_id;
    __u64 instances;
    __u64 reserved[2];
 };

🦋 Members 🦋

• extensions — pointer to the first extension struct, if any. like, if you got extras, they go here. ✨
• width — the submission width (number BB per exec) for this exec queue.
• num_placements — how many valid placements this exec queue has.
• vm_id — the VM this exec queue is gonna use.
• flags — the flags for this exec queue.
• exec_queue_id — the exec queue ID that gets returned to you. 🎁
• instances — user pointer to a 2-d array of struct drm_xe_engine_class_instance.

and here's the indexing math, memorize it iykyk:

length = width (i) * num_placements (j) index = j + i * width

• reserved — reserved. hands off. 🙈

🔥 Description 🔥

this ioctl supports setting the following properties via the DRM_XE_EXEC_QUEUE_EXTENSION_SET_PROPERTY extension, which uses the generic struct drm_xe_ext_set_property:

• DRM_XE_EXEC_QUEUE_SET_PROPERTY_PRIORITY — set the queue priority. heads up: CAP_SYS_NICE is required to set a value above normal. no cap, you need the cap. 👑
• DRM_XE_EXEC_QUEUE_SET_PROPERTY_TIMESLICE — set the queue timeslice duration in microseconds.
• DRM_XE_EXEC_QUEUE_SET_PROPERTY_PXP_TYPE — set the type of PXP session this queue will be used with. valid values are listed in enum drm_xe_pxp_session_type. DRM_XE_PXP_TYPE_NONE is the default behavior, so there's literally no need to explicitly set that. when a queue of type DRM_XE_PXP_TYPE_HWDRM is created, the PXP default HWDRM session (DRM_XE_PXP_HWDRM_DEFAULT_SESSION) will be started, if it isn't already running. the user is expected to query the PXP status via the query ioctl (see DRM_XE_DEVICE_QUERY_PXP_STATUS) and to wait for PXP to be ready before attempting to create a queue with this property. when a queue is created before PXP is ready, the ioctl will return -EBUSY if init is still in progress or -EIO if init failed. and given that going into a power-saving state kills PXP HWDRM sessions, runtime PM will be blocked while queues of this type are alive. all PXP queues will be killed if a PXP invalidation event occurs. 😭
• DRM_XE_EXEC_QUEUE_SET_PROPERTY_MULTI_GROUP — create a multi-queue group or add secondary queues to a multi-queue group. if the extension's value field has the DRM_XE_MULTI_GROUP_CREATE flag set, then a new multi-queue group is created with this queue as the primary queue (Q0). otherwise, the queue gets added to the multi-queue group whose primary queue's exec_queue_id is specified in the lower 32 bits of the value field. all the other non-relevant bits of the extension's value field while adding the primary or the secondary queues of the group must be set to 0. periodt, zero them out. 💀
• DRM_XE_EXEC_QUEUE_SET_PROPERTY_MULTI_QUEUE_PRIORITY — set the queue priority within the multi-queue group. current valid priority values are 0–2 (default is 1), with higher values indicating higher priority.
• DRM_XE_EXEC_QUEUE_SET_DISABLE_STATE_CACHE_PERF_FIX — set the queue to enable render color cache keying on BTP+BTI instead of just BTI (only valid for render queues).

---

the example below shows how to use struct drm_xe_exec_queue_create to create a simple exec_queue (no parallel submission) of class DRM_XE_ENGINE_CLASS_RENDER. slay, a minimal working example:

struct drm_xe_engine_class_instance instance = {
    .engine_class = DRM_XE_ENGINE_CLASS_RENDER,
};
struct drm_xe_exec_queue_create exec_queue_create = {
     .extensions = 0,
     .vm_id = vm,
     .width = 1,
     .num_placements = 1,
     .instances = to_user_pointer(instance),
};
ioctl(fd, DRM_IOCTL_XE_EXEC_QUEUE_CREATE, exec_queue_create);

allow users to provide a hint to kernel for cases demanding a low latency profile. please note it will have impact on power consumption ⚡ — yes bestie, low latency costs battery, that's the tradeoff. user can indicate the low latency hint with the flag while creating the exec queue as mentioned below:

struct drm_xe_exec_queue_create exec_queue_create = {
     .flags = DRM_XE_EXEC_QUEUE_LOW_LATENCY_HINT,
     .extensions = 0,
     .vm_id = vm,
     .width = 1,
     .num_placements = 1,
     .instances = to_user_pointer(instance),
};
ioctl(fd, DRM_IOCTL_XE_EXEC_QUEUE_CREATE, exec_queue_create);

🌈 SEE ALSO 🌈

go read these next, bestie — every single one, no skipping:

Kernel file ./include/uapi/drm/xe_drm.h 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_device_query(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_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, diva. now go create some queues responsibly.

mwah 💋 — this little number lives at ./include/uapi/drm, freshly dropped October 2026, and it's filed under struct drm_...queue_create(9) in the Kernel API Manual. catch you in the next one, bestie 🎀✨