Hide most of the unstable peripherals (#2667)

* Hide most of the unstable peripherals * Lint with correct toolchain, lint with unstable enabled * Require unstable feature and lint using it * Auto-lint xtensas with esp toolchain * Fix msrv and ieee802154 * Add feature to examples * Don't require building ieee802154 for all examples * Mark modules in documentation
esp-rs · Dec 6, 2024 · 5135965 · 5135965
1 parent 6b01f79
commit 5135965
Show file tree

Hide file tree

Showing 54 changed files with 183 additions and 112 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -137,10 +137,10 @@ jobs:
 
       - name: msrv RISCV (esp-wifi)
         run: |
-          cargo xtask build-package --features=esp32c2,wifi,ble --target=riscv32imc-unknown-none-elf   esp-wifi
-          cargo xtask build-package --features=esp32c3,wifi,ble --target=riscv32imc-unknown-none-elf   esp-wifi
-          cargo xtask build-package --features=esp32c6,wifi,ble --target=riscv32imac-unknown-none-elf  esp-wifi
-          cargo xtask build-package --features=esp32h2,ble --target=riscv32imac-unknown-none-elf  esp-wifi
+          cargo xtask build-package --features=esp32c2,wifi,ble,esp-hal/unstable --target=riscv32imc-unknown-none-elf   esp-wifi
+          cargo xtask build-package --features=esp32c3,wifi,ble,esp-hal/unstable --target=riscv32imc-unknown-none-elf   esp-wifi
+          cargo xtask build-package --features=esp32c6,wifi,ble,esp-hal/unstable --target=riscv32imac-unknown-none-elf  esp-wifi
+          cargo xtask build-package --features=esp32h2,ble,esp-hal/unstable --target=riscv32imac-unknown-none-elf  esp-wifi
 
         # Verify the MSRV for all Xtensa chips:
       - name: msrv Xtensa (esp-hal)
@@ -151,9 +151,9 @@ jobs:
 
       - name: msrv Xtensa (esp-wifi)
         run: |
-          cargo xtask build-package --toolchain=esp --features=esp32,wifi,ble   --target=xtensa-esp32-none-elf   esp-wifi
-          cargo xtask build-package --toolchain=esp --features=esp32s2,wifi --target=xtensa-esp32s2-none-elf esp-wifi
-          cargo xtask build-package --toolchain=esp --features=esp32s3,wifi,ble --target=xtensa-esp32s3-none-elf esp-wifi
+          cargo xtask build-package --toolchain=esp --features=esp32,wifi,ble,esp-hal/unstable   --target=xtensa-esp32-none-elf   esp-wifi
+          cargo xtask build-package --toolchain=esp --features=esp32s2,wifi,esp-hal/unstable     --target=xtensa-esp32s2-none-elf esp-wifi
+          cargo xtask build-package --toolchain=esp --features=esp32s3,wifi,ble,esp-hal/unstable --target=xtensa-esp32s3-none-elf esp-wifi
 
       - name: msrv (esp-lp-hal)
         run: |

diff --git a/esp-hal-embassy/README.md b/esp-hal-embassy/README.md
@@ -8,6 +8,8 @@
 
 [Embassy] support for `esp-hal`.
 
+Note that this crate currently requires you to enable the `unstable` feature on `esp-hal`.
+
 [embassy]: https://github.com/embassy-rs/embassy
 
 ## [Documentation]
@@ -16,7 +18,7 @@
 
 ## Minimum Supported Rust Version (MSRV)
 
-This crate is guaranteed to compile on stable Rust 1.76 and up. It _might_
+This crate is guaranteed to compile on stable Rust 1.79 and up. It _might_
 compile with older versions but that may change in any new patch release.
 
 ## License

diff --git a/esp-hal-embassy/src/lib.rs b/esp-hal-embassy/src/lib.rs
@@ -4,6 +4,9 @@
 //! systems. This package provides support for building applications using
 //! Embassy with [esp-hal].
 //!
+//! Note that this crate currently requires you to enable the `unstable` feature
+//! on `esp-hal`.
+//!
 //! [esp-hal]: https://github.com/esp-rs/esp-hal
 //! [embassy]: https://github.com/embassy-rs/embassy
 //!

diff --git a/esp-hal/src/dma/gdma.rs b/esp-hal/src/dma/gdma.rs
@@ -732,7 +732,7 @@ cfg_if::cfg_if! {
     }
 }
 
