i915_gem_mmap_gtt_version(9)

💅 i915_gem_mmap_gtt_version — the Kernel API Manual glow-up ✨

okay bestie, so this page is called i915_gem_mmap_gtt_version and it lives in the Kernel API Manual, and it's basically the receipts of how the GTT mmap interface grew up over time 🎀

---

✨ SYNOPSIS ✨

int i915_gem_mmap_gtt_version (void );

---

🫶 ARGUMENTS 🫶

• void — no arguments, babes. nothing. nada. she takes zero input and still serves 💅

---

🌸 DESCRIPTION 🌸

so here's the whole ✨history✨ of the GTT mmap interface, told in versions, and honestly it's giving character development:

• 0 — Everything had to fit into the GTT. Both parties of a memcpy had to aligned and suitable for fencing, and still fit into the available mappable space left by the pinned display objects. A classic problem we called the page-fault-of-doom where we would ping-pong between two objects that could not fit inside the GTT and so the memcpy would page one object in at the expense of the other between every single byte. 😭 literally the worst era, no cap.
• 1 — Objects can be any size, and have any compatible fencing (X, Y, or none as set via i915_gem_set_tiling [DRM_I915_GEM_SET_TILING]). If the object is too large for the available space (or simply too large for the mappable aperture!), a view is created instead and faulted into userspace. (This view is aligned and sized appropriately for fenced access.) iconic behaviour, honestly 👑
• 2 — Recognise WC as a separate cache domain so that we can flush the delayed writes via GTT before performing direct access via WC. we love a clean flush 🧚
• 3 — Remove implicit set-domain(GTT) and synchronisation on initial pagefault; swapin remains transparent. she's subtle now, we stan 🌸
• 4 — Support multiple fault handlers per object depending on object's backing storage (a.k.a. MMAP_OFFSET). options, options, options 💅
• 5 — Support multiple partial mmaps (mmap part of BO + unmap a offset, multiple times with different size and offset). flexible queen 🦋

---

🚫 Restrictions 🚫

• snoopable objects cannot be accessed via the GTT. It can cause machine hangs on some architectures, corruption on others. An attempt to service a GTT page fault from a snoopable object will generate a SIGBUS. 💀 like, do not.
• the object must be able to fit into RAM (physical memory, though no limited to the mappable aperture).

---

🙈 Caveats 🙈

• a new GTT page fault will synchronize rendering from the GPU and flush all data to system memory. Subsequent access will not be synchronized. so, y'know, the first one's on the house, the rest do NOT come with a guarantee 🫶
• all mappings are revoked on runtime device suspend. bye bye mappings 👋
• there are only 8, 16 or 32 fence registers to share between all users (older machines require fence register for display and blitter access as well). Contention of the fence registers will cause the previous users to be unmapped and any new access will generate new page faults. sharing is caring but there's literally only so much to go around 😭
• running out of memory while servicing a fault may generate a SIGBUS, rather than the expected SIGSEGV. plot twist nobody asked for 💀

lowkey read the caveats twice, bestie. they're not decorative 🌈

---

🌈 SEE ALSO 🌈

• Kernel file ./drivers/gpu/drm/i915/gem/i915_gem_mman.c
• i915_gem_mmap_ioctl(9)
• i915_gem_mmap_offset_ioctl(9)

---

and that's the whole page, bestie 💖 shoutout to the source, ./drivers/gpu/drm/i915/gem, and to October 2026 for the timestamp — we love a documented queen 🎀✨ periodt.