STRUCT DRM_GEM_VRAM_OBJECT(9)

👑 struct drm_gem_vram_object — GEM object backed by VRAM 💖

okay bestie so this is from the Kernel API Manual, and today's main character is struct drm_gem_vram_object — a GEM object whose whole thing is being backed by VRAM. no cap, she's iconic. ✨

---

🌸 SYNOPSIS 🌸

struct drm_gem_vram_object {
    struct ttm_buffer_object bo;
    struct iosys_map map;
    unsigned int vmap_use_count;
    struct ttm_placement placement;
    struct ttm_place placements[2];
 };

like, that's the whole struct. five members. she's lowkey efficient about it. 💅

---

🎀 Members 🎀

• bo — the TTM buffer object. the actual backbone of the situation. 🦋
• map — mapping information for bo. where the mapping tea lives.
• vmap_use_count — the reference count on the virtual address. and listen, the way this works is: the address are un-mapped when the count reaches zero. so when it hits 0, bestie's gone. periodt. 😭
• placement — TTM placement information. the supported placements are TTM_PL_VRAM and TTM_PL_SYSTEM, and yes those are the only two, don't come for me. 🫶
• placements — TTM placement information. (yes, plural. yes, she has both. we love a thorough queen. 👑)

---

🌈 Description 🌈

so struct drm_gem_vram_object represents a GEM object that is backed by VRAM. literally that's her job description. she can be used for simple framebuffer devices with dedicated memory — very much "small but mighty" energy. and here's the cute part: the buffer object can be evicted to system memory if video memory becomes scarce. so when VRAM gets crowded, she just… moves to system memory. adaptable. main character energy fr fr. ✨

now the important bit, because this is where people mess up — GEM VRAM objects perform reference counting for pin and mapping operations. so a buffer object that has been pinned N times with drm_gem_vram_pin must be unpinned N times with drm_gem_vram_unpin. N times in, N times out. balanced. symmetric. the way it should be. 🧚

the same applies to pairs of drm_gem_vram_kmap and drm_gem_vram_kunmap, as well as pairs of drm_gem_vram_vmap and drm_gem_vram_vunmap.

⚠️ okay real talk for a sec: these are pairs, bestie. if you pin N times you unpin N times. if you kmap you kunmap. if you vmap you vunmap. skip the other half and you've got leaked references and a very sad driver. don't do that to yourself. 💀

---

🦋 SEE ALSO 🦋

• Kernel file ./include/drm/drm_gem_vram_helper.h
• drm_gem_vram_of_bo(9)
• drm_gem_vram_of_gem(9)
• DRM_GEM_VRAM_PLANE_HELPER_FUNCS(9)
• DRM_GEM_VRAM_DRIVER(9)
• struct drm_vram_mm(9)
• drm_vram_mm_of_bdev(9)

like, go read those next. iykyk. 📚💜

---

okay that's the whole page!! 🎀 and for the receipts: this one lives under ./include/drm, dated October 2026, and the proper title is struct drm_gem_vram_object(9) — which is also literally the name we started with, so we've come full circle. slay. 🫶✨🌸