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

["Gary Guo" <gary@garyguo.net>]

On Sat Mar 21, 2026 at 5:27 PM GMT, Danilo Krummrich wrote:
> 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.

Thinking about this a bit more, instead of creating new separate types, we can
probably just have multiple flavour/kind of `Coherent`, and we default to the
most common one.

Something like

pub struct Normal;
pub struct NoMapping;

struct Coherent<T: KnonwSize + ?Sized, Kind = Normal> {
    ...
}

Where for the common functions, they're implemented on `Coherent<T, Kind>` while
the ones that require CPU mapping have `impl Coherent<T>`.

The benefit is that there's no code duplication. Also, you could also implement
`Io` but leave out all `IoCapable` impls, so you may do I/O projections on
these and be able to get offseted DMA addresses without having to do manual
computation.

Best,
Gary

>
> 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,
> +}
> +