STRUCT DRM_I915_GEM_CREATE_EXT(9)

📦 version 7.3.1, in nixpkgs unstable

✨ struct drm_i915_gem_create_ext — Kernel API Manual ✨

okay so bestie, welcome to the struct drm_i915_gem_create_ext page 💅 this is the Kernel API Manual, and this struct is literally the glow-up of the old gem_create behaviour — same energy, but with added extension support using struct i915_user_extension. it's giving "we kept the vibe and upgraded the fit" 🎀

🦋 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;
  #define I915_GEM_CREATE_EXT_SET_PAT 2;
    __u64 extensions;
 };

🌸 Members 🌸

💖 size

Requested size for the object, bestie — that's the ask.

The (page-aligned) allocated size for the object will be returned. so what you ask for and what you get back are page-aligned different, lowkey.

On platforms like DG2/ATS the kernel will always use 64K or larger pages for I915_MEMORY_CLASS_DEVICE. Also, the kernel requires a minimum of 64K GTT alignment for such objects. no cap, 64K is the floor 🫶

NOTE: Previously the ABI here required a minimum GTT alignment of 2M on DG2/ATS, due to how the hardware implemented 64K GTT page support, where we had the following complications:
  1. The entire PDE (which covers a 2MB virtual address range), must contain only 64K PTEs, i.e mixing 4K and 64K PTEs in the same PDE is forbidden by the hardware.
  2. We still need to support 4K PTEs for I915_MEMORY_CLASS_SYSTEM objects.

However on actual production HW this was completely changed to now allow setting a TLB hint at the PTE level (see PS64), which is a lot more flexible than the above. With this the 2M restriction was dropped where we now only require 64K. iconic behaviour honestly 💅

🎀 handle

Returned handle for the object.

Object handles are nonzero. periodt.

⭐ flags

Optional flags. ngl these are the spicy part.

Supported values:

  • I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS — Signal to the kernel that the object will need to be accessed via the CPU.

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. like, it has to be there or the whole thing falls apart 😭

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. they simply don't vibe together, bestie 💀

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. zero. none. 🍓

🧚 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. nostalgia arc 🥺

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.

For I915_GEM_CREATE_EXT_SET_PAT usage see struct drm_i915_gem_create_ext_set_pat.

🌈 Description 🌈

Note that new buffer flags should be added here, at least for the stuff that is immutable. Previously 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. rip to the old way, we hardly knew ye 🕊️

👑 SEE ALSO 👑

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

and that's the whole page, bestie!! 🫶 this one came from ./tools/perf/trace/beauty/incl... and it's dated October 2026, filed under struct drm_i...m_create_ext(9) — go slay your allocations, mwah 💋✨

📦 where this page comes from