Skip to content

Commit

Permalink
Create newtypes for all PAC peripherals, mark unstable peripheral sin…
Browse files Browse the repository at this point in the history 
…gletons (#2957)

* Create newtypes for all PAC peripherals, mark unstable peripheral singletons

* Hide unstable singletons
  • Loading branch information
@bugadani
bugadani authored Jan 17, 2025
1 parent 2105ba0 commit 40d552f
Show file tree
Hide file tree
Showing 12 changed files with 163 additions and 62 deletions.
1 change: 1 addition & 0 deletions esp-hal/src/aes/mod.rs
View file
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]
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
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
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
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
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
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
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

0 comments on commit 40d552f

Please sign in to comment.