Merge 6588f5429a into 040c0fd353

esp-hal-embassy/src/executor/thread.rs

@@ -5,7 +5,7 @@ use core::marker::PhantomData;
 use embassy_executor::{raw, Spawner};
 use esp_hal::Cpu;
 #[cfg(multi_core)]
-use esp_hal::{interrupt::software::SoftwareInterrupt, macros::handler};
+use esp_hal::{handler, interrupt::software::SoftwareInterrupt};
 #[cfg(low_power_wait)]
 use portable_atomic::{AtomicBool, Ordering};
 

esp-hal/CHANGELOG.md

@@ -101,6 +101,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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)
 

esp-hal/MIGRATING-0.22.md

@@ -476,3 +476,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};
+```
+

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);
             }
         }
     }

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;

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;

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;

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,
 };

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,
 };

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) {

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

@@ -2258,7 +2258,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);
                 }

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;
+}

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,

esp-hal/src/lib.rs

@@ -143,41 +143,42 @@
 // MUST be the first module
 mod fmt;
 
-pub mod asynch;
-
 #[cfg(riscv)]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 pub use esp_riscv_rt::{self, entry, riscv};
 #[cfg(xtensa)]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 pub use xtensa_lx;
 #[cfg(xtensa)]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 pub use xtensa_lx_rt::{self, entry};
 
 // TODO what should we reexport stably?
 #[cfg(any(esp32, esp32s3))]
 pub use self::soc::cpu_control;
 #[cfg(efuse)]
+#[instability::unstable]
+#[cfg_attr(not(feature = "unstable"), allow(unused))]
 pub use self::soc::efuse;
 #[cfg(lp_core)]
+#[instability::unstable]
+#[cfg_attr(not(feature = "unstable"), allow(unused))]
 pub use self::soc::lp_core;
 pub use self::soc::peripherals;
+#[instability::unstable]
 #[cfg(any(feature = "quad-psram", feature = "octal-psram"))]
 pub use self::soc::psram;
 #[cfg(ulp_riscv_core)]
+#[instability::unstable]
+#[cfg_attr(not(feature = "unstable"), allow(unused))]
 pub use self::soc::ulp_core;
 
 #[cfg(any(dport, hp_sys, pcr, system))]
 pub mod clock;
-
-pub mod config;
-
-#[cfg(any(xtensa, all(riscv, systimer)))]
-pub mod delay;
 #[cfg(gpio)]
 pub mod gpio;
 #[cfg(any(i2c0, i2c1))]
 pub mod i2c;
-#[cfg(any(dport, interrupt_core0, interrupt_core1))]
-pub mod interrupt;
 pub mod peripheral;
 #[cfg(any(hmac, sha))]
 mod reg_access;
@@ -186,13 +187,16 @@ pub mod spi;
 #[cfg(any(uart0, uart1, uart2))]
 pub mod uart;
 
-pub mod macros;
-pub mod rom;
+mod macros;
 
-pub mod debugger;
-#[doc(hidden)]
-pub mod sync;
-pub mod time;
+#[cfg(any(lp_core, ulp_riscv_core))]
+#[cfg(feature = "unstable")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
+pub use procmacros::load_lp_code;
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
+#[instability::unstable]
+#[cfg_attr(not(feature = "unstable"), allow(unused))]
+pub use procmacros::{handler, ram};
 
 // can't use instability on inline module definitions, see https://github.com/rust-lang/rust/issues/54727
 #[doc(hidden)]
@@ -223,8 +227,13 @@ unstable_module! {
     pub mod aes;
     #[cfg(any(adc, dac))]
     pub mod analog;
+    pub mod asynch;
     #[cfg(assist_debug)]
     pub mod assist_debug;
+    pub mod config;
+    pub mod debugger;
+    #[cfg(any(xtensa, all(riscv, systimer)))]
+    pub mod delay;
     #[cfg(any(gdma, pdma))]
     pub mod dma;
     #[cfg(ecc)]
@@ -235,6 +244,8 @@ unstable_module! {
     pub mod hmac;
     #[cfg(any(i2s0, i2s1))]
     pub mod i2s;
+    #[cfg(any(dport, interrupt_core0, interrupt_core1))]
+    pub mod interrupt;
     #[cfg(lcd_cam)]
     pub mod lcd_cam;
     #[cfg(ledc)]
@@ -253,14 +264,18 @@ unstable_module! {
     pub mod rmt;
     #[cfg(rng)]
     pub mod rng;
+    pub mod rom;
     #[cfg(rsa)]
     pub mod rsa;
     #[cfg(any(lp_clkrst, rtc_cntl))]
     pub mod rtc_cntl;
     #[cfg(sha)]
     pub mod sha;
+    #[doc(hidden)]
+    pub mod sync;
     #[cfg(any(dport, hp_sys, pcr, system))]
     pub mod system;
+    pub mod time;
     #[cfg(any(systimer, timg0, timg1))]
     pub mod timer;
     #[cfg(touch)]
@@ -351,6 +366,7 @@ pub use private::Internal;
 ///   reset occurs during a write or a reset interrupts the zero initialization
 ///   on first boot.
 /// - Structs must contain only `Persistable` fields and padding
+#[instability::unstable]
 pub unsafe trait Persistable: Sized {}
 
 macro_rules! impl_persistable {
@@ -368,6 +384,7 @@ impl_persistable!(atomic AtomicU8, AtomicI8, AtomicU16, AtomicI16, AtomicU32, At
 unsafe impl<T: Persistable, const N: usize> Persistable for [T; N] {}
 
 #[doc(hidden)]
+#[instability::unstable]
 pub mod __macro_implementation {
     //! Unstable private implementation details of esp-hal-procmacros.
 
@@ -493,9 +510,10 @@ unsafe extern "C" fn stack_chk_fail() {
     panic!("Stack corruption detected");
 }
 
+#[cfg(feature = "unstable")]
+use crate::config::{WatchdogConfig, WatchdogStatus};
 use crate::{
     clock::{Clocks, CpuClock},
-    config::{WatchdogConfig, WatchdogStatus},
     peripherals::Peripherals,
 };
 
@@ -514,9 +532,13 @@ pub struct Config {
     pub cpu_clock: CpuClock,
 
     /// Enable watchdog timer(s).
+    #[cfg(any(doc, feature = "unstable"))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
     pub watchdog: WatchdogConfig,
 
     /// PSRAM configuration.
+    #[cfg(any(doc, feature = "unstable"))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
     #[cfg(any(feature = "quad-psram", feature = "octal-psram"))]
     pub psram: psram::PsramConfig,
 }
@@ -533,43 +555,61 @@ pub fn init(config: Config) -> Peripherals {
     // RTC domain must be enabled before we try to disable
     let mut rtc = crate::rtc_cntl::Rtc::new(&mut peripherals.LPWR);
 
-    #[cfg(not(any(esp32, esp32s2)))]
-    if config.watchdog.swd {
-        rtc.swd.enable();
-    } else {
-        rtc.swd.disable();
-    }
+    // Handle watchdog configuration with defaults
+    cfg_if::cfg_if! {
+        if #[cfg(feature = "unstable")]
+        {
+            #[cfg(not(any(esp32, esp32s2)))]
+            if config.watchdog.swd {
+                rtc.swd.enable();
+            } else {
+                rtc.swd.disable();
+            }
 
-    match config.watchdog.rwdt {
-        WatchdogStatus::Enabled(duration) => {
-            rtc.rwdt.enable();
-            rtc.rwdt
-                .set_timeout(crate::rtc_cntl::RwdtStage::Stage0, duration);
+            match config.watchdog.rwdt {
+                WatchdogStatus::Enabled(duration) => {
+                    rtc.rwdt.enable();
+                    rtc.rwdt
+                        .set_timeout(crate::rtc_cntl::RwdtStage::Stage0, duration);
+                }
+                WatchdogStatus::Disabled => {
+                    rtc.rwdt.disable();
+                }
+            }
+
+            match config.watchdog.timg0 {
+                WatchdogStatus::Enabled(duration) => {
+                    let mut timg0_wd = crate::timer::timg::Wdt::<self::peripherals::TIMG0>::new();
+                    timg0_wd.enable();
+                    timg0_wd.set_timeout(crate::timer::timg::MwdtStage::Stage0, duration);
+                }
+                WatchdogStatus::Disabled => {
+                    crate::timer::timg::Wdt::<self::peripherals::TIMG0>::new().disable();
+                }
+            }
+
+            #[cfg(timg1)]
+            match config.watchdog.timg1 {
+                WatchdogStatus::Enabled(duration) => {
+                    let mut timg1_wd = crate::timer::timg::Wdt::<self::peripherals::TIMG1>::new();
+                    timg1_wd.enable();
+                    timg1_wd.set_timeout(crate::timer::timg::MwdtStage::Stage0, duration);
+                }
+                WatchdogStatus::Disabled => {
+                    crate::timer::timg::Wdt::<self::peripherals::TIMG1>::new().disable();
+                }
+            }
         }
-        WatchdogStatus::Disabled => {
+        else
+        {
+            #[cfg(not(any(esp32, esp32s2)))]
+            rtc.swd.disable();
+
             rtc.rwdt.disable();
-        }
-    }
 
-    match config.watchdog.timg0 {
-        WatchdogStatus::Enabled(duration) => {
-            let mut timg0_wd = crate::timer::timg::Wdt::<self::peripherals::TIMG0>::new();
-            timg0_wd.enable();
-            timg0_wd.set_timeout(crate::timer::timg::MwdtStage::Stage0, duration);
-        }
-        WatchdogStatus::Disabled => {
             crate::timer::timg::Wdt::<self::peripherals::TIMG0>::new().disable();
-        }
-    }
 
-    #[cfg(timg1)]
-    match config.watchdog.timg1 {
-        WatchdogStatus::Enabled(duration) => {
-            let mut timg1_wd = crate::timer::timg::Wdt::<self::peripherals::TIMG1>::new();
-            timg1_wd.enable();
-            timg1_wd.set_timeout(crate::timer::timg::MwdtStage::Stage0, duration);
-        }
-        WatchdogStatus::Disabled => {
+            #[cfg(timg1)]
             crate::timer::timg::Wdt::<self::peripherals::TIMG1>::new().disable();
         }
     }

esp-hal/src/macros.rs

@@ -3,9 +3,6 @@
 //! Most of the macros in this module are hidden and intended for internal use
 //! only. For the list of public macros, see the [procmacros](https://docs.rs/esp-hal-procmacros/latest/esp_hal_procmacros/)
 //! documentation.
-
-pub use procmacros::*;
-
 #[doc(hidden)]
 /// Helper macro for checking doctest code snippets
 #[macro_export]

esp-hal/src/rmt.rs

@@ -227,7 +227,7 @@ use crate::{
     asynch::AtomicWaker,
     gpio::interconnect::{PeripheralInput, PeripheralOutput},
     interrupt::InterruptConfigurable,
-    macros::handler,
+    handler,
     peripheral::Peripheral,
     peripherals::Interrupt,
     soc::constants,

esp-hal/src/rom/mod.rs

@@ -44,8 +44,6 @@ extern "C" {
     );
 }
 
-#[doc(hidden)]
-#[macro_export]
 macro_rules! regi2c_write {
     ( $block: ident, $reg_add: ident, $indata: expr ) => {
         paste::paste! {
@@ -62,8 +60,9 @@ macro_rules! regi2c_write {
     };
 }
 
-#[doc(hidden)]
-#[macro_export]
+#[allow(unused_imports)]
+pub(crate) use regi2c_write;
+
 macro_rules! regi2c_write_mask {
     ( $block: ident, $reg_add: ident, $indata: expr ) => {
         paste::paste! {
@@ -82,6 +81,9 @@ macro_rules! regi2c_write_mask {
     };
 }
 
+#[allow(unused_imports)]
+pub(crate) use regi2c_write_mask;
+
 #[inline(always)]
 pub(crate) fn ets_delay_us(us: u32) {
     extern "C" {

esp-hal/src/rtc_cntl/rtc/esp32c2.rs

@@ -2,7 +2,7 @@ use strum::FromRepr;
 
 use crate::{
     peripherals::{APB_CTRL, EXTMEM, RTC_CNTL, SPI0, SPI1, SYSTEM},
-    regi2c_write_mask,
+    rom::regi2c_write_mask,
     rtc_cntl::{RtcCalSel, RtcClock, RtcFastClock, RtcSlowClock},
 };
 

esp-hal/src/rtc_cntl/rtc/esp32c3.rs

@@ -3,7 +3,7 @@ use strum::FromRepr;
 use crate::{
     clock::XtalClock,
     peripherals::{APB_CTRL, EXTMEM, RTC_CNTL, SPI0, SPI1, SYSTEM},
-    regi2c_write_mask,
+    rom::regi2c_write_mask,
     rtc_cntl::{RtcCalSel, RtcClock, RtcFastClock, RtcSlowClock},
 };
 

esp-hal/src/rtc_cntl/sleep/esp32c2.rs

@@ -1,7 +1,7 @@
 use super::{TimerWakeupSource, WakeSource, WakeTriggers, WakeupLevel};
 use crate::{
     gpio::{RtcFunction, RtcPinWithResistors},
-    regi2c_write_mask,
+    rom::regi2c_write_mask,
     rtc_cntl::{sleep::RtcioWakeupSource, Clock, Rtc, RtcClock},
 };
 

esp-hal/src/rtc_cntl/sleep/esp32c3.rs

@@ -1,7 +1,7 @@
 use super::{TimerWakeupSource, WakeSource, WakeTriggers, WakeupLevel};
 use crate::{
     gpio::{RtcFunction, RtcPinWithResistors},
-    regi2c_write_mask,
+    rom::regi2c_write_mask,
     rtc_cntl::{sleep::RtcioWakeupSource, Clock, Rtc, RtcClock},
 };
 

esp-hal/src/rtc_cntl/sleep/esp32s3.rs

@@ -8,7 +8,7 @@ use super::{
 };
 use crate::{
     gpio::{RtcFunction, RtcPin},
-    regi2c_write_mask,
+    rom::regi2c_write_mask,
     rtc_cntl::{sleep::RtcioWakeupSource, Clock, Rtc, RtcClock},
 };
 

esp-hal/src/soc/efuse_field.rs

@@ -110,6 +110,7 @@ impl Efuse {
     ///
     /// This function panics if the field's bit length is not equal to 1.
     #[inline(always)]
+    #[cfg_attr(not(feature = "unstable"), allow(unused))]
     pub fn read_bit(field: EfuseField) -> bool {
         assert_eq!(field.bit_len, 1);
         Self::read_field_le::<u8>(field) != 0

esp-hal/src/soc/esp32/mod.rs

@@ -9,14 +9,16 @@ use core::ptr::addr_of_mut;
 
 use crate::rtc_cntl::SocResetReason;
 
+crate::unstable_module! {
+    pub mod efuse;
+    #[cfg(feature = "quad-psram")]
+    pub mod psram;
+    pub mod radio_clocks;
+    pub mod trng;
+}
 pub mod cpu_control;
-pub mod efuse;
 pub mod gpio;
 pub mod peripherals;
-#[cfg(feature = "quad-psram")]
-pub mod psram;
-pub mod radio_clocks;
-pub mod trng;
 
 /// The name of the chip ("esp32") as `&str`
 #[macro_export]

esp-hal/src/soc/esp32c2/mod.rs

@@ -5,11 +5,13 @@
 //! The `SOC` module provides access, functions and structures that are useful
 //! for interacting with various system-related peripherals on `ESP32-C2` chip.
 
-pub mod efuse;
+crate::unstable_module! {
+    pub mod efuse;
+    pub mod radio_clocks;
+    pub mod trng;
+}
 pub mod gpio;
 pub mod peripherals;
-pub mod radio_clocks;
-pub mod trng;
 
 /// The name of the chip ("esp32c2") as `&str`
 #[macro_export]

esp-hal/src/soc/esp32c2/trng.rs

@@ -13,7 +13,7 @@ const ADC_SARADC_ENT_TSENS_ADDR: u8 = 0x07;
 const ADC_SARADC_ENT_TSENS_ADDR_MSB: u8 = 2;
 const ADC_SARADC_ENT_TSENS_ADDR_LSB: u8 = 2;
 
-use crate::regi2c_write_mask;
+use crate::rom::regi2c_write_mask;
 
 /// Enable true randomness by enabling the entropy source.
 /// Blocks `ADC` usage.

esp-hal/src/soc/esp32c3/mod.rs

@@ -9,11 +9,13 @@
 //!    * I2S_SCLK: 160_000_000 - I2S clock frequency
 //!    * I2S_DEFAULT_CLK_SRC: 2 - I2S clock source
 
-pub mod efuse;
+crate::unstable_module! {
+    pub mod efuse;
+    pub mod radio_clocks;
+    pub mod trng;
+}
 pub mod gpio;
 pub mod peripherals;
-pub mod radio_clocks;
-pub mod trng;
 
 /// The name of the chip ("esp32c3") as `&str`
 #[macro_export]

esp-hal/src/soc/esp32c3/trng.rs

@@ -13,7 +13,7 @@ const ADC_SARADC_ENT_TSENS_ADDR: u8 = 0x07;
 const ADC_SARADC_ENT_TSENS_ADDR_MSB: u8 = 2;
 const ADC_SARADC_ENT_TSENS_ADDR_LSB: u8 = 2;
 
-use crate::regi2c_write_mask;
+use crate::rom::regi2c_write_mask;
 
 /// Enable true randomness by enabling the entropy source.
 /// Blocks `ADC` usage.

esp-hal/src/soc/esp32c6/mod.rs

@@ -10,12 +10,14 @@
 //!    * I2S_DEFAULT_CLK_SRC: 2 - I2S clock source
 //!    * I2S_SCLK: 160_000_000 - I2S clock frequency
 
-pub mod efuse;
+crate::unstable_module! {
+    pub mod efuse;
+    pub mod lp_core;
+    pub mod radio_clocks;
+    pub mod trng;
+}
 pub mod gpio;
-pub mod lp_core;
 pub mod peripherals;
-pub mod radio_clocks;
-pub mod trng;
 
 /// The name of the chip ("esp32c6") as `&str`
 #[macro_export]

esp-hal/src/soc/esp32h2/mod.rs

@@ -10,11 +10,13 @@
 //!    * I2S_DEFAULT_CLK_SRC: 1 - I2S clock source
 //!    * I2S_SCLK: 96_000_000 - I2S clock frequency
 
-pub mod efuse;
+crate::unstable_module! {
+    pub mod efuse;
+    pub mod radio_clocks;
+    pub mod trng;
+}
 pub mod gpio;
 pub mod peripherals;
-pub mod radio_clocks;
-pub mod trng;
 
 /// The name of the chip ("esp32h2") as `&str`
 #[macro_export]

esp-hal/src/soc/esp32s2/mod.rs

@@ -13,15 +13,16 @@ use core::ptr::addr_of_mut;
 
 use crate::rtc_cntl::SocResetReason;
 
-pub mod efuse;
+crate::unstable_module! {
+    pub mod efuse;
+    #[cfg(feature = "quad-psram")]
+    pub mod psram;
+    pub mod radio_clocks;
+    pub mod trng;
+    pub mod ulp_core;
+}
 pub mod gpio;
 pub mod peripherals;
-#[cfg(feature = "quad-psram")]
-pub mod psram;
-pub mod radio_clocks;
-pub mod trng;
-
-pub mod ulp_core;
 
 /// The name of the chip ("esp32s2") as `&str`
 #[macro_export]

esp-hal/src/soc/esp32s3/mod.rs

@@ -13,16 +13,17 @@ use core::ptr::addr_of_mut;
 
 use crate::rtc_cntl::SocResetReason;
 
+crate::unstable_module! {
+    pub mod efuse;
+    #[cfg(any(feature = "quad-psram", feature = "octal-psram"))]
+    pub mod psram;
+    pub mod radio_clocks;
+    pub mod trng;
+    pub mod ulp_core;
+}
 pub mod cpu_control;
-pub mod efuse;
 pub mod gpio;
 pub mod peripherals;
-#[cfg(any(feature = "quad-psram", feature = "octal-psram"))]
-pub mod psram;
-pub mod radio_clocks;
-pub mod trng;
-
-pub mod ulp_core;
 
 /// The name of the chip ("esp32s3") as `&str`
 #[macro_export]

esp-hal/src/soc/esp32s3/trng.rs

@@ -15,7 +15,7 @@ const ADC_SARADC_DTEST_RTC_ADDR: u32 = 0x7;
 const ADC_SARADC_DTEST_RTC_ADDR_MSB: u32 = 1;
 const ADC_SARADC_DTEST_RTC_ADDR_LSB: u32 = 0;
 
-use crate::regi2c_write_mask;
+use crate::rom::regi2c_write_mask;
 
 /// Enable true randomness by enabling the entropy source.
 /// Blocks `ADC` usage.

esp-hal/src/soc/mod.rs

@@ -53,16 +53,20 @@ pub struct MappedPsram {
 // Values other than 0 indicate that we cannot attempt setting the mac address
 // again, and values other than 2 indicate that we should read the mac address
 // from eFuse.
+#[cfg_attr(not(feature = "unstable"), allow(unused))]
 static MAC_OVERRIDE_STATE: AtomicU8 = AtomicU8::new(0);
+#[cfg_attr(not(feature = "unstable"), allow(unused))]
 static mut MAC_OVERRIDE: [u8; 6] = [0; 6];
 
 /// Error indicating issues with setting the MAC address.
 #[derive(PartialEq, Eq, Copy, Clone, Debug)]
+#[cfg_attr(not(feature = "unstable"), allow(unused))]
 pub enum SetMacError {
     /// The MAC address has already been set and cannot be changed.
     AlreadySet,
 }
 
+#[cfg_attr(not(feature = "unstable"), allow(unused))]
 impl self::efuse::Efuse {
     /// Set the base mac address
     ///

esp-hal/src/spi/master.rs

@@ -95,6 +95,7 @@ use crate::{
 #[derive(Debug, Hash, EnumSetType)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
+#[instability::unstable]
 pub enum SpiInterrupt {
     /// Indicates that the SPI transaction has completed successfully.
     ///
@@ -704,6 +705,11 @@ where
     ///
     /// Sets the specified pin to push-pull output and connects it to the SPI CS
     /// signal.
+    ///
+    /// # Current Stability Limitations
+    /// The hardware chip select functionality is limited; only one CS line can
+    /// be set, regardless of the total number available. There is no
+    /// mechanism to select which CS line to use.
     #[instability::unstable]
     pub fn with_cs<CS: PeripheralOutput>(self, cs: impl Peripheral<P = CS> + 'd) -> Self {
         crate::into_mapped_ref!(cs);
@@ -741,6 +747,10 @@ where
     ///
     /// Enables both input and output functionality for the pin, and connects it
     /// to the SIO2 output and input signals.
+    ///
+    /// # Current Stability Limitations
+    /// QSPI operations are unstable, associated pins configuration is
+    /// inefficient.
     #[instability::unstable]
     pub fn with_sio2<SIO2: PeripheralOutput>(self, sio2: impl Peripheral<P = SIO2> + 'd) -> Self {
         // TODO: panic if not QSPI?
@@ -758,6 +768,10 @@ where
     ///
     /// Enables both input and output functionality for the pin, and connects it
     /// to the SIO3 output and input signals.
+    ///
+    /// # Current Stability Limitations
+    /// QSPI operations are unstable, associated pins configuration is
+    /// inefficient.
     #[instability::unstable]
     pub fn with_sio3<SIO3: PeripheralOutput>(self, sio3: impl Peripheral<P = SIO3> + 'd) -> Self {
         // TODO: panic if not QSPI?
@@ -3370,7 +3384,7 @@ macro_rules! master_instance {
             }
 
             fn handler(&self) -> InterruptHandler {
-                #[$crate::macros::handler]
+                #[$crate::handler]
                 #[cfg_attr(place_spi_driver_in_ram, ram)]
                 fn handle() {
                     handle_async(unsafe { $crate::peripherals::$peri::steal() })

esp-hal/src/timer/systimer.rs

@@ -429,7 +429,7 @@ impl Alarm {
 
             static mut HANDLERS: [Option<extern "C" fn()>; 3] = [None, None, None];
 
-            #[crate::macros::ram]
+            #[crate::ram]
             unsafe extern "C" fn _handle_interrupt<const CH: u8>() {
                 if unsafe { &*SYSTIMER::PTR }
                     .int_raw()

esp-hal/src/touch.rs

@@ -530,7 +530,8 @@ mod asynch {
     use super::*;
     use crate::{
         asynch::AtomicWaker,
-        macros::{handler, ram},
+        handler,
+        ram,
         Async,
     };
 

esp-hal/src/uart.rs

@@ -1040,6 +1040,7 @@ impl<'d> Uart<'d, Async> {
 #[derive(Debug, EnumSetType)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
+#[instability::unstable]
 pub enum UartInterrupt {
     /// Indicates that the received has detected the configured
     /// [`Uart::set_at_cmd`] character.
@@ -1238,21 +1239,25 @@ impl InterruptConfigurable for Uart<'_, Blocking> {
 
 impl Uart<'_, Blocking> {
     /// Listen for the given interrupts
+    #[instability::unstable]
     pub fn listen(&mut self, interrupts: impl Into<EnumSet<UartInterrupt>>) {
         self.tx.uart.info().enable_listen(interrupts.into(), true)
     }
 
     /// Unlisten the given interrupts
+    #[instability::unstable]
     pub fn unlisten(&mut self, interrupts: impl Into<EnumSet<UartInterrupt>>) {
         self.tx.uart.info().enable_listen(interrupts.into(), false)
     }
 
     /// Gets asserted interrupts
+    #[instability::unstable]
     pub fn interrupts(&mut self) -> EnumSet<UartInterrupt> {
         self.tx.uart.info().interrupts()
     }
 
     /// Resets asserted interrupts
+    #[instability::unstable]
     pub fn clear_interrupts(&mut self, interrupts: EnumSet<UartInterrupt>) {
         self.tx.uart.info().clear_interrupts(interrupts)
     }
@@ -1878,6 +1883,7 @@ pub(super) fn intr_handler(uart: &Info, state: &State) {
 
 /// Low-power UART
 #[cfg(lp_uart)]
+#[instability::unstable]
 pub mod lp_uart {
     use crate::{
         gpio::lp_io::{LowPowerInput, LowPowerOutput},
@@ -2510,7 +2516,7 @@ macro_rules! impl_instance {
     ($inst:ident, $peri:ident, $txd:ident, $rxd:ident, $cts:ident, $rts:ident) => {
         impl Instance for crate::peripherals::$inst {
             fn parts(&self) -> (&'static Info, &'static State) {
-                #[crate::macros::handler]
+                #[crate::handler]
                 pub(super) fn irq_handler() {
                     intr_handler(&PERIPHERAL, &STATE);
                 }

esp-ieee802154/src/raw.rs

@@ -2,8 +2,8 @@ use core::{cell::RefCell, ptr::addr_of};
 
 use critical_section::Mutex;
 use esp_hal::{
+    handler,
     interrupt::Priority,
-    macros::handler,
     peripherals::RADIO_CLK,
     system::{RadioClockController, RadioPeripherals},
 };

esp-wifi/src/ble/btdm.rs

@@ -13,7 +13,7 @@ use crate::{
         HCI_OUT_COLLECTOR,
     },
     compat::common::{self, str_from_c, ConcurrentQueue},
-    hal::macros::ram,
+    hal::ram,
 };
 
 #[cfg_attr(esp32c3, path = "os_adapter_esp32c3.rs")]

esp-wifi/src/common_adapter/common_adapter_esp32.rs

@@ -4,7 +4,7 @@ use super::phy_init_data::PHY_INIT_DATA_DEFAULT;
 use crate::{
     binary::include::*,
     hal::{
-        macros::ram,
+        ram,
         system::{RadioClockController, RadioPeripherals},
     },
 };

esp-wifi/src/common_adapter/common_adapter_esp32s2.rs

@@ -4,7 +4,7 @@ use super::phy_init_data::PHY_INIT_DATA_DEFAULT;
 use crate::{
     binary::include::*,
     hal::{
-        macros::ram,
+        ram,
         system::{RadioClockController, RadioPeripherals},
     },
 };

esp-wifi/src/common_adapter/mod.rs

@@ -1,5 +1,5 @@
 use esp_wifi_sys::include::timeval;
-use hal::macros::ram;
+use hal::ram;
 
 use crate::{
     binary::include::{esp_event_base_t, esp_timer_get_time},

esp-wifi/src/wifi/mod.rs

@@ -67,8 +67,8 @@ use crate::{
     common_adapter::*,
     esp_wifi_result,
     hal::{
-        macros::ram,
         peripheral::{Peripheral, PeripheralRef},
+        ram,
     },
     EspWifiController,
 };

examples/src/bin/debug_assist.rs

@@ -12,12 +12,7 @@ use core::cell::RefCell;
 
 use critical_section::Mutex;
 use esp_backtrace as _;
-use esp_hal::{
-    assist_debug::DebugAssist,
-    entry,
-    interrupt::InterruptConfigurable,
-    macros::handler,
-};
+use esp_hal::{assist_debug::DebugAssist, entry, handler, interrupt::InterruptConfigurable};
 use esp_println::println;
 
 static DA: Mutex<RefCell<Option<DebugAssist>>> = Mutex::new(RefCell::new(None));

examples/src/bin/flash_read_write.rs

@@ -3,7 +3,7 @@
 //! Uses flash address 0x9000 (default NVS)
 //! See https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/partition-tables.html#built-in-partition-tables
 
-//% FEATURES: esp-storage
+//% FEATURES: esp-storage esp-hal/unstable
 //% CHIPS: esp32 esp32c2 esp32c3 esp32c6 esp32h2 esp32s2 esp32s3
 
 #![no_std]

examples/src/bin/gpio_interrupt.rs

@@ -8,6 +8,7 @@
 //! - BUTTON => GPIO0 (ESP32, ESP32-S2, ESP32-S3) / GPIO9
 
 //% CHIPS: esp32 esp32c2 esp32c3 esp32c6 esp32h2 esp32s2 esp32s3
+//% FEATURES: esp-hal/unstable
 
 #![no_std]
 #![no_main]
@@ -20,8 +21,9 @@ use esp_hal::{
     delay::Delay,
     entry,
     gpio::{Event, Input, Io, Level, Output, Pull},
+    handler,
     interrupt::InterruptConfigurable,
-    macros::{handler, ram},
+    ram,
 };
 
 static BUTTON: Mutex<RefCell<Option<Input>>> = Mutex::new(RefCell::new(None));

examples/src/bin/lp_core_basic.rs

@@ -18,8 +18,8 @@ use esp_backtrace as _;
 use esp_hal::{
     entry,
     gpio::lp_io::LowPowerOutput,
+    load_lp_code,
     lp_core::{LpCore, LpCoreWakeupSource},
-    macros::load_lp_code,
 };
 use esp_println::{print, println};
 

examples/src/bin/touch.rs

@@ -20,8 +20,9 @@ use esp_hal::{
     delay::Delay,
     entry,
     gpio::GpioPin,
+    handler,
     interrupt::InterruptConfigurable,
-    macros::{handler, ram},
+    ram,
     rtc_cntl::Rtc,
     touch::{Continuous, Touch, TouchConfig, TouchPad},
     Blocking,

hil-test/tests/esp_wifi_floats.rs

@@ -12,8 +12,8 @@ use critical_section::Mutex;
 use esp_hal::{
     clock::CpuClock,
     delay::Delay,
+    handler,
     interrupt::software::{SoftwareInterrupt, SoftwareInterruptControl},
-    macros::handler,
     peripherals::Peripherals,
     rng::Rng,
     timer::timg::TimerGroup,

hil-test/tests/gpio.rs

@@ -7,19 +7,20 @@
 #![no_std]
 #![no_main]
 
+#[cfg(feature = "unstable")] // unused in stable build
 use core::cell::RefCell;
 
+#[cfg(feature = "unstable")] // unused in stable build
 use critical_section::Mutex;
 #[cfg(feature = "unstable")]
 use embassy_time::{Duration, Timer};
-use esp_hal::{
-    delay::Delay,
-    gpio::{AnyPin, Input, Level, Output, OutputOpenDrain, Pin, Pull},
-    macros::handler,
-};
+use esp_hal::gpio::{AnyPin, Input, Level, Output, Pin, Pull};
 #[cfg(feature = "unstable")]
 use esp_hal::{
-    gpio::{Event, Flex, Io},
+    // OutputOpenDrain is here because will be unused otherwise
+    delay::Delay,
+    gpio::{Event, Flex, Io, OutputOpenDrain},
+    handler,
     interrupt::InterruptConfigurable,
     timer::timg::TimerGroup,
 };
@@ -27,16 +28,20 @@ use hil_test as _;
 #[cfg(feature = "unstable")]
 use portable_atomic::{AtomicUsize, Ordering};
 
+#[cfg(feature = "unstable")] // unused in stable build
 static COUNTER: Mutex<RefCell<u32>> = Mutex::new(RefCell::new(0));
+#[cfg(feature = "unstable")] // unused in stable build
 static INPUT_PIN: Mutex<RefCell<Option<Input>>> = Mutex::new(RefCell::new(None));
 
 struct Context {
     test_gpio1: AnyPin,
     test_gpio2: AnyPin,
+    #[cfg(feature = "unstable")]
     delay: Delay,
 }
 
-#[handler]
+#[cfg_attr(feature = "unstable", handler)]
+#[cfg(feature = "unstable")]
 pub fn interrupt_handler() {
     critical_section::with(|cs| {
         *COUNTER.borrow_ref_mut(cs) += 1;
@@ -56,6 +61,7 @@ mod tests {
     fn init() -> Context {
         let peripherals = esp_hal::init(esp_hal::Config::default());
 
+        #[cfg(feature = "unstable")]
         let delay = Delay::new();
 
         let (gpio1, gpio2) = hil_test::common_test_pins!(peripherals);
@@ -74,6 +80,7 @@ mod tests {
         Context {
             test_gpio1: gpio1.degrade(),
             test_gpio2: gpio2.degrade(),
+            #[cfg(feature = "unstable")]
             delay,
         }
     }
@@ -244,6 +251,7 @@ mod tests {
     }
 
     #[test]
+    #[cfg(feature = "unstable")] // delay is unstable
     fn gpio_od(ctx: Context) {
         let mut test_gpio1 = OutputOpenDrain::new(ctx.test_gpio1, Level::High, Pull::Up);
         let mut test_gpio2 = OutputOpenDrain::new(ctx.test_gpio2, Level::High, Pull::Up);

hil-test/tests/gpio_custom_handler.rs

@@ -14,8 +14,8 @@
 use embassy_time::{Duration, Timer};
 use esp_hal::{
     gpio::{AnyPin, Flex, Input, Io, Level, Output, Pull},
+    handler,
     interrupt::InterruptConfigurable,
-    macros::handler,
     timer::timg::TimerGroup,
 };
 use hil_test as _;

hil-test/tests/systimer.rs

@@ -13,7 +13,7 @@ use critical_section::Mutex;
 use embedded_hal::delay::DelayNs;
 use esp_hal::{
     delay::Delay,
-    macros::handler,
+    handler,
     time::ExtU64,
     timer::{
         systimer::{Alarm, SystemTimer},

qa-test/src/bin/embassy_executor_benchmark.rs

@@ -16,7 +16,7 @@ use embassy_executor::{raw::TaskStorage, Spawner};
 use esp_backtrace as _;
 use esp_hal::{
     clock::{Clock, CpuClock},
-    macros::handler,
+    handler,
     time::Duration,
     timer::{systimer::SystemTimer, OneShotTimer},
 };

qa-test/src/bin/ram.rs

@@ -18,7 +18,7 @@
 #![no_main]
 
 use esp_backtrace as _;
-use esp_hal::{delay::Delay, entry, macros::ram, rtc_cntl::Rtc, time::ExtU64};
+use esp_hal::{delay::Delay, entry, ram, rtc_cntl::Rtc, time::ExtU64};
 use esp_println::println;
 
 #[ram(rtc_fast)]