xe_pagemap_find_or_create(9)

💅 xe_pagemap_find_or_create(9)

okay bestie, so this is a page straight out of the Kernel API Manual — yep, the Kernel API Manual, we're fancy now — and it's all about xe_pagemap_find_or_create: the little function that goes "hmm, do I already have a struct xe_pagemap for this tile, or do I need to make one?" 🎀 She's a finder and a maker. Multitasking icon. ✨

---

🌸 NAME 🌸

xe_pagemap_find_or_create — find or create a struct xe_pagemap. that's it, that's the whole job, and she does it flawlessly 💅

---

✨ SYNOPSIS ✨

struct xe_pagemap * xe_pagemap_find_or_create (struct xe_device *xe ,
       struct drm_pagemap_cache *cache , struct xe_vram_region *vr );

like, look at her signature. three arguments, one pointer back. no cap, it's giving main character energy 🫶

---

🦋 ARGUMENTS 🦋

• xe — the xe device. the whole vibe, the big picture 💖
• cache — the struct xe_pagemap_cache. this is the lil stash where pagemaps hang out when they're not being used.
• vr — the VRAM region. where the memory actually lives, bestie.

---

🔥 DESCRIPTION 🔥

okay so here's the whole flow, and honestly it's so clean:

1. check if there's already a used xe_pagemap for this tile — and if there is, just return it. done. no drama, no extra work. slay 💅
2. if not, check if there's a cached xe_pagemap for this tile. if there is, we cancel its destruction, re-initialize it, and return it. literally resurrecting her. iconic behavior 🧚✨
3. finally, if there's no cached and no already-used pagemap? we create one and register it in the tile's pagemap cache. brand new baby pagemap, welcome to the world 🎀

also a lil heads up: this function is typically called from within an IOCTL, and waits are therefore carried out interruptible if possible. so like, keep that in mind, she's polite about waiting 🙈

---

🌈 RETURN 🌈

a pointer to a struct xe_pagemap if it all works out 💖 — or an error pointer on failure 😭. that's the whole deal.

---

⭐ SEE ALSO ⭐

the whole friend group, fr fr:

• Kernel file ./drivers/gpu/drm/xe/xe_svm.c
• drm_pagemap reference-counting in xe:(9)
• xe_svm_init(9)
• xe_svm_close(9)
• xe_svm_fini(9)
• xe_svm_range_validate(9)
• xe_svm_find_vma_start(9)
• xe_svm_range_needs_migrate_to_vram(9)
• xe_svm_handle_pagefault(9)
• xe_svm_has_mapping(9)
• xe_svm_unmap_address_range(9)
• xe_svm_bo_evict(9)
• xe_svm_range_find_or_insert(9)
• xe_svm_range_get_pages(9)
• xe_svm_ranges_zap_ptes_in_range(9)
• xe_vma_resolve_pagemap(9)
• xe_svm_alloc_vram(9)
• xe_pagemap_create(9)
• xe_pagemap_shrinker_create(9)
• xe_pagemap_cache_create(9)
• xe_drm_pagemap_from_fd(9)
• xe_svm_flush(9)

---

and that's the page!! 💜 this one lives over in ./drivers/gpu/drm/xe and it's dated October 2026 — so yeah, she's from the future, we don't ask questions 🦋👑 mwah, go read the other nine-ers, ily, bye!! 🌸