CONTEXT ENGINE MAP UAPI(9)

🎀 Context Engine Map uAPI — bestie edition 🎀

okay so this is a Context Engine Map uAPI(9) situation, straight out of the Kernel API Manual, and honestly? it's giving glow-up. let me walk you through it 💅

---

✨ DESCRIPTION ✨

so the context engine map is a whole new way of addressing engines when you're submitting batch-buffers 💖. it's literally replacing the old way of doing things, where you'd use identifiers like I915_EXEC_BLT inside the flags field of struct drm_i915_gem_execbuffer2. rip to that era, but we've moved on 🦋.

to actually use it, the GEM contexts you create need to be configured with a list of engines that you're intending to submit to — like, you gotta tell the kernel your whole roster upfront, no cap. you do this with the I915_CONTEXT_PARAM_ENGINES parameter and struct i915_context_param_engines 🌸.

for contexts set up like this, the I915_EXEC_RING_MASK field becomes an index into the configured map 👑. periodt. that's the whole vibe shift.

---

🌈 EXAMPLE: creating one of these contexts and submitting against it 🌈

here's the iconic little demo, and yes you should absolutely read it, it's not long:

I915_DEFINE_CONTEXT_PARAM_ENGINES(engines, 2) = {
        .engines = { { I915_ENGINE_CLASS_RENDER, 0 },
                     { I915_ENGINE_CLASS_COPY, 0 } }
};
struct drm_i915_gem_context_create_ext_setparam p_engines = {
        .base = {
                .name = I915_CONTEXT_CREATE_EXT_SETPARAM,
        },
        .param = {
                .param = I915_CONTEXT_PARAM_ENGINES,
                .value = to_user_pointer(engines),
                .size = sizeof(engines),
        },
};
struct drm_i915_gem_context_create_ext create = {
        .flags = I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS,
        .extensions = to_user_pointer(p_engines);
};

ctx_id = gem_context_create_ext(drm_fd, create);

// We have now created a GEM context with two engines in the map:
// Index 0 points to rcs0 while index 1 points to bcs0. Other engines
// will not be accessible from this context.

...
execbuf.rsvd1 = ctx_id;
execbuf.flags = 0; // Submits to index 0, which is rcs0 for this context
gem_execbuf(drm_fd, execbuf);

...
execbuf.rsvd1 = ctx_id;
execbuf.flags = 1; // Submits to index 0, which is bcs0 for this context
gem_execbuf(drm_fd, execbuf);

🫶 friendly little heads-up, bestie: copy the code exactly as written above, comments and all — the comments in that last block are what the page says, even where they look a little quirky 🙈. don't go "fixing" them, that's not our job, we're just the messenger 💀.

---

💜 SEE ALSO 💜

okay this list is long but every single one of these is invited to the party, no gatekeeping 🎀:

• 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)
• 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(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)

like, that's the whole squad 😭🔥.

---

🌟 sign-off 🌟

this masterpiece comes to you from source ./tools/perf/trace/beauty/incl... and it's dated October 2026 — future iconic behavior honestly 👑✨. go forth and index your engines, bestie, iykyk 💖🦋🎀