Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Hide most of the unstable peripherals #2667

Merged
merged 8 commits into from
Dec 6, 2024
Merged

Hide most of the unstable peripherals #2667

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
19c62b0
Hide most of the unstable peripherals
bugadani Dec 2, 2024
9b07d5a
Lint with correct toolchain, lint with unstable enabled
bugadani Dec 3, 2024
9ce6e30
Require unstable feature and lint using it
bugadani Dec 3, 2024
6516769
Auto-lint xtensas with esp toolchain
bugadani Dec 3, 2024
3ab9e2c
Fix msrv and ieee802154
bugadani Dec 4, 2024
3a18f4d
Add feature to examples
bugadani Dec 4, 2024
e686ad8
Don't require building ieee802154 for all examples
bugadani Dec 4, 2024
eba09a3
Mark modules in documentation
bugadani Dec 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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: |
Expand Down
4 changes: 3 additions & 1 deletion esp-hal-embassy/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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
Expand Down
3 changes: 3 additions & 0 deletions esp-hal-embassy/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
//!
Expand Down
4 changes: 2 additions & 2 deletions esp-hal/src/dma/gdma.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -720,7 +720,7 @@ cfg_if::cfg_if! {
}
}

crate::impl_dma_eligible! {
crate::dma::impl_dma_eligible! {
AnyGdmaChannel {
#[cfg(spi2)]
SPI2 => Spi2,
Expand Down Expand Up @@ -764,7 +764,7 @@ crate::impl_dma_eligible! {
}

#[cfg(any(esp32c6, esp32h2))]
crate::impl_dma_eligible! {
crate::dma::impl_dma_eligible! {
AnyGdmaChannel {
MEM2MEM4 => Mem2Mem4,
MEM2MEM5 => Mem2Mem5,
Expand Down
8 changes: 5 additions & 3 deletions esp-hal/src/dma/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The weird pub use on macros is a solution to the following error:

error: macro-expanded `macro_export` macros from the current crate cannot be referred to by absolute paths
   --> C:\_Espressif\esp-hal\esp-hal\src\spi\master.rs:969:21
    |
969 |                     crate::as_mut_byte_array!(BUFFERS[id], 4)
    |                     ^^^^^^^^^^^^^^^^^^^^^^^^
    |
    = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
    = note: for more information, see issue #52234 <https://github.com/rust-lang/rust/issues/52234>
note: the macro is defined here
   --> C:\_Espressif\esp-hal\esp-hal\src\dma\mod.rs:554:1
    |
554 | / macro_rules! as_mut_byte_array {
555 | |     ($name:expr, $size:expr) => {
556 | |         unsafe { &mut *($name.as_mut_ptr() as *mut [u8; $size]) }
557 | |     };
558 | | }
    | |_^
    = note: `#[deny(macro_expanded_macro_exports_accessed_by_absolute_paths)]` on by default


/// Convenience macro to create DMA buffers and descriptors with specific chunk
/// size.
Expand Down Expand Up @@ -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),
)
}
Expand Down Expand Up @@ -1558,7 +1559,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 {
Expand All @@ -1577,11 +1577,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.
Expand Down
8 changes: 4 additions & 4 deletions esp-hal/src/dma/pdma.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -870,11 +870,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)]
Expand Down
138 changes: 82 additions & 56 deletions esp-hal/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)]
Expand All @@ -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;
bugadani marked this conversation as resolved.
Show resolved Hide resolved

$(#[$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 {
Expand Down Expand Up @@ -309,6 +334,7 @@ pub(crate) mod private {
}
}

#[cfg(feature = "unstable")]
#[doc(hidden)]
pub use private::Internal;

Expand Down
2 changes: 1 addition & 1 deletion esp-hal/src/spi/master.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -969,7 +969,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)
))
};

Expand Down
3 changes: 3 additions & 0 deletions esp-ieee802154/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
//!
Expand Down
2 changes: 2 additions & 0 deletions esp-wifi/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
3 changes: 3 additions & 0 deletions esp-wifi/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions examples/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,8 +52,8 @@ usbd-serial = "0.2.2"
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"]

Expand Down
1 change: 1 addition & 0 deletions examples/src/bin/debug_assist.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
2 changes: 1 addition & 1 deletion examples/src/bin/dma_extmem2mem.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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]
Expand Down
2 changes: 1 addition & 1 deletion examples/src/bin/dma_mem2mem.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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]
Expand Down
2 changes: 1 addition & 1 deletion examples/src/bin/embassy_hello_world.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
Loading
Loading