pub struct Dma { /* private fields */ }Expand description
A physically-contiguous DMA arena granted to a driver (e.g. via
crate::ServiceContext::dma_region). The CPU accesses it through base, the device through
phys. Both views cover the same len bytes one-to-one.
SEC-28 (SMP-port contract, kernel/src/arch/CLAUDE.md): this wrapper does NO cache maintenance.
That is correct only because of how each port maps the arena (DMA_ARENA_UNCACHED): x86 maps it
cacheable, its DMA being coherent; arm32 and aarch64, whose DMA is not, map it UNCACHED, which is
their answer to SEC-28; riscv64 maps it cacheable. A port whose DMA is not coherent must map it
uncached too, or add maintenance here - else the CPU and the device can see stale copies.
Implementations§
Source§impl Dma
impl Dma
Sourcepub fn phys_base(&self) -> u64
pub fn phys_base(&self) -> u64
Physical base address - program this (plus offsets) into the controller.
Sourcepub fn zero(&self)
pub fn zero(&self)
Zero the whole arena.
Deliberately not write_bytes. That lowers to memset, and a memset is free to reach
for whatever the ISA makes fastest - unaligned stores, cache-line zeroing hints (AArch64’s
DC ZVA), non-temporal stores. Every one of those is legal on the Normal cacheable memory
x86 maps this arena as, and every one of them is a fault on the Device memory a
non-coherent port maps it as instead (DMA_ARENA_UNCACHED, the SEC-28 answer): Device-nGnRnE
forbids unaligned access outright and cache maintenance by address on it is not meaningful.
So the clear is an explicit aligned 64-bit volatile loop, which is the one shape that is correct on both. The arena is page-based (a whole number of 4 KiB frames at a page-aligned VA), so the fast path always applies; the byte tail exists only so this function is total rather than silently leaving a remainder, and it cannot run on a real grant.
volatile matters as much as the alignment: an ordinary store loop over Device memory is
something the optimiser may merge back into a memset call, which would reintroduce exactly
what this avoids.
Sourcepub fn read16(&self, off: usize) -> u16
pub fn read16(&self, off: usize) -> u16
Read a 16-bit value at byte offset off (off + 2 <= len; any alignment - see ALIGNMENT above).
Sourcepub fn read32(&self, off: usize) -> u32
pub fn read32(&self, off: usize) -> u32
Read a 32-bit value at byte offset off (off + 4 <= len; any alignment - see ALIGNMENT above).
Sourcepub fn write32(&self, off: usize, val: u32)
pub fn write32(&self, off: usize, val: u32)
Write a 32-bit value at byte offset off (off + 4 <= len; any alignment - see ALIGNMENT above).
Sourcepub fn write8(&self, off: usize, val: u8)
pub fn write8(&self, off: usize, val: u8)
Write an 8-bit value at byte offset off (off < len). For byte-granular
device structures (e.g. an e1000 TX descriptor’s command byte, or frame bytes).
Sourcepub fn write16(&self, off: usize, val: u16)
pub fn write16(&self, off: usize, val: u16)
Write a 16-bit value at byte offset off (off + 2 <= len; any alignment - see ALIGNMENT above).