Merge #226

226: Fast double-buffered DMA r=richardeoin a=jordens

When handling multiple double-buffered DMA streams the current safe-and-universal API becomes slower than necessary.
This adds `next_dbm_transfer_with()`, a closure-based API to the inactive buffer, without address poisoning, compiler fences, data barriers, or buffer swapping. For some applications this reduces the overhead significantly (speedup of 5).

Co-authored-by: Robert Jördens <[email protected]>

Author: bors[bot]

src/dma/bdma.rs

@@ -288,11 +288,18 @@ macro_rules! bdma_stream {
                 }
 
                 #[inline(always)]
-                fn clear_transfer_complete_interrupt(&mut self) {
+                fn clear_transfer_complete_flag(&mut self) {
                     //NOTE(unsafe) Atomic write with no side-effects and we only access the bits
                     // that belongs to the StreamX
                     let dma = unsafe { &*I::ptr() };
                     dma.$ifcr.write(|w| w.$tcif().set_bit());
+                }
+
+                #[inline(always)]
+                fn clear_transfer_complete_interrupt(&mut self) {
+                    self.clear_transfer_complete_flag();
+                    //NOTE(unsafe) Atomic read with no side-effects.
+                    let dma = unsafe { &*I::ptr() };
                     let _ = dma.$isr.read();
                     let _ = dma.$isr.read(); // Delay 2 peripheral clocks
                 }

src/dma/dma.rs

@@ -369,11 +369,18 @@ macro_rules! dma_stream {
                 }
 
                 #[inline(always)]
-                fn clear_transfer_complete_interrupt(&mut self) {
+                fn clear_transfer_complete_flag(&mut self) {
                     //NOTE(unsafe) Atomic write with no side-effects and we only access the bits
                     // that belongs to the StreamX
                     let dma = unsafe { &*I::ptr() };
                     dma.$ifcr.write(|w| w.$tcif().set_bit());
+                }
+
+                #[inline(always)]
+                fn clear_transfer_complete_interrupt(&mut self) {
+                    self.clear_transfer_complete_flag();
+                    //NOTE(unsafe) Atomic read with no side-effects.
+                    let dma = unsafe { &*I::ptr() };
                     let _ = dma.$isr.read();
                     let _ = dma.$isr.read(); // Delay 2 peripheral clocks
                 }

src/dma/mod.rs

@@ -46,6 +46,8 @@ pub enum DMAError {
     NotReady,
     /// The user provided a buffer that is not big enough while double buffering.
     SmallBuffer,
+    /// DMA started transfer on the inactive buffer while the user was processing it.
+    Overflow,
 }
 
 /// Possible DMA's directions.
@@ -602,6 +604,48 @@ macro_rules! db_transfer_def {
                 Ok((buf, current, last_remaining))
             }
 
+            /// Wait for the transfer of the currently active buffer to complete,
+            /// then call a function on the now inactive buffer and acknowledge the
+            /// transfer complete flag.
+            ///
+            /// NOTE(panic): This will panic then used in single buffer mode (not DBM).
+            ///
+            /// NOTE(unsafe): Memory safety is not guaranteed.
+            /// The user must ensure that the user function called on the inactive
+            /// buffer completes before the running DMA transfer of the active buffer
+            /// completes. If the DMA wins the race to the inactive buffer
+            /// a `DMAError::Overflow` is returned but processing continues.
+            ///
+            /// NOTE(fence): The user function must ensure buffer access ordering
+            /// against the flag accesses. Call
+            /// `core::sync::atomic::fence(core::sync::atomic::Ordering::SeqCst)`
+            /// before and after accessing the buffer.
+            pub unsafe fn next_dbm_transfer_with<F, T>(
+                &mut self,
+                func: F,
+            ) -> Result<T, DMAError>
+            where
+                F: FnOnce(&mut BUF, CurrentBuffer) -> T,
+            {
+                while !STREAM::get_transfer_complete_flag() { }
+                self.stream.clear_transfer_complete_flag();
+
+                // NOTE(panic): Panic if stream not configured in double buffer mode.
+                let inactive = STREAM::get_inactive_buffer().unwrap();
+
+                // This buffer is inactive now and can be accessed.
+                // NOTE(panic): We always hold ownership in lieu of the DMA peripheral.
+                let buf = self.buf[inactive as usize].as_mut().unwrap();
+
+                let result = func(buf, inactive);
+
+                if STREAM::get_transfer_complete_flag() {
+                    Err(DMAError::Overflow)
+                } else {
+                    Ok(result)
+                }
+            }
+
             /// Clear half transfer interrupt (htif) for the DMA stream.
             #[inline(always)]
             pub fn clear_half_transfer_interrupt(&mut self) {

src/dma/traits.rs

@@ -32,7 +32,13 @@ pub trait Stream: Sealed {
     /// Clear all interrupts for the DMA stream.
     fn clear_interrupts(&mut self);
 
-    /// Clear transfer complete interrupt (tcif) for the DMA stream.
+    /// Clear transfer complete interrupt flag (tcif) for the DMA stream
+    /// but do not insert artificial delays.
+    fn clear_transfer_complete_flag(&mut self);
+
+    /// Clear transfer complete interrupt (tcif) for the DMA stream and delay
+    /// to ensure the change has settled through the bridge, peripheral, and
+    /// synchronizers.
     fn clear_transfer_complete_interrupt(&mut self);
 
     /// Clear transfer error interrupt (teif) for the DMA stream.