Use linked transfers for async+DMA sercom

Author: jbeaurivage

hal/src/dmac/channel/mod.rs

@@ -512,7 +512,7 @@ impl<Id: ChId> Channel<Id, Ready> {
         Ok(())
     }
 
-    /// Begin a [`Transfer`], without changing the channel's type to [`Busy`].
+    /// Begin a transfer, without changing the channel's type to [`Busy`].
     ///
     /// Also provides support for linked transfers via an optional `&mut
     /// DmacDescriptor`.
@@ -636,14 +636,57 @@ impl<Id: ChId> Channel<Id, ReadyFuture> {
         trig_src: TriggerSource,
         trig_act: TriggerAction,
     ) -> Result<(), super::Error>
+    where
+        S: super::Buffer,
+        D: super::Buffer<Beat = S::Beat>,
+    {
+        unsafe {
+            self.transfer_future_linked(&mut source, &mut dest, trig_src, trig_act, None)
+                .await
+        }
+    }
+
+    /// Begin an async transfer, without changing the channel's type to
+    /// [`Busy`].
+    ///
+    /// Also provides support for linked transfers via an optional `&mut
+    /// DmacDescriptor`.
+    ///
+    /// # Safety
+    ///
+    /// * This method does not check that the two provided buffers have
+    ///   compatible lengths. You must guarantee that:
+    ///   - Either `source` or `dest` has a buffer length of 1, or
+    ///   - Both buffers have the same length.
+    /// * You must ensure that the transfer is completed or stopped before
+    ///   returning the [`Channel`]. Doing otherwise breaks type safety, because
+    ///   a [`ReadyFuture`] channel would still be in the middle of a transfer.
+    /// * If the provided `linked_descriptor` is `Some` it must not be dropped
+    ///   until the transfer is completed or stopped.
+    /// * Additionnally, this function doesn't take `'static` buffers. Again,
+    ///   you must guarantee that the returned transfer has completed or has
+    ///   been stopped before giving up control of the underlying [`Channel`].
+    pub(crate) async unsafe fn transfer_future_linked<S, D>(
+        &mut self,
+        source: &mut S,
+        dest: &mut D,
+        trig_src: TriggerSource,
+        trig_act: TriggerAction,
+        linked_descriptor: Option<&mut DmacDescriptor>,
+    ) -> Result<(), super::Error>
     where
         S: super::Buffer,
         D: super::Buffer<Beat = S::Beat>,
     {
         super::Transfer::<Self, super::transfer::BufferPair<S, D>>::check_buffer_pair(
-            &source, &dest,
+            source, dest,
         )?;
-        unsafe { self.fill_descriptor(&mut source, &mut dest, false) };
+        unsafe {
+            self.fill_descriptor(source, dest, false);
+            if let Some(next) = linked_descriptor {
+                self.link_next(next as *mut _);
+            }
+        }
 
         self.disable_interrupts(
             InterruptFlags::new()

hal/src/sercom/dma.rs

@@ -651,20 +651,35 @@ pub(crate) mod async_dma {
     use super::*;
 
     /// Perform a SERCOM DMA read with a provided `&mut [T]`
-    pub(in super::super) async fn read_dma<T: Beat, S: Sercom>(
+    #[inline]
+    pub(in super::super) async fn read_dma<T, B, S>(
         channel: &mut impl AnyChannel<Status = ReadyFuture>,
         sercom_ptr: SercomPtr<T>,
-        words: &mut [T],
-    ) -> Result<(), Error> {
-        read_dma_buffer::<_, _, S>(channel, sercom_ptr, words).await
+        buf: &mut B,
+    ) -> Result<(), Error>
+    where
+        B: Buffer<Beat = T>,
+        T: Beat,
+        S: Sercom,
+    {
+        unsafe { read_dma_linked::<_, _, S>(channel, sercom_ptr, buf, None).await }
     }
 
-    /// Perform a SERCOM DMA read with a provided [`Buffer`]
+    /// Perform a SERCOM DMA read with a provided [`Buffer`], and add an
+    /// optional link to a next [`DmacDescriptor`] to support linked
+    /// transfers.
+    ///
+    /// # Safety
+    ///
+    /// You **must** guarantee that the DMA transfer is either stopped or
+    /// completed before giving back control of `channel` AND `buf`.
+    #[inline]
     #[hal_macro_helper]
-    pub(in super::super) async fn read_dma_buffer<T, B, S>(
+    pub(in super::super) async unsafe fn read_dma_linked<T, B, S>(
         channel: &mut impl AnyChannel<Status = ReadyFuture>,
-        sercom_ptr: SercomPtr<T>,
-        buf: B,
+        mut sercom_ptr: SercomPtr<T>,
+        buf: &mut B,
+        next: Option<&mut DmacDescriptor>,
     ) -> Result<(), Error>
     where
         T: Beat,
@@ -677,35 +692,54 @@ pub(crate) mod async_dma {
         #[hal_cfg(any("dmac-d11", "dmac-d21"))]
         let trigger_action = TriggerAction::Beat;
 
+        // Safety: It is safe to bypass the buffer length check because `SercomPtr`
+        // always has a buffer length of 1.
         channel
             .as_mut()
-            .transfer_future(sercom_ptr, buf, S::DMA_RX_TRIGGER, trigger_action)
+            .transfer_future_linked(
+                &mut sercom_ptr,
+                buf,
+                S::DMA_RX_TRIGGER,
+                trigger_action,
+                next,
+            )
             .await
     }
 
     /// Perform a SERCOM DMA write with a provided `&[T]`
-    pub(in super::super) async fn write_dma<T: Beat, S: Sercom>(
+    #[inline]
+    pub(in super::super) async fn write_dma<T, B, S>(
         channel: &mut impl AnyChannel<Status = ReadyFuture>,
         sercom_ptr: SercomPtr<T>,
-        words: &[T],
-    ) -> Result<(), Error> {
-        // SAFETY: Using ImmutableSlice is safe because we hold on
-        // to words as long as the transfer hasn't completed.
-        let words = SharedSliceBuffer::from_slice(words);
-
-        write_dma_buffer::<_, _, S>(channel, sercom_ptr, words).await
+        buf: &mut B,
+    ) -> Result<(), Error>
+    where
+        B: Buffer<Beat = T>,
+        T: Beat,
+        S: Sercom,
+    {
+        unsafe { write_dma_linked::<_, _, S>(channel, sercom_ptr, buf, None).await }
     }
 
-    /// Perform a SERCOM DMA write with a provided [`Buffer`]
+    /// Perform a SERCOM DMA write with a provided [`Buffer`], and add an
+    /// optional link to a next [`DmacDescriptor`] to support linked
+    /// transfers.
+    ///
+    /// # Safety
+    ///
+    /// You **must** guarantee that the DMA transfer is either stopped or
+    /// completed before giving back control of `channel` AND `buf`.
+    #[inline]
     #[hal_macro_helper]
-    pub(in super::super) async fn write_dma_buffer<T, B, S>(
+    pub(in super::super) async unsafe fn write_dma_linked<T, B, S>(
         channel: &mut impl AnyChannel<Status = ReadyFuture>,
-        sercom_ptr: SercomPtr<T>,
-        buf: B,
+        mut sercom_ptr: SercomPtr<T>,
+        buf: &mut B,
+        next: Option<&mut DmacDescriptor>,
     ) -> Result<(), Error>
     where
-        T: Beat,
         B: Buffer<Beat = T>,
+        T: Beat,
         S: Sercom,
     {
         #[hal_cfg("dmac-d5x")]
@@ -714,9 +748,17 @@ pub(crate) mod async_dma {
         #[hal_cfg(any("dmac-d11", "dmac-d21"))]
         let trigger_action = TriggerAction::Beat;
 
+        // Safety: It is safe to bypass the buffer length check because `SercomPtr`
+        // always has a buffer length of 1.
         channel
             .as_mut()
-            .transfer_future(buf, sercom_ptr, S::DMA_TX_TRIGGER, trigger_action)
+            .transfer_future_linked(
+                buf,
+                &mut sercom_ptr,
+                S::DMA_TX_TRIGGER,
+                trigger_action,
+                next,
+            )
             .await
     }
 }