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

Create newtypes for all PAC peripherals, mark unstable peripheral singletons #2957

Merged
merged 2 commits into from
Jan 17, 2025
Merged

Create newtypes for all PAC peripherals, mark unstable peripheral singletons #2957

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
20ad8d1
Create newtypes for all PAC peripherals, mark unstable peripheral sin…
bugadani Jan 15, 2025
9aefa35
Hide unstable singletons
bugadani Jan 16, 2025
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
1 change: 1 addition & 0 deletions esp-hal/src/aes/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -274,6 +274,7 @@ pub mod dma {
}

/// A DMA capable AES instance.
#[instability::unstable]
Copy link
Member

Choose a reason for hiding this comment

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

Is marking the the top level module unstable not enough? Just for future me's understanding :)

Copy link
Contributor Author

@bugadani bugadani Jan 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Something in the traits ends up not compiling because of some public reexport somewhere, it's a bit of a mess that I'm trying to untangle. (Specifically, without these we have Private type in public interface errors)

pub struct AesDma<'d> {
/// The underlying [`Aes`](super::Aes) driver
pub aes: super::Aes<'d>,
Expand Down
2 changes: 2 additions & 0 deletions esp-hal/src/parl_io.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -906,6 +906,7 @@ where
}

/// Parallel IO TX channel
#[instability::unstable]
pub struct ParlIoTx<'d, Dm>
where
Dm: DriverMode,
Expand Down Expand Up @@ -987,6 +988,7 @@ where
}

