Add unsafe dma api

esp-hal/CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - ESP32-PICO-V3-02: Initial support (#1155)
 - `time::current_time` API (#1503)
+- Add an unsafe API to SPI master enabling use-cases which are not possible using the safe API (#1523)
 
 ### Fixed
 

esp-hal/src/aes/mod.rs

@@ -281,7 +281,7 @@ pub mod dma {
             ChannelTypes,
             DmaError,
             DmaPeripheral,
-            DmaTransferRxTx,
+            DmaTransfer,
             RxPrivate,
             TxPrivate,
         },
@@ -346,7 +346,7 @@ pub mod dma {
         aes_dma: &'t mut AesDma<'d, C>,
     }
 
-    impl<'t, 'd, C> DmaTransferRxTx for AesDmaTransferRxTx<'t, 'd, C>
+    impl<'t, 'd, C> DmaTransfer for AesDmaTransferRxTx<'t, 'd, C>
     where
         C: ChannelTypes,
         C::P: AesPeripheral,

esp-hal/src/dma/mod.rs

@@ -1504,16 +1504,6 @@ pub trait DmaTransfer: Drop {
     fn is_done(&self) -> bool;
 }
 
-/// Trait to be implemented for an in progress dma transfer.
-#[allow(clippy::type_complexity, drop_bounds)]
-#[doc(hidden)]
-pub trait DmaTransferRxTx: Drop {
-    /// Wait for the transfer to finish.
-    fn wait(self) -> Result<(), DmaError>;
-    /// Check if the transfer is finished.
-    fn is_done(&self) -> bool;
-}
-
 #[cfg(feature = "async")]
 pub(crate) mod asynch {
     use core::task::Poll;

esp-hal/src/prelude.rs

@@ -16,10 +16,7 @@ pub use nb;
 #[cfg(any(dport, pcr, system))]
 pub use crate::clock::Clock as _esp_hal_clock_Clock;
 #[cfg(any(gdma, pdma))]
-pub use crate::dma::{
-    DmaTransfer as _esp_hal_dma_DmaTransfer,
-    DmaTransferRxTx as _esp_hal_dma_DmaTransferRxTx,
-};
+pub use crate::dma::DmaTransfer as _esp_hal_dma_DmaTransfer;
 #[cfg(gpio)]
 pub use crate::gpio::{
     InputPin as _esp_hal_gpio_InputPin,

esp-hal/src/spi/master.rs

@@ -823,7 +823,6 @@ pub mod dma {
             ChannelTypes,
             DmaError,
             DmaTransfer,
-            DmaTransferRxTx,
             RxPrivate,
             Spi2Peripheral,
             SpiPeripheral,
@@ -901,6 +900,7 @@ pub mod dma {
             }
         }
     }
+
     /// An in-progress DMA transfer
     #[must_use]
     pub struct SpiDmaTransferRxTx<'t, 'd, T, C, M, DmaMode>
@@ -914,7 +914,7 @@ pub mod dma {
         spi_dma: &'t mut SpiDma<'d, T, C, M, DmaMode>,
     }
 
-    impl<'t, 'd, T, C, M, DmaMode> DmaTransferRxTx for SpiDmaTransferRxTx<'t, 'd, T, C, M, DmaMode>
+    impl<'t, 'd, T, C, M, DmaMode> DmaTransfer for SpiDmaTransferRxTx<'t, 'd, T, C, M, DmaMode>
     where
         T: InstanceDma<C::Tx<'d>, C::Rx<'d>>,
         C: ChannelTypes,
@@ -1109,14 +1109,9 @@ pub mod dma {
         where
             TXBUF: ReadBuffer<Word = u8>,
         {
-            let (ptr, len) = unsafe { words.read_buffer() };
-
-            if len > MAX_DMA_SIZE {
-                return Err(super::Error::MaxDmaTransferSizeExceeded);
+            unsafe {
+                self.dma_write_unchecked(words)?;
             }
-
-            self.spi
-                .start_write_bytes_dma(ptr, len, &mut self.channel.tx, false)?;
             Ok(SpiDmaTransfer { spi_dma: self })
         }
 
@@ -1133,15 +1128,8 @@ pub mod dma {
         where
             RXBUF: WriteBuffer<Word = u8>,
         {
-            let (ptr, len) = unsafe { words.write_buffer() };
-
-            if len > MAX_DMA_SIZE {
-                return Err(super::Error::MaxDmaTransferSizeExceeded);
-            }
-
             unsafe {
-                self.spi
-                    .start_read_bytes_dma(ptr, len, &mut self.channel.rx, false)?;
+                self.dma_read_unchecked(words)?;
             }
             Ok(SpiDmaTransfer { spi_dma: self })
         }
@@ -1156,6 +1144,81 @@ pub mod dma {
             words: &'t TXBUF,
             read_buffer: &'t mut RXBUF,
         ) -> Result<SpiDmaTransferRxTx<'t, 'd, T, C, M, DmaMode>, super::Error>
+        where
+            TXBUF: ReadBuffer<Word = u8>,
+            RXBUF: WriteBuffer<Word = u8>,
+        {
+            unsafe {
+                self.dma_transfer_unchecked(words, read_buffer)?;
+            }
+            Ok(SpiDmaTransferRxTx { spi_dma: self })
+        }
+
+        /// Perform a DMA write. Use [Self::wait] to await completion of the
+        /// current transfer.
+        ///
+        /// # Safety
+        /// - don't use the buffers while the DMA transaction is ongoing
+        /// - don't start a new transfer while the DMA transaction is ongoing
+        #[cfg_attr(feature = "place-spi-driver-in-ram", ram)]
+        pub unsafe fn dma_write_unchecked<TXBUF>(
+            &mut self,
+            words: &TXBUF,
+        ) -> Result<(), super::Error>
+        where
+            TXBUF: ReadBuffer<Word = u8>,
+        {
+            let (ptr, len) = unsafe { words.read_buffer() };
+
+            if len > MAX_DMA_SIZE {
+                return Err(super::Error::MaxDmaTransferSizeExceeded);
+            }
+
+            self.spi
+                .start_write_bytes_dma(ptr, len, &mut self.channel.tx, false)?;
+
+            Ok(())
+        }
+
+        /// Perform a DMA read. Use [Self::wait] to await completion of the
+        /// current transfer.
+        ///
+        /// # Safety
+        /// - don't use the buffers while the DMA transaction is ongoing
+        /// - don't start a new transfer while the DMA transaction is ongoing
+        #[cfg_attr(feature = "place-spi-driver-in-ram", ram)]
+        pub unsafe fn dma_read_unchecked<RXBUF>(
+            &mut self,
+            words: &mut RXBUF,
+        ) -> Result<(), super::Error>
+        where
+            RXBUF: WriteBuffer<Word = u8>,
+        {
+            let (ptr, len) = unsafe { words.write_buffer() };
+
+            if len > MAX_DMA_SIZE {
+                return Err(super::Error::MaxDmaTransferSizeExceeded);
+            }
+
+            unsafe {
+                self.spi
+                    .start_read_bytes_dma(ptr, len, &mut self.channel.rx, false)?;
+            }
+
+            Ok(())
+        }
+
+        /// Perform a DMA transfer. Use [Self::wait] to await completion of the
+        /// current transfer.
+        ///
+        /// # Safety
+        /// - don't use the buffers while the DMA transaction is ongoing
+        /// - don't start a new transfer while the DMA transaction is ongoing
+        pub unsafe fn dma_transfer_unchecked<TXBUF, RXBUF>(
+            &mut self,
+            words: &TXBUF,
+            read_buffer: &mut RXBUF,
+        ) -> Result<(), super::Error>
         where
             TXBUF: ReadBuffer<Word = u8>,
             RXBUF: WriteBuffer<Word = u8>,
@@ -1177,7 +1240,21 @@ pub mod dma {
                     &mut self.channel.rx,
                 )?;
             }
-            Ok(SpiDmaTransferRxTx { spi_dma: self })
+
+            Ok(())
+        }
+
+        /// Wait for the DMA transfer to complete
+        pub fn wait(&mut self) -> Result<(), DmaError> {
+            // Waiting for the DMA transfer is not enough. We need to wait for the
+            // peripheral to finish flushing its buffers, too.
+            self.spi.flush().ok();
+
+            if self.channel.rx.has_error() || self.channel.tx.has_error() {
+                Err(DmaError::DescriptorError)
+            } else {
+                Ok(())
+            }
         }
     }
 

esp-hal/src/spi/slave.rs

@@ -137,7 +137,6 @@ pub mod dma {
             ChannelTypes,
             DmaError,
             DmaTransfer,
-            DmaTransferRxTx,
             RxPrivate,
             Spi2Peripheral,
             SpiPeripheral,
@@ -239,7 +238,7 @@ pub mod dma {
         spi_dma: &'t mut SpiDma<'d, T, C, DmaMode>,
     }
 
-    impl<'t, 'd, T, C, DmaMode> DmaTransferRxTx for SpiDmaTransferRxTx<'t, 'd, T, C, DmaMode>
+    impl<'t, 'd, T, C, DmaMode> DmaTransfer for SpiDmaTransferRxTx<'t, 'd, T, C, DmaMode>
     where
         T: InstanceDma<C::Tx<'d>, C::Rx<'d>>,
         C: ChannelTypes,