Remove ChannelCreator types and burst mode

esp-hal/CHANGELOG.md

@@ -39,6 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - I8080: Added `set_8bits_order()` to set the byte order in 8-bit mode (#2487)
 - `I2c::{apply_config(), with_sda(), with_scl()}` (#2477)
 - ESP32-S2: Added missing GPIO alternate functions (#2512)
+- `dma::{Channel, ChannelRx, ChannelTx}::set_priority` for GDMA devices (#2403)
 
 ### Changed
 
@@ -98,6 +99,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Removed the pin type parameters from `lcd_cam::cam::{RxEightBits, RxSixteenBits}` (#2388)
 - Most of the async-specific constructors (`new_async`, `new_async_no_transceiver`) have been removed. (#2430)
 - The `configure_for_async` DMA functions have been removed (#2430)
+- The `configure` DMA channel functions has been removed (#2403)
 - The `Uart::{change_baud, change_stop_bits}` functions have been removed (#2449)
 - `gpio::{Input, Output, OutputOpenDrain, Flex, GpioPin}::{peripheral_input, into_peripheral_output}` have been removed. (#2418)
 - The `GpioEtm` prefix has been removed from `gpio::etm` types (#2427)

esp-hal/MIGRATING-0.21.md

@@ -311,6 +311,12 @@ In case of any error you should drop the transfer and restart it.
 +ChannelTx<'d, Async, DmaChannel0>
 ```
 
+## Configuration changes
+
+- `configure_for_async` and `configure` have been removed
+- PDMA devices (ESP32, ESP32-S2) provide no configurability
+- GDMA devices provide `set_priority` to change DMA in/out channel priority
+
 ## Removed `peripheral_input` and `into_peripheral_output` from GPIO pin types
 
 Creating peripheral interconnect signals now consume the GPIO pin used for the connection.

esp-hal/src/dma/buffers.rs

@@ -14,16 +14,16 @@ pub struct Preparation {
     #[cfg_attr(not(esp32s3), allow(dead_code))]
     pub block_size: Option<DmaBufBlkSize>,
 
-    /// Specifies whether descriptor linked list specified in `start` conforms
-    /// to the alignment requirements required to enable burst transfers.
+    /// Specifies whether the data should be transferred in burst mode.
     ///
-    /// Note: This only applies to burst transfer of the buffer data, not the
-    /// descriptors themselves.
+    /// The implementation of the buffer must ensure that burst mode is only
+    /// enabled when alignment requirements are met.
     ///
     /// There are no additional alignment requirements for TX burst transfers,
     /// but RX transfers require all descriptors to have buffer pointers and
     /// sizes that are a multiple of 4 (word aligned).
-    pub is_burstable: bool,
+    // TODO: currently unused, buffers should not hardcode their preference.
+    pub burst: bool,
 
     /// Configures the "check owner" feature of the DMA channel.
     ///
@@ -330,7 +330,7 @@ unsafe impl DmaTxBuffer for DmaTxBuf {
             start: self.descriptors.head(),
             block_size: self.block_size,
             // This is TX, the DMA channel is free to do a burst transfer.
-            is_burstable: true,
+            burst: true,
             check_owner: None,
         }
     }
@@ -481,7 +481,7 @@ unsafe impl DmaRxBuffer for DmaRxBuf {
             // DmaRxBuf doesn't currently enforce the alignment requirements required for bursting.
             // In the future, it could either enforce the alignment or calculate if the alignment
             // requirements happen to be met.
-            is_burstable: false,
+            burst: false,
             check_owner: None,
         }
     }
@@ -609,7 +609,7 @@ unsafe impl DmaTxBuffer for DmaRxTxBuf {
             block_size: None, // TODO: support block size!
 
             // This is TX, the DMA channel is free to do a burst transfer.
-            is_burstable: true,
+            burst: true,
             check_owner: None,
         }
     }
@@ -641,7 +641,7 @@ unsafe impl DmaRxBuffer for DmaRxTxBuf {
 
             // DmaRxTxBuf doesn't currently enforce the alignment requirements required for
             // bursting.
-            is_burstable: false,
+            burst: false,
             check_owner: None,
         }
     }
@@ -782,7 +782,7 @@ unsafe impl DmaRxBuffer for DmaRxStreamBuf {
 
             // DmaRxStreamBuf doesn't currently enforce the alignment requirements required for
             // bursting.
-            is_burstable: false,
+            burst: false,
 
             // Whilst we give ownership of the descriptors the DMA, the correctness of this buffer
             // implementation doesn't rely on the DMA checking for descriptor ownership.
@@ -995,7 +995,7 @@ unsafe impl DmaTxBuffer for EmptyBuf {
             block_size: None,
 
             // This is TX, the DMA channel is free to do a burst transfer.
-            is_burstable: true,
+            burst: true,
 
             // As we don't give ownership of the descriptor to the DMA, it's important that the DMA
             // channel does *NOT* check for ownership, otherwise the channel will return an error.
@@ -1026,7 +1026,7 @@ unsafe impl DmaRxBuffer for EmptyBuf {
             block_size: None,
 
             // As much as bursting is meaningless here, the descriptor does meet the requirements.
-            is_burstable: true,
+            burst: true,
 
             // As we don't give ownership of the descriptor to the DMA, it's important that the DMA
             // channel does *NOT* check for ownership, otherwise the channel will return an error.

esp-hal/src/dma/gdma.rs

@@ -621,19 +621,19 @@ macro_rules! impl_channel {
                 }
             }
 
-            impl ChannelCreator<$num> {
-                /// Configure the channel for use with blocking APIs
-                pub fn configure<'a>(
-                    self,
-                    burst_mode: bool,
-                    priority: DmaPriority,
-                ) -> Channel<'a, Blocking, [<DmaChannel $num>]> {
+            impl [<DmaChannel $num>] {
+                /// Unsafely constructs a new DMA channel.
+                ///
+                /// # Safety
+                ///
+                /// The caller must ensure that only a single instance is used.
+                pub unsafe fn steal<'a>() -> Channel<'a, Blocking, Self> {
                     let mut this = Channel {
                         tx: ChannelTx::new(ChannelTxImpl(SpecificGdmaChannel::<$num> {})),
                         rx: ChannelRx::new(ChannelRxImpl(SpecificGdmaChannel::<$num> {})),
                     };
 
-                    this.configure(burst_mode, priority);
+                    this.set_priority(DmaPriority::Priority0);
 
                     this
                 }
@@ -731,19 +731,19 @@ crate::impl_dma_eligible! {
 pub struct Dma<'d> {
     _inner: PeripheralRef<'d, crate::peripherals::DMA>,
     /// Channel 0
-    pub channel0: ChannelCreator<0>,
+    pub channel0: Channel<'d, Blocking, DmaChannel0>,
     /// Channel 1
     #[cfg(not(esp32c2))]
-    pub channel1: ChannelCreator<1>,
+    pub channel1: Channel<'d, Blocking, DmaChannel1>,
     /// Channel 2
     #[cfg(not(esp32c2))]
-    pub channel2: ChannelCreator<2>,
+    pub channel2: Channel<'d, Blocking, DmaChannel2>,
     /// Channel 3
     #[cfg(esp32s3)]
-    pub channel3: ChannelCreator<3>,
+    pub channel3: Channel<'d, Blocking, DmaChannel3>,
     /// Channel 4
     #[cfg(esp32s3)]
-    pub channel4: ChannelCreator<4>,
+    pub channel4: Channel<'d, Blocking, DmaChannel4>,
 }
 
 impl<'d> Dma<'d> {
@@ -759,17 +759,19 @@ impl<'d> Dma<'d> {
             .modify(|_, w| w.ahbm_rst_inter().clear_bit());
         dma.misc_conf().modify(|_, w| w.clk_en().set_bit());
 
-        Dma {
-            _inner: dma,
-            channel0: ChannelCreator {},
-            #[cfg(not(esp32c2))]
-            channel1: ChannelCreator {},
-            #[cfg(not(esp32c2))]
-            channel2: ChannelCreator {},
-            #[cfg(esp32s3)]
-            channel3: ChannelCreator {},
-            #[cfg(esp32s3)]
-            channel4: ChannelCreator {},
+        unsafe {
+            Dma {
+                _inner: dma,
+                channel0: DmaChannel0::steal(),
+                #[cfg(not(esp32c2))]
+                channel1: DmaChannel1::steal(),
+                #[cfg(not(esp32c2))]
+                channel2: DmaChannel2::steal(),
+                #[cfg(esp32s3)]
+                channel3: DmaChannel3::steal(),
+                #[cfg(esp32s3)]
+                channel4: DmaChannel4::steal(),
+            }
         }
     }
 }