DataMode::Single -> DataMode::FourWire

esp-rs · Jan 17, 2025 · c92f91e · c92f91e
1 parent 6e85726
commit c92f91e
Show file tree

Hide file tree

Showing 10 changed files with 63 additions and 50 deletions.
diff --git a/esp-hal/CHANGELOG.md b/esp-hal/CHANGELOG.md
@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- SPI: Added support for 3-wire SPI (#2919)
 
 ### Changed
 - RMT: `TxChannelConfig` and `RxChannelConfig` now support the builder-lite pattern (#2978)
@@ -80,7 +81,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - ESP32-S2: Made Wi-Fi peripheral non virtual. (#2942)
 - `UartRx::check_for_errors`, `Uart::check_for_rx_errors`, `{Uart, UartRx}::read_buffered_bytes` (#2935)
 - Added `i2c` interrupt API (#2944)
-- SPI: Added support for 3-wire SPI (#2919)
 
 ### Changed
 

diff --git a/esp-hal/MIGRATING-0.23.md b/esp-hal/MIGRATING-0.23.md
@@ -70,3 +70,14 @@ The more descriptive `gpio::Level` enum is now used to specify output levels of
 - let code = PulseCode::new(true, 200, false, 50);
 + let code = PulseCode::new(Level::High, 200, Level::Low, 50);
 ```
+
+## SPI Changes
+
+`spi::DataMode` changed the meaning of `DataMode::Single` - it now means 3-wire SPI. Use `DataMode::FourWire` to get the previous behavior.
+
+```diff
+- DataMode::Single,
++ DataMode::FourWire,
+```
+
+`Spi` now offers both, `with_mosi` and `with_sio0`. Consider using `with_sio` for half-duplex SPI except for [DataMode::FourWire] or for a mixed-bus.
diff --git a/esp-hal/src/spi/master.rs b/esp-hal/src/spi/master.rs
@@ -216,7 +216,7 @@ impl Command {
 
     fn mode(&self) -> DataMode {
         match self {
-            Command::None => DataMode::Single,
+            Command::None => DataMode::FourWire,
             Command::_1Bit(_, mode)
             | Command::_2Bit(_, mode)
             | Command::_3Bit(_, mode)
@@ -401,7 +401,7 @@ impl Address {
 
     fn mode(&self) -> DataMode {
         match self {
-            Address::None => DataMode::Single,
+            Address::None => DataMode::FourWire,
             Address::_1Bit(_, mode)
             | Address::_2Bit(_, mode)
             | Address::_3Bit(_, mode)
@@ -640,7 +640,7 @@ where
     /// Assign the MOSI (Master Out Slave In) pin for the SPI instance.
     ///
     /// Enables output functionality for the pin, and connects it to the MOSI.
-    /// You want to use this for full-duplex SPI or [DataMode::Single]
+    /// You want to use this for full-duplex SPI or [DataMode::FourWire]
     pub fn with_mosi<MOSI: PeripheralOutput>(self, mosi: impl Peripheral<P = MOSI> + 'd) -> Self {
         crate::into_mapped_ref!(mosi);
         mosi.enable_output(false);
@@ -654,7 +654,8 @@ where
     ///
     /// Enables both input and output functionality for the pin, and connects it
     /// to the MOSI signal and SIO0 input signal.
-    /// Use this for half-duplex SPI except for [DataMode::Single]
+    /// Use this for half-duplex SPI except for [DataMode::FourWire]. The pin is
+    /// configured to open-drain mode.
     pub fn with_sio0<MOSI: PeripheralOutput>(self, mosi: impl Peripheral<P = MOSI> + 'd) -> Self {
         crate::into_mapped_ref!(mosi);
         mosi.enable_output(true);
@@ -670,7 +671,7 @@ where
     ///
     /// Enables input functionality for the pin, and connects it to the MISO
     /// signal.
-    /// You want to use this for full-duplex SPI or [DataMode::Single]
+    /// You want to use this for full-duplex SPI or [DataMode::FourWire]
     pub fn with_miso<MISO: PeripheralInput>(self, miso: impl Peripheral<P = MISO> + 'd) -> Self {
         crate::into_mapped_ref!(miso);
         miso.enable_input(true);
@@ -684,7 +685,8 @@ where
     ///
     /// Enables both input and output functionality for the pin, and connects it
     /// to the MISO signal and SIO1 input signal.
-    /// Use this for half-duplex SPI except for [DataMode::Single
+    /// Use this for half-duplex SPI except for [DataMode::FourWire]. The pin is
+    /// configured to open-drain mode.
     ///
     /// Note: You do not need to call [Self::with_miso] when this is used.
     pub fn with_sio1<SIO1: PeripheralOutput>(self, miso: impl Peripheral<P = SIO1> + 'd) -> Self {
@@ -1541,7 +1543,7 @@ mod dma {
             {
                 // On the ESP32, if we don't have data, the address is always sent
                 // on a single line, regardless of its data mode.
-                if bytes_to_write == 0 && address.mode() != DataMode::Single {
+                if bytes_to_write == 0 && address.mode() != DataMode::FourWire {
                     return self.set_up_address_workaround(cmd, address, dummy);
                 }
             }
@@ -2607,13 +2609,13 @@ impl Driver {
     ) -> Result<(), Error> {
         let reg_block = self.register_block();
         match cmd_mode {
-            DataMode::Single => (),
+            DataMode::FourWire => (),
             // FIXME: more detailed error - Only 1-bit commands are supported.
             _ => return Err(Error::Unsupported),
         }
 
         match address_mode {
-            DataMode::Single => {
+            DataMode::FourWire => {
                 reg_block.ctrl().modify(|_, w| {
                     w.fread_dio().clear_bit();
                     w.fread_qio().clear_bit();
@@ -3131,14 +3133,14 @@ impl Driver {
         no_mosi_miso: bool,
         data_mode: DataMode,
     ) -> Result<(), Error> {
-        let three_wire = cmd.mode() == DataMode::SingleThreeWire
-            || address.mode() == DataMode::SingleThreeWire
-            || data_mode == DataMode::SingleThreeWire;
+        let three_wire = cmd.mode() == DataMode::Single
+            || address.mode() == DataMode::Single
+            || data_mode == DataMode::Single;
 
         if three_wire
-            && ((cmd != Command::None && cmd.mode() != DataMode::SingleThreeWire)
-                || (address != Address::None && address.mode() != DataMode::SingleThreeWire)
-                || data_mode != DataMode::SingleThreeWire)
+            && ((cmd != Command::None && cmd.mode() != DataMode::Single)
+                || (address != Address::None && address.mode() != DataMode::Single)
+                || data_mode != DataMode::Single)
         {
             return Err(Error::Unsupported);
         }

diff --git a/esp-hal/src/spi/mod.rs b/esp-hal/src/spi/mod.rs
@@ -98,9 +98,9 @@ pub enum BitOrder {
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[instability::unstable]
 pub enum DataMode {
-    /// Clock, CS and one data line (SIO0)
-    SingleThreeWire,
-    /// `Single` Data Mode - 1 bit, two data lines. (SIO0, SIO1)
+    /// 4-Wire Data Mode - 1 bit, two data lines. (MOSI, MISO)
+    FourWire,
+    /// 3-Wire Data Mode, Clock, CS and one data line (SIO0)
     Single,
     /// `Dual` Data Mode - 2 bits, two data lines. (SIO0, SIO1)
     Dual,

diff --git a/hil-test/tests/qspi.rs b/hil-test/tests/qspi.rs
@@ -32,9 +32,9 @@ cfg_if::cfg_if! {
 
 cfg_if::cfg_if! {
     if #[cfg(esp32)] {
-        const COMMAND_DATA_MODES: [DataMode; 1] = [DataMode::Single];
+        const COMMAND_DATA_MODES: [DataMode; 1] = [DataMode::FourWire];
     } else {
-        const COMMAND_DATA_MODES: [DataMode; 2] = [DataMode::Single, DataMode::Quad];
+        const COMMAND_DATA_MODES: [DataMode; 2] = [DataMode::FourWire, DataMode::Quad];
     }
 }
 
@@ -155,7 +155,7 @@ fn execute_write(
         assert_eq!(unit0.value() + unit1.value(), 8);
 
         if data_on_multiple_pins {
-            if command_data_mode == DataMode::Single {
+            if command_data_mode == DataMode::FourWire {
                 assert_eq!(unit0.value(), 1);
                 assert_eq!(unit1.value(), 7);
             } else {
@@ -173,7 +173,7 @@ fn execute_write(
         assert_eq!(unit0.value() + unit1.value(), 4);
 
         if data_on_multiple_pins {
-            if command_data_mode == DataMode::Single {
+            if command_data_mode == DataMode::FourWire {
                 assert_eq!(unit0.value(), 1);
                 assert_eq!(unit1.value(), 3);
             } else {

diff --git a/hil-test/tests/spi_half_duplex_read.rs b/hil-test/tests/spi_half_duplex_read.rs
@@ -75,7 +75,7 @@ mod tests {
 
         let transfer = spi
             .half_duplex_read(
-                DataMode::Single,
+                DataMode::FourWire,
                 Command::None,
                 Address::None,
                 0,
@@ -93,7 +93,7 @@ mod tests {
 
         let transfer = spi
             .half_duplex_read(
-                DataMode::Single,
+                DataMode::FourWire,
                 Command::None,
                 Address::None,
                 0,
@@ -124,7 +124,7 @@ mod tests {
 
         let mut buffer = [0xAA; DMA_BUFFER_SIZE];
         spi.half_duplex_read(
-            DataMode::Single,
+            DataMode::FourWire,
             Command::None,
             Address::None,
             0,
@@ -138,7 +138,7 @@ mod tests {
         ctx.miso_mirror.set_high();
 
         spi.half_duplex_read(
-            DataMode::Single,
+            DataMode::FourWire,
             Command::None,
             Address::None,
             0,

diff --git a/hil-test/tests/spi_half_duplex_write.rs b/hil-test/tests/spi_half_duplex_write.rs
@@ -146,21 +146,21 @@ mod tests {
 
     #[test]
     fn test_spi_writes_are_correctly_by_pcnt(ctx: Context) {
-        super::perform_spi_writes_are_correctly_by_pcnt(ctx, DataMode::Single);
+        super::perform_spi_writes_are_correctly_by_pcnt(ctx, DataMode::FourWire);
     }
 
     #[test]
     fn test_spidmabus_writes_are_correctly_by_pcnt(ctx: Context) {
-        super::perform_spidmabus_writes_are_correctly_by_pcnt(ctx, DataMode::Single);
+        super::perform_spidmabus_writes_are_correctly_by_pcnt(ctx, DataMode::FourWire);
     }
 
     #[test]
     fn test_spi_writes_are_correctly_by_pcnt_tree_wire(ctx: Context) {
-        super::perform_spi_writes_are_correctly_by_pcnt(ctx, DataMode::SingleThreeWire);
+        super::perform_spi_writes_are_correctly_by_pcnt(ctx, DataMode::FourWire);
     }
 
     #[test]
     fn test_spidmabus_writes_are_correctly_by_pcnt_tree_wire(ctx: Context) {
-        super::perform_spidmabus_writes_are_correctly_by_pcnt(ctx, DataMode::SingleThreeWire);
+        super::perform_spidmabus_writes_are_correctly_by_pcnt(ctx, DataMode::FourWire);
     }
 }
diff --git a/hil-test/tests/spi_half_duplex_write_psram.rs b/hil-test/tests/spi_half_duplex_write_psram.rs
@@ -102,7 +102,7 @@ mod tests {
         dma_tx_buf.fill(&[0b0110_1010; DMA_BUFFER_SIZE]);
         let transfer = spi
             .half_duplex_write(
-                DataMode::Single,
+                DataMode::FourWire,
                 Command::None,
                 Address::None,
                 0,
@@ -117,7 +117,7 @@ mod tests {
 
         let transfer = spi
             .half_duplex_write(
-                DataMode::Single,
+                DataMode::FourWire,
                 Command::None,
                 Address::None,
                 0,
@@ -153,12 +153,12 @@ mod tests {
 
         let buffer = [0b0110_1010; DMA_BUFFER_SIZE];
         // Write the buffer where each byte has 3 pos edges.
-        spi.half_duplex_write(DataMode::Single, Command::None, Address::None, 0, &buffer)
+        spi.half_duplex_write(DataMode::FourWire, Command::None, Address::None, 0, &buffer)
             .unwrap();
 
         assert_eq!(unit.value(), (3 * DMA_BUFFER_SIZE) as _);
 
-        spi.half_duplex_write(DataMode::Single, Command::None, Address::None, 0, &buffer)
+        spi.half_duplex_write(DataMode::FourWire, Command::None, Address::None, 0, &buffer)
             .unwrap();
 
         assert_eq!(unit.value(), (6 * DMA_BUFFER_SIZE) as _);

diff --git a/qa-test/src/bin/qspi_flash.rs b/qa-test/src/bin/qspi_flash.rs
@@ -98,8 +98,8 @@ fn main() -> ! {
     dma_tx_buf.set_length(0);
     let transfer = spi
         .half_duplex_write(
-            DataMode::Single,
-            Command::_8Bit(0x06, DataMode::Single),
+            DataMode::FourWire,
+            Command::_8Bit(0x06, DataMode::FourWire),
             Address::None,
             0,
             0,
@@ -113,9 +113,9 @@ fn main() -> ! {
     // erase sector
     let transfer = spi
         .half_duplex_write(
-            DataMode::Single,
-            Command::_8Bit(0x20, DataMode::Single),
-            Address::_24Bit(0x000000, DataMode::Single),
+            DataMode::FourWire,
+            Command::_8Bit(0x20, DataMode::FourWire),
+            Address::_24Bit(0x000000, DataMode::FourWire),
             0,
             dma_tx_buf.len(),
             dma_tx_buf,
@@ -128,8 +128,8 @@ fn main() -> ! {
     // write enable
     let transfer = spi
         .half_duplex_write(
-            DataMode::Single,
-            Command::_8Bit(0x06, DataMode::Single),
+            DataMode::FourWire,
+            Command::_8Bit(0x06, DataMode::FourWire),
             Address::None,
             0,
             dma_tx_buf.len(),
@@ -147,8 +147,8 @@ fn main() -> ! {
     let transfer = spi
         .half_duplex_write(
             DataMode::Quad,
-            Command::_8Bit(0x32, DataMode::Single),
-            Address::_24Bit(0x000000, DataMode::Single),
+            Command::_8Bit(0x32, DataMode::FourWire),
+            Address::_24Bit(0x000000, DataMode::FourWire),
             0,
             dma_tx_buf.len(),
             dma_tx_buf,
@@ -163,7 +163,7 @@ fn main() -> ! {
         let transfer = spi
             .half_duplex_read(
                 DataMode::Quad,
-                Command::_8Bit(0xeb, DataMode::Single),
+                Command::_8Bit(0xeb, DataMode::FourWire),
                 Address::_32Bit(0x000000 << 8, DataMode::Quad),
                 4,
                 dma_rx_buf.len(),

diff --git a/qa-test/src/bin/spi_halfduplex_read_manufacturer_id.rs b/qa-test/src/bin/spi_halfduplex_read_manufacturer_id.rs
@@ -83,9 +83,9 @@ fn main() -> ! {
         // READ MANUFACTURER ID FROM FLASH CHIP
         let mut data = [0u8; 2];
         spi.half_duplex_read(
-            DataMode::Single,
-            Command::_8Bit(0x90, DataMode::Single),
-            Address::_24Bit(0x000000, DataMode::Single),
+            DataMode::FourWire,
+            Command::_8Bit(0x90, DataMode::FourWire),
+            Address::_24Bit(0x000000, DataMode::FourWire),
             0,
             &mut data,
         )
@@ -97,7 +97,7 @@ fn main() -> ! {
         let mut data = [0u8; 2];
         spi.half_duplex_read(
             DataMode::Dual,
-            Command::_8Bit(0x92, DataMode::Single),
+            Command::_8Bit(0x92, DataMode::FourWire),
             Address::_32Bit(0x000000_00, DataMode::Dual),
             0,
             &mut data,
@@ -110,7 +110,7 @@ fn main() -> ! {
         let mut data = [0u8; 2];
         spi.half_duplex_read(
             DataMode::Quad,
-            Command::_8Bit(0x94, DataMode::Single),
+            Command::_8Bit(0x94, DataMode::FourWire),
             Address::_32Bit(0x000000_00, DataMode::Quad),
             4,
             &mut data,