From 9e93cf2cd0d9bedbb0f1a038bd29574a97b2c56d Mon Sep 17 00:00:00 2001 From: Kirill Mikhailov Date: Tue, 7 Jan 2025 13:42:36 +0100 Subject: [PATCH 1/7] Mark unstable APIs + make `macros` private --- esp-hal-embassy/src/executor/thread.rs | 2 +- esp-hal/src/analog/adc/xtensa.rs | 20 +-- esp-hal/src/clock/clocks_ll/esp32.rs | 2 +- esp-hal/src/clock/clocks_ll/esp32c2.rs | 3 +- esp-hal/src/clock/clocks_ll/esp32c3.rs | 3 +- esp-hal/src/dma/gdma.rs | 2 +- esp-hal/src/dma/pdma/mod.rs | 2 +- esp-hal/src/i2c/master/mod.rs | 2 +- esp-hal/src/lcd_cam/mod.rs | 2 +- esp-hal/src/lib.rs | 116 +++++++++++------- esp-hal/src/macros.rs | 3 - esp-hal/src/rmt.rs | 2 +- esp-hal/src/rom/mod.rs | 4 + esp-hal/src/rtc_cntl/rtc/esp32c2.rs | 2 +- esp-hal/src/rtc_cntl/rtc/esp32c3.rs | 2 +- esp-hal/src/rtc_cntl/sleep/esp32c2.rs | 2 +- esp-hal/src/rtc_cntl/sleep/esp32c3.rs | 2 +- esp-hal/src/rtc_cntl/sleep/esp32s3.rs | 2 +- esp-hal/src/soc/esp32c2/trng.rs | 2 +- esp-hal/src/soc/esp32c3/trng.rs | 2 +- esp-hal/src/soc/esp32s3/trng.rs | 2 +- esp-hal/src/spi/master.rs | 2 +- esp-hal/src/timer/systimer.rs | 2 +- esp-hal/src/touch.rs | 3 +- esp-hal/src/uart.rs | 2 +- esp-ieee802154/src/raw.rs | 2 +- esp-wifi/src/ble/btdm.rs | 2 +- .../common_adapter/common_adapter_esp32.rs | 2 +- .../common_adapter/common_adapter_esp32s2.rs | 2 +- esp-wifi/src/common_adapter/mod.rs | 2 +- esp-wifi/src/wifi/mod.rs | 2 +- examples/src/bin/debug_assist.rs | 7 +- examples/src/bin/gpio_interrupt.rs | 4 +- examples/src/bin/lp_core_basic.rs | 2 +- examples/src/bin/touch.rs | 3 +- hil-test/tests/esp_wifi_floats.rs | 2 +- hil-test/tests/gpio.rs | 2 +- hil-test/tests/gpio_custom_handler.rs | 2 +- hil-test/tests/systimer.rs | 2 +- qa-test/src/bin/embassy_executor_benchmark.rs | 2 +- qa-test/src/bin/ram.rs | 2 +- 41 files changed, 126 insertions(+), 102 deletions(-) diff --git a/esp-hal-embassy/src/executor/thread.rs b/esp-hal-embassy/src/executor/thread.rs index 47d826c6f90..e9f829fdc20 100644 --- 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 index f92b7406f09..069bc502d11 100644 --- 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 index 64fe67b2118..5547df5d590 100644 --- 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 index 6be34d8920a..1ddd459578f 100644 --- 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 index 264b2568675..6b1186f677e 100644 --- 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 index fb5f0447256..bfafc153cca 100644 --- 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 index 712607fe264..957f2bd61e6 100644 --- 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 index d090dba8970..eba3bcf078b 100644 --- a/esp-hal/src/i2c/master/mod.rs +++ b/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); } diff --git a/esp-hal/src/lcd_cam/mod.rs b/esp-hal/src/lcd_cam/mod.rs index 52e412471b6..0252f6114f5 100644 --- 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 index 1230738192e..a0e74a2c1a1 100644 --- 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)] @@ -493,9 +496,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 +518,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 +541,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::::new(); + timg0_wd.enable(); + timg0_wd.set_timeout(crate::timer::timg::MwdtStage::Stage0, duration); + } + WatchdogStatus::Disabled => { + crate::timer::timg::Wdt::::new().disable(); + } + } + + #[cfg(timg1)] + match config.watchdog.timg1 { + WatchdogStatus::Enabled(duration) => { + let mut timg1_wd = crate::timer::timg::Wdt::::new(); + timg1_wd.enable(); + timg1_wd.set_timeout(crate::timer::timg::MwdtStage::Stage0, duration); + } + WatchdogStatus::Disabled => { + crate::timer::timg::Wdt::::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::::new(); - timg0_wd.enable(); - timg0_wd.set_timeout(crate::timer::timg::MwdtStage::Stage0, duration); - } - WatchdogStatus::Disabled => { crate::timer::timg::Wdt::::new().disable(); - } - } - #[cfg(timg1)] - match config.watchdog.timg1 { - WatchdogStatus::Enabled(duration) => { - let mut timg1_wd = crate::timer::timg::Wdt::::new(); - timg1_wd.enable(); - timg1_wd.set_timeout(crate::timer::timg::MwdtStage::Stage0, duration); - } - WatchdogStatus::Disabled => { + #[cfg(timg1)] crate::timer::timg::Wdt::::new().disable(); } } diff --git a/esp-hal/src/macros.rs b/esp-hal/src/macros.rs index 0d3c3636c35..648a3959eef 100644 --- 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 index 4e756a8d85a..d2cc16ddd69 100644 --- 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 index 0dae4108380..bf7eef5cd9c 100644 --- 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 index f4763966e23..79fda721109 100644 --- 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 index 6a2249ccb5a..ab6de7c4188 100644 --- 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 index 9609ea5141f..940643ae6e2 100644 --- 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}, }; diff --git a/esp-hal/src/rtc_cntl/sleep/esp32c3.rs b/esp-hal/src/rtc_cntl/sleep/esp32c3.rs index 48a23fcec69..8d0bc69dc34 100644 --- a/esp-hal/src/rtc_cntl/sleep/esp32c3.rs +++ b/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}, }; diff --git a/esp-hal/src/rtc_cntl/sleep/esp32s3.rs b/esp-hal/src/rtc_cntl/sleep/esp32s3.rs index 44e8bd63899..550920e6a92 100644 --- a/esp-hal/src/rtc_cntl/sleep/esp32s3.rs +++ b/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}, }; diff --git a/esp-hal/src/soc/esp32c2/trng.rs b/esp-hal/src/soc/esp32c2/trng.rs index 92a565ae665..ff16a6a7112 100644 --- a/esp-hal/src/soc/esp32c2/trng.rs +++ b/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. diff --git a/esp-hal/src/soc/esp32c3/trng.rs b/esp-hal/src/soc/esp32c3/trng.rs index a1e7f5d281b..781d9f7fbf5 100644 --- a/esp-hal/src/soc/esp32c3/trng.rs +++ b/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. diff --git a/esp-hal/src/soc/esp32s3/trng.rs b/esp-hal/src/soc/esp32s3/trng.rs index fc98ddda813..67ca73c1af8 100644 --- a/esp-hal/src/soc/esp32s3/trng.rs +++ b/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. diff --git a/esp-hal/src/spi/master.rs b/esp-hal/src/spi/master.rs index 5840107ebb3..3d3fb3e75f2 100644 --- a/esp-hal/src/spi/master.rs +++ b/esp-hal/src/spi/master.rs @@ -3370,7 +3370,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() }) diff --git a/esp-hal/src/timer/systimer.rs b/esp-hal/src/timer/systimer.rs index 037171fb78f..83a1b1a468f 100644 --- a/esp-hal/src/timer/systimer.rs +++ b/esp-hal/src/timer/systimer.rs @@ -429,7 +429,7 @@ impl Alarm { static mut HANDLERS: [Option; 3] = [None, None, None]; - #[crate::macros::ram] + #[crate::ram] unsafe extern "C" fn _handle_interrupt() { if unsafe { &*SYSTIMER::PTR } .int_raw() diff --git a/esp-hal/src/touch.rs b/esp-hal/src/touch.rs index 09bb15926e5..8c7440aadc6 100644 --- a/esp-hal/src/touch.rs +++ b/esp-hal/src/touch.rs @@ -530,7 +530,8 @@ mod asynch { use super::*; use crate::{ asynch::AtomicWaker, - macros::{handler, ram}, + handler, + ram, Async, }; diff --git a/esp-hal/src/uart.rs b/esp-hal/src/uart.rs index 513fa135152..a08dddafb15 100644 --- a/esp-hal/src/uart.rs +++ b/esp-hal/src/uart.rs @@ -2510,7 +2510,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); } diff --git a/esp-ieee802154/src/raw.rs b/esp-ieee802154/src/raw.rs index 1afb3e505fe..21a8cc1077c 100644 --- a/esp-ieee802154/src/raw.rs +++ b/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}, }; diff --git a/esp-wifi/src/ble/btdm.rs b/esp-wifi/src/ble/btdm.rs index 0997ce1a5b5..8790b557f5a 100644 --- a/esp-wifi/src/ble/btdm.rs +++ b/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")] diff --git a/esp-wifi/src/common_adapter/common_adapter_esp32.rs b/esp-wifi/src/common_adapter/common_adapter_esp32.rs index 1be2d065260..f9596bad80b 100644 --- a/esp-wifi/src/common_adapter/common_adapter_esp32.rs +++ b/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}, }, }; diff --git a/esp-wifi/src/common_adapter/common_adapter_esp32s2.rs b/esp-wifi/src/common_adapter/common_adapter_esp32s2.rs index 825f073df69..0d716dee570 100644 --- a/esp-wifi/src/common_adapter/common_adapter_esp32s2.rs +++ b/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}, }, }; diff --git a/esp-wifi/src/common_adapter/mod.rs b/esp-wifi/src/common_adapter/mod.rs index 2a1e5d9da89..2223ea3a108 100644 --- a/esp-wifi/src/common_adapter/mod.rs +++ b/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}, diff --git a/esp-wifi/src/wifi/mod.rs b/esp-wifi/src/wifi/mod.rs index aee2f2281b1..8f804dba746 100644 --- a/esp-wifi/src/wifi/mod.rs +++ b/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, }; diff --git a/examples/src/bin/debug_assist.rs b/examples/src/bin/debug_assist.rs index 25198e0006e..288e58b920c 100644 --- a/examples/src/bin/debug_assist.rs +++ b/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>> = Mutex::new(RefCell::new(None)); diff --git a/examples/src/bin/gpio_interrupt.rs b/examples/src/bin/gpio_interrupt.rs index 1675738fb25..93f9331d5cc 100644 --- a/examples/src/bin/gpio_interrupt.rs +++ b/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>> = Mutex::new(RefCell::new(None)); diff --git a/examples/src/bin/lp_core_basic.rs b/examples/src/bin/lp_core_basic.rs index e771685eef3..3841ea493eb 100644 --- a/examples/src/bin/lp_core_basic.rs +++ b/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}; diff --git a/examples/src/bin/touch.rs b/examples/src/bin/touch.rs index 4d2dd715e1e..37de40be439 100644 --- a/examples/src/bin/touch.rs +++ b/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, diff --git a/hil-test/tests/esp_wifi_floats.rs b/hil-test/tests/esp_wifi_floats.rs index d5b2faab9c4..2e4de828bc6 100644 --- a/hil-test/tests/esp_wifi_floats.rs +++ b/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, diff --git a/hil-test/tests/gpio.rs b/hil-test/tests/gpio.rs index a2ee0b31228..d8f2a3a5058 100644 --- a/hil-test/tests/gpio.rs +++ b/hil-test/tests/gpio.rs @@ -15,7 +15,7 @@ use embassy_time::{Duration, Timer}; use esp_hal::{ delay::Delay, gpio::{AnyPin, Input, Level, Output, OutputOpenDrain, Pin, Pull}, - macros::handler, + handler, }; #[cfg(feature = "unstable")] use esp_hal::{ diff --git a/hil-test/tests/gpio_custom_handler.rs b/hil-test/tests/gpio_custom_handler.rs index 718b81df2fa..dd9494cd8eb 100644 --- a/hil-test/tests/gpio_custom_handler.rs +++ b/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 _; diff --git a/hil-test/tests/systimer.rs b/hil-test/tests/systimer.rs index b72156ef327..667b3ef619b 100644 --- a/hil-test/tests/systimer.rs +++ b/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}, diff --git a/qa-test/src/bin/embassy_executor_benchmark.rs b/qa-test/src/bin/embassy_executor_benchmark.rs index 77aa749e9e1..07855bbcbcc 100644 --- a/qa-test/src/bin/embassy_executor_benchmark.rs +++ b/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}, }; diff --git a/qa-test/src/bin/ram.rs b/qa-test/src/bin/ram.rs index 3dce40f3182..3a0b91aa55f 100644 --- a/qa-test/src/bin/ram.rs +++ b/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)] From c063fa1b39ef715ba95cfb60d6c46755f5b385f9 Mon Sep 17 00:00:00 2001 From: Kirill Mikhailov Date: Tue, 7 Jan 2025 17:14:54 +0100 Subject: [PATCH 2/7] address reviews --- esp-hal/CHANGELOG.md | 1 + esp-hal/MIGRATING-0.22.md | 10 ++++++++++ esp-hal/src/lib.rs | 9 ++++++--- esp-hal/src/rom/mod.rs | 10 ++++------ examples/src/bin/flash_read_write.rs | 2 +- 5 files changed, 22 insertions(+), 10 deletions(-) diff --git a/esp-hal/CHANGELOG.md b/esp-hal/CHANGELOG.md index dcc4525d676..48b30736426 100644 --- a/esp-hal/CHANGELOG.md +++ b/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) diff --git a/esp-hal/MIGRATING-0.22.md b/esp-hal/MIGRATING-0.22.md index 82f44edf65c..e52e10083ce 100644 --- a/esp-hal/MIGRATING-0.22.md +++ b/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}; +``` + diff --git a/esp-hal/src/lib.rs b/esp-hal/src/lib.rs index a0e74a2c1a1..f75e8079092 100644 --- a/esp-hal/src/lib.rs +++ b/esp-hal/src/lib.rs @@ -143,8 +143,6 @@ // MUST be the first module mod fmt; -pub mod asynch; - #[cfg(riscv)] pub use esp_riscv_rt::{self, entry, riscv}; #[cfg(xtensa)] @@ -156,13 +154,17 @@ pub use xtensa_lx_rt::{self, entry}; #[cfg(any(esp32, esp32s3))] pub use self::soc::cpu_control; #[cfg(efuse)] +#[cfg(feature = "unstable")] pub use self::soc::efuse; #[cfg(lp_core)] +#[cfg(feature = "unstable")] pub use self::soc::lp_core; pub use self::soc::peripherals; +#[cfg(feature = "unstable")] #[cfg(any(feature = "quad-psram", feature = "octal-psram"))] pub use self::soc::psram; #[cfg(ulp_riscv_core)] +#[cfg(feature = "unstable")] pub use self::soc::ulp_core; #[cfg(any(dport, hp_sys, pcr, system))] @@ -216,6 +218,7 @@ 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; @@ -543,7 +546,7 @@ pub fn init(config: Config) -> Peripherals { // Handle watchdog configuration with defaults cfg_if::cfg_if! { - if #[cfg(any(doc, feature = "unstable"))] + if #[cfg(feature = "unstable")] { #[cfg(not(any(esp32, esp32s2)))] if config.watchdog.swd { diff --git a/esp-hal/src/rom/mod.rs b/esp-hal/src/rom/mod.rs index bf7eef5cd9c..bcf681c3f98 100644 --- a/esp-hal/src/rom/mod.rs +++ b/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,10 +60,9 @@ macro_rules! regi2c_write { }; } -pub use regi2c_write; // TODO: can be removed as soon as ROM is stabilized +#[allow(unused_imports)] +pub(crate) use regi2c_write; -#[doc(hidden)] -#[macro_export] macro_rules! regi2c_write_mask { ( $block: ident, $reg_add: ident, $indata: expr ) => { paste::paste! { @@ -84,7 +81,8 @@ macro_rules! regi2c_write_mask { }; } -pub use regi2c_write_mask; // TODO: can be removed as soon as ROM is stabilized +#[allow(unused_imports)] +pub(crate) use regi2c_write_mask; #[inline(always)] pub(crate) fn ets_delay_us(us: u32) { diff --git a/examples/src/bin/flash_read_write.rs b/examples/src/bin/flash_read_write.rs index 81b53a8d013..93b4cea7a39 100644 --- a/examples/src/bin/flash_read_write.rs +++ b/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] From 72bac161f9bb7c1d0af42fa986dbc364e58c8065 Mon Sep 17 00:00:00 2001 From: Kirill Mikhailov Date: Wed, 8 Jan 2025 10:10:33 +0100 Subject: [PATCH 3/7] use `instability` instead of feature --- esp-hal/src/lib.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/esp-hal/src/lib.rs b/esp-hal/src/lib.rs index f75e8079092..772eaf2afb5 100644 --- a/esp-hal/src/lib.rs +++ b/esp-hal/src/lib.rs @@ -154,17 +154,17 @@ pub use xtensa_lx_rt::{self, entry}; #[cfg(any(esp32, esp32s3))] pub use self::soc::cpu_control; #[cfg(efuse)] -#[cfg(feature = "unstable")] +#[instability::unstable] pub use self::soc::efuse; #[cfg(lp_core)] -#[cfg(feature = "unstable")] +#[instability::unstable] pub use self::soc::lp_core; pub use self::soc::peripherals; -#[cfg(feature = "unstable")] +#[instability::unstable] #[cfg(any(feature = "quad-psram", feature = "octal-psram"))] pub use self::soc::psram; #[cfg(ulp_riscv_core)] -#[cfg(feature = "unstable")] +#[instability::unstable] pub use self::soc::ulp_core; #[cfg(any(dport, hp_sys, pcr, system))] From b8a9cd7205cd3da01fcdfe8ebdae6898813bc564 Mon Sep 17 00:00:00 2001 From: Kirill Mikhailov Date: Wed, 8 Jan 2025 12:43:17 +0100 Subject: [PATCH 4/7] fix dependencies --- esp-hal/src/lib.rs | 3 +++ esp-hal/src/soc/efuse_field.rs | 1 + esp-hal/src/soc/esp32/mod.rs | 12 +++++++----- esp-hal/src/soc/esp32c2/mod.rs | 8 +++++--- esp-hal/src/soc/esp32c3/mod.rs | 8 +++++--- esp-hal/src/soc/esp32c6/mod.rs | 10 ++++++---- esp-hal/src/soc/esp32h2/mod.rs | 8 +++++--- esp-hal/src/soc/esp32s2/mod.rs | 15 ++++++++------- esp-hal/src/soc/esp32s3/mod.rs | 15 ++++++++------- esp-hal/src/soc/mod.rs | 4 ++++ 10 files changed, 52 insertions(+), 32 deletions(-) diff --git a/esp-hal/src/lib.rs b/esp-hal/src/lib.rs index 772eaf2afb5..caf7bc689f5 100644 --- a/esp-hal/src/lib.rs +++ b/esp-hal/src/lib.rs @@ -155,9 +155,11 @@ pub use xtensa_lx_rt::{self, entry}; 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] @@ -165,6 +167,7 @@ pub use self::soc::peripherals; 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))] diff --git a/esp-hal/src/soc/efuse_field.rs b/esp-hal/src/soc/efuse_field.rs index cd27a2ed098..b3052b98329 100644 --- a/esp-hal/src/soc/efuse_field.rs +++ b/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::(field) != 0 diff --git a/esp-hal/src/soc/esp32/mod.rs b/esp-hal/src/soc/esp32/mod.rs index a4609a8032a..8beeae79eb4 100644 --- a/esp-hal/src/soc/esp32/mod.rs +++ b/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] diff --git a/esp-hal/src/soc/esp32c2/mod.rs b/esp-hal/src/soc/esp32c2/mod.rs index 93541428ec7..d59a916a349 100644 --- a/esp-hal/src/soc/esp32c2/mod.rs +++ b/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] diff --git a/esp-hal/src/soc/esp32c3/mod.rs b/esp-hal/src/soc/esp32c3/mod.rs index b8c5ae881ff..226451009d9 100644 --- a/esp-hal/src/soc/esp32c3/mod.rs +++ b/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] diff --git a/esp-hal/src/soc/esp32c6/mod.rs b/esp-hal/src/soc/esp32c6/mod.rs index 85040794775..604fb25c2bb 100644 --- a/esp-hal/src/soc/esp32c6/mod.rs +++ b/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] diff --git a/esp-hal/src/soc/esp32h2/mod.rs b/esp-hal/src/soc/esp32h2/mod.rs index 8eb9701de2b..127da29a989 100644 --- a/esp-hal/src/soc/esp32h2/mod.rs +++ b/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] diff --git a/esp-hal/src/soc/esp32s2/mod.rs b/esp-hal/src/soc/esp32s2/mod.rs index b85203c4d59..90d54f98644 100644 --- a/esp-hal/src/soc/esp32s2/mod.rs +++ b/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] diff --git a/esp-hal/src/soc/esp32s3/mod.rs b/esp-hal/src/soc/esp32s3/mod.rs index 69189e2d4b1..73464a419cc 100644 --- a/esp-hal/src/soc/esp32s3/mod.rs +++ b/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] diff --git a/esp-hal/src/soc/mod.rs b/esp-hal/src/soc/mod.rs index 562510e902d..06a9c016841 100644 --- a/esp-hal/src/soc/mod.rs +++ b/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 /// From bdd3b3f280c480f8b5cac227f20c22b5186f1e87 Mon Sep 17 00:00:00 2001 From: Kirill Mikhailov Date: Thu, 9 Jan 2025 14:49:15 +0100 Subject: [PATCH 5/7] More tagging --- esp-hal/src/gpio/mod.rs | 2 ++ esp-hal/src/i2c/mod.rs | 4 +++- esp-hal/src/lib.rs | 4 ++++ esp-hal/src/spi/master.rs | 14 ++++++++++++++ esp-hal/src/uart.rs | 6 ++++++ 5 files changed, 29 insertions(+), 1 deletion(-) diff --git a/esp-hal/src/gpio/mod.rs b/esp-hal/src/gpio/mod.rs index 9a32f316a64..2e87d47a9e3 100644 --- a/esp-hal/src/gpio/mod.rs +++ b/esp-hal/src/gpio/mod.rs @@ -1024,6 +1024,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/mod.rs b/esp-hal/src/i2c/mod.rs index 69d84bc5576..ec19dba62fd 100644 --- 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/lib.rs b/esp-hal/src/lib.rs index caf7bc689f5..5dd29337e9f 100644 --- a/esp-hal/src/lib.rs +++ b/esp-hal/src/lib.rs @@ -144,10 +144,13 @@ mod fmt; #[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? @@ -190,6 +193,7 @@ mod macros; #[cfg(feature = "unstable")] #[cfg_attr(docsrs, doc(cfg(feature = "unstable")))] pub use procmacros::load_lp_code; +#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))] pub use procmacros::{handler, ram}; // can't use instability on inline module definitions, see https://github.com/rust-lang/rust/issues/54727 diff --git a/esp-hal/src/spi/master.rs b/esp-hal/src/spi/master.rs index 3d3fb3e75f2..59bfe369ef5 100644 --- a/esp-hal/src/spi/master.rs +++ b/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(self, cs: impl Peripheral

