[PATCH 2/2] rust: dma: add CoherentHandle for DMA allocations without kernel mapping

Danilo Krummrich
2026-03-21T17:27:58Z

Add CoherentHandle, an opaque DMA allocation type for buffers that are
only ever accessed by hardware. Unlike Coherent<T>, it does not provide
CPU access to the allocated memory.

CoherentHandle implicitly sets DMA_ATTR_NO_KERNEL_MAPPING and stores the
value returned by dma_alloc_attrs() as an opaque handle
(NonNull<c_void>) rather than a typed pointer, since with this flag the
C API returns an opaque cookie (e.g. struct page *), not a CPU pointer
to the allocated memory.

Only the DMA bus address is exposed to drivers; the opaque handle is
used solely to free the allocation on drop.

This commit is for reference only; there is currently no in-tree user.

Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
rust/kernel/dma.rs | 119 +++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 119 insertions(+)

diff --git a/rust/kernel/dma.rs b/rust/kernel/dma.rs
index 9e0c9ff91cba..fa30793c798d 100644
--- a/rust/kernel/dma.rs
+++ b/rust/kernel/dma.rs
@@ -1011,6 +1011,125 @@ fn drop(&mut self) {
// can be sent to another thread.
unsafe impl<T: KnownSize + Send + ?Sized> Send for Coherent<T> {}

+/// An opaque DMA allocation without a kernel virtual mapping.
+///
+/// Unlike [`Coherent`], a `CoherentHandle` does not provide CPU access to the allocated memory.
+/// The allocation is always performed with `DMA_ATTR_NO_KERNEL_MAPPING`, meaning no kernel
+/// virtual mapping is created for the buffer. The value returned by the C API as the CPU
+/// address is an opaque handle used only to free the allocation.
+///
+/// This is useful for buffers that are only ever accessed by hardware.
+///
+/// # Invariants
+///
+/// - `cpu_handle` holds the opaque handle returned by `dma_alloc_attrs` with
+/// `DMA_ATTR_NO_KERNEL_MAPPING` set, and is only valid for passing back to `dma_free_attrs`.
+/// - `dma_handle` is the corresponding bus address for device DMA.
+/// - `size` is the allocation size in bytes as passed to `dma_alloc_attrs`.
+/// - `dma_attrs` contains the attributes used for the allocation, always including
+/// `DMA_ATTR_NO_KERNEL_MAPPING`.
+pub struct CoherentHandle {
+ dev: ARef<device::Device>,
+ dma_handle: DmaAddress,
+ cpu_handle: NonNull<c_void>,
+ size: usize,
+ dma_attrs: Attrs,
+}
+
+impl CoherentHandle {
+ /// Allocates `size` bytes of coherent DMA memory without creating a kernel virtual mapping.
+ ///
+ /// Additional DMA attributes may be passed via `dma_attrs`; `DMA_ATTR_NO_KERNEL_MAPPING` is
+ /// always set implicitly.
+ ///
+ /// Returns `EINVAL` if `size` is zero, `ENOMEM` if the allocation fails.
+ pub fn alloc_with_attrs(
+ dev: &device::Device<Bound>,
+ size: usize,
+ gfp_flags: kernel::alloc::Flags,
+ dma_attrs: Attrs,
+ ) -> Result<Self> {
+ if size == 0 {
+ return Err(EINVAL);
+ }
+
+ let dma_attrs = dma_attrs | Attrs(bindings::DMA_ATTR_NO_KERNEL_MAPPING);
+ let mut dma_handle = 0;
+ // SAFETY: `dev.as_raw()` is valid by the type invariant on `device::Device`.
+ let cpu_handle = unsafe {
+ bindings::dma_alloc_attrs(
+ dev.as_raw(),
+ size,
+ &mut dma_handle,
+ gfp_flags.as_raw(),
+ dma_attrs.as_raw(),
+ )
+ };
+
+ let cpu_handle = NonNull::new(cpu_handle).ok_or(ENOMEM)?;
+
+ // INVARIANT: `cpu_handle` is the opaque handle from a successful `dma_alloc_attrs` call
+ // with `DMA_ATTR_NO_KERNEL_MAPPING`, `dma_handle` is the corresponding DMA address,
+ // and we hold a refcounted reference to the device.
+ Ok(Self {
+ dev: dev.into(),
+ dma_handle,
+ cpu_handle,
+ size,
+ dma_attrs,
+ })
+ }
+
+ /// Allocates `size` bytes of coherent DMA memory without creating a kernel virtual mapping.
+ #[inline]
+ pub fn alloc(
+ dev: &device::Device<Bound>,
+ size: usize,
+ gfp_flags: kernel::alloc::Flags,
+ ) -> Result<Self> {
+ Self::alloc_with_attrs(dev, size, gfp_flags, Attrs(0))
+ }
+
+ /// Returns the DMA handle for this allocation.
+ ///
+ /// This address can be programmed into device hardware for DMA access.
+ #[inline]
+ pub fn dma_handle(&self) -> DmaAddress {
+ self.dma_handle
+ }
+
+ /// Returns the size in bytes of this allocation.
+ #[inline]
+ pub fn size(&self) -> usize {
+ self.size
+ }
+}
+
+impl Drop for CoherentHandle {
+ fn drop(&mut self) {
+ // SAFETY: All values are valid by the type invariants on `CoherentHandle`.
+ // `cpu_handle` is the opaque handle from `dma_alloc_attrs` and is passed back unchanged.
+ unsafe {
+ bindings::dma_free_attrs(
+ self.dev.as_raw(),
+ self.size,
+ self.cpu_handle.as_ptr(),
+ self.dma_handle,
+ self.dma_attrs.as_raw(),
+ )
+ }
+ }
+}
+
+// SAFETY: `CoherentHandle` only holds a device reference, a DMA handle, an opaque CPU handle,
+// and a size. None of these are tied to a specific thread.
+unsafe impl Send for CoherentHandle {}
+
+// SAFETY: `CoherentHandle` provides no CPU access to the underlying allocation. The only
+// operations on `&CoherentHandle` are reading the DMA handle and size, both of which are
+// plain `Copy` values.
+unsafe impl Sync for CoherentHandle {}
+
/// Reads a field of an item from an allocated region of structs.
///
/// The syntax is of the form `kernel::dma_read!(dma, proj)` where `dma` is an expression evaluating
--
2.53.0