STRUCT XE_EXEC_QUEUE(9)

💅 struct xe_exec_queue — Kernel API Manual, bestie edition 💅

okay so like. this is the Kernel API Manual page for struct xe_exec_queue, and honestly? it's giving main character struct. it's a whole execution queue and it has so many fields. grab a snack, we're going through all of them 🍓

---

🌸 NAME 🌸

struct xe_exec_queue — Execution queue. that's the vibe. that's the whole assignment. ✨

---

🎀 SYNOPSIS 🎀

bestie. look at this. it's long but it's iconic. i'm putting it down verbatim because every single line matters, no cap 🔥

struct xe_exec_queue {
    struct xe_file *xef;
    struct xe_gt *gt;
    struct xe_hw_engine *hwe;
    struct kref refcount;
    struct xe_vm *vm;
    struct xe_vm *user_vm;
    enum xe_engine_class class;
    u32 logical_mask;
    char name[MAX_FENCE_NAME_LEN];
    u16 width;
    u16 msix_vec;
    struct xe_hw_fence_irq *fence_irq;
    struct dma_fence *last_fence;
  #define EXEC_QUEUE_FLAG_KERNEL                  BIT(0);
  #define EXEC_QUEUE_FLAG_PERMANENT               BIT(1);
  #define EXEC_QUEUE_FLAG_VM                      BIT(2);
  #define EXEC_QUEUE_FLAG_BIND_ENGINE_CHILD       BIT(3);
  #define EXEC_QUEUE_FLAG_HIGH_PRIORITY           BIT(4);
  #define EXEC_QUEUE_FLAG_LOW_LATENCY             BIT(5);
  #define EXEC_QUEUE_FLAG_MIGRATE                 BIT(6);
  #define EXEC_QUEUE_FLAG_DISABLE_STATE_CACHE_PERF_FIX    BIT(7);
    unsigned long flags;
    union {
      struct list_head multi_gt_list;
      struct list_head multi_gt_link;
    };
    union {
      struct xe_execlist_exec_queue *execlist;
      struct xe_guc_exec_queue *guc;
    };
    struct {
      struct xe_exec_queue_group *group;
      struct list_head link;
      enum xe_multi_queue_priority priority;
      spinlock_t lock;
      u8 pos;
      u8 valid:1;
      u8 is_primary:1;
    } multi_queue;
    struct {
      u32 timeslice_us;
      u32 preempt_timeout_us;
      u32 job_timeout_ms;
      enum xe_exec_queue_priority priority;
    } sched_props;
    struct {
      struct dma_fence *pfence;
      u64 context;
      u32 seqno;
      struct list_head link;
      bool suspended;
    } lr;
  #define XE_EXEC_QUEUE_TLB_INVAL_PRIMARY_GT      0;
  #define XE_EXEC_QUEUE_TLB_INVAL_MEDIA_GT        1;
  #define XE_EXEC_QUEUE_TLB_INVAL_COUNT
(XE_EXEC_QUEUE_TLB_INVAL_MEDIA_GT  + 1);
    struct {
      struct xe_dep_scheduler *dep_scheduler;
      struct dma_fence *last_fence;
    } tlb_inval[XE_EXEC_QUEUE_TLB_INVAL_COUNT];
    struct list_head vm_exec_queue_link;
    struct {
      u8 type;
      struct list_head link;
    } pxp;
    struct drm_syncobj *ufence_syncobj;
    u64 ufence_timeline_value;
    void *replay_state;
    const struct xe_exec_queue_ops *ops;
    const struct xe_ring_ops *ring_ops;
    struct drm_sched_entity *entity;
  #define XE_MAX_JOB_COUNT_PER_EXEC_QUEUE 1000;
    atomic_t job_cnt;
    u64 tlb_flush_seqno;
    struct list_head hw_engine_group_link;
    spinlock_t lrc_lookup_lock;
    struct xe_lrc *lrc[];
};

---

🦋 Members 🦋

okay now the fun part — every single member, explained. i'm obsessed with how much detail is in here. let's go 🫶