/// Parallel IO RX channel
#[instability::unstable]
pub struct ParlIoRx<'d, Dm>
where
Dm: DriverMode,
Expand Down
65 changes: 56 additions & 9 deletions esp-hal/src/peripheral.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -250,6 +250,11 @@ mod peripheral_macros {
$name:ident <= $from_pac:tt $(($($interrupt:ident),*))?
),* $(,)?
],
unstable_peripherals: [
$(
$unstable_name:ident <= $unstable_from_pac:tt $(($($unstable_interrupt:ident),*))?
),* $(,)?
],
pins: [
$( ( $pin:literal, $($pin_tokens:tt)* ) )*
],
Expand All @@ -260,12 +265,16 @@ mod peripheral_macros {
]
) => {


/// Contains the generated peripherals which implement [`Peripheral`]
mod peripherals {
pub use super::pac::*;
$(
$crate::create_peripheral!($name <= $from_pac);
)*
$(
$crate::create_peripheral!(#[instability::unstable] $unstable_name <= $unstable_from_pac);
)*
}

pub(crate) mod gpio {
Expand All @@ -280,7 +289,24 @@ mod peripheral_macros {
pub struct Peripherals {
$(
#[doc = concat!("The ", stringify!($name), " peripheral.")]
pub $name: peripherals::$name,
pub $name: $name,
)*
$(
#[doc = concat!("The ", stringify!($unstable_name), " peripheral.")]
#[doc = "**This API is marked as unstable** and is only available when the `unstable`
crate feature is enabled. This comes with no stability guarantees, and could be changed
or removed at any time."]
#[cfg(any(doc, feature = "unstable"))]
#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
pub $unstable_name: $unstable_name,

#[doc = concat!("The ", stringify!($unstable_name), " peripheral.")]
#[doc = "**This API is marked as unstable** and is only available when the `unstable`
crate feature is enabled. This comes with no stability guarantees, and could be changed
or removed at any time."]
#[cfg(not(any(doc, feature = "unstable")))]
#[allow(unused)]
pub(crate) $unstable_name: $unstable_name,
)*

$(
Expand Down Expand Up @@ -319,7 +345,10 @@ mod peripheral_macros {
pub unsafe fn steal() -> Self {
Self {
$(
$name: peripherals::$name::steal(),
$name: $name::steal(),
)*
$(
$unstable_name: $unstable_name::steal(),
)*

$(
Expand All @@ -334,17 +363,16 @@ mod peripheral_macros {
}
}

// expose the new structs
$(
pub use peripherals::$name;
)*
// expose the new structs, implement interrupt binder

$(
pub use peripherals::$name;
$(
impl peripherals::$name {
$(
paste::paste!{
/// Binds an interrupt handler to the corresponding interrupt for this peripheral.
#[instability::unstable]
pub fn [<bind_ $interrupt:lower _interrupt >](&mut self, handler: unsafe extern "C" fn() -> ()) {
unsafe { $crate::interrupt::bind_interrupt($crate::peripherals::Interrupt::$interrupt, handler); }
}
Expand All @@ -353,6 +381,24 @@ mod peripheral_macros {
}
)*
)*

$(
#[instability::unstable]
pub use peripherals::$unstable_name;
$(
impl peripherals::$unstable_name {
$(
paste::paste!{
/// Binds an interrupt handler to the corresponding interrupt for this peripheral.
#[instability::unstable]
pub fn [<bind_ $unstable_interrupt:lower _interrupt >](&mut self, handler: unsafe extern "C" fn() -> ()) {
unsafe { $crate::interrupt::bind_interrupt($crate::peripherals::Interrupt::$unstable_interrupt, handler); }
}
}
)*
}
)*
)*
};
}

Expand Down Expand Up @@ -382,7 +428,8 @@ mod peripheral_macros {
#[macro_export]
/// Macro to create a peripheral structure.
macro_rules! create_peripheral {
($name:ident <= virtual) => {
($(#[$attr:meta])? $name:ident <= virtual) => {
$(#[$attr])?
#[derive(Debug)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[non_exhaustive]
Expand Down Expand Up @@ -414,8 +461,8 @@ mod peripheral_macros {
impl $crate::private::Sealed for $name {}
};

($name:ident <= $base:ident) => {
$crate::create_peripheral!($name <= virtual);
($(#[$attr:meta])? $name:ident <= $base:ident) => {
$crate::create_peripheral!($(#[$attr])? $name <= virtual);

impl $name {
#[doc = r"Pointer to the register block"]
Expand Down
1 change: 1 addition & 0 deletions esp-hal/src/soc/esp32/cpu_control.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,6 +174,7 @@ unsafe fn internal_park_core(core: Cpu) {

impl<'d> CpuControl<'d> {
/// Creates a new instance of `CpuControl`.
#[instability::unstable]
pub fn new(cpu_control: impl Peripheral<P = CPU_CTRL> + 'd) -> CpuControl<'d> {
crate::into_ref!(cpu_control);

Expand Down
29 changes: 17 additions & 12 deletions esp-hal/src/soc/esp32/peripherals.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
//! from the PAC, allowing users to handle interrupts associated with these
//! peripherals.

use esp32 as pac;
pub(crate) use esp32 as pac;
// We need to export this for users to use
pub use pac::Interrupt;

Expand All @@ -21,6 +21,16 @@ pub(crate) use self::peripherals::*;
// creating "virtual peripherals" for them.
crate::peripherals! {
peripherals: [
I2C0 <= I2C0,
I2C1 <= I2C1,
IO_MUX <= IO_MUX,
SPI2 <= SPI2 (SPI2_DMA, SPI2),
SPI3 <= SPI3 (SPI3_DMA, SPI3),
UART0 <= UART0,
UART1 <= UART1,
UART2 <= UART2,
],
unstable_peripherals: [
ADC1 <= virtual,
ADC2 <= virtual,
AES <= AES,
Expand All @@ -30,46 +40,41 @@ crate::peripherals! {
CPU_CTRL <= virtual,
DAC1 <= virtual,
DAC2 <= virtual,
DPORT <= DPORT,
EFUSE <= EFUSE,
FLASH_ENCRYPTION <= FLASH_ENCRYPTION,
FRC_TIMER <= FRC_TIMER,
GPIO <= GPIO,
GPIO_SD <= GPIO_SD,
HINF <= HINF,
I2C0 <= I2C0,
I2C1 <= I2C1,
I2S0 <= I2S0 (I2S0),
I2S1 <= I2S1 (I2S1),
IO_MUX <= IO_MUX,
LEDC <= LEDC,
LPWR <= RTC_CNTL,
MCPWM0 <= MCPWM0,
MCPWM1 <= MCPWM1,
NRX <= NRX,
PCNT <= PCNT,
PSRAM <= virtual,
RADIO_CLK <= virtual,
RMT <= RMT,
RNG <= RNG,
RSA <= RSA,
LPWR <= RTC_CNTL,
RADIO_CLK <= virtual,
RTC_IO <= RTC_IO,
RTC_I2C <= RTC_I2C,
RTC_IO <= RTC_IO,
SDHOST <= SDHOST,
SENS <= SENS,
SHA <= SHA,
SLC <= SLC,
SLCHOST <= SLCHOST,
SPI0 <= SPI0,
SPI1 <= SPI1,
SPI2 <= SPI2 (SPI2_DMA, SPI2),
SPI3 <= SPI3 (SPI3_DMA, SPI3),
SYSTEM <= DPORT,
SW_INTERRUPT <= virtual,
TIMG0 <= TIMG0,
TIMG1 <= TIMG1,
TOUCH <= virtual,
TWAI0 <= TWAI0,
UART0 <= UART0,
UART1 <= UART1,
UART2 <= UART2,
UHCI0 <= UHCI0,
UHCI1 <= UHCI1,
WIFI <= WIFI,
Expand Down
19 changes: 13 additions & 6 deletions esp-hal/src/soc/esp32c2/peripherals.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
//! from the PAC, allowing users to handle interrupts associated with these
//! peripherals.

use esp32c2 as pac;
pub(crate) use esp32c2 as pac;
// We need to export this for users to use
pub use pac::Interrupt;

Expand All @@ -21,31 +21,38 @@ pub(crate) use self::peripherals::*;
// creating "virtual peripherals" for them.
crate::peripherals! {
peripherals: [
I2C0 <= I2C0,
IO_MUX <= IO_MUX,
SPI2 <= SPI2 (SPI2),
UART0 <= UART0,
UART1 <= UART1,
],
unstable_peripherals: [
ADC1 <= virtual,
APB_CTRL <= APB_CTRL,
APB_SARADC <= APB_SARADC,
ASSIST_DEBUG <= ASSIST_DEBUG,
BB <= BB,
BT <= virtual,
DMA <= DMA,
ECC <= ECC,
EFUSE <= EFUSE,
EXTMEM <= EXTMEM,
I2C0 <= I2C0,
GPIO <= GPIO,
INTERRUPT_CORE0 <= INTERRUPT_CORE0,
IO_MUX <= IO_MUX,
LEDC <= LEDC,
LPWR <= RTC_CNTL,
MODEM_CLKRST <= MODEM_CLKRST,
RADIO_CLK <= virtual,
RNG <= RNG,
SENSITIVE <= SENSITIVE,
SHA <= SHA,
SPI0 <= SPI0,
SPI1 <= SPI1,
SPI2 <= SPI2 (SPI2),
SYSTEM <= SYSTEM,
SYSTIMER <= SYSTIMER,
SW_INTERRUPT <= virtual,
TIMG0 <= TIMG0,
UART0 <= UART0,
UART1 <= UART1,
WIFI <= virtual,
XTS_AES <= XTS_AES,
MEM2MEM1 <= virtual,
Expand Down
21 changes: 15 additions & 6 deletions esp-hal/src/soc/esp32c3/peripherals.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
//! from the PAC, allowing users to handle interrupts associated with these
//! peripherals.

use esp32c3 as pac;
pub(crate) use esp32c3 as pac;
// We need to export this for users to use
pub use pac::Interrupt;

Expand All @@ -21,23 +21,35 @@ pub(crate) use self::peripherals::*;
// creating "virtual peripherals" for them.
crate::peripherals! {
peripherals: [
I2C0 <= I2C0,
IO_MUX <= IO_MUX,
SPI2 <= SPI2 (SPI2),
UART0 <= UART0,
UART1 <= UART1,
],
unstable_peripherals: [
ADC1 <= virtual,
ADC2 <= virtual,
AES <= AES,
APB_CTRL <= APB_CTRL,
APB_SARADC <= APB_SARADC,
ASSIST_DEBUG <= ASSIST_DEBUG,
BB <= BB,
BT <= virtual,
DMA <= DMA,
DS <= DS,
EFUSE <= EFUSE,
EXTMEM <= EXTMEM,
FE <= FE,
FE2 <= FE2,
GPIO <= GPIO,
GPIO_SD <= GPIO_SD,
HMAC <= HMAC,
I2C0 <= I2C0,
I2S0 <= I2S0 (I2S0),
INTERRUPT_CORE0 <= INTERRUPT_CORE0,
IO_MUX <= IO_MUX,
LEDC <= LEDC,
LPWR <= RTC_CNTL,
NRX <= NRX,
RADIO_CLK <= virtual,
RMT <= RMT,
RNG <= RNG,
Expand All @@ -46,16 +58,13 @@ crate::peripherals! {
SHA <= SHA,
SPI0 <= SPI0,
SPI1 <= SPI1,
SPI2 <= SPI2 (SPI2),
SYSTEM <= SYSTEM,
SYSTIMER <= SYSTIMER,
SW_INTERRUPT <= virtual,
TIMG0 <= TIMG0,
TIMG1 <= TIMG1,
TSENS <= virtual,
TWAI0 <= TWAI0,
UART0 <= UART0,
UART1 <= UART1,
UHCI0 <= UHCI0,
UHCI1 <= UHCI1,
USB_DEVICE <= USB_DEVICE,
Expand Down
Loading
Loading