Update i2c/spi instance info (#3627)

* Add instances to drivers

* Move AnyI2c

* Move AnySpi and DataMode

* Generate new semver baseline

esp-hal/CHANGELOG.md

@@ -13,6 +13,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- `AnyI2c` has been moved from `esp_hal::i2c` to `esp_hal::i2c::master` (#3627)
+- `AnySpi` has been moved from `esp_hal::spi` to `esp_hal::spi::master` and `esp_hal::spi::slave` (#3627)
+- `DataMode` has been moved from `esp_hal::spi` to `esp_hal::spi::master` (#3627)
 
 ### Fixed
 

esp-hal/MIGRATING-1.0.0-beta.1.md

@@ -1 +1,24 @@
 # Migration Guide from 1.0.0-beta.1 to {{currentVersion}}
+
+## AnyI2c and AnySpi have been moved to mode-specific submodules
+
+```diff
+-use esp_hal::i2c::AnyI2c;
++use esp_hal::i2c::master::AnyI2c;
+```
+
+`AnySpi` has been separated into master and slave counterparts.
+
+```diff
+-use esp_hal::spi::AnySpi;
++use esp_hal::spi::master::AnySpi;
++// or:
++use esp_hal:spi::slave::AnySpi;
+```
+
+## SPI DataMode has been moved into `esp_hal::spi::master`
+
+```diff
+-use esp_hal::spi::DataMode;
++use esp_hal::spi::master::DataMode;
+```

esp-hal/src/dma/mod.rs

@@ -1663,8 +1663,9 @@ impl<DEG: DmaChannel> DmaChannelConvert<DEG> for DEG {
 ///
 /// ```rust,no_run
 #[doc = crate::before_snippet!()]
-/// use esp_hal::spi::AnySpi;
-/// use esp_hal::spi::master::{Spi, SpiDma, Config, Instance as SpiInstance};
+/// use esp_hal::spi::master::{
+///     AnySpi, Spi, SpiDma, Config, Instance as SpiInstance
+/// };
 /// use esp_hal::dma::DmaChannelFor;
 /// use esp_hal::Blocking;
 ///

esp-hal/src/i2c/master/mod.rs

@@ -137,7 +137,6 @@ use crate::{
         Pull,
         interconnect::{self, PeripheralOutput},
     },
-    i2c::{AnyI2c, AnyI2cInner},
     interrupt::InterruptHandler,
     pac::i2c0::{COMD, RegisterBlock},
     peripherals::Interrupt,
@@ -3012,7 +3011,7 @@ pub struct State {
 }
 
 /// A peripheral singleton compatible with the I2C master driver.
-pub trait Instance: crate::private::Sealed + super::IntoAnyI2c {
+pub trait Instance: crate::private::Sealed + IntoAnyI2c {
     #[doc(hidden)]
     /// Returns the peripheral data and state describing this instance.
     fn parts(&self) -> (&Info, &State);
@@ -3144,16 +3143,27 @@ macro_rules! instance {
     };
 }
 
-#[cfg(i2c0)]
+#[cfg(i2c_master_i2c0)]
 instance!(I2C0, I2cExt0, I2CEXT0_SCL, I2CEXT0_SDA, I2C_EXT0);
-#[cfg(i2c1)]
+#[cfg(i2c_master_i2c1)]
 instance!(I2C1, I2cExt1, I2CEXT1_SCL, I2CEXT1_SDA, I2C_EXT1);
 
+crate::any_peripheral! {
+    /// Any I2C peripheral.
+    pub peripheral AnyI2c<'d> {
+        #[cfg(i2c_master_i2c0)]
+        I2c0(crate::peripherals::I2C0<'d>),
+        #[cfg(i2c_master_i2c1)]
+        I2c1(crate::peripherals::I2C1<'d>),
+    }
+}
+
 impl Instance for AnyI2c<'_> {
     delegate::delegate! {
         to match &self.0 {
+            #[cfg(i2c_master_i2c0)]
             AnyI2cInner::I2c0(i2c) => i2c,
-            #[cfg(i2c1)]
+            #[cfg(i2c_master_i2c1)]
             AnyI2cInner::I2c1(i2c) => i2c,
         } {
             fn parts(&self) -> (&Info, &State);

esp-hal/src/i2c/mod.rs

@@ -14,13 +14,3 @@ pub mod master;
 crate::unstable_module! {
     pub mod lp_i2c;
 }
-
-crate::any_peripheral! {
-    /// Any I2C peripheral.
-    pub peripheral AnyI2c<'d> {
-        #[cfg(i2c0)]
-        I2c0(crate::peripherals::I2C0<'d>),
-        #[cfg(i2c1)]
-        I2c1(crate::peripherals::I2C1<'d>),
-    }
-}

esp-hal/src/spi/master.rs

@@ -44,7 +44,7 @@ use enumset::{EnumSet, EnumSetType};
 #[cfg(place_spi_master_driver_in_ram)]
 use procmacros::ram;
 
-use super::{BitOrder, DataMode, DmaError, Error, Mode};
+use super::{BitOrder, DmaError, Error, Mode};
 use crate::{
     Async,
     Blocking,
@@ -64,7 +64,6 @@ use crate::{
     interrupt::InterruptHandler,
     pac::spi2::RegisterBlock,
     private::{self, OnDrop, Sealed},
-    spi::AnySpi,
     system::{Cpu, PeripheralGuard},
     time::Rate,
 };
@@ -3713,9 +3712,6 @@ impl PartialEq for Info {
 
 unsafe impl Sync for Info {}
 
-// TODO: this macro needs to move to one level up, and it needs to describe the
-// hardware fully. The master module should extend it with the master specific
-// details.
 macro_rules! spi_instance {
     ($num:literal, $sclk:ident, $mosi:ident, $miso:ident, [$($cs:ident),+] $(, $sio2:ident, $sio3:ident $(, $sio4:ident, $sio5:ident, $sio6:ident, $sio7:ident)?)?) => {
         paste::paste! {
@@ -3767,7 +3763,7 @@ macro_rules! spi_instance {
     }
 }
 
-#[cfg(spi2)]
+#[cfg(spi_master_spi2)]
 cfg_if::cfg_if! {
     if #[cfg(esp32)] {
         spi_instance!(2, HSPICLK, HSPID, HSPIQ, [HSPICS0, HSPICS1, HSPICS2], HSPIWP, HSPIHD);
@@ -3778,7 +3774,7 @@ cfg_if::cfg_if! {
     }
 }
 
-#[cfg(spi3)]
+#[cfg(spi_master_spi3)]
 cfg_if::cfg_if! {
     if #[cfg(esp32)] {
         spi_instance!(3, VSPICLK, VSPID, VSPIQ, [VSPICS0, VSPICS1, VSPICS2], VSPIWP, VSPIHD);
@@ -3789,19 +3785,20 @@ cfg_if::cfg_if! {
     }
 }
 
-impl PeripheralInstance for super::AnySpi<'_> {
+impl PeripheralInstance for AnySpi<'_> {
     delegate::delegate! {
         to match &self.0 {
-            super::AnySpiInner::Spi2(spi) => spi,
-            #[cfg(spi3)]
-            super::AnySpiInner::Spi3(spi) => spi,
+            #[cfg(spi_master_spi2)]
+            AnySpiInner::Spi2(spi) => spi,
+            #[cfg(spi_master_spi3)]
+            AnySpiInner::Spi3(spi) => spi,
         } {
             fn info(&self) -> &'static Info;
         }
     }
 }
 
-impl QspiInstance for super::AnySpi<'_> {}
+impl QspiInstance for AnySpi<'_> {}
 
 #[doc(hidden)]
 pub struct State {
@@ -3833,7 +3830,7 @@ fn handle_async(instance: impl Instance) {
 }
 
 /// A peripheral singleton compatible with the SPI master driver.
-pub trait Instance: PeripheralInstance + super::IntoAnySpi {
+pub trait Instance: PeripheralInstance + IntoAnySpi {
     #[doc(hidden)]
     fn state(&self) -> &'static State;
     #[doc(hidden)]
@@ -3869,16 +3866,62 @@ macro_rules! master_instance {
     };
 }
 
+/// SPI data mode
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[instability::unstable]
+pub enum DataMode {
+    /// 1 bit, two data lines. (MOSI, MISO)
+    SingleTwoDataLines,
+    /// 1 bit, 1 data line (SIO0)
+    Single,
+    /// 2 bits, two data lines. (SIO0, SIO1)
+    Dual,
+    /// 4 bit, 4 data lines. (SIO0 .. SIO3)
+    Quad,
+    #[cfg(spi_octal)]
+    /// 8 bit, 8 data lines. (SIO0 .. SIO7)
+    Octal,
+}
+
+crate::any_peripheral! {
+    /// Any SPI peripheral.
+    pub peripheral AnySpi<'d> {
+        #[cfg(spi_master_spi2)]
+        Spi2(crate::peripherals::SPI2<'d>),
+        #[cfg(spi_master_spi3)]
+        Spi3(crate::peripherals::SPI3<'d>),
+    }
+}
+
+impl<'d> DmaEligible for AnySpi<'d> {
+    #[cfg(gdma)]
+    type Dma = crate::dma::AnyGdmaChannel<'d>;
+    #[cfg(pdma)]
+    type Dma = crate::dma::AnySpiDmaChannel<'d>;
+
+    fn dma_peripheral(&self) -> crate::dma::DmaPeripheral {
+        match &self.0 {
+            #[cfg(spi_master_spi2)]
+            AnySpiInner::Spi2(_) => crate::dma::DmaPeripheral::Spi2,
+            #[cfg(spi_master_spi3)]
+            AnySpiInner::Spi3(_) => crate::dma::DmaPeripheral::Spi3,
+        }
+    }
+}
+
+#[cfg(spi_master_spi2)]
 master_instance!(SPI2);
-#[cfg(spi3)]
+#[cfg(spi_master_spi3)]
 master_instance!(SPI3);
 
-impl Instance for super::AnySpi<'_> {
+impl Instance for AnySpi<'_> {
     delegate::delegate! {
         to match &self.0 {
-            super::AnySpiInner::Spi2(spi) => spi,
-            #[cfg(spi3)]
-            super::AnySpiInner::Spi3(spi) => spi,
+            #[cfg(spi_master_spi2)]
+            AnySpiInner::Spi2(spi) => spi,
+            #[cfg(spi_master_spi3)]
+            AnySpiInner::Spi3(spi) => spi,
         } {
             fn state(&self) -> &'static State;
             fn handler(&self) -> InterruptHandler;

esp-hal/src/spi/mod.rs

@@ -9,7 +9,7 @@
 //! more information on these modes, please refer to the documentation in their
 //! respective modules.
 
-use crate::dma::{DmaEligible, DmaError};
+use crate::dma::DmaError;
 
 pub mod master;
 
@@ -92,47 +92,3 @@ pub enum BitOrder {
     /// Least Significant Bit (LSB) is transmitted first.
     LsbFirst,
 }
-
-/// SPI data mode
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-#[cfg_attr(feature = "defmt", derive(defmt::Format))]
-#[instability::unstable]
-pub enum DataMode {
-    /// 1 bit, two data lines. (MOSI, MISO)
-    SingleTwoDataLines,
-    /// 1 bit, 1 data line (SIO0)
-    Single,
-    /// 2 bits, two data lines. (SIO0, SIO1)
-    Dual,
-    /// 4 bit, 4 data lines. (SIO0 .. SIO3)
-    Quad,
-    #[cfg(spi_octal)]
-    /// 8 bit, 8 data lines. (SIO0 .. SIO7)
-    Octal,
-}
-
-crate::any_peripheral! {
-    /// Any SPI peripheral.
-    pub peripheral AnySpi<'d> {
-        #[cfg(spi2)]
-        Spi2(crate::peripherals::SPI2<'d>),
-        #[cfg(spi3)]
-        Spi3(crate::peripherals::SPI3<'d>),
-    }
-}
-
-impl<'d> DmaEligible for AnySpi<'d> {
-    #[cfg(gdma)]
-    type Dma = crate::dma::AnyGdmaChannel<'d>;
-    #[cfg(pdma)]
-    type Dma = crate::dma::AnySpiDmaChannel<'d>;
-
-    fn dma_peripheral(&self) -> crate::dma::DmaPeripheral {
-        match &self.0 {
-            #[cfg(spi2)]
-            AnySpiInner::Spi2(_) => crate::dma::DmaPeripheral::Spi2,
-            #[cfg(spi3)]
-            AnySpiInner::Spi3(_) => crate::dma::DmaPeripheral::Spi3,
-        }
-    }
-}

esp-hal/src/spi/slave.rs

@@ -80,7 +80,6 @@ use crate::{
         interconnect::{PeripheralInput, PeripheralOutput},
     },
     pac::spi2::RegisterBlock,
-    spi::AnySpi,
     system::PeripheralGuard,
 };
 
@@ -579,7 +578,7 @@ pub mod dma {
 }
 
 /// A peripheral singleton compatible with the SPI slave driver.
-pub trait Instance: crate::private::Sealed + super::IntoAnySpi {
+pub trait Instance: crate::private::Sealed + IntoAnySpi {
     /// Returns the peripheral data describing this SPI instance.
     #[doc(hidden)]
     fn info(&self) -> &'static Info;
@@ -809,30 +808,55 @@ macro_rules! spi_instance {
     };
 }
 
+crate::any_peripheral! {
+    /// Any SPI peripheral.
+    pub peripheral AnySpi<'d> {
+        #[cfg(spi_master_spi2)]
+        Spi2(crate::peripherals::SPI2<'d>),
+        #[cfg(spi_master_spi3)]
+        Spi3(crate::peripherals::SPI3<'d>),
+    }
+}
+
+impl<'d> DmaEligible for AnySpi<'d> {
+    #[cfg(gdma)]
+    type Dma = crate::dma::AnyGdmaChannel<'d>;
+    #[cfg(pdma)]
+    type Dma = crate::dma::AnySpiDmaChannel<'d>;
+
+    fn dma_peripheral(&self) -> crate::dma::DmaPeripheral {
+        match &self.0 {
+            #[cfg(spi_master_spi2)]
+            AnySpiInner::Spi2(_) => crate::dma::DmaPeripheral::Spi2,
+            #[cfg(spi_master_spi3)]
+            AnySpiInner::Spi3(_) => crate::dma::DmaPeripheral::Spi3,
+        }
+    }
+}
+
 cfg_if::cfg_if! {
     if #[cfg(esp32)] {
-        #[cfg(spi2)]
         spi_instance!(2, HSPICLK, HSPID, HSPIQ, HSPICS0);
-        #[cfg(spi3)]
         spi_instance!(3, VSPICLK, VSPID, VSPIQ, VSPICS0);
     } else {
-        #[cfg(spi2)]
+        #[cfg(spi_master_spi2)]
         spi_instance!(2, FSPICLK, FSPID, FSPIQ, FSPICS0);
-        #[cfg(spi3)]
+        #[cfg(spi_master_spi3)]
         spi_instance!(3, SPI3_CLK, SPI3_D, SPI3_Q, SPI3_CS0);
     }
 }
 
-impl Instance for super::AnySpi<'_> {
+impl Instance for AnySpi<'_> {
     delegate::delegate! {
         to match &self.0 {
-            super::AnySpiInner::Spi2(spi) => spi,
-            #[cfg(spi3)]
-            super::AnySpiInner::Spi3(spi) => spi,
+            #[cfg(spi_master_spi2)]
+            AnySpiInner::Spi2(spi) => spi,
+            #[cfg(spi_master_spi3)]
+            AnySpiInner::Spi3(spi) => spi,
         } {
             fn info(&self) -> &'static Info;
         }
     }
 }
 
-impl InstanceDma for super::AnySpi<'_> {}
+impl InstanceDma for AnySpi<'_> {}

esp-metadata/devices/esp32.toml

@@ -90,6 +90,7 @@ status = "supported"
 
 [device.i2c_master]
 status = "supported"
+instances = [{ name = "i2c0" }, { name = "i2c1" }]
 ll_intr_mask = 0x3ffff
 fifo_size = 32
 max_bus_timeout = 0xFFFFF
@@ -106,6 +107,7 @@ channel_ram_size = 64
 
 [device.spi_master]
 status = "supported"
+instances = [{ name = "spi2" }, { name = "spi3" }]
 
 [device.timergroup]
 timg_has_timer1 = true

esp-metadata/devices/esp32c2.toml

@@ -66,6 +66,7 @@ status = "supported"
 
 [device.i2c_master]
 status = "supported"
+instances = [{ name = "i2c0" }]
 has_fsm_timeouts = true
 has_hw_bus_clear = true
 ll_intr_mask = 0x3ffff
@@ -79,6 +80,7 @@ bus_timeout_is_exponential = true
 
 [device.spi_master]
 status = "supported"
+instances = [{ name = "spi2" }]
 
 [device.timergroup]
 instances = [{ name = "timg0" }]

esp-metadata/devices/esp32c3.toml

@@ -81,6 +81,7 @@ status = "supported"
 
 [device.i2c_master]
 status = "supported"
+instances = [{ name = "i2c0" }]
 has_fsm_timeouts = true
 has_hw_bus_clear = true
 ll_intr_mask = 0x3ffff
@@ -99,6 +100,7 @@ channel_ram_size = 48
 
 [device.spi_master]
 status = "supported"
+instances = [{ name = "spi2" }]
 
 [device.timergroup]
 instances = [{ name = "timg0" }, { name = "timg1" }]

esp-metadata/devices/esp32c6.toml

@@ -110,6 +110,7 @@ status = "supported"
 
 [device.i2c_master]
 status = "supported"
+instances = [{ name = "i2c0" }]
 has_fsm_timeouts = true
 has_hw_bus_clear = true
 ll_intr_mask = 0x3ffff
@@ -130,6 +131,7 @@ channel_ram_size = 48
 
 [device.spi_master]
 status = "supported"
+instances = [{ name = "spi2" }]
 
 [device.timergroup]
 instances = [{ name = "timg0" }, { name = "timg1" }]

esp-metadata/devices/esp32h2.toml

@@ -92,6 +92,7 @@ status = "supported"
 
 [device.i2c_master]
 status = "supported"
+instances = [{ name = "i2c0" }, { name = "i2c1" }]
 has_fsm_timeouts = true
 has_hw_bus_clear = true
 ll_intr_mask = 0x3ffff
@@ -112,6 +113,7 @@ channel_ram_size = 48
 
 [device.spi_master]
 status = "supported"
+instances = [{ name = "spi2" }]
 
 [device.timergroup]
 instances = [{ name = "timg0" }, { name = "timg1" }]

esp-metadata/devices/esp32s2.toml

@@ -90,6 +90,7 @@ status = "supported"
 
 [device.i2c_master]
 status = "supported"
+instances = [{ name = "i2c0" }, { name = "i2c1" }]
 ll_intr_mask = 0x1ffff
 fifo_size = 32
 has_bus_timeout_enable = true
@@ -105,6 +106,7 @@ channel_ram_size = 64
 
 [device.spi_master]
 status = "supported"
+instances = [{ name = "spi2" }, { name = "spi3" }]
 
 [device.timergroup]
 timg_has_timer1 = true

esp-metadata/devices/esp32s3.toml

@@ -106,6 +106,7 @@ status = "supported"
 
 [device.i2c_master]
 status = "supported"
+instances = [{ name = "i2c0" }, { name = "i2c1" }]
 has_fsm_timeouts = true
 has_hw_bus_clear = true
 ll_intr_mask = 0x3ffff
@@ -125,6 +126,7 @@ channel_ram_size = 48
 
 [device.spi_master]
 status = "supported"
+instances = [{ name = "spi2" }, { name = "spi3" }]
 
 [device.timergroup]
 timg_has_timer1 = true

hil-test/tests/qspi.rs

@@ -14,9 +14,8 @@ use esp_hal::{
     dma_buffers,
     gpio::{AnyPin, Input, InputConfig, Level, Output, OutputConfig, Pull},
     spi::{
-        DataMode,
         Mode,
-        master::{Address, Command, Config, Spi, SpiDma},
+        master::{Address, Command, Config, DataMode, Spi, SpiDma},
     },
     time::Rate,
 };

hil-test/tests/spi_full_duplex.rs

@@ -11,8 +11,6 @@
 
 use embedded_hal::spi::SpiBus;
 use embedded_hal_async::spi::SpiBus as SpiBusAsync;
-#[cfg(feature = "unstable")]
-use esp_hal::peripherals::SPI2;
 use esp_hal::{
     Blocking,
     gpio::Input,
@@ -29,6 +27,8 @@ cfg_if::cfg_if! {
             dma::{DmaDescriptor, DmaRxBuf, DmaTxBuf},
             dma_buffers,
             gpio::{Level, NoPin},
+            peripherals::SPI2,
+            spi::master::{Address, Command, DataMode},
         };
         #[cfg(pcnt)]
         use esp_hal::pcnt::{channel::EdgeMode, unit::Unit, Pcnt};
@@ -844,9 +844,9 @@ mod tests {
 
         let mut buffer = [0u8; 4];
         spi.half_duplex_read(
-            esp_hal::spi::DataMode::Dual,
-            esp_hal::spi::master::Command::_8Bit(0x92, esp_hal::spi::DataMode::SingleTwoDataLines),
-            esp_hal::spi::master::Address::_32Bit(0x000000_00, esp_hal::spi::DataMode::Dual),
+            DataMode::Dual,
+            Command::_8Bit(0x92, DataMode::SingleTwoDataLines),
+            Address::_32Bit(0x000000_00, DataMode::Dual),
             0,
             &mut buffer,
         )
@@ -868,9 +868,9 @@ mod tests {
 
         let mut buffer = [0u8; 4];
         spi.half_duplex_read(
-            esp_hal::spi::DataMode::Dual,
-            esp_hal::spi::master::Command::_8Bit(0x92, esp_hal::spi::DataMode::SingleTwoDataLines),
-            esp_hal::spi::master::Address::_32Bit(0x000000_00, esp_hal::spi::DataMode::Dual),
+            DataMode::Dual,
+            Command::_8Bit(0x92, DataMode::SingleTwoDataLines),
+            Address::_32Bit(0x000000_00, DataMode::Dual),
             0,
             &mut buffer,
         )

hil-test/tests/spi_half_duplex_read.rs

@@ -12,9 +12,8 @@ use esp_hal::{
     dma_buffers,
     gpio::{Level, Output, OutputConfig},
     spi::{
-        DataMode,
         Mode,
-        master::{Address, Command, Config, Spi, SpiDma},
+        master::{Address, Command, Config, DataMode, Spi, SpiDma},
     },
     time::Rate,
 };

hil-test/tests/spi_half_duplex_write.rs

@@ -13,9 +13,8 @@ use esp_hal::{
     gpio::interconnect::InputSignal,
     pcnt::{Pcnt, channel::EdgeMode, unit::Unit},
     spi::{
-        DataMode,
         Mode,
-        master::{Address, Command, Config, Spi, SpiDma},
+        master::{Address, Command, Config, DataMode, Spi, SpiDma},
     },
     time::Rate,
 };

hil-test/tests/spi_half_duplex_write_psram.rs

@@ -17,9 +17,8 @@ use esp_hal::{
     gpio::interconnect::InputSignal,
     pcnt::{Pcnt, channel::EdgeMode, unit::Unit},
     spi::{
-        DataMode,
         Mode,
-        master::{Address, Command, Config, Spi, SpiDma},
+        master::{Address, Command, Config, DataMode, Spi, SpiDma},
     },
     time::Rate,
 };

qa-test/src/bin/qspi_flash.rs

@@ -35,9 +35,8 @@ use esp_hal::{
     dma_buffers,
     main,
     spi::{
-        DataMode,
         Mode,
-        master::{Address, Command, Config, Spi},
+        master::{Address, Command, Config, DataMode, Spi},
     },
     time::Rate,
 };

qa-test/src/bin/spi_halfduplex_read_manufacturer_id.rs

@@ -33,9 +33,8 @@ use esp_hal::{
     delay::Delay,
     main,
     spi::{
-        DataMode,
         Mode,
-        master::{Address, Command, Config, Spi},
+        master::{Address, Command, Config, DataMode, Spi},
     },
     time::Rate,
 };