[PATCH v2 3/8] rust: dma: add zeroed constructor to `Coherent`

Danilo Krummrich
2026-03-20T19:46:56Z

From: Gary Guo <gary@garyguo.net>

These constructors create a coherent container of a single object
instead of slice. They are named `zeroed` and `zeroed_with_attrs` to
emphasis that they are created initialized zeroed. It is intended that
there'll be new constructors that take `PinInit` instead of zeroing.

Signed-off-by: Gary Guo <gary@garyguo.net>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
rust/kernel/dma.rs | 81 ++++++++++++++++++++++++++++++++++++----
samples/rust/rust_dma.rs | 8 ++--
2 files changed, 77 insertions(+), 12 deletions(-)

diff --git a/rust/kernel/dma.rs b/rust/kernel/dma.rs
index ff3e147f1a23..db645b01bdd0 100644
--- a/rust/kernel/dma.rs
+++ b/rust/kernel/dma.rs
@@ -47,7 +47,7 @@ pub trait Device: AsRef<device::Device<Core>> {
/// # Safety
///
/// This method must not be called concurrently with any DMA allocation or mapping primitives,
- /// such as [`CoherentAllocation::alloc_attrs`].
+ /// such as [`Coherent::zeroed`].
unsafe fn dma_set_mask(&self, mask: DmaMask) -> Result {
// SAFETY:
// - By the type invariant of `device::Device`, `self.as_ref().as_raw()` is valid.
@@ -64,7 +64,7 @@ unsafe fn dma_set_mask(&self, mask: DmaMask) -> Result {
/// # Safety
///
/// This method must not be called concurrently with any DMA allocation or mapping primitives,
- /// such as [`CoherentAllocation::alloc_attrs`].
+ /// such as [`Coherent::zeroed`].
unsafe fn dma_set_coherent_mask(&self, mask: DmaMask) -> Result {
// SAFETY:
// - By the type invariant of `device::Device`, `self.as_ref().as_raw()` is valid.
@@ -83,7 +83,7 @@ unsafe fn dma_set_coherent_mask(&self, mask: DmaMask) -> Result {
/// # Safety
///
/// This method must not be called concurrently with any DMA allocation or mapping primitives,
- /// such as [`CoherentAllocation::alloc_attrs`].
+ /// such as [`Coherent::zeroed`].
unsafe fn dma_set_mask_and_coherent(&self, mask: DmaMask) -> Result {
// SAFETY:
// - By the type invariant of `device::Device`, `self.as_ref().as_raw()` is valid.
@@ -102,7 +102,7 @@ unsafe fn dma_set_mask_and_coherent(&self, mask: DmaMask) -> Result {
/// # Safety
///
/// This method must not be called concurrently with any DMA allocation or mapping primitives,
- /// such as [`CoherentAllocation::alloc_attrs`].
+ /// such as [`Coherent::zeroed`].
unsafe fn dma_set_max_seg_size(&self, size: u32) {
// SAFETY:
// - By the type invariant of `device::Device`, `self.as_ref().as_raw()` is valid.
@@ -202,12 +202,12 @@ pub const fn value(&self) -> u64 {
///
/// ```
/// # use kernel::device::{Bound, Device};
-/// use kernel::dma::{attrs::*, CoherentAllocation};
+/// use kernel::dma::{attrs::*, Coherent};
///
/// # fn test(dev: &Device<Bound>) -> Result {
/// let attribs = DMA_ATTR_FORCE_CONTIGUOUS | DMA_ATTR_NO_WARN;
-/// let c: CoherentAllocation<u64> =
-/// CoherentAllocation::alloc_attrs(dev, 4, GFP_KERNEL, attribs)?;
+/// let c: Coherent<[u64]> =
+/// Coherent::zeroed_slice_with_attrs(dev, 4, GFP_KERNEL, attribs)?;
/// # Ok::<(), Error>(()) }
/// ```
#[derive(Clone, Copy, PartialEq)]
@@ -492,7 +492,6 @@ pub unsafe fn field_write<F: AsBytes>(&self, field: *mut F, val: F) {

impl<T: AsBytes + FromBytes> Coherent<T> {
/// Allocates a region of `T` of coherent memory.
- #[expect(unused)]
fn alloc_with_attrs(
dev: &device::Device<Bound>,
gfp_flags: kernel::alloc::Flags,
@@ -529,6 +528,35 @@ fn alloc_with_attrs(
})
}

+ /// Allocates a region of type `T` of coherent memory.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// # use kernel::device::{Bound, Device};
+ /// use kernel::dma::{attrs::*, Coherent};
+ ///
+ /// # fn test(dev: &Device<Bound>) -> Result {
+ /// let c: Coherent<[u64; 4]> =
+ /// Coherent::zeroed_with_attrs(dev, GFP_KERNEL, DMA_ATTR_NO_WARN)?;
+ /// # Ok::<(), Error>(()) }
+ /// ```
+ #[inline]
+ pub fn zeroed_with_attrs(
+ dev: &device::Device<Bound>,
+ gfp_flags: kernel::alloc::Flags,
+ dma_attrs: Attrs,
+ ) -> Result<Self> {
+ Self::alloc_with_attrs(dev, gfp_flags | __GFP_ZERO, dma_attrs)
+ }
+
+ /// Performs the same functionality as [`Coherent::zeroed_with_attrs`], except the
+ /// `dma_attrs` is 0 by default.
+ #[inline]
+ pub fn zeroed(dev: &device::Device<Bound>, gfp_flags: kernel::alloc::Flags) -> Result<Self> {
+ Self::zeroed_with_attrs(dev, gfp_flags, Attrs(0))
+ }
+
/// Allocates a region of `[T; len]` of coherent memory.
fn alloc_slice_with_attrs(
dev: &device::Device<Bound>,
@@ -572,6 +600,43 @@ fn alloc_slice_with_attrs(
dma_attrs,
})
}
+
+ /// Allocates a zeroed region of type `T` of coherent memory.
+ ///
+ /// Unlike `Coherent::<[T; N]>::zeroed_with_attrs`, `Coherent::<T>::zeroed_slices` support
+ /// a runtime length.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// # use kernel::device::{Bound, Device};
+ /// use kernel::dma::{attrs::*, Coherent};
+ ///
+ /// # fn test(dev: &Device<Bound>) -> Result {
+ /// let c: Coherent<[u64]> =
+ /// Coherent::zeroed_slice_with_attrs(dev, 4, GFP_KERNEL, DMA_ATTR_NO_WARN)?;
+ /// # Ok::<(), Error>(()) }
+ /// ```
+ #[inline]
+ pub fn zeroed_slice_with_attrs(
+ dev: &device::Device<Bound>,
+ len: usize,
+ gfp_flags: kernel::alloc::Flags,
+ dma_attrs: Attrs,
+ ) -> Result<Coherent<[T]>> {
+ Coherent::alloc_slice_with_attrs(dev, len, gfp_flags | __GFP_ZERO, dma_attrs)
+ }
+
+ /// Performs the same functionality as [`Coherent::zeroed_slice_with_attrs`], except the
+ /// `dma_attrs` is 0 by default.
+ #[inline]
+ pub fn zeroed_slice(
+ dev: &device::Device<Bound>,
+ len: usize,
+ gfp_flags: kernel::alloc::Flags,
+ ) -> Result<Coherent<[T]>> {
+ Self::zeroed_slice_with_attrs(dev, len, gfp_flags, Attrs(0))
+ }
}

impl<T> Coherent<[T]> {
diff --git a/samples/rust/rust_dma.rs b/samples/rust/rust_dma.rs
index ce39b5545097..314ef51cd86c 100644
--- a/samples/rust/rust_dma.rs
+++ b/samples/rust/rust_dma.rs
@@ -6,7 +6,7 @@

use kernel::{
device::Core,
- dma::{CoherentAllocation, DataDirection, Device, DmaMask},
+ dma::{Coherent, DataDirection, Device, DmaMask},
page, pci,
prelude::*,
scatterlist::{Owned, SGTable},
@@ -16,7 +16,7 @@
#[pin_data(PinnedDrop)]
struct DmaSampleDriver {
pdev: ARef<pci::Device>,
- ca: CoherentAllocation<MyStruct>,
+ ca: Coherent<[MyStruct]>,
#[pin]
sgt: SGTable<Owned<VVec<u8>>>,
}
@@ -64,8 +64,8 @@ fn probe(pdev: &pci::Device<Core>, _info: &Self::IdInfo) -> impl PinInit<Self, E
// SAFETY: There are no concurrent calls to DMA allocation and mapping primitives.
unsafe { pdev.dma_set_mask_and_coherent(mask)? };

- let ca: CoherentAllocation<MyStruct> =
- CoherentAllocation::alloc_coherent(pdev.as_ref(), TEST_VALUES.len(), GFP_KERNEL)?;
+ let ca: Coherent<[MyStruct]> =
+ Coherent::zeroed_slice(pdev.as_ref(), TEST_VALUES.len(), GFP_KERNEL)?;

for (i, value) in TEST_VALUES.into_iter().enumerate() {
kernel::dma_write!(ca, [i]?, MyStruct::new(value.0, value.1));
--
2.53.0