i915_gem_gtt_insert(9)

📦 version 7.3.1, in nixpkgs unstable

💅 i915_gem_gtt_insert — the Kernel API Manual moment ✨

okay so bestie, brace yourself: this is i915_gem_gtt_insert(9) from the kernel's own API manual, and it's lowkey the function that finds your node a home inside an address_space (the GTT). no cap. let's get into it 🫶

🌸 SYNOPSIS 🌸

int i915_gem_gtt_insert (struct i915_address_space *vm , struct
       i915_gem_ww_ctx *ww , struct drm_mm_node *node , u64 size , u64
       alignment , unsigned long color , u64 start , u64 end , unsigned int
       flags );

like, literally five different types in one signature and every single one of them matters. main character energy fr fr 💀

🎀 ARGUMENTS 🎀

  • vm — the struct i915_address_space. this is the space we're inserting into, the whole vibe check of the operation ✨
  • ww — An optional struct i915_gem_ww_ctx. optional!! so it can be a whole thing or it can be nothing, she's flexible 💅
  • node — the struct drm_mm_node, and typically you're passing i915_vma.node here. that's the actual thing getting placed, like the lil nugget we're finding room for 🍓
  • size — how much space to allocate inside the GTT. and listen: it must be #I915_GTT_PAGE_SIZE aligned. not kinda aligned, not almost, aligned. periodt 🔥
  • alignment — required alignment of the starting offset. may be 0, but if you do specify it, it must be a power-of-two and at least #I915_GTT_MIN_ALIGNMENT. two rules, no exceptions, iykyk 💀
  • color — color to apply to node. yes really, colors, we'll get to why in a sec 🌈
  • start — start of any range restriction inside GTT (0 for all). must be #I915_GTT_PAGE_SIZE aligned. that aligned thing again, she's consistent 💖
  • end — end of any range restriction inside GTT (U64_MAX for all). must be #I915_GTT_PAGE_SIZE aligned if not U64_MAX. read that conditional twice bestie 👀
  • flags — control search and eviction behaviour. this is where you tell her how spicy to be 🌶️

🦋 DESCRIPTION 🦋

so first things first: i915_gem_gtt_insert goes hunting for an available hole it can insert the node into. shopping spree, but for address space 🛍️

the hole's address gets aligned to alignment, and then its size must fit entirely within the [start, end] bounds. no half-in-half-out situations, it's all or nothing, we don't do situationships here 😤

now — the nodes on either side of that hole? they must match color, or else a guard page gets inserted between the two nodes (or, alternative ending, the node gets evicted). it's giving "you can sit with us but only if you match the aesthetic" 💅

and if no suitable hole pops up at all? watch this:

  1. first, a victim is randomly selected and tested for eviction. literally random. chaotic but iconic 🎲
  2. otherwise, the LRU list of objects within the GTT gets scanned to find the first set of replacement nodes that can create the hole 🔍

those old overlapping nodes get evicted from the GTT, which means — and this is the important part — they must be rebound before any future use. so write that down 📝

also: any node that's currently pinned cannot be evicted. see i915_vma_pin. pinned means pinned, she said no 🚫

similar situation: if the node's VMA is currently active and #PIN_NONBLOCK is specified, that node is also skipped when it's searching for an eviction candidate. skipped!! 🙈

and if you want the gory details on the whole eviction algorithm, go read i915_gem_evict_something — that's where the mess lives 💀

⭐ RETURN ⭐

  • 0 on success 🎉 slay
  • -ENOSPC if no suitable hole is found 😭 no space, no vibes
  • -EINTR if it's asked to wait for eviction and gets interrupted 🫠

💜 SEE ALSO 💜

okay and finally, the credits moment because we respect the source 🫶 this whole thing lives in ./drivers/gpu/drm/i915, dated October 2026 in the Kernel API Manual. go forth and insert those nodes bestie, you're gonna ate 💖✨🎀🦋

📦 where this page comes from