-crate::impl_dma_eligible! {
+crate::dma::impl_dma_eligible! {
     AnyGdmaChannel {
         #[cfg(spi2)]
         SPI2 => Spi2,
@@ -776,7 +776,7 @@ crate::impl_dma_eligible! {
 }
 
 #[cfg(any(esp32c6, esp32h2))]
-crate::impl_dma_eligible! {
+crate::dma::impl_dma_eligible! {
     AnyGdmaChannel {
         MEM2MEM4 => Mem2Mem4,
         MEM2MEM5 => Mem2Mem5,

diff --git a/esp-hal/src/dma/mod.rs b/esp-hal/src/dma/mod.rs
@@ -556,6 +556,7 @@ macro_rules! as_mut_byte_array {
         unsafe { &mut *($name.as_mut_ptr() as *mut [u8; $size]) }
     };
 }
+pub use as_mut_byte_array; // TODO: can be removed as soon as DMA is stabilized
 
 /// Convenience macro to create DMA buffers and descriptors with specific chunk
 /// size.
@@ -670,7 +671,7 @@ macro_rules! dma_buffers_impl {
 
         unsafe {
             (
-                $crate::as_mut_byte_array!(BUFFER, $size),
+                $crate::dma::as_mut_byte_array!(BUFFER, $size),
                 $crate::dma_descriptors_impl!($size, $chunk_size, is_circular = $circular),
             )
         }
@@ -1553,7 +1554,6 @@ impl RxCircularState {
 }
 
 #[doc(hidden)]
-#[macro_export]
 macro_rules! impl_dma_eligible {
     ([$dma_ch:ident] $name:ident => $dma:ident) => {
         impl $crate::dma::DmaEligible for $crate::peripherals::$name {
@@ -1572,11 +1572,13 @@ macro_rules! impl_dma_eligible {
     ) => {
         $(
             $(#[$cfg])?
-            $crate::impl_dma_eligible!([$dma_ch] $name => $dma);
+            $crate::dma::impl_dma_eligible!([$dma_ch] $name => $dma);
         )*
     };
 }
 
+pub(crate) use impl_dma_eligible; // TODO: can be removed as soon as DMA is stabilized
+
 /// Helper type to get the DMA (Rx and Tx) channel for a peripheral.
 pub type PeripheralDmaChannel<T> = <T as DmaEligible>::Dma;
 /// Helper type to get the DMA Rx channel for a peripheral.

diff --git a/esp-hal/src/dma/pdma.rs b/esp-hal/src/dma/pdma.rs
@@ -920,11 +920,11 @@ ImplPdmaChannel!(AnyI2s, I2sRegisterBlock, I2s1, I2S1, [I2s1]);
 // Specific peripherals use specific channels. Note that this may be overly
 // restrictive (ESP32 allows configuring 2 SPI DMA channels between 3 different
 // peripherals), but for the current set of restrictions this is sufficient.
-crate::impl_dma_eligible!([Spi2DmaChannel] SPI2 => Spi2);
-crate::impl_dma_eligible!([Spi3DmaChannel] SPI3 => Spi3);
-crate::impl_dma_eligible!([I2s0DmaChannel] I2S0 => I2s0);
+crate::dma::impl_dma_eligible!([Spi2DmaChannel] SPI2 => Spi2);
+crate::dma::impl_dma_eligible!([Spi3DmaChannel] SPI3 => Spi3);
+crate::dma::impl_dma_eligible!([I2s0DmaChannel] I2S0 => I2s0);
 #[cfg(i2s1)]
-crate::impl_dma_eligible!([I2s1DmaChannel] I2S1 => I2s1);
+crate::dma::impl_dma_eligible!([I2s1DmaChannel] I2S1 => I2s1);
 
 pub(super) fn init_dma(_cs: CriticalSection<'_>) {
     #[cfg(esp32)]

diff --git a/esp-hal/src/lib.rs b/esp-hal/src/lib.rs
@@ -151,6 +151,7 @@ pub use xtensa_lx;
 #[cfg(xtensa)]
 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)]
@@ -163,88 +164,112 @@ pub use self::soc::psram;
 #[cfg(ulp_riscv_core)]
 pub use self::soc::ulp_core;
 
-#[cfg(aes)]
-pub mod aes;
-#[cfg(any(adc, dac))]
-pub mod analog;
-#[cfg(assist_debug)]
-pub mod assist_debug;
 #[cfg(any(dport, hp_sys, pcr, system))]
 pub mod clock;
 
 pub mod config;
 
 #[cfg(any(xtensa, all(riscv, systimer)))]
 pub mod delay;
-#[cfg(any(gdma, pdma))]
-pub mod dma;
-#[cfg(ecc)]
-pub mod ecc;
-#[cfg(soc_etm)]
-pub mod etm;
 #[cfg(gpio)]
 pub mod gpio;
-#[cfg(hmac)]
-pub mod hmac;
 #[cfg(any(i2c0, i2c1))]
 pub mod i2c;
-#[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)]
-pub mod ledc;
-#[cfg(any(mcpwm0, mcpwm1))]
-pub mod mcpwm;
-#[cfg(usb0)]
-pub mod otg_fs;
-#[cfg(parl_io)]
-pub mod parl_io;
-#[cfg(pcnt)]
-pub mod pcnt;
 pub mod peripheral;
 pub mod prelude;
 #[cfg(any(hmac, sha))]
 mod reg_access;
-#[cfg(any(lp_clkrst, rtc_cntl))]
-pub mod reset;
-#[cfg(rmt)]
-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;
 #[cfg(any(spi0, spi1, spi2, spi3))]
 pub mod spi;
-#[cfg(any(dport, hp_sys, pcr, system))]
-pub mod system;
-pub mod time;
-#[cfg(any(systimer, timg0, timg1))]
-pub mod timer;
-#[cfg(touch)]
-pub mod touch;
-#[cfg(trace0)]
-pub mod trace;
-#[cfg(any(twai0, twai1))]
-pub mod twai;
 #[cfg(any(uart0, uart1, uart2))]
 pub mod uart;
-#[cfg(usb_device)]
-pub mod usb_serial_jtag;
 
-pub mod debugger;
+pub mod macros;
+pub mod rom;
 
+pub mod debugger;
 #[doc(hidden)]
 pub mod sync;
+pub mod time;
 
-pub mod macros;
+// can't use instability on inline module definitions, see https://github.com/rust-lang/rust/issues/54727
+#[doc(hidden)]
+macro_rules! unstable {
+    ($(
+        $(#[$meta:meta])*
+        pub mod $module:ident;
+    )*) => {
+        $(
+            $(#[$meta])*
+            #[cfg(feature = "unstable")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
+            pub mod $module;
+
+            $(#[$meta])*
+            #[cfg(not(feature = "unstable"))]
+            #[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
+            #[allow(unused)]
+            pub(crate) mod $module;
+        )*
+    };
+}
+
+unstable! {
+    #[cfg(aes)]
+    pub mod aes;
+    #[cfg(any(adc, dac))]
+    pub mod analog;
+    #[cfg(assist_debug)]
+    pub mod assist_debug;
+    #[cfg(any(gdma, pdma))]
+    pub mod dma;
+    #[cfg(ecc)]
+    pub mod ecc;
+    #[cfg(soc_etm)]
+    pub mod etm;
+    #[cfg(hmac)]
+    pub mod hmac;
+    #[cfg(any(i2s0, i2s1))]
+    pub mod i2s;
+    #[cfg(lcd_cam)]
+    pub mod lcd_cam;
+    #[cfg(ledc)]
+    pub mod ledc;
+    #[cfg(any(mcpwm0, mcpwm1))]
+    pub mod mcpwm;
+    #[cfg(usb0)]
+    pub mod otg_fs;
+    #[cfg(parl_io)]
+    pub mod parl_io;
+    #[cfg(pcnt)]
+    pub mod pcnt;
+    #[cfg(any(lp_clkrst, rtc_cntl))]
+    pub mod reset;
+    #[cfg(rmt)]
+    pub mod rmt;
+    #[cfg(rng)]
+    pub mod rng;
+    #[cfg(rsa)]
+    pub mod rsa;
+    #[cfg(any(lp_clkrst, rtc_cntl))]
+    pub mod rtc_cntl;
+    #[cfg(sha)]
+    pub mod sha;
+    #[cfg(any(dport, hp_sys, pcr, system))]
+    pub mod system;
+    #[cfg(any(systimer, timg0, timg1))]
+    pub mod timer;
+    #[cfg(touch)]
+    pub mod touch;
+    #[cfg(trace0)]
+    pub mod trace;
+    #[cfg(any(twai0, twai1))]
+    pub mod twai;
+    #[cfg(usb_device)]
+    pub mod usb_serial_jtag;
+}
 
 /// State of the CPU saved when entering exception or interrupt
 pub mod trapframe {
@@ -309,6 +334,7 @@ pub(crate) mod private {
     }
 }
 
+#[cfg(feature = "unstable")]
 #[doc(hidden)]
 pub use private::Internal;
 

diff --git a/esp-hal/src/spi/master.rs b/esp-hal/src/spi/master.rs
@@ -971,7 +971,7 @@ mod dma {
 
                 unwrap!(DmaTxBuf::new(
                     unsafe { &mut DESCRIPTORS[id] },
-                    crate::as_mut_byte_array!(BUFFERS[id], 4)
+                    crate::dma::as_mut_byte_array!(BUFFERS[id], 4)
                 ))
             };
 

diff --git a/esp-ieee802154/src/lib.rs b/esp-ieee802154/src/lib.rs
@@ -6,6 +6,9 @@
 //! This library is intended to be used to implement support for higher-level
 //! communication protocols, for example [esp-openthread].
 //!
+//! Note that this crate currently requires you to enable the `unstable` feature
+//! on `esp-hal`.
+//!
 //! [IEEE 802.15.4]: https://en.wikipedia.org/wiki/IEEE_802.15.4
 //! [esp-openthread]: https://github.com/esp-rs/esp-openthread
 //!

diff --git a/esp-wifi/README.md b/esp-wifi/README.md
@@ -8,6 +8,8 @@
 
 A WiFi, BLE and ESP-NOW driver for Espressif microcontrollers.
 
+Note that this crate currently requires you to enable the `unstable` feature on `esp-hal`.
+
 ## Current support
 
 If a cell contains an em dash (&mdash;) this means that the particular feature is not present for a chip. A check mark (✓) means that some driver implementation exists. A Tilde (&tilde;) means it is implemented but buggy. An empty cell means that the feature is present in the chip but not implemented yet.

diff --git a/esp-wifi/src/lib.rs b/esp-wifi/src/lib.rs
@@ -17,6 +17,9 @@
 //!
 //! ### Importing
 //!
+//! Note that this crate currently requires you to enable the `unstable` feature
+//! on `esp-hal`.
+//!
 //! Ensure that the right features are enabled for your chip. See [Examples](https://github.com/esp-rs/esp-hal/tree/main/examples#examples) for more examples.
 //!
 //! ```toml

diff --git a/examples/Cargo.toml b/examples/Cargo.toml
@@ -56,8 +56,8 @@ edge-nal-embassy = "0.3.0"
 esp32   = ["esp-hal/esp32",   "esp-backtrace/esp32",   "esp-hal-embassy?/esp32",   "esp-println/esp32",   "esp-storage?/esp32",   "esp-wifi?/esp32"]
 esp32c2 = ["esp-hal/esp32c2", "esp-backtrace/esp32c2", "esp-hal-embassy?/esp32c2", "esp-println/esp32c2", "esp-storage?/esp32c2", "esp-wifi?/esp32c2", ]
 esp32c3 = ["esp-hal/esp32c3", "esp-backtrace/esp32c3", "esp-hal-embassy?/esp32c3", "esp-println/esp32c3", "esp-storage?/esp32c3", "esp-wifi?/esp32c3"]
-esp32c6 = ["esp-hal/esp32c6", "esp-backtrace/esp32c6", "esp-hal-embassy?/esp32c6", "esp-println/esp32c6", "esp-storage?/esp32c6", "esp-wifi?/esp32c6", "esp-ieee802154/esp32c6"]
-esp32h2 = ["esp-hal/esp32h2", "esp-backtrace/esp32h2", "esp-hal-embassy?/esp32h2", "esp-println/esp32h2", "esp-storage?/esp32h2", "esp-wifi?/esp32h2", "esp-ieee802154/esp32h2"]
+esp32c6 = ["esp-hal/esp32c6", "esp-backtrace/esp32c6", "esp-hal-embassy?/esp32c6", "esp-println/esp32c6", "esp-storage?/esp32c6", "esp-wifi?/esp32c6", "esp-ieee802154?/esp32c6"]
+esp32h2 = ["esp-hal/esp32h2", "esp-backtrace/esp32h2", "esp-hal-embassy?/esp32h2", "esp-println/esp32h2", "esp-storage?/esp32h2", "esp-wifi?/esp32h2", "esp-ieee802154?/esp32h2"]
 esp32s2 = ["esp-hal/esp32s2", "esp-backtrace/esp32s2", "esp-hal-embassy?/esp32s2", "esp-println/esp32s2", "esp-storage?/esp32s2", "esp-wifi?/esp32s2"]
 esp32s3 = ["esp-hal/esp32s3", "esp-backtrace/esp32s3", "esp-hal-embassy?/esp32s3", "esp-println/esp32s3", "esp-storage?/esp32s3", "esp-wifi?/esp32s3"]
 

diff --git a/examples/src/bin/debug_assist.rs b/examples/src/bin/debug_assist.rs
@@ -3,6 +3,7 @@
 //! Uncomment the functionality you want to test
 
 //% CHIPS: esp32c2 esp32c3 esp32c6 esp32h2 esp32s3
+//% FEATURES: esp-hal/unstable
 
 #![no_std]
 #![no_main]

diff --git a/examples/src/bin/dma_extmem2mem.rs b/examples/src/bin/dma_extmem2mem.rs
@@ -1,6 +1,6 @@
 //! Uses DMA to copy psram to internal memory.
 
-//% FEATURES: esp-hal/log esp-hal/octal-psram aligned
+//% FEATURES: esp-hal/log esp-hal/octal-psram aligned esp-hal/unstable
 //% CHIPS: esp32s3
 
 #![no_std]

diff --git a/examples/src/bin/dma_mem2mem.rs b/examples/src/bin/dma_mem2mem.rs
@@ -1,6 +1,6 @@
 //! Uses DMA to copy memory to memory.
 
-//% FEATURES: esp-hal/log
+//% FEATURES: esp-hal/log esp-hal/unstable
 //% CHIPS: esp32s3 esp32c2 esp32c3 esp32c6 esp32h2
 
 #![no_std]

diff --git a/examples/src/bin/embassy_hello_world.rs b/examples/src/bin/embassy_hello_world.rs
@@ -4,7 +4,7 @@
 //! concurrently.
 
 //% CHIPS: esp32 esp32c2 esp32c3 esp32c6 esp32h2 esp32s2 esp32s3
-//% FEATURES: embassy esp-hal-embassy/integrated-timers
+//% FEATURES: embassy esp-hal-embassy/integrated-timers esp-hal/unstable
 
 #![no_std]
 #![no_main]