[PATCH 6/9] rust: dma: add dma_read! and dma_write! macros

[Eliot Courtney <ecourtney@nvidia.com>]

Add dma_read! and dma_write! macros using the new infallible methods
on CoherentArray.

Signed-off-by: Eliot Courtney <ecourtney@nvidia.com>
---
 rust/kernel/dma.rs | 103 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)

diff --git a/rust/kernel/dma.rs b/rust/kernel/dma.rs
index e4bca7a18ac1..f3920f74583a 100644
--- a/rust/kernel/dma.rs
+++ b/rust/kernel/dma.rs
@@ -811,6 +811,24 @@ pub unsafe fn as_slice_mut<const OFFSET: usize, const COUNT: usize>(&mut self) -
             )
         };
     }
+
+    /// Returns a pointer to an element from the region with bounds checking. `OFFSET` is in
+    /// units of `T`, not the number of bytes.
+    ///
+    /// Public but hidden since it should only be used from [`dma_read`] and [`dma_write`] macros.
+    #[doc(hidden)]
+    pub fn ptr_at<const OFFSET: usize>(&self) -> *mut T {
+        build_assert!(
+            OFFSET < N,
+            "Index out of bounds when accessing CoherentArray"
+        );
+        // SAFETY:
+        // - The pointer is valid due to type invariant on `CoherentAllocation`
+        // and we've just checked that the range and index is within bounds.
+        // - `OFFSET` can't overflow since it is smaller than `N` and we've checked
+        // that `N` won't overflow early in the constructor.
+        unsafe { self.cpu_addr.as_ptr().add(OFFSET) }
+    }
 }
 
 /// Note that the device configured to do DMA must be halted before this object is dropped.
@@ -927,3 +945,88 @@ macro_rules! try_dma_write {
         $crate::try_dma_write!($($dma).*, $idx, $($field)*)
     }};
 }
+
+/// Reads a field of an item from a [`CoherentArray`] with compile-time bounds checking.
+///
+/// # Examples
+///
+/// ```
+/// use kernel::device::Device;
+/// use kernel::dma::{attrs::*, CoherentArray};
+///
+/// struct MyStruct { field: u32, }
+///
+/// // SAFETY: All bit patterns are acceptable values for `MyStruct`.
+/// unsafe impl kernel::transmute::FromBytes for MyStruct{};
+/// // SAFETY: Instances of `MyStruct` have no uninitialized portions.
+/// unsafe impl kernel::transmute::AsBytes for MyStruct{};
+///
+/// # fn test(alloc: &kernel::dma::CoherentArray<MyStruct, 3>) {
+/// let whole = kernel::dma_read!(alloc[2]);
+/// let field = kernel::dma_read!(alloc[1].field);
+/// # }
+/// ```
+#[macro_export]
+macro_rules! dma_read {
+    ($dma:expr, $idx:expr, $($field:tt)*) => {{
+        (|| {
+            let ptr = $crate::dma::CoherentArray::ptr_at::<$idx>(&$dma);
+            // SAFETY: `ptr_at` ensures that `ptr` is always a valid pointer and can be
+            // dereferenced. The compiler also further validates the expression on whether `field`
+            // is a member of `ptr` when expanded by the macro.
+            unsafe {
+                let ptr_field = ::core::ptr::addr_of!((*ptr) $($field)*);
+                $crate::dma::CoherentAllocation::field_read(&$dma, ptr_field)
+            }
+        })()
+    }};
+    ($($dma:ident).* [ $idx:expr ] $($field:tt)* ) => {
+        $crate::dma_read!($($dma).*, $idx, $($field)*)
+    };
+}
+
+/// Writes to a field of an item in a [`CoherentArray`] with compile-time bounds checking.
+///
+/// # Examples
+///
+/// ```
+/// use kernel::device::Device;
+/// use kernel::dma::{attrs::*, CoherentArray};
+///
+/// struct MyStruct { member: u32, }
+///
+/// // SAFETY: All bit patterns are acceptable values for `MyStruct`.
+/// unsafe impl kernel::transmute::FromBytes for MyStruct{};
+/// // SAFETY: Instances of `MyStruct` have no uninitialized portions.
+/// unsafe impl kernel::transmute::AsBytes for MyStruct{};
+///
+/// # fn test(alloc: &kernel::dma::CoherentArray<MyStruct, 3>) {
+/// kernel::dma_write!(alloc[2].member = 0xf);
+/// kernel::dma_write!(alloc[1] = MyStruct { member: 0xf });
+/// # }
+/// ```
+#[macro_export]
+macro_rules! dma_write {
+    ($dma:expr, $idx:expr, = $val:expr) => {
+        (|| {
+            let ptr = $crate::dma::CoherentArray::ptr_at::<$idx>(&$dma);
+            // SAFETY: `ptr_at` ensures that `ptr` is always a valid ptr.
+            unsafe { $crate::dma::CoherentAllocation::field_write(&$dma, ptr, $val) }
+        })()
+    };
+    ($dma:expr, $idx:expr, $(.$field:ident)* = $val:expr) => {
+        (|| {
+            let ptr = $crate::dma::CoherentArray::ptr_at::<$idx>(&$dma);
+            // SAFETY: `ptr_at` ensures that `ptr` is always a valid pointer and can be
+            // dereferenced. The compiler also further validates the expression on whether `field`
+            // is a member of `ptr` when expanded by the macro.
+            unsafe {
+                let ptr_field = ::core::ptr::addr_of_mut!((*ptr) $(.$field)*);
+                $crate::dma::CoherentAllocation::field_write(&$dma, ptr_field, $val)
+            }
+        })()
+    };
+    ($($dma:ident).* [ $idx:expr ] $($field:tt)* ) => {{
+        $crate::dma_write!($($dma).*, $idx, $($field)*)
+    }};
+}

-- 
2.52.0