LRU SCAN ROSTER(9)

🦋 lru scan roster(9) 🦋

okay so hi bestie 💖 you've wandered into the Kernel API Manual, and today's main character is the lru scan roster — aka the DRM range allocator's whole scanning situation. ngl it's lowkey iconic once you get the vibe, so let's get into it ✨

---

🌸 NAME 🌸

lru scan roster — the scanning interfaces the DRM range allocator uses so GPUs can snag continuous allocations without evicting a million tiny objects for absolutely no reason 💅

---

💖 DESCRIPTION 💖

okay so picture this: very often GPUs need to have continuous allocations for a given object. so when you're evicting objects to make space for a new one, it is therefore not most efficient when we simply start to select all objects from the tail of an LRU until there's a suitable hole 🫠

especially for big objects, or nodes that otherwise have special allocation constraints — there's a good chance we evict lots of (smaller) objects unnecessarily. and bestie, that's giving wasteful 😭

the DRM range allocator supports this use-case through the scanning interfaces. here's the whole flow, step by step:

1. first a scan operation needs to be initialized with drm_mm_scan_init or drm_mm_scan_init_with_range. pick your fighter ✨
2. the driver adds objects to the roster — probably by walking an LRU list, but this can be freely implemented. no rules, just vibes 🦋
3. eviction candidates are added using drm_mm_scan_add_block until a suitable hole is found or there are no further evictable objects
4. eviction roster metadata is tracked in struct drm_mm_scan — that's where the whole roster's lore lives 📓

⚠️ okay this part is important bestie: the driver must walk through all objects again in exactly the reverse order to restore the allocator state. and note that while the allocator is used in the scan mode, no other operation is allowed. like, none. the allocator is booked and busy, do not interrupt 💀

finally, the driver evicts all objects selected in the scan (the ones where drm_mm_scan_remove_block reported true), and any overlapping nodes after color adjustment (drm_mm_scan_color_evict) 🎀

and now the complexity tea ☕ — adding and removing an object is O(1), and since freeing a node is also O(1), the overall complexity is O(scanned_objects) 🔥 so like the free stack, which needs to be walked before a scan operation even begins, this is linear in the number of objects. it doesn't seem to hurt too badly — and honestly? periodt 💅

---

🔗 SEE ALSO 🔗

• Kernel file ./drivers/gpu/drm/drm_mm.c Overview(9)
• DECLARE_NEXT_HOLE_ADDR(9)
• drm_mm_reserve_node(9)
• drm_mm_insert_node_in_range(9)
• drm_mm_remove_node(9)
• drm_mm_scan_init_with_range(9)
• drm_mm_scan_add_block(9)
• drm_mm_scan_remove_block(9)
• drm_mm_scan_color_evict(9)
• drm_mm_init(9)
• drm_mm_takedown(9)
• drm_mm_print(9)

---

and that's the whole page bestie 🫶 this little gem lives over in ./drivers/gpu/drm and is dated October 2026 — go off, kernel docs, we love to see it 🌈⭐💜