STRUCT DRM_I915_GEM_SET_DOMAIN(9)

💅 struct drm_i915_gem_set_domain(9) — Kernel API Manual, but make it make sense

okay so bestie, we're in the <purple>Kernel API Manual</purple> section of the kernel docs and this one is literally called struct drm_i915_gem_set_domain ✨ she's a little struct with a big job and i'm obsessed with her ngl.

---

🌸 NAME 🌸

struct drm_i915_gem_set_domain — adjust the object's write or read domain, getting it all prepped for when you access the pages through some CPU domain 🎀

---

✨ SYNOPSIS ✨

struct drm_i915_gem_set_domain {
    __u32 handle;
    __u32 read_domains;
    __u32 write_domain;
 };

---

🧩 Members 🧩

• handle — the handle for the object 🫶 like, which object are we even talking about, this one.
• read_domains — the new read domains 💖
• write_domain — the new write domain 🔥

💀 heads up: having something in the write domain implies it's in the read domain — and only that read domain. that's just how it works, no cap.

---

🌈 Description 🌈

so the way this works: specifying a new write or read domain will flush the object out of the previous domain (if required), and then it updates the object's domain tracking with the new domain ✨ clean slate energy.

😭 ngl this might involve waiting for the object first if it's still active on the GPU. so like, be patient with her.

The supported values for read_domains and write_domain are, periodt:

• I915_GEM_DOMAIN_WC — uncached write-combined domain 🦋
• I915_GEM_DOMAIN_CPU — CPU cache domain 🍓
• I915_GEM_DOMAIN_GTT — mappable aperture domain ⭐

Every other domain gets rejected 🙈 like, respectfully, no.

💀 big important note: for discrete, starting from DG1, this is no longer supported and is instead rejected. on those platforms the CPU domain is effectively static, and we also only support a single drm_i915_gem_mmap_offset cache mode, which can't be set explicitly and instead depends on the object placements, as per the below 👇

Implicit caching rules, starting from DG1:

• if any of the object placements (see drm_i915_gem_create_ext_memory_regions) contain I915_MEMORY_CLASS_DEVICE, then the object will be allocated and mapped as write-combined only 💅
• everything else is always allocated and mapped as write-back, with the guarantee that everything is also coherent with the GPU 👑

🧚 and yes, this is likely to change in the future again — where we might need more flexibility on future devices — so making this all explicit as part of a new drm_i915_gem_create_ext extension is probable. manifesting it for us fr fr.

---

👑 SEE ALSO 👑

the whole friend group 💜:

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

---

okay that's the whole thing bestie, you ate that 💅✨

mwah, this page came to you from ./tools/perf/trace/beauty/incl..., dated <pink>October 2026</pink>, and she's officially the struct drm_i915_gem_set_domain(9) page 🎀🫶 go forth and set those domains fr fr 🌸