ENUM DMA_RESV_USAGE(9)

💅 enum dma_resv_usage(9)

okay so this is a page from the Kernel API Manual — yes, the kernel has a manual, and yes, it has lore. buckle up bestie, we're learning how the fences attached to a dma_resv object get categorized 🎀

---

✨ NAME ✨

enum dma_resv_usage — literally the whole vibe check for how the fences from a dma_resv obj are used 🦋

---

🌸 SYNOPSIS 🌸

enum dma_resv_usage {
    DMA_RESV_USAGE_KERNEL ,
    DMA_RESV_USAGE_WRITE ,
    DMA_RESV_USAGE_READ ,
    DMA_RESV_USAGE_BOOKKEEP

};

---

👑 CONSTANTS 👑

⭐ DMA_RESV_USAGE_KERNEL

For in kernel memory management only.

This is strictly for stuff like copying or clearing memory with a DMA hardware engine, purely for the purpose of kernel memory management. that's it, that's the gig 🙈

Drivers always must wait for those fences before accessing the resource protected by the dma_resv object. always always, no cap. The only exception ever? when the resource is known to be locked down in place by pinning it previously. that's the one loophole, periodt.

💜 DMA_RESV_USAGE_WRITE

Implicit write synchronization.

Only used for userspace command submissions that add an implicit write dependency. nothing else, bestie 💅

🦋 DMA_RESV_USAGE_READ

Implicit read synchronization.

Only used for userspace command submissions that add an implicit read dependency. keep it that simple 🫶

🎀 DMA_RESV_USAGE_BOOKKEEP

No implicit sync.

This one's for submissions that simply do not want to participate in any implicit synchronization. not invited to the sync party, and honestly? fair 🌈

The most common cases are preemption fences, page table updates, TLB flushes, as well as explicitly synced user submissions.

and here's the glow-up: explicitly synced user submissions can be promoted to DMA_RESV_USAGE_READ or DMA_RESV_USAGE_WRITE as needed using dma_buf_import_sync_file — that's for when implicit synchronization should become necessary after initial adding of the fence. main character energy 🔥

---

🌼 DESCRIPTION 🌼

So this enum describes the different use cases for a dma_resv object and controls which fences are returned when queried. it's giving traffic controller for fences ⭐

An important fact — like, write this on your mirror important — is that there's the order

KERNEL<WRITE<READ<BOOKKEEP

and when the dma_resv object is asked for fences for one use case, the fences for the lower use case are returned as well. it's a package deal, you don't get to pick only one 💀

For example: when asking for WRITE fences, then the KERNEL fences are returned as well. Similar when asked for READ fences, then both WRITE and KERNEL fences are returned as well. they come as a set, iykyk ✨

Already used fences can be promoted — in the sense that a fence with DMA_RESV_USAGE_BOOKKEEP could become DMA_RESV_USAGE_READ by adding it again with this usage. But fences can never be degraded, in the sense that a fence with DMA_RESV_USAGE_WRITE could become DMA_RESV_USAGE_READ. nope, no take-backs, no downgrades, the upgrade is permanent 😭 💅

---

💖 SEE ALSO 💖

Kernel file ./include/linux/dma-resv.h

and then the whole squad, all of them, every single one: dma_resv_usage_rw(9), struct dma_resv(9), struct dma_resv_iter(9), dma_resv_iter_begin(9), dma_resv_iter_end(9), dma_resv_iter_usage(9), dma_resv_iter_is_restarted(9), dma_resv_for_each_fence_unlocked(9), dma_resv_for_each_fence(9), dma_resv_lock(9), dma_resv_lock_interruptible(9), dma_resv_lock_slow(9), dma_resv_lock_slow_interruptible(9), dma_resv_trylock(9), dma_resv_is_locked(9), dma_resv_locking_ctx(9), dma_resv_unlock(9)

---

anyway that's the page 🫶 this whole thing lives over in ./include/linux and it's dated October 2026 — so yeah, future knowledge, use it wisely 💜 🧚‍♀️