STRUCT I915_GEM_CONTEXT(9)

✨ NAME ✨

struct i915_gem_context — literally the client state, bestie. That's the whole vibe. 💅

This is a page from the Kernel API Manual, and we're about to become unwell about a struct together. 🫶

---

🦋 SYNOPSIS 🦋

struct i915_gem_context {
    struct drm_i915_private *i915;
    struct drm_i915_file_private *file_priv;
    struct i915_gem_engines *engines;
    struct mutex engines_mutex;
    struct drm_syncobj *syncobj;
    struct i915_address_space *vm;
    struct pid *pid;
    struct list_head link;
    struct i915_drm_client *client;
    struct list_head client_link;
    struct kref ref;
    struct work_struct release_work;
    struct rcu_head rcu;
    unsigned long user_flags;
  #define UCONTEXT_NO_ERROR_CAPTURE       1;
  #define UCONTEXT_BANNABLE               2;
  #define UCONTEXT_RECOVERABLE            3;
  #define UCONTEXT_PERSISTENCE            4;
  #define UCONTEXT_LOW_LATENCY            5;
    unsigned long flags;
  #define CONTEXT_CLOSED                  0;
  #define CONTEXT_USER_ENGINES            1;
    bool uses_protected_content;
    intel_wakeref_t pxp_wakeref;
    struct mutex mutex;
    struct i915_sched_attr sched;
    atomic_t guilty_count;
    atomic_t active_count;
    unsigned long hang_timestamp[2];
  #define CONTEXT_FAST_HANG_JIFFIES (120 * HZ) ;
    u8 remap_slice;
    struct radix_tree_root handles_vma;
    struct mutex lut_mutex;
    char name[TASK_COMM_LEN + 8];
    struct {
      spinlock_t lock;
      struct list_head engines;
    } stale;
  };

No cap, that's the whole shape of it. Now let's go member by member, because every single field is a main character. 👑

---

🎀 MEMBERS 🎀

i915

i915 device backpointer. It's giving "who's your parent" energy. 💖

file_priv

The owning file descriptor. 🐚

engines

User defined engines for this context.

Various uAPI offer the ability to lookup up an index from this array to select an engine operate on.

Multiple logically distinct instances of the same engine may be defined in the array, as well as composite virtual engines.

Execbuf uses the I915_EXEC_RING_MASK as an index into this array to select which HW context + engine to execute on. For the default array, the user_ring_map[] is used to translate the legacy uABI onto the appropriate index (e.g. both I915_EXEC_DEFAULT and I915_EXEC_RENDER select the same context, and I915_EXEC_BSD is weird). For a user defined array, execbuf uses I915_EXEC_RING_MASK as a plain index.

User defined by I915_CONTEXT_PARAM_ENGINE (when the CONTEXT_USER_ENGINES flag is set).

engines_mutex

guards writes to engines. 🔒

syncobj

Shared timeline syncobj. ⏱️

When the SHARED_TIMELINE flag is set on context creation, we emulate a single timeline across all engines using this syncobj. For every execbuffer2 call, this syncobj is used as both an in- and out-fence. Unlike the real intel_timeline, this doesn't provide perfect atomic in-order guarantees if the client races with itself by calling execbuffer2 twice concurrently. However, if userspace races with itself, that's not likely to yield well- defined results anyway so we choose to not care. 💀

vm

unique address space (GTT).

In full-ppgtt mode, each context has its own address space ensuring complete separation of one client from all others. 🧚

In other modes, this is a NULL pointer with the expectation that the caller uses the shared global GTT.

pid

process id of creator. 🌸

Note that who created the context may not be the principle user, as the context may be shared across a local socket. However, that should only affect the default context, all contexts created explicitly by the client are expected to be isolated.

link

place with drm_i915_private.context_list. 🔗

client

struct i915_drm_client.

client_link

for linking onto i915_drm_client.ctx_list.

ref

reference count. 🧮

A reference to a context is held by both the client who created it and on each request submitted to the hardware using the request (to ensure the hardware has access to the state until it has finished all pending writes). See i915_gem_context_get and i915_gem_context_put for access.

release_work

Work item for deferred cleanup, since i915_gem_context_put tends to be called from hardirq context.

FIXME: The only real reason for this is i915_gem_engines.fence, all other callers are from process context and need at most some mild shuffling to pull the i915_gem_context_put call out of a spinlock. 😭

rcu

rcu_head for deferred freeing.

user_flags

small set of booleans controlled by the user. 🎛️

flags

small set of booleans.

uses_protected_content

context uses PXP-encrypted objects.

This flag can only be set at ctx creation time and it's immutable for the lifetime of the context. See I915_CONTEXT_PARAM_PROTECTED_CONTENT in uapi/drm/i915_drm.h for more info on setting restrictions and expected behaviour of marked contexts. 🔐

pxp_wakeref

wakeref to keep the device awake when PXP is in use.

PXP sessions are invalidated when the device is suspended, which in turns invalidates all contexts and objects using it. To keep the flow simple, we keep the device awake when contexts using PXP objects are in use. It is expected that the userspace application only uses PXP when the display is on, so taking a wakeref here shouldn't worsen our power metrics. 🔥

mutex

guards everything that isn't engines or handles_vma. 💅

sched

scheduler parameters.

guilty_count

How many times this context has caused a GPU hang. 😬

active_count

How many times this context was active during a GPU hang, but did not cause it. Innocent bystander behavior fr fr.

hang_timestamp

The last time(s) this context caused a GPU hang. 🕰️

remap_slice

Bitmask of cache lines that need remapping.

handles_vma

rbtree to look up our context specific obj/vma for the user handle. (user handles are per fd, but the binding is per vm, which may be one per context or shared with the global GTT) 🌈

lut_mutex

Locks handles_vma. 🔐

name

arbitrary name, used for user debug.

A name is constructed for the context from the creator's process name, pid and user handle in order to uniquely identify the context in messages. 🏷️

stale

tracks stale engines to be destroyed. 🍂

stale.lock

guards engines.

stale.engines

list of stale engines.

---

💜 DESCRIPTION 💜

The struct i915_gem_context represents the combined view of the driver and logical hardware state for a particular client. It's the whole package, honestly. ✨

---

⭐ 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_proto_context(9)

---

okay that's the whole page bestie, go read the source at ./drivers/gpu/drm/i915/gem 🍓 — this one's dated October 2026, and yes it's still struct i915_gem_context(9) erasure in the Kernel API Manual, periodt. 🎀💖