Mark unstable APIs + make macros private

esp-rs · Jan 7, 2025 · a75c65f · a75c65f
1 parent b3401bf
commit a75c65f
Show file tree

Hide file tree

Showing 41 changed files with 126 additions and 102 deletions.
diff --git a/esp-hal-embassy/src/executor/thread.rs b/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};
 

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/i2c/master/mod.rs b/esp-hal/src/i2c/master/mod.rs
@@ -2288,7 +2288,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/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,

diff --git a/esp-hal/src/lib.rs b/esp-hal/src/lib.rs
@@ -167,17 +167,10 @@ 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 +179,13 @@ 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;
+pub use procmacros::{handler, ram};
 
 // can't use instability on inline module definitions, see https://github.com/rust-lang/rust/issues/54727
 #[doc(hidden)]
@@ -225,6 +218,10 @@ unstable_module! {
     pub mod analog;
     #[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 +232,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 +252,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)]
@@ -491,9 +494,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,
 };
 
@@ -512,9 +516,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,
 }
@@ -531,43 +539,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(any(doc, 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();
         }
     }

diff --git a/esp-hal/src/macros.rs b/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]

diff --git a/esp-hal/src/rmt.rs b/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,

diff --git a/esp-hal/src/rom/mod.rs b/esp-hal/src/rom/mod.rs
@@ -62,6 +62,8 @@ macro_rules! regi2c_write {
     };
 }
 
+pub use regi2c_write; // TODO: can be removed as soon as ROM is stabilized
+
 #[doc(hidden)]
 #[macro_export]
 macro_rules! regi2c_write_mask {
@@ -82,6 +84,8 @@ macro_rules! regi2c_write_mask {
     };
 }
 
+pub use regi2c_write_mask; // TODO: can be removed as soon as ROM is stabilized
+
 #[inline(always)]
 pub(crate) fn ets_delay_us(us: u32) {
     extern "C" {

diff --git a/esp-hal/src/rtc_cntl/rtc/esp32c2.rs b/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},
 };
 

diff --git a/esp-hal/src/rtc_cntl/rtc/esp32c3.rs b/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},
 };
 

diff --git a/esp-hal/src/rtc_cntl/sleep/esp32c2.rs b/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},
 };