STRUCT DRM_I915_GEM_CREATE_EXT_MEMORY_REGIONS(9)

💅 struct drm_i915_gem_create_ext_memory_regions ✨

okay so bestie, welcome to the Kernel API Manual 🎀 — this page is all about struct drm_i915_gem_create_ext_memory_regions, aka the I915_GEM_CREATE_EXT_MEMORY_REGIONS extension. it's giving "tell the kernel where you want your object to live" energy and honestly? iconic. no cap, let's get into it 🦋

---

✨ NAME ✨

struct drm_i915_gem_create_ext_memory_regions — literally the I915_GEM_CREATE_EXT_MEMORY_REGIONS extension, bestie 💖 that's the whole vibe.

---

🧚 SYNOPSIS 🧚

struct drm_i915_gem_create_ext_memory_regions {
    struct i915_user_extension base;
    __u32 pad;
    __u32 num_regions;
    __u64 regions;
 };

---

🌸 Members 🌸

• base — the extension link, bestie 🔗. see struct i915_user_extension for the deets.
• pad — MBZ 💀 (must be zero, don't be weird about it).
• num_regions — how many elements are chillin' in the regions array.
• regions — the regions/placements array 🔥. it's an array of struct drm_i915_gem_memory_class_instance.

---

👑 Description 👑

so what this actually does: you set the object with the desired set of placements/regions in priority order ✨. every single entry has to be unique and supported by the device — no duplicates, no delulu unsupported picks 🙈.

this is provided as an array of struct drm_i915_gem_memory_class_instance, or an equivalent layout of class:instance pair encodings 🫶. see struct drm_i915_query_memory_regions and DRM_I915_QUERY_MEMORY_REGIONS for how to query the supported regions for a device — iykyk, that's where you find out what your GPU can actually do 🌈.

as an example, on discrete devices, if we wish to set the placement as device local-memory we can do something like ✨:

struct drm_i915_gem_memory_class_instance region_lmem = {
        .memory_class = I915_MEMORY_CLASS_DEVICE,
        .memory_instance = 0,
};
struct drm_i915_gem_create_ext_memory_regions regions = {
        .base = { .name = I915_GEM_CREATE_EXT_MEMORY_REGIONS },
        .regions = (uintptr_t)region_lmem,
        .num_regions = 1,
};
struct drm_i915_gem_create_ext create_ext = {
        .size = 16 * PAGE_SIZE,
        .extensions = (uintptr_t)regions,
};

int err = ioctl(fd, DRM_IOCTL_I915_GEM_CREATE_EXT, create_ext);
if (err) ...

at which point we get the object handle in drm_i915_gem_create_ext.handle 👑, along with the final object size in drm_i915_gem_create_ext.size, which should account for any rounding up, if required 📏. slay.

⚠️ important caveat bestie: note that userspace has no means of knowing the current backing region for objects where num_regions is larger than one 😭. the kernel will only ensure that the priority order of the regions array is honoured, either when initially placing the object, or when moving memory around due to memory pressure. so like, it tries its best, fr fr.

now the Flat-CCS lore 🧚: on Flat-CCS capable HW, compression is supported for the objects residing in I915_MEMORY_CLASS_DEVICE. when such objects (compressed) have other memory class in regions and migrated (by i915, due to memory constraints) to the non I915_MEMORY_CLASS_DEVICE region, then i915 needs to decompress the content. but i915 doesn't have the required information to decompress the userspace compressed objects 💀.

so i915 supports Flat-CCS, on the objects which can reside only on I915_MEMORY_CLASS_DEVICE regions. periodt. 💅

---

🔥 SEE ALSO 🔥

the whole friend group, assembled 🫶:

• 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)
• 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_protected_content(9)
• struct drm_i915_gem_create_ext_set_pat(9)

---

🌸 that's the whole page bestie, you ate 💅 source is ./tools/perf/trace/beauty/incl... and it's dated October 2026 — go forth and place your objects with main character energy 👑✨💜