Remove Dma[Rx|Tx]Buffer::length (#2587)

Co-authored-by: Dominic Fischer <[email protected]>
esp-rs · Dec 3, 2024 · 94e7ffb · 94e7ffb
1 parent a6a83d3
commit 94e7ffb
Show file tree

Hide file tree

Showing 11 changed files with 184 additions and 95 deletions.
diff --git a/esp-hal/CHANGELOG.md b/esp-hal/CHANGELOG.md
@@ -39,6 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `SystemTimer` no longer uses peripheral ref (#2576)
 - `TIMGX` no longer uses peripheral ref (#2581)
 - `SystemTimer::now` has been renamed `SystemTimer::unit_value(Unit)` (#2576)
+- `SpiDma` transfers now explicitly take a length along with the DMA buffer object (#2587)
 - `dma::{Channel, ChannelRx, ChannelTx}::set_priority` for GDMA devices (#2403)
 - `SystemTimer`s `Alarm`s are now type erased (#2576)
 - `TimerGroup` `Timer`s are now type erased (#2581)
@@ -66,6 +67,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The DMA channel objects no longer have `tx` and `rx` fields. (#2526)
 - `SysTimerAlarms` has been removed, alarms are now part of the `SystemTimer` struct (#2576)
 - `FrozenUnit`, `AnyUnit`, `SpecificUnit`, `SpecificComparator`, `AnyComparator` have been removed from `systimer` (#2576)
+- Remove Dma[Rx|Tx]Buffer::length (#2587)
 - `esp_hal::psram::psram_range` (#2546)
 - The `Dma` structure has been removed. (#2545)
 - Removed `embedded-hal 0.2.x` impls and deps from `esp-hal` (#2593)

diff --git a/esp-hal/MIGRATING-0.22.md b/esp-hal/MIGRATING-0.22.md
@@ -273,3 +273,24 @@ is not compatible with the hardware.
 +    cam_config,
  )
 ```
+
+## SpiDma now requires you specify the transfer length explicitly
+
+```diff
+  dma_tx_buf.set_length(5 /* or greater */);
+- spi_dma.write(dma_tx_buf);
++ spi_dma.write(5, dma_tx_buf);
+```
+
+```diff
+  dma_rx_buf.set_length(5 /* or greater */);
+- spi_dma.read(dma_rx_buf);
++ spi_dma.read(5, dma_rx_buf);
+```
+
+```diff
+  dma_rx_buf.set_length(5 /* or greater */);
+  dma_tx_buf.set_length(5 /* or greater */);
+- spi_dma.transfer(dma_rx_buf, dma_tx_buf);
++ spi_dma.transfer(5, dma_rx_buf, 5, dma_tx_buf);
+```
diff --git a/esp-hal/src/dma/buffers.rs b/esp-hal/src/dma/buffers.rs
@@ -120,13 +120,6 @@ pub unsafe trait DmaTxBuffer {
 
     /// This is called after the DMA is done using the buffer.
     fn from_view(view: Self::View) -> Self;
-
-    /// Returns the maximum number of bytes that would be transmitted by this
-    /// buffer.
-    ///
-    /// This is a convenience hint for SPI. Most peripherals don't care how long
-    /// the transfer is.
-    fn length(&self) -> usize;
 }
 
 /// [DmaRxBuffer] is a DMA descriptor + memory combo that can be used for
@@ -156,12 +149,6 @@ pub unsafe trait DmaRxBuffer {
 
     /// This is called after the DMA is done using the buffer.
     fn from_view(view: Self::View) -> Self;
-
-    /// Returns the maximum number of bytes that can be received by this buffer.
-    ///
-    /// This is a convenience hint for SPI. Most peripherals don't care how long
-    /// the transfer is.
-    fn length(&self) -> usize;
 }
 
 /// An in-progress view into [DmaRxBuf]/[DmaTxBuf].
@@ -387,10 +374,6 @@ unsafe impl DmaTxBuffer for DmaTxBuf {
     fn from_view(view: Self::View) -> Self {
         view.0
     }
-
-    fn length(&self) -> usize {
-        self.len()
-    }
 }
 
 /// DMA receive buffer
@@ -543,10 +526,6 @@ unsafe impl DmaRxBuffer for DmaRxBuf {
     fn from_view(view: Self::View) -> Self {
         view.0
     }
-
-    fn length(&self) -> usize {
-        self.len()
-    }
 }
 
 /// DMA transmit and receive buffer.
@@ -675,10 +654,6 @@ unsafe impl DmaTxBuffer for DmaRxTxBuf {
     fn from_view(view: Self::View) -> Self {
         view.0
     }
-
-    fn length(&self) -> usize {
-        self.len()
-    }
 }
 
 unsafe impl DmaRxBuffer for DmaRxTxBuf {
@@ -711,10 +686,6 @@ unsafe impl DmaRxBuffer for DmaRxTxBuf {
     fn from_view(view: Self::View) -> Self {
         view.0
     }
-
-    fn length(&self) -> usize {
-        self.len()
-    }
 }
 
 /// DMA Streaming Receive Buffer.
@@ -865,10 +836,6 @@ unsafe impl DmaRxBuffer for DmaRxStreamBuf {
     fn from_view(view: Self::View) -> Self {
         view.buf
     }
-
-    fn length(&self) -> usize {
-        panic!("DmaCircularBuf doesn't have a length")
-    }
 }
 
 /// A view into a [DmaRxStreamBuf]
@@ -1072,10 +1039,6 @@ unsafe impl DmaTxBuffer for EmptyBuf {
     fn from_view(view: Self::View) -> Self {
         view
     }
-
-    fn length(&self) -> usize {
-        0
-    }
 }
 
 unsafe impl DmaRxBuffer for EmptyBuf {
@@ -1103,10 +1066,6 @@ unsafe impl DmaRxBuffer for EmptyBuf {
     fn from_view(view: Self::View) -> Self {
         view
     }
-
-    fn length(&self) -> usize {
-        0
-    }
 }
 
 /// DMA Loop Buffer
@@ -1180,10 +1139,6 @@ unsafe impl DmaTxBuffer for DmaLoopBuf {
     fn from_view(view: Self::View) -> Self {
         view
     }
-
-    fn length(&self) -> usize {
-        panic!("DmaLoopBuf does not have a length")
-    }
 }
 
 impl Deref for DmaLoopBuf {