STRUCT INTEL_ENGINE_EXECLISTS(9)

💅 struct intel_engine_execlists — Kernel API Manual edition, bestie 🎀

okay so picture this: it's a Kernel API Manual page, the whole thing is about struct intel_engine_execlists, and it's literally the execlist submission queue and the port state, like both of them, together, one struct. iconic behavior honestly ✨

---

✨ NAME ✨

struct intel_engine_execlists — execlist submission queue and port state 🦋

---

🌸 SYNOPSIS 🌸

struct intel_engine_execlists {
    struct timer_list timer;
    struct timer_list preempt;
    const struct i915_request *preempt_target;
    u32 ccid;
    u32 yield;
    u32 error_interrupt;
  #define ERROR_CSB       BIT(31);
  #define ERROR_PREEMPT   BIT(30);
    u32 reset_ccid;
    u32 __iomem *submit_reg;
    u32 __iomem *ctrl_reg;
  #define EXECLIST_MAX_PORTS 2;
    struct i915_request * const *active;
    struct i915_request *inflight[EXECLIST_MAX_PORTS + 1 ];
    struct i915_request *pending[EXECLIST_MAX_PORTS + 1];
    unsigned int port_mask;
    struct rb_root_cached virtual;
    u32 *csb_write;
    u64 *csb_status;
    u8 csb_size;
    u8 csb_head;
 };

no cap, that's the whole vibe of the struct 💀 every field gets its own little moment below 👑

---

🫶 Members 🫶

• timer — kicks the current context if its timeslice expires, like a little alarm clock that says "girl, your turn is OVER" ⏰
• preempt — resets the current context if it fails to give way. not mean, just boundary-setting 💅
• preempt_target — the active request at the time of the preemption request.

so here's the tea 🍵: we force a preemption to occur if the pending contexts have not been promoted to active upon receipt of the CS ack event within the timeout. This timeout maybe chosen based on the target, using a very short timeout if the context is no longer schedulable. That short timeout may not be applicable to other contexts, so if a context switch should happen within before the preemption timeout, we may shoot early at an innocent context. To prevent this, we record which context was active at the time of the preemption request and only reset that context upon the timeout. literally protecting the innocent, that's main character energy 🛡️

• ccid — identifier for contexts submitted to this engine 🆔
• yield — CCID at the time of the last semaphore-wait interrupt.

Instead of leaving a semaphore busy-spinning on an engine, we would like to switch to another ready context, i.e. yielding the semaphore timeslice. sharing is caring, bestie 🤝

• error_interrupt — CS Master EIR.

The CS generates an interrupt when it detects an error. We capture the first error interrupt, record the EIR and schedule the tasklet. In the tasklet, we process the pending CS events to ensure we have the guilty request, and then reset the engine. 🚨

Low 16b are used by HW, with the upper 16b used as the enabling mask. Reserve the upper 16b for tracking internal errors. yes the bit math is real and yes it matters 💀

• reset_ccid — Active CCID [EXECLISTS_STATUS_HI] at the time of reset 🔄
• submit_reg — gen-specific execlist submission register set to the ExecList Submission Port (elsp) register pre-Gen11 and to the ExecList Submission Queue Contents register array for Gen11+ 🧬
• ctrl_reg — the enhanced execlists control register, used to load the submit queue on the HW and to request preemptions to idle 🎛️
• active — the currently known context executing on HW. she's on stage rn 👑✨
• inflight — the set of contexts submitted and acknowledged by HW.

The set of inflight contexts is managed by reading CS events from the HW. On a context-switch event (not preemption), we know the HW has transitioned from port0 to port1, and we advance our inflight/active tracking accordingly. port0 → port1, the glow-up pipeline 🌈

• pending — the next set of contexts submitted to ELSP.

We store the array of contexts that we submit to HW (via ELSP) and promote them to the inflight array once HW has signaled the preemption or idle-to-active event. it's giving waitlist, then vip list 🎟️

• port_mask — number of execlist ports - 1 🔢
• virtual — Queue of requests on a virtual engine, sorted by priority. Each RB entry is a struct i915_priolist containing a list of requests of the same priority. sorted by priority fr fr, no cutting the line 🙈
• csb_write — control register for Context Switch buffer.

Note this register may be either mmio or HWSP shadow. ⚠️ like, either/or, don't assume

• csb_status — status array for Context Switch buffer.

Note these register may be either mmio or HWSP shadow. ⚠️ same deal, both options are valid

• csb_size — context status buffer FIFO size 📏
• csb_head — context status buffer head 🎯

---

🔥 Description 🔥

The struct intel_engine_execlists represents the combined logical state of driver and the hardware state for execlist mode of submission. two states, one struct, one vibe check passed 💖

---

⭐ SEE ALSO ⭐

• Kernel file ./drivers/gpu/drm/i915/gt/intel_engine_types.h 👀 go read it, iykyk

---

and that's the whole page, bestie 🫶 this came out of ./drivers/gpu/drm/i915/gt, dated October 2026, and it goes by struct inte...ne_execlists(9) in the Kernel API Manual — slay, bye 💜✨