+ '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(self, sio2: impl Peripheral

+ '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(self, sio3: impl Peripheral

+ 'd) -> Self { // TODO: panic if not QSPI? diff --git a/esp-hal/src/uart.rs b/esp-hal/src/uart.rs index a08dddafb15..f0402ecb10e 100644 --- a/esp-hal/src/uart.rs +++ b/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>) { self.tx.uart.info().enable_listen(interrupts.into(), true) } /// Unlisten the given interrupts + #[instability::unstable] pub fn unlisten(&mut self, interrupts: impl Into>) { self.tx.uart.info().enable_listen(interrupts.into(), false) } /// Gets asserted interrupts + #[instability::unstable] pub fn interrupts(&mut self) -> EnumSet { self.tx.uart.info().interrupts() } /// Resets asserted interrupts + #[instability::unstable] pub fn clear_interrupts(&mut self, interrupts: EnumSet) { 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}, From cec6425c8e3970d855a12f866277bf180178ee7a Mon Sep 17 00:00:00 2001 From: Kirill Mikhailov Date: Thu, 9 Jan 2025 15:14:42 +0100 Subject: [PATCH 6/7] `Persistable` and `procmacros` - unstable --- esp-hal/src/lib.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/esp-hal/src/lib.rs b/esp-hal/src/lib.rs index 5dd29337e9f..8612f42b2f2 100644 --- a/esp-hal/src/lib.rs +++ b/esp-hal/src/lib.rs @@ -194,6 +194,8 @@ mod macros; #[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 @@ -364,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 { @@ -381,6 +384,7 @@ impl_persistable!(atomic AtomicU8, AtomicI8, AtomicU16, AtomicI16, AtomicU32, At unsafe impl Persistable for [T; N] {} #[doc(hidden)] +#[instability::unstable] pub mod __macro_implementation { //! Unstable private implementation details of esp-hal-procmacros. From 6588f5429aaef2c4d265e7c90770a9a5ff33f065 Mon Sep 17 00:00:00 2001 From: Kirill Mikhailov Date: Thu, 9 Jan 2025 16:39:10 +0100 Subject: [PATCH 7/7] Adjust for changes --- hil-test/tests/gpio.rs | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/hil-test/tests/gpio.rs b/hil-test/tests/gpio.rs index d8f2a3a5058..aa0eb9a6c81 100644 --- a/hil-test/tests/gpio.rs +++ b/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::gpio::{AnyPin, Input, Level, Output, Pin, Pull}; +#[cfg(feature = "unstable")] use esp_hal::{ + // OutputOpenDrain is here because will be unused otherwise delay::Delay, - gpio::{AnyPin, Input, Level, Output, OutputOpenDrain, Pin, Pull}, + gpio::{Event, Flex, Io, OutputOpenDrain}, handler, -}; -#[cfg(feature = "unstable")] -use esp_hal::{ - gpio::{Event, Flex, Io}, 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> = Mutex::new(RefCell::new(0)); +#[cfg(feature = "unstable")] // unused in stable build static INPUT_PIN: Mutex>> = 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);