STRUCT I915_CONTEXT_ENGINES_PARALLEL_SUBMIT(9)

💅 struct i915_context_engines_parallel_submit — Kernel API Manual 💅

okay so bestie, welcome to the group chat. this is the Kernel API Manual page for struct i915_context_engines_parallel_submit, and honestly? it's a baddie. it's literally the struct that lets your GPU run a bunch of batches at the same time. let's get into it 🫶

---

✨ NAME ✨

struct i915_context_engines_parallel_submit — Configure engine for parallel submission.

like the name says: we're configuring an engine so it can do parallel submission. she's a multi-tasker, she's booked and busy 💅

---

🎀 SYNOPSIS 🎀

struct i915_context_engines_parallel_submit {
    struct i915_user_extension base;
    __u16 engine_index;
    __u16 width;
    __u16 num_siblings;
    __u16 mbz16;
    __u64 flags;
    __u64 mbz64[3];
    struct i915_engine_class_instance engines[];
};

look at her. iconic. every field matters, so let's go one by one 🌸

---

🦋 Members 🦋

• base — the base user extension. she's the foundation, the main character energy of the whole struct.
• engine_index — the slot for the parallel engine.
• width — number of contexts per parallel engine, or, in other words, the number of batches in each submission.
• num_siblings — number of siblings per context, or, in other words, the number of possible placements for each submission.
• mbz16 — reserved for future use; must be zero. (mbz = "must be zero", bestie. don't be weird about it 🙈)
• flags — all undefined flags must be zero, currently not defined flags.
• mbz64 — reserved for future use; must be zero.
• engines — 2-d array of engine instances to configure parallel engine

and the indexing math, which you should literally just copy exactly:

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

---

🔥 Description 🔥

so what does this thing actually do? Setup a slot in the context engine map to allow multiple BBs to be submitted in a single execbuf IOCTL. Those BBs will then be scheduled to run on the GPU in parallel. Multiple hardware contexts are created internally in the i915 to run these BBs.

Once a slot is configured for N BBs, only N BBs can be submitted in each execbuf IOCTL, and this is implicit behavior — e.g. the user doesn't tell the execbuf IOCTL there are N BBs, the execbuf IOCTL knows how many BBs there are based on the slot's configuration. The N BBs are the last N buffer objects or first N if I915_EXEC_BATCH_FIRST is set. (iykyk 🔥)

The default placement behavior is to create implicit bonds between each context if each context maps to more than 1 physical engine (e.g. context is a virtual engine). Also we only allow contexts of same engine class and these contexts must be in logically contiguous order. Examples of the placement behavior are described below. Lastly, the default is to not allow BBs to be preempted mid-batch — instead insert coordinated preemption points on all hardware contexts between each set of BBs. Flags could be added in the future to change both of these default behaviors. so yeah, future flag energy, not here yet ⭐

Returns -EINVAL if hardware context placement configuration is invalid or if the placement configuration isn't supported on the platform / submission interface. Returns -ENODEV if extension isn't supported on the platform / submission interface. bestie, if you see these, the config was NOT it 😭

---

💜 Examples — the part everyone actually reads 💜

Examples syntax:
CS[X] = generic engine of same class, logical instance X
INVALID = I915_ENGINE_CLASS_INVALID, I915_ENGINE_CLASS_INVALID_NONE

Example 1 pseudo code 🍓

set_engines(INVALID)
set_parallel(engine_index=0, width=2, num_siblings=1,
             engines=CS[0],CS[1])

Results in the following valid placement:

CS[0], CS[1]

Example 2 pseudo code 🌈

set_engines(INVALID)
set_parallel(engine_index=0, width=2, num_siblings=2,
             engines=CS[0],CS[2],CS[1],CS[3])

Results in the following valid placements:

CS[0], CS[1]
CS[2], CS[3]

This can be thought of as two virtual engines, each containing two engines thereby making a 2D array. However, there are bonds tying the entries together and placing restrictions on how they can be scheduled. Specifically, the scheduler can choose only vertical columns from the 2D array. That is, CS[0] is bonded to CS[1] and CS[2] to CS[3]. So if the scheduler wants to submit to CS[0], it must also choose CS[1] and vice versa. Same for CS[2] requires also using CS[3].

VE[0] = CS[0], CS[2]
VE[1] = CS[1], CS[3]

they're bonded, your honor 💀

Example 3 pseudo code 🧚

set_engines(INVALID)
set_parallel(engine_index=0, width=2, num_siblings=2,
             engines=CS[0],CS[1],CS[1],CS[3])

Results in the following valid and invalid placements:

CS[0], CS[1]
CS[1], CS[3] - Not logically contiguous, return -EINVAL

that second one? not logically contiguous, so it returns -EINVAL. she got rejected at the door 🚪💅

---

👑 SEE ALSO 👑

the full squad, no cap, nobody left behind:

• 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)
• Context Engine Map uAPI(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)

---

and that's the whole page, bestie, you ate that 🫶 source: ./tools/perf/trace/beauty/incl... — dated October 2026, and yes, the footer still says struct i915...allel_submit(9) because some things are sacred. mwah 💖✨