Migrate I8080 driver to a move based API (esp-rs#2191)

* Migrate I8080 driver to a move based API * fmt * comments --------- Co-authored-by: Dominic Fischer <[email protected]>
Dominaezzz · Oct 2, 2024 · 8789ca3 · 8789ca3
1 parent a3304c6
commit 8789ca3
Show file tree

Hide file tree

Showing 7 changed files with 308 additions and 307 deletions.
diff --git a/esp-hal/CHANGELOG.md b/esp-hal/CHANGELOG.md
@@ -23,6 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - You can now use `Input`, `Output`, `OutputOpenDrain` and `Flex` pins as EXTI and RTCIO wakeup sources (#2095)
 - Added `Rtc::set_current_time` to allow setting RTC time, and `Rtc::current_time` to getting RTC time while taking into account boot time (#1883)
 - Added APIs to allow connecting signals through the GPIO matrix. (#2128)
+- Allow I8080 transfers to be cancelled on the spot (#2191)
 - Implement `TryFrom<u32>` for `ledc::timer::config::Duty` (#1984)
 - Expose `RtcClock::get_xtal_freq` and `RtcClock::get_slow_freq` publically for all chips (#2183)
 - TWAI support for ESP32-H2 (#2199)
@@ -46,6 +47,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - ESP32: Added support for touch sensing on GPIO32 and 33 (#2109)
 - Removed gpio pin generics from I8080 driver type. (#2171)
 - I8080 driver now decides bus width at transfer time rather than construction time. (#2171)
+- Migrate the I8080 driver to a move based API (#2191)
 - Replaced `AnyPin` with `InputSignal` and `OutputSignal` and renamed `ErasedPin` to `AnyPin` (#2128)
 - Replaced the `ErasedTimer` enum with the `AnyTimer` struct. (#2144)
 - `Camera` and `AesDma` now support erasing the DMA channel type (#2258)
@@ -93,6 +95,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Removed the following functions from `GpioPin`: `is_high`, `is_low`, `set_high`, `set_low`, `set_state`, `is_set_high`, `is_set_low`, `toggle`. (#2094)
 - Removed `Rtc::get_time_raw` (#1883)
 - Removed `_with_default_pins` UART constructors (#2132)
+- Removed transfer methods `send`, `send_dma` and `send_dma_async` from `I8080` (#2191)
 - Removed `uart::{DefaultRxPin, DefaultTxPin}` (#2132)
 - Removed `PcntSource` and `PcntInputConfig`. (#2134)
 - Removed the `place-spi-driver-in-ram` feature, this is now enabled via [esp-config](https://docs.rs/esp-config) (#2156)

diff --git a/esp-hal/MIGRATING-0.20.md b/esp-hal/MIGRATING-0.20.md
@@ -189,14 +189,31 @@ The I8080 driver no longer holds on to pins in its type definition.
 + let _: I8080<'a, DmaChannel3, Blocking>;
 ```
 
-## I8080 start transfer type inference
+## I8080 transfer API changes
 
-The I8080 driver now decides bus width at transfer time, which means you don't get inference.
+- The I8080 driver now decides bus width at transfer time, which means you don't get type inference anymore.
+- Starting a transfer moves the driver into the transfer object, allowing you to store it in a `static` or struct.
+- The transfer API no longer works with plain slices, it now works with `DmaTxBuffer`s which allow to bring your own DMA data structure and implement efficient queueing of transfers.
+- The three transfer methods (`send`, `send_dma`, `send_dma_async`) have been merged into one `send` method.
 
 ```diff
-let mut i8080 = I8080::new(....);
+let (_, _, tx_buffer, tx_descriptors) = dma_buffers!(0, 32678);
++ let mut dma_buf = DmaTxBuf::new(tx_descriptors, tx_buffer).unwrap();
+
+let mut i8080 = I8080::new(
+    lcd_cam.lcd,
+    channel.tx,
+-   tx_descriptors,
+    tx_pins,
+    20.MHz(),
+    Config::default(),
+)
+
 - i8080.send(0x12, 0, &[0, 1, 2, 3, 4]);
-+ i8080.send(0x12u8, 0, &[0, 1, 2, 3, 4]);
++ dma_buf.fill(&[0, 1, 2, 3, 4]);
++ let transfer = i8080.send(0x12u8, 0, dma_buf).unwrap();
++ // transfer.wait_for_done().await;
++ (_, i8080, dma_buf) = transfer.wait();
 ```
 
 ### Placing drivers in RAM is now done via esp-config