• xef — back pointer to the xe file if this is a user-created exec queue. like a little "return to sender" tag 💌
• gt — the GT structure this exec queue can submit to
• hwe — a hardware engine of the same class. it may (physical engine) or may not (virtual engine) be where the job's actual engine ends up running. should never really be used for submissions. ngl, it's decorative-adjacent. don't submit through it 💀
• refcount — ref count of this exec queue. keep it balanced or things get spicy
• vm — the VM (address space) for this exec queue
• user_vm — the User VM (address space) for this exec queue — bind queues only 🎀
• class — class of this exec queue
• logical_mask — logical mask of where a job submitted to this exec queue can run
• name — name of this exec queue (yes it has a name, it's a whole person)
• width — width (number of BBs submitted per exec) of this exec queue
• msix_vec — MSI-X vector (for platforms that support it)
• fence_irq — fence IRQ used to signal job completion ⭐
• last_fence — last fence on the exec queue. protected by vm->lock in write mode if it's a bind exec queue, and protected by the dma resv lock if it's a non-bind exec queue 🔒
• flags — flags for this exec queue. should be statically set up aside from the ban bit
• {unnamed_union} — anonymous. mysterious. no name. we love a mystery 🕵️
  • multi_gt_list — list head for VM bind engines if multi-GT
  • multi_gt_link — link for VM bind engines if multi-GT
• {unnamed_union} — anonymous (again! two mysterious unions, it's giving twins 👯)
  • execlist — execlist backend specific state for the exec queue
  • guc — GuC backend specific state for the exec queue
• multi_queue — multi queue information
  • multi_queue.group — queue group information
  • multi_queue.link — link into the group's secondary queues list
  • multi_queue.priority — queue priority within the multi-queue group. it's protected by multi_queue.lock
  • multi_queue.lock — lock for protecting certain members
  • multi_queue.pos — position of the queue within the multi-queue group
  • multi_queue.valid — the queue belongs to a multi queue group
  • multi_queue.is_primary — is this the primary queue (Q0) of the group? 👑
• sched_props — scheduling properties
  • sched_props.timeslice_us — timeslice period in micro-seconds
  • sched_props.preempt_timeout_us — preemption timeout in micro-seconds
  • sched_props.job_timeout_ms — job timeout in milliseconds
  • sched_props.priority — priority of this exec queue
• lr — long-running exec queue state
  • lr.pfence — preemption fence
  • lr.context — preemption fence context
  • lr.seqno — preemption fence seqno
  • lr.link — link into the VM's list of exec queues
  • lr.suspended — tracks whether the consumer-issued suspend succeeded and a matching resume is still owed. suspend can fail (e.g. killed/banned/wedged), leaving the queue un-suspended, so consumers must only resume queues that were actually suspended. set by the suspend caller on success and cleared by the resume caller. a queue is only ever suspended by a single consumer at a time (preempt-fence mode and hw engine group fault mode are mutually exclusive), so a single flag is sufficient. genuinely very thoughtful of them, tbh 🧚
• tlb_inval — TLB invalidations exec queue state
  • tlb_inval.dep_scheduler — the TLB invalidation dependency scheduler
  • tlb_inval.last_fence — last fence for tlb invalidation, protected by vm->lock in write mode
• vm_exec_queue_link — link to track the exec queue within a VM's list of exec queues
• pxp — PXP info tracking
  • pxp.type — PXP session type used by this queue
  • pxp.link — link into the list of PXP exec queues
• ufence_syncobj — user fence syncobj
• ufence_timeline_value — user fence timeline value
• replay_state — GPU hang replay state 😭 (hope you never need it)
• ops — submission backend exec queue operations
• ring_ops — ring operations for this exec queue
• entity — DRM sched entity for this exec queue (1 to 1 relationship, they're exclusive 💖)
• job_cnt — number of drm jobs in this exec queue
• tlb_flush_seqno — the seqno of the last rebind tlb flush performed. protected by the vm's resv. unused if vm == NULL
• hw_engine_group_link — link into exec queues in the same hw engine group
• lrc_lookup_lock — lock for protecting lrc array access. only used when running in parallel to queue creation is possible
• lrc — logical ring context for this exec queue 🌈

---

💖 Description 💖

contains all state necessary for submissions. can either be a user object or a kernel object. that's the whole point, and it ate. periodt.

---

⭐ SEE ALSO ⭐

• Kernel file ./drivers/gpu/drm/xe/xe_exec_queue_types.h
• enum xe_multi_queue_priority(9)
• struct xe_exec_queue_group(9)
• struct xe_exec_queue_ops(9)

go read those too, iykyk 💅

---

and that's the page, bestie! 🫶 this came from ./drivers/gpu/drm/xe, dated October 2026, and it's the struct xe_exec_queue(9) manual page. go forth and submit responsibly ✨🎀🦋