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

[Alexandre Courbot]

On Sun Mar 22, 2026 at 2:27 AM JST, 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.

nova-core's sysmem flush memory page would be a prime candidate to use
this, I'll add this patch as a dependency to [1] and use it.

Reviewed-by: Alexandre Courbot <acourbot@xxxxxxxxxx>

(one question below)

[1] https://lore.kernel.org/all/20260321-b4-nova-dma-removal-v1-0-5cf18a75ff64@xxxxxxxxxx/

>
> Signed-off-by: Danilo Krummrich <dakr@xxxxxxxxxx>
> ---
>  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`.

Quick question for my erudition: I understand all the invariants are
referred to by `drop`, but some of them (`size` notably) really read
more like doccomments. Do we need to be that exhaustive every time we
call a C API?