STRUCT I915_GEM_PROTO_CONTEXT(9)

✨ struct i915_gem_proto_context(9) ✨

okay so welcome to the Kernel API Manual, bestie — this is the entry for struct i915_gem_proto_context, and it is literally the “prototype context” era of an i915 context before the real one gets born. 🫶

---

🎀 NAME 🎀

struct i915_gem_proto_context — prototype context.

✨ SYNOPSIS ✨

struct i915_gem_proto_context {
    struct drm_i915_file_private *fpriv;
    struct i915_address_space *vm;
    unsigned long user_flags;
    struct i915_sched_attr sched;
    int num_user_engines;
    struct i915_gem_proto_engine *user_engines;
    struct intel_sseu legacy_rcs_sseu;
    bool single_timeline;
    bool uses_protected_content;
    intel_wakeref_t pxp_wakeref;
};

👑 Members 👑

• fpriv — the client which creates the context.
• vm — see i915_gem_context.vm.
• user_flags — see i915_gem_context.user_flags.
• sched — see i915_gem_context.sched.
• num_user_engines — number of user-specified engines or -1.
• user_engines — user-specified engines.
• legacy_rcs_sseu — client-set SSEU parameters for the legacy RCS.
• single_timeline — See See i915_gem_context.syncobj (the double “See” is literally in the original, no cap 💀).
• uses_protected_content — see i915_gem_context.uses_protected_content.
• pxp_wakeref — see i915_gem_context.pxp_wakeref.

💖 Description 💖

Okay so struct i915_gem_proto_context represents the creation parameters for a struct i915_gem_context. It’s the little gather-everything-first spot for params that come in either through creation flags or via SET_CONTEXT_PARAM, so that when the final i915_gem_context gets created, those parameters can be immutable. Iconic, honestly. 🔥

The context uAPI allows for two methods of setting context parameters: SET_CONTEXT_PARAM and CONTEXT_CREATE_EXT_SETPARAM. The former is allowed to be called at any time, while the latter happens as part of GEM_CONTEXT_CREATE. Back when these were initially added — and currently too — everything settable via one is settable via the other. Some params are fairly simple and setting them on a live context is harmless, such as the context priority. Others are far trickier, such as the VM or the set of engines. To avoid some truly nasty race conditions, we don’t allow setting the VM or the set of engines on live contexts. 🚫

The way we dealt with this without breaking older userspace that sets the VM or engine set via SET_CONTEXT_PARAM is to delay the creation of the actual context until after the client is done configuring it with SET_CONTEXT_PARAM. From the perspective of the client, it has the same u32 context ID the whole time. From the perspective of i915, however, it’s an i915_gem_proto_context right up until the point where we attempt to do something which the proto-context can’t handle — at which point the real context gets created. ✨

This is accomplished via a little xarray dance. 🩰 When GEM_CONTEXT_CREATE is called, we create a proto-context, reserve a slot in context_xa but leave it NULL, and put the proto-context in the corresponding slot in proto_context_xa. Then, whenever we go to look up a context, we first check context_xa. If it’s there, we return the i915_gem_context and we’re done. If it’s not, we look in proto_context_xa and, if we find it there, we create the actual context and kill the proto-context. 💅

At the time we made this change (April, 2021), we did a fairly complete audit of existing userspace to ensure this wouldn’t break anything:

• Mesa/i965 didn’t use the engines or VM APIs at all.
• Mesa/ANV used the engines API but via CONTEXT_CREATE_EXT_SETPARAM and didn’t use the VM API.
• Mesa/iris didn’t use the engines or VM APIs at all.
• The open-source compute-runtime didn’t yet use the engines API but did use the VM API via SET_CONTEXT_PARAM. However, CONTEXT_SETPARAM was always the second ioctl on that context, immediately following GEM_CONTEXT_CREATE.
• The media driver sets engines and bonding/balancing via SET_CONTEXT_PARAM. However, CONTEXT_SETPARAM to set the VM was always the second ioctl on that context, immediately following GEM_CONTEXT_CREATE and setting engines immediately followed that.

In order for this dance to work properly, any modification to an i915_gem_proto_context that is exposed to the client via drm_i915_file_private::proto_context_xa must be guarded by drm_i915_file_private::proto_context_lock. The exception is when a proto-context has not yet been exposed, such as when handling CONTEXT_CREATE_SET_PARAM during GEM_CONTEXT_CREATE. 🔐

🌈 SEE ALSO 🌈

Kernel file ./drivers/gpu/drm/i915/gem/i915_gem_context_types.h struct i915_gem_engines(9), struct i915_gem_engines_iter(9), enum i915_gem_engine_type(9), struct i915_gem_proto_engine(9), struct i915_gem_context(9).

---

okay bestie, that’s the whole page! this came from the source/version path ./drivers/gpu/drm/i915/gem, and the date on it is October 2026 — go off, calendar. 🗓️💖