PAGETABLE BUILDING(9)

💅 Pagetable building (9) 💅

okay so bestie, welcome to the Kernel API Manual — section 9, pagetable building, and honestly? it's giving "lowkey complicated but we're gonna slay it together" 🫶 grab a lil snack, we're learning page-tables.

---

✨ DESCRIPTION ✨

Real quick, terminology check 📝 — below, we use the term "page-table" for both:

• page-directories — the ones holding pointers to lower level page-directories or page-tables, and
• level 0 page-tables — the ones that contain only page-table-entries pointing to memory pages.

periodt. that's the whole naming vibe.

So like, when you're inserting an address range into an already existing page-table tree, you'll typically end up with two little groups of page-tables:

1. a set that's shared with other address ranges, and
2. a set that's private to this address range.

The shared set can be at most two per level 🎀 and ngl, those can't be updated immediately, because their entries may still be in use by the gpu for other mappings 😭 so instead of just yolo-ing writes in, we stage those insertions by adding insertion data into struct xe_vm_pgtable_update structures. iconic, honestly.

That data — the subtrees for the cpu and the page-table-entries for the gpu — gets added in a separate commit step ✨:

• CPU-data is committed while still under the vm lock, the object lock and, for userptr, the notifier lock in read mode.
• GPU async data is committed either by the GPU or by the CPU after fulfilling the relevant dependencies 👑.

For non-shared page-tables — and, fr fr, also for shared ones that aren't existing at the time of staging — we add the data in-place without the special update structures 💅.

And here's the cute lil plot twist 🦋: this private part of the page-table tree stays disconnected from the vm page-table tree until data is committed to the shared page tables of the vm tree in the commit phase. the way that it just chills there unlinked until commit time? main character energy, no cap.

⚠️ heads up bestie: this is all about staging + commit phases. don't be out here assuming the private tree is live before the commit phase — it is not, and the shared entries cannot be updated immediately. that's the whole reason this dance exists 💀

---

🌈 SEE ALSO 🌈

Kernel file ./drivers/gpu/drm/xe/xe_pt.c, plus the whole friend group 🫶:

• xe_pt_create(9)
• xe_pt_populate_empty(9)
• xe_pt_shift(9)
• xe_pt_destroy(9)
• xe_pt_clear(9)
• struct xe_pt_stage_bind_walk(9)
• xe_pt_stage_bind(9)
• xe_pt_nonshared_offsets(9)
• xe_pt_zap_ptes(9)
• xe_pt_zap_ptes_range(9)
• xe_pt_stage_unbind(9)
• xe_pt_update_ops_prepare(9)
• xe_pt_update_ops_run(9)
• xe_pt_update_ops_fini(9)
• xe_pt_update_ops_abort(9)

---

and that's the page, bestie 🎀 this lil drop of knowledge lives in ./drivers/gpu/drm/xe, dated October 2026. go forth and build pagetables, you absolute icon 💜✨