Mark unstable modules, make macros private (#2900)

* Mark unstable APIs + make `macros` private * address reviews * use `instability` instead of feature * fix dependencies * More tagging * `Persistable` and `procmacros` - unstable * Adjust for changes * sure...
esp-rs · Jan 10, 2025 · 8d948ba · 8d948ba
1 parent e62141f
commit 8d948ba
Show file tree

Hide file tree

Showing 55 changed files with 245 additions and 148 deletions.
diff --git a/esp-hal-embassy/src/lib.rs b/esp-hal-embassy/src/lib.rs
@@ -162,7 +162,7 @@ pub fn init(time_driver: impl TimerCollection) {
     unsafe {
         use esp_hal::interrupt::software::SoftwareInterrupt;
 
-        #[esp_hal::macros::ram]
+        #[esp_hal::ram]
         extern "C" fn software3_interrupt() {
             // This interrupt is fired when the thread-mode executor's core needs to be
             // woken. It doesn't matter which core handles this interrupt first, the

diff --git a/esp-hal/CHANGELOG.md b/esp-hal/CHANGELOG.md
@@ -100,6 +100,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - SPI: Fix naming violations for `Mode` enum variants (#2902)
 - SPI: Fix naming violations for `Address` and `Command` enum variants (#2906)
 - `ClockSource` enums are now `#[non_exhaustive]` (#2912)
+- `macros` module is now private (#2900)
+
 - `gpio::{Input, Flex}::wakeup_enable` now returns an error instead of panicking. (#2916)
 - Removed the `I` prefix from `DriveStrength` enum variants. (#2922)
 - Removed the `Attenuation` prefix from `Attenuation` enum variants. (#2922)

diff --git a/esp-hal/MIGRATING-0.22.md b/esp-hal/MIGRATING-0.22.md
@@ -483,3 +483,13 @@ The ADC attenuation variants are renamed from e.g. `Attenuation0dB` to `_0dB`.
 -Attenuation::Attenuation0dB
 +Attenuation::_0dB
 ```
+
+## `macro` module is private now
+
+Macros from `procmacros` crate (`handler`, `ram`, `load_lp_code`) are now imported via `esp-hal`.
+
+```diff
+- use esp_hal::macros::{handler, ram, load_lp_code};
++ use esp_hal::{handler, ram, load_lp_code};
+```
+
diff --git a/esp-hal/src/analog/adc/xtensa.rs b/esp-hal/src/analog/adc/xtensa.rs
@@ -234,8 +234,8 @@ impl RegisterAccess for crate::peripherals::ADC1 {
     fn set_init_code(data: u16) {
         let [msb, lsb] = data.to_be_bytes();
 
-        crate::regi2c_write_mask!(I2C_SAR_ADC, ADC_SAR1_INITIAL_CODE_HIGH_ADDR, msb as u32);
-        crate::regi2c_write_mask!(I2C_SAR_ADC, ADC_SAR1_INITIAL_CODE_LOW_ADDR, lsb as u32);
+        crate::rom::regi2c_write_mask!(I2C_SAR_ADC, ADC_SAR1_INITIAL_CODE_HIGH_ADDR, msb as u32);
+        crate::rom::regi2c_write_mask!(I2C_SAR_ADC, ADC_SAR1_INITIAL_CODE_LOW_ADDR, lsb as u32);
     }
 
     fn reset() {
@@ -257,16 +257,16 @@ impl super::CalibrationAccess for crate::peripherals::ADC1 {
     const ADC_VAL_MASK: u16 = ADC_VAL_MASK;
 
     fn enable_vdef(enable: bool) {
-        crate::regi2c_write_mask!(I2C_SAR_ADC, ADC_SAR1_DREF_ADDR, enable as u8);
+        crate::rom::regi2c_write_mask!(I2C_SAR_ADC, ADC_SAR1_DREF_ADDR, enable as u8);
     }
 
     fn connect_cal(source: AdcCalSource, enable: bool) {
         match source {
             AdcCalSource::Gnd => {
-                crate::regi2c_write_mask!(I2C_SAR_ADC, ADC_SAR1_ENCAL_GND_ADDR, enable as u8);
+                crate::rom::regi2c_write_mask!(I2C_SAR_ADC, ADC_SAR1_ENCAL_GND_ADDR, enable as u8);
             }
             AdcCalSource::Ref => {
-                crate::regi2c_write_mask!(I2C_SAR_ADC, ADC_SARADC1_ENCAL_REF_ADDR, enable as u8);
+                crate::rom::regi2c_write_mask!(I2C_SAR_ADC, ADC_SARADC1_ENCAL_REF_ADDR, enable as u8);
             }
         }
     }
@@ -348,8 +348,8 @@ impl RegisterAccess for crate::peripherals::ADC2 {
     fn set_init_code(data: u16) {
         let [msb, lsb] = data.to_be_bytes();
 
-        crate::regi2c_write_mask!(I2C_SAR_ADC, ADC_SAR2_INITIAL_CODE_HIGH_ADDR, msb as u32);
-        crate::regi2c_write_mask!(I2C_SAR_ADC, ADC_SAR2_INITIAL_CODE_LOW_ADDR, lsb as u32);
+        crate::rom::regi2c_write_mask!(I2C_SAR_ADC, ADC_SAR2_INITIAL_CODE_HIGH_ADDR, msb as u32);
+        crate::rom::regi2c_write_mask!(I2C_SAR_ADC, ADC_SAR2_INITIAL_CODE_LOW_ADDR, lsb as u32);
     }
 
     fn reset() {
@@ -371,16 +371,16 @@ impl super::CalibrationAccess for crate::peripherals::ADC2 {
     const ADC_VAL_MASK: u16 = ADC_VAL_MASK;
 
     fn enable_vdef(enable: bool) {
-        crate::regi2c_write_mask!(I2C_SAR_ADC, ADC_SAR2_DREF_ADDR, enable as u8);
+        crate::rom::regi2c_write_mask!(I2C_SAR_ADC, ADC_SAR2_DREF_ADDR, enable as u8);
     }
 
     fn connect_cal(source: AdcCalSource, enable: bool) {
         match source {
             AdcCalSource::Gnd => {
-                crate::regi2c_write_mask!(I2C_SAR_ADC, ADC_SAR2_ENCAL_GND_ADDR, enable as u8);
+                crate::rom::regi2c_write_mask!(I2C_SAR_ADC, ADC_SAR2_ENCAL_GND_ADDR, enable as u8);
             }
             AdcCalSource::Ref => {
-                crate::regi2c_write_mask!(I2C_SAR_ADC, ADC_SARADC2_ENCAL_REF_ADDR, enable as u8);
+                crate::rom::regi2c_write_mask!(I2C_SAR_ADC, ADC_SARADC2_ENCAL_REF_ADDR, enable as u8);
             }
         }
     }

diff --git a/esp-hal/src/clock/clocks_ll/esp32.rs b/esp-hal/src/clock/clocks_ll/esp32.rs
@@ -1,6 +1,6 @@
 use crate::{
     clock::{Clock, PllClock, XtalClock},
-    regi2c_write,
+    rom::regi2c_write,
 };
 
 const REF_CLK_FREQ: u32 = 1000000;

diff --git a/esp-hal/src/clock/clocks_ll/esp32c2.rs b/esp-hal/src/clock/clocks_ll/esp32c2.rs
@@ -1,7 +1,6 @@
 use crate::{
     clock::{ApbClock, Clock, CpuClock, PllClock, XtalClock},
-    regi2c_write,
-    regi2c_write_mask,
+    rom::{regi2c_write, regi2c_write_mask},
 };
 
 const I2C_BBPLL: u32 = 0x66;

diff --git a/esp-hal/src/clock/clocks_ll/esp32c3.rs b/esp-hal/src/clock/clocks_ll/esp32c3.rs
@@ -1,7 +1,6 @@
 use crate::{
     clock::{ApbClock, Clock, CpuClock, PllClock, XtalClock},
-    regi2c_write,
-    regi2c_write_mask,
+    rom::{regi2c_write, regi2c_write_mask},
 };
 
 const I2C_BBPLL: u32 = 0x66;

diff --git a/esp-hal/src/dma/gdma.rs b/esp-hal/src/dma/gdma.rs
@@ -19,7 +19,7 @@ use critical_section::CriticalSection;
 use crate::{
     dma::*,
     interrupt::Priority,
-    macros::handler,
+    handler,
     peripheral::{Peripheral, PeripheralRef},
     peripherals::Interrupt,
 };

diff --git a/esp-hal/src/dma/pdma/mod.rs b/esp-hal/src/dma/pdma/mod.rs
@@ -18,7 +18,7 @@ use crate::{
     asynch::AtomicWaker,
     dma::*,
     interrupt::Priority,
-    macros::handler,
+    handler,
     peripheral::{Peripheral, PeripheralRef},
     peripherals::Interrupt,
 };

diff --git a/esp-hal/src/gpio/mod.rs b/esp-hal/src/gpio/mod.rs
@@ -1026,6 +1026,8 @@ macro_rules! io_type {
     (Analog, $gpionum:literal) => {
         // FIXME: the implementation shouldn't be in the GPIO module
         #[cfg(any(esp32c2, esp32c3, esp32c6, esp32h2))]
+        #[cfg(any(doc, feature = "unstable"))]
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
         impl $crate::gpio::AnalogPin for $crate::gpio::GpioPin<$gpionum> {
             /// Configures the pin for analog mode.
             fn set_analog(&self, _: $crate::private::Internal) {

diff --git a/esp-hal/src/i2c/master/mod.rs b/esp-hal/src/i2c/master/mod.rs
@@ -2324,7 +2324,7 @@ macro_rules! instance {
     ($inst:ident, $peri:ident, $scl:ident, $sda:ident, $interrupt:ident) => {
         impl Instance for crate::peripherals::$inst {
             fn parts(&self) -> (&Info, &State) {
-                #[crate::macros::handler]
+                #[crate::handler]
                 pub(super) fn irq_handler() {
                     async_handler(&PERIPHERAL, &STATE);
                 }

diff --git a/esp-hal/src/i2c/mod.rs b/esp-hal/src/i2c/mod.rs
@@ -8,4 +8,6 @@
 pub mod master;
 
 #[cfg(lp_i2c0)]
-pub mod lp_i2c;
+crate::unstable_module! {
+    pub mod lp_i2c;
+}
diff --git a/esp-hal/src/lcd_cam/mod.rs b/esp-hal/src/lcd_cam/mod.rs
@@ -14,7 +14,7 @@ use crate::{
     asynch::AtomicWaker,
     interrupt::{InterruptConfigurable, InterruptHandler},
     lcd_cam::{cam::Cam, lcd::Lcd},
-    macros::handler,
+    handler,
     peripheral::Peripheral,
     peripherals::{Interrupt, LCD_CAM},
     system::GenericPeripheralGuard,