STRUCT __DRM_I915_GEM_CREATE_EXT(9)

✨ struct __drm_i915_gem_create_ext(9) ✨

okay so this is a page from the Kernel API Manual, and it's all about struct __drm_i915_gem_create_ext — bestie, it's literally the classic gem_create vibe but with extension support bolted on via struct i915_user_extension. 🎀

---

💖 NAME 💖

struct __drm_i915_gem_create_ext — the existing gem_create behaviour, except now with added extension support using struct i915_user_extension. it's giving "same girl, new tricks" 💅

---

🌸 SYNOPSIS 🌸

struct __drm_i915_gem_create_ext {
    __u64 size;
    __u32 handle;
  #define I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS (1 << 0);
    __u32 flags;
  #define I915_GEM_CREATE_EXT_MEMORY_REGIONS 0;
  #define I915_GEM_CREATE_EXT_PROTECTED_CONTENT 1;
    __u64 extensions;
 };

---

🦋 Members 🦋

🌟 size

the requested size for the object. 📏

the (page-aligned) allocated size for the object is what gets returned — so don't be surprised when it's not your exact number, she rounds up.

note that for some devices we might have further minimum page-size restrictions (bigger than 4K), like for device local-memory. but in general the final size here should always reflect any rounding up — for example if you're using the I915_GEM_CREATE_EXT_MEMORY_REGIONS extension to place the object in device local-memory. the kernel will always select the largest minimum page-size for the set of possible placements as the value to use when rounding up the size. no cap, that's just how she rolls. ✨

---

🌟 handle

the returned handle for the object. 🎀

object handles are nonzero. periodt.

---

🌟 flags

optional flags. the supported values are:

• I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS — signals to the kernel that the object will need to be accessed via the CPU. 🖥️

this one is only valid when placing objects in I915_MEMORY_CLASS_DEVICE, and only strictly required on configurations where some subset of the device memory is directly visible/mappable through the CPU (which we also call small BAR), like on some DG2+ systems. note that this is quite undesirable, but due to various factors like the client CPU, BIOS etc it's something we can expect to see in the wild. 👀 see __drm_i915_memory_region_info.probed_cpu_visible_size for how to determine if this system applies.

note that one of the placements MUST be I915_MEMORY_CLASS_SYSTEM, to ensure the kernel can always spill the allocation to system memory, if the object can't be allocated in the mappable part of I915_MEMORY_CLASS_DEVICE.

also note that since the kernel only supports flat-CCS on objects that can only be placed in I915_MEMORY_CLASS_DEVICE, we therefore don't support I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS together with flat-CCS. 💀

without this hint, the kernel will assume that non-mappable I915_MEMORY_CLASS_DEVICE is preferred for this object. note that the kernel can still migrate the object to the mappable part, as a last resort, if userspace ever CPU faults this object — but this might be expensive, and so ideally should be avoided. 😭

on older kernels which lack the relevant small-bar uAPI support (see also __drm_i915_memory_region_info.probed_cpu_visible_size), usage of the flag will result in an error, but it should NEVER be possible to end up with a small BAR configuration, assuming we can also successfully load the i915 kernel module. in such cases the entire I915_MEMORY_CLASS_DEVICE region will be CPU accessible, and as such there are zero restrictions on where the object can be placed. 🙈

---

🌟 extensions

the chain of extensions to apply to this object. 🔗

this will be useful in the future when we need to support several different extensions, and we need to apply more than one when creating the object. see struct i915_user_extension.

if we don't supply any extensions then we get the same old gem_create behaviour — iconic, classic, no notes. ✨

for I915_GEM_CREATE_EXT_MEMORY_REGIONS usage see struct drm_i915_gem_create_ext_memory_regions.

for I915_GEM_CREATE_EXT_PROTECTED_CONTENT usage see struct drm_i915_gem_create_ext_protected_content.

---

🔥 Description 🔥

quick heads up: new buffer flags should be added here, at least for the stuff that's immutable. 👑

back in the day we would have two ioctls — one to create the object with gem_create, and another to apply various parameters — however this creates some ambiguity for the params which are considered immutable. also in general we're phasing out the various SET/GET ioctls. so yeah, glow-up achieved, we're doing it in one struct now. 💅✨

---

👑 SEE ALSO 👑

• kernel file ./Documentation/gpu/rfc/i915_small_bar.h
• struct __drm_i915_memory_region_info(9)

---

ok bestie, a lil recap so you don't get caught lacking: the flags have to go here (at least the immutable ones), I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS is a small-BAR-only situation and does not play nice with flat-CCS, and if you skip extensions entirely you just get plain old gem_create. mwah. 🫶

---

and that's the whole page, bestie!! 🎀 source is ./Documentation/gpu/rfc, dated October 2026, and it's filed under struct __drm...m_create_ext(9) — go forth and create those objects, you've got this 💜✨🌈