Rework hal initialization (#1970)

* Rework hal initialization

* Turn sw interrupt control into a virtual peripheral

* Return a tuple instead of a named struct

* Fix docs

* Remove SystemClockControl

* Move software interrupts under interrupt

* Re-document what's left in system

* Update time docs

* Update sw int docs

* Introduce Config

* Fix tests

* Remove redundant inits

* Doc

* Clean up examples&tests

* Update tests

* Add changelog entry

* Start migration guide

* Restore some convenience-imports

* Remove Config from prelude

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,6 +7,7 @@ To help us review it efficiently, please ensure you've gone through the followin
 - [ ] I have updated existing examples or added new ones (if applicable).
 - [ ] I have used `cargo xtask fmt-packages` command to ensure that all changed code is formatted correctly.
 - [ ] My changes were added to the [`CHANGELOG.md`](https://github.com/esp-rs/esp-hal/blob/main/esp-hal/CHANGELOG.md) in the **_proper_** section.
+- [ ] I have added necessary changes to user code to the [Migration Guide](https://github.com/esp-rs/esp-hal/blob/main/esp-hal/MIGRATING-0.21.md).
 - [ ] My changes are in accordance to the [esp-rs API guidelines](https://github.com/esp-rs/esp-hal/blob/main/documentation/API-GUIDELINES.md)
 
 #### Extra:

documentation/CONTRIBUTING.md

@@ -122,6 +122,7 @@ This will use `rustfmt` to ensure that all source code is formatted correctly pr
 *   [Link your PR] to any relevant issues it addresses.
 *   [Allow edits from maintainers] so the branch can be updated for a merge. Once you submit your PR, a Docs team member will review your proposal. We may ask questions or request additional information.
 *   Make sure you add an entry with your changes to the [Changelog]. Also make sure that it is in the appropriate section of the document.
+*   Make sure you add your changes to the current [migration guide].
 *   We may ask for changes to be made before a PR can be merged, either using [suggested changes] or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.
 *   As you update your PR and apply changes, mark each conversation as [resolved].
 *   Resolve merge conflicts if they arise, using resources like [this git tutorial] for help.
@@ -129,6 +130,7 @@ This will use `rustfmt` to ensure that all source code is formatted correctly pr
 [Link your PR]: https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue
 [Allow edits from maintainers]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-forkmember
 [Changelog]: esp-hal/CHANGELOG.md
+[migration guide]: esp-hal/MIGRATING-0.20.md
 [suggested changes]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request
 [resolved]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request#resolving-conversations
 [this git tutorial]: https://github.com/skills/resolve-merge-conflicts

esp-hal-embassy/src/executor/interrupt.rs

@@ -5,8 +5,7 @@ use core::{cell::UnsafeCell, mem::MaybeUninit};
 use embassy_executor::{raw, SendSpawner};
 use esp_hal::{
     get_core,
-    interrupt::{self, InterruptHandler},
+    interrupt::{self, software::SoftwareInterrupt, InterruptHandler},
-    system::SoftwareInterrupt,
 };
 use portable_atomic::{AtomicUsize, Ordering};
 

esp-hal-embassy/src/executor/mod.rs

@@ -5,7 +5,7 @@ mod thread;
 
 #[export_name = "__pender"]
 fn __pender(context: *mut ()) {
-    use esp_hal::system::SoftwareInterrupt;
+    use esp_hal::interrupt::software::SoftwareInterrupt;
 
     let context = (context as usize).to_le_bytes();
 

esp-hal-embassy/src/executor/thread.rs

@@ -77,7 +77,7 @@ This will use software-interrupt 3 which isn't available for anything else to wa
     pub fn new() -> Self {
         #[cfg(multi_core)]
         unsafe {
-            esp_hal::system::SoftwareInterrupt::<3>::steal()
+            esp_hal::interrupt::software::SoftwareInterrupt::<3>::steal()
                 .set_interrupt_handler(software3_interrupt)
         }
 

esp-hal/CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Added `esp_hal::init` to simplify HAL initialisation (#1970)
+
 ### Changed
 
 ### Fixed

esp-hal/MIGRATING-0.20.md

@@ -0,0 +1,26 @@
+Migration Guide from 0.20.x to vNext
+====================================
+
+HAL initialsation
+-----------------
+
+Instead of manually grabbing peripherals and setting up clocks, you should now call `esp_hal::init`.
+
+```diff
+ use esp_hal::{
+-    clock::ClockControl,
+-    peripherals::Peripherals,
+     prelude::*,
+-    system::SystemControl,
+ };
+ 
+ #[entry]
+ fn main() -> ! {
+-    let peripherals = Peripherals::take();
+-    let system = SystemControl::new(peripherals.SYSTEM);
+-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
++    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
+
+     // ...
+ }
+```

esp-hal/src/aes/mod.rs

@@ -28,26 +28,30 @@
 //! # let plaintext = b"message";
 //! # let mut keybuf = [0_u8; 16];
 //! # keybuf[..keytext.len()].copy_from_slice(keytext);
-//! let mut block_buf = [0_u8; 16];
+//! #
-//! block_buf[..plaintext.len()].copy_from_slice(plaintext);
+//! let mut block = [0_u8; 16];
-//! let mut block = block_buf.clone();
+//! block[..plaintext.len()].copy_from_slice(plaintext);
 //!
 //! let mut aes = Aes::new(peripherals.AES);
 //! aes.process(&mut block, Mode::Encryption128, keybuf);
-//! let hw_encrypted = block.clone();
+//!
+//! // The encryption happens in-place, so the ciphertext is in `block`
 //!
 //! aes.process(&mut block, Mode::Decryption128, keybuf);
-//! let hw_decrypted = block;
+//!
+//! // The decryption happens in-place, so the plaintext is in `block`
 //! # }
 //! ```
 //! 
 //! ### AES-DMA
+//!
 //! Visit the [AES-DMA] test for a more advanced example of using AES-DMA
 //! mode.
 //!
 //! [AES-DMA]: https://github.com/esp-rs/esp-hal/blob/main/hil-test/tests/aes_dma.rs
 //!
 //! ## Implementation State
+//!
 //! * AES-DMA mode is currently not supported on ESP32 and ESP32S2
 //! * AES-DMA Initialization Vector (IV) is currently not supported
 

esp-hal/src/analog/adc/mod.rs

@@ -32,7 +32,6 @@
 //! # use esp_hal::analog::adc::Adc;
 //! # use esp_hal::delay::Delay;
 //! # use esp_hal::gpio::Io;
-//!
 //! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 #![cfg_attr(esp32, doc = "let analog_pin = io.pins.gpio32;")]
 #![cfg_attr(any(esp32s2, esp32s3), doc = "let analog_pin = io.pins.gpio3;")]
@@ -41,8 +40,10 @@
     doc = "let analog_pin = io.pins.gpio2;"
 )]
 //! let mut adc1_config = AdcConfig::new();
-//! let mut pin = adc1_config.enable_pin(analog_pin,
+//! let mut pin = adc1_config.enable_pin(
-//!               Attenuation::Attenuation11dB);
+//!     analog_pin,
+//!     Attenuation::Attenuation11dB,
+//! );
 //! let mut adc1 = Adc::new(peripherals.ADC1, adc1_config);
 //!
 //! let mut delay = Delay::new(&clocks);
@@ -54,7 +55,9 @@
 //! }
 //! # }
 //! ```
+//! 
 //! ## Implementation State
+//!
 //!  - [ADC calibration is not implemented for all targets].
 //!
 //! [ADC calibration is not implemented for all targets]: https://github.com/esp-rs/esp-hal/issues/326

esp-hal/src/clock/mod.rs

@@ -13,20 +13,14 @@
 //! module clocks.
 //!
 //! ## Configuration
-//! Proper clock configuration is essential for the correct functioning of the
-//! microcontroller and its peripherals.
 //!
-//! The `Clock` driver supports configuring multiple clocks, including:
+//! During HAL initialization, specify a CPU clock speed to configure the
-//!   * CPU clock
+//! desired clock frequencies.
-//!   * APB (Advanced Peripheral Bus) clock
-//!   * XTAL (External Crystal) clock
-//!   * PLL (Phase Lock Loop) clock
-//!
-//! and other specific clocks based on the ESP microcontroller's architecture.
 //!
 //! The `CPU clock` is responsible for defining the speed at which the central
 //! processing unit (CPU) operates. This driver provides predefined options for
-//! different CPU clock speeds, such
+//! different CPU clock speeds, such as
+//!
 //!   * 80 MHz
 //!   * 96 MHz
 //!   * 120 MHz
@@ -35,52 +29,56 @@
 //!
 //! and others, depending on the microcontroller model.
 //!
-//! ### Clock Control
-//! The `ClockControl` struct allows users to configure the desired clock
-//! frequencies before applying them. It offers flexibility in selecting
-//! appropriate clock frequencies based on specific application requirements.
-//!
 //! ### Frozen Clock Frequencies
-//! Once the clock configuration is applied using the `freeze` function of the
+//!
-//! ClockControl struct, the clock frequencies become `frozen` and cannot be
+//! Once the clock configuration is applied, the clock frequencies become
-//! changed. The `Clocks` struct is returned after freezing, providing read-only
+//! `frozen` and cannot be changed. The `Clocks` struct is returned as part of
-//! access to the configured clock frequencies.
+//! the `System` struct, providing read-only access to the configured clock
+//! frequencies.
 //!
 //! ## Examples
+//!
 //! ### Initialize With Different Clock Frequencies
 //! ```rust, no_run
 //! # #![no_std]
-//! # use esp_hal::peripherals::Peripherals;
+//! # use esp_hal::prelude::*;
-//! # use esp_hal::clock::ClockControl;
-//! # use esp_hal::system::SystemControl;
 //! # #[panic_handler]
 //! # fn panic(_ : &core::panic::PanicInfo) -> ! {
 //! #     loop {}
 //! # }
 //! # fn main() {
-//! #   let peripherals = Peripherals::take();
-//! #   let system = SystemControl::new(peripherals.SYSTEM);
 //! // Initialize with the highest possible frequency for this chip
-//! let clocks = ClockControl::max(system.clock_control).freeze();
+//! let (peripherals, clocks) = esp_hal::init({
+//!     let mut config = esp_hal::Config::default();
+//!     config.cpu_clock = CpuClock::max();
+//!     config
+//! });
 //!
 //! // Initialize with custom clock frequency
-//! // let clocks = ClockControl::configure(system.clock_control, CpuClock::Clock160MHz).freeze();
+//! // let (peripherals, clocks) = esp_hal::init({
+//! //    let mut config = esp_hal::Config::default();
+#![cfg_attr(
+    not(any(esp32c2, esp32h2)),
+    doc = "//    config.cpu_clock = CpuClock::Clock160MHz;"
+)]
+#![cfg_attr(esp32c2, doc = "//    config.cpu_clock = CpuClock::Clock120MHz;")]
+#![cfg_attr(esp32h2, doc = "//    config.cpu_clock = CpuClock::Clock96MHz;")]
+//! //    config
+//! // });
 //! //
 //! // Initialize with default clock frequency for this chip
-//! // let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
+//! // let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
 //! # }
 //! ```
 
+use core::marker::PhantomData;
+
 use fugit::HertzU32;
 #[cfg(esp32c2)]
 use portable_atomic::{AtomicU32, Ordering};
 
 #[cfg(any(esp32, esp32c2))]
 use crate::rtc_cntl::RtcClock;
-use crate::{
-    peripheral::{Peripheral, PeripheralRef},
-    system::SystemClockControl,
-};
 
 #[cfg_attr(esp32, path = "clocks_ll/esp32.rs")]
 #[cfg_attr(esp32c2, path = "clocks_ll/esp32c2.rs")]
@@ -108,40 +106,63 @@ pub trait Clock {
 }
 
 /// CPU clock speed
-#[derive(Debug, Clone, Copy)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum CpuClock {
     /// 80MHz CPU clock
     #[cfg(not(esp32h2))]
-    Clock80MHz,
+    Clock80MHz  = 80,
+
     /// 96MHz CPU clock
     #[cfg(esp32h2)]
-    Clock96MHz,
+    Clock96MHz  = 96,
+
     /// 120MHz CPU clock
     #[cfg(esp32c2)]
-    Clock120MHz,
+    Clock120MHz = 120,
+
     /// 160MHz CPU clock
     #[cfg(not(any(esp32c2, esp32h2)))]
-    Clock160MHz,
+    Clock160MHz = 160,
+
     /// 240MHz CPU clock
     #[cfg(xtensa)]
-    Clock240MHz,
+    Clock240MHz = 240,
+}
+
+impl Default for CpuClock {
+    fn default() -> Self {
+        cfg_if::cfg_if! {
+            if #[cfg(esp32h2)] {
+                Self::Clock96MHz
+            } else {
+                // FIXME: I don't think this is correct in general?
+                Self::Clock80MHz
+            }
+        }
+    }
+}
+
+impl CpuClock {
+    /// Use the highest possible frequency for a particular chip.
+    pub const fn max() -> Self {
+        cfg_if::cfg_if! {
+            if #[cfg(esp32c2)] {
+                Self::Clock120MHz
+            } else if #[cfg(any(esp32c3, esp32c6))] {
+                Self::Clock160MHz
+            } else if #[cfg(esp32h2)] {
+                Self::Clock96MHz
+            } else {
+                Self::Clock240MHz
+            }
+        }
+    }
 }
 
-#[allow(dead_code)]
 impl Clock for CpuClock {
     fn frequency(&self) -> HertzU32 {
-        match self {
+        HertzU32::MHz(*self as u32)
-            #[cfg(not(esp32h2))]
-            CpuClock::Clock80MHz => HertzU32::MHz(80),
-            #[cfg(esp32h2)]
-            CpuClock::Clock96MHz => HertzU32::MHz(96),
-            #[cfg(esp32c2)]
-            CpuClock::Clock120MHz => HertzU32::MHz(120),
-            #[cfg(not(any(esp32c2, esp32h2)))]
-            CpuClock::Clock160MHz => HertzU32::MHz(160),
-            #[cfg(xtensa)]
-            CpuClock::Clock240MHz => HertzU32::MHz(240),
-        }
     }
 }
 
@@ -257,81 +278,65 @@ impl Clock for ApbClock {
 /// Frozen clock frequencies
 ///
 /// The instantiation of this type indicates that the clock configuration can no
-/// longer be changed
+/// longer be changed.
-pub struct Clocks<'d> {
+pub struct Clocks<'a> {
-    _private: PeripheralRef<'d, SystemClockControl>,
+    _private: PhantomData<&'a ()>,
-    /// CPU clock frequency
+    rates: RawClocks,
-    pub cpu_clock: HertzU32,
-    /// APB clock frequency
-    pub apb_clock: HertzU32,
-    /// XTAL clock frequency
-    pub xtal_clock: HertzU32,
-    /// I2C clock frequency
-    #[cfg(esp32)]
-    pub i2c_clock: HertzU32,
-    /// PWM clock frequency
-    #[cfg(esp32)]
-    pub pwm_clock: HertzU32,
-    /// Crypto PWM  clock frequency
-    #[cfg(esp32s3)]
-    pub crypto_pwm_clock: HertzU32,
-    /// Crypto clock frequency
-    #[cfg(any(esp32c6, esp32h2))]
-    pub crypto_clock: HertzU32,
-    /// PLL 48M clock frequency (fixed)
-    #[cfg(esp32h2)]
-    pub pll_48m_clock: HertzU32,
-    /// PLL 96M clock frequency (fixed)
-    #[cfg(esp32h2)]
-    pub pll_96m_clock: HertzU32,
 }
 
-#[doc(hidden)]
+impl<'a> Clocks<'a> {
-impl<'d> Clocks<'d> {
     /// This should not be used in user code.
     /// The whole point this exists is make it possible to have other crates
     /// (i.e. esp-wifi) create `Clocks`
     #[doc(hidden)]
-    pub fn from_raw_clocks(
+    pub(crate) fn from_raw_clocks(raw_clocks: RawClocks) -> Clocks<'a> {
-        system_clock_control: PeripheralRef<'d, SystemClockControl>,
-        raw_clocks: RawClocks,
-    ) -> Clocks<'d> {
         Self {
-            _private: system_clock_control,
+            _private: PhantomData,
-            cpu_clock: raw_clocks.cpu_clock,
+            rates: raw_clocks,
-            apb_clock: raw_clocks.apb_clock,
-            xtal_clock: raw_clocks.xtal_clock,
-            #[cfg(esp32)]
-            i2c_clock: raw_clocks.i2c_clock,
-            #[cfg(esp32)]
-            pwm_clock: raw_clocks.pwm_clock,
-            #[cfg(esp32s3)]
-            crypto_pwm_clock: raw_clocks.crypto_pwm_clock,
-            #[cfg(any(esp32c6, esp32h2))]
-            crypto_clock: raw_clocks.crypto_clock,
-            #[cfg(esp32h2)]
-            pll_48m_clock: raw_clocks.pll_48m_clock,
-            #[cfg(esp32h2)]
-            pll_96m_clock: raw_clocks.pll_96m_clock,
         }
     }
 }
 
-#[doc(hidden)]
+impl core::ops::Deref for Clocks<'_> {
+    type Target = RawClocks;
+
+    fn deref(&self) -> &RawClocks {
+        &self.rates
+    }
+}
+
+/// The list of the clock frequencies that are used in the system.
 pub struct RawClocks {
+    /// CPU clock frequency
     pub cpu_clock: HertzU32,
+
+    /// APB clock frequency
     pub apb_clock: HertzU32,
+
+    /// XTAL clock frequency
     pub xtal_clock: HertzU32,
+
+    /// I2C clock frequency
     #[cfg(esp32)]
     pub i2c_clock: HertzU32,
+
+    /// PWM clock frequency
     #[cfg(esp32)]
     pub pwm_clock: HertzU32,
+
+    /// Crypto PWM  clock frequency
     #[cfg(esp32s3)]
     pub crypto_pwm_clock: HertzU32,
+
+    /// Crypto clock frequency
     #[cfg(any(esp32c6, esp32h2))]
     pub crypto_clock: HertzU32,
+
+    /// PLL 48M clock frequency (fixed)
     #[cfg(esp32h2)]
     pub pll_48m_clock: HertzU32,
+
+    /// PLL 96M clock frequency (fixed)
     #[cfg(esp32h2)]
     pub pll_96m_clock: HertzU32,
 }
@@ -360,55 +365,34 @@ cfg_if::cfg_if! {
 ///
 /// After setting all frequencies, call the freeze function to apply the
 /// configuration.
-pub struct ClockControl<'d> {
+pub struct ClockControl {
-    _private: PeripheralRef<'d, SystemClockControl>,
     desired_rates: RawClocks,
 }
 
-impl<'d> ClockControl<'d> {
+impl ClockControl {
+    pub(crate) fn new(clock: CpuClock) -> Self {
+        Self::configure(clock)
+    }
+
     /// Applies the clock configuration and returns a Clocks struct that
     /// signifies that the clocks are frozen, and contains the frequencies
     /// used. After this function is called, the clocks can not change
-    pub fn freeze(self) -> Clocks<'d> {
+    pub fn freeze(self) -> Clocks<'static> {
-        Clocks::from_raw_clocks(self._private, self.desired_rates)
+        Clocks::from_raw_clocks(self.desired_rates)
     }
 }
 
 #[cfg(esp32)]
-impl<'d> ClockControl<'d> {
+impl ClockControl {
-    /// Use what is considered the default settings after boot.
-    pub fn boot_defaults(
-        clock_control: impl Peripheral<P = SystemClockControl> + 'd,
-    ) -> ClockControl<'d> {
-        let xtal_freq = if RtcClock::estimate_xtal_frequency() > 33 {
-            40
-        } else {
-            26
-        };
-
-        ClockControl {
-            _private: clock_control.into_ref(),
-            desired_rates: RawClocks {
-                cpu_clock: HertzU32::MHz(80),
-                apb_clock: HertzU32::MHz(80),
-                xtal_clock: HertzU32::MHz(xtal_freq),
-                i2c_clock: HertzU32::MHz(80),
-                pwm_clock: HertzU32::MHz(160),
-            },
-        }
-    }
-
     /// Configure the CPU clock speed.
-    pub fn configure(
+    pub(crate) fn configure(cpu_clock_speed: CpuClock) -> ClockControl {
-        clock_control: impl Peripheral<P = SystemClockControl> + 'd,
-        cpu_clock_speed: CpuClock,
-    ) -> ClockControl<'d> {
         let xtal_freq = if RtcClock::estimate_xtal_frequency() > 33 {
             XtalClock::RtcXtalFreq40M
         } else {
             XtalClock::RtcXtalFreq26M
         };
 
+        if cpu_clock_speed != CpuClock::default() {
             let pll_freq = match cpu_clock_speed {
                 CpuClock::Clock80MHz => PllClock::Pll320MHz,
                 CpuClock::Clock160MHz => PllClock::Pll320MHz,
@@ -419,13 +403,13 @@ impl<'d> ClockControl<'d> {
             clocks_ll::esp32_rtc_bbpll_enable();
             clocks_ll::esp32_rtc_bbpll_configure(xtal_freq, pll_freq);
             clocks_ll::set_cpu_freq(cpu_clock_speed);
+        }
 
         ClockControl {
-            _private: clock_control.into_ref(),
             desired_rates: RawClocks {
                 cpu_clock: cpu_clock_speed.frequency(),
                 apb_clock: HertzU32::MHz(80),
-                xtal_clock: HertzU32::MHz(40),
+                xtal_clock: HertzU32::MHz(xtal_freq.mhz()),
                 i2c_clock: HertzU32::MHz(80),
                 // The docs are unclear here. pwm_clock seems to be tied to clocks.apb_clock
                 // while simultaneously being fixed at 160 MHz.
@@ -434,43 +418,12 @@ impl<'d> ClockControl<'d> {
             },
         }
     }
-
-    /// Use the highest possible frequency for a particular chip
-    pub fn max(clock_control: impl Peripheral<P = SystemClockControl> + 'd) -> ClockControl<'d> {
-        Self::configure(clock_control, CpuClock::Clock240MHz)
-    }
 }
 
 #[cfg(esp32c2)]
-impl<'d> ClockControl<'d> {
+impl ClockControl {
-    /// Use what is considered the default settings after boot.
-    pub fn boot_defaults(
-        clock_control: impl Peripheral<P = SystemClockControl> + 'd,
-    ) -> ClockControl<'d> {
-        let xtal_freq = if RtcClock::estimate_xtal_frequency() > 33 {
-            40
-        } else {
-            26
-        };
-        XTAL_FREQ_MHZ.store(xtal_freq, Ordering::Relaxed);
-
-        ClockControl {
-            _private: clock_control.into_ref(),
-            desired_rates: RawClocks {
-                cpu_clock: HertzU32::MHz(80),
-                apb_clock: HertzU32::MHz(40),
-                xtal_clock: HertzU32::MHz(xtal_freq),
-            },
-        }
-    }
-
     /// Configure the CPU clock speed.
-    pub fn configure(
+    pub(crate) fn configure(cpu_clock_speed: CpuClock) -> ClockControl {
-        clock_control: impl Peripheral<P = SystemClockControl> + 'd,
-        cpu_clock_speed: CpuClock,
-    ) -> ClockControl<'d> {
-        let apb_freq;
-
         let xtal_freq = if RtcClock::estimate_xtal_frequency() > 33 {
             XtalClock::RtcXtalFreq40M
         } else {
@@ -478,6 +431,8 @@ impl<'d> ClockControl<'d> {
         };
         XTAL_FREQ_MHZ.store(xtal_freq.mhz(), Ordering::Relaxed);
 
+        let apb_freq;
+        if cpu_clock_speed != CpuClock::default() {
             let pll_freq = PllClock::Pll480MHz;
 
             if cpu_clock_speed.mhz() <= xtal_freq.mhz() {
@@ -491,9 +446,11 @@ impl<'d> ClockControl<'d> {
                 clocks_ll::esp32c2_rtc_freq_to_pll_mhz(cpu_clock_speed);
                 clocks_ll::esp32c2_rtc_apb_freq_update(apb_freq);
             }
+        } else {
+            apb_freq = ApbClock::ApbFreq40MHz;
+        }
 
         ClockControl {
-            _private: clock_control.into_ref(),
             desired_rates: RawClocks {
                 cpu_clock: cpu_clock_speed.frequency(),
                 apb_clock: apb_freq.frequency(),
@@ -501,52 +458,33 @@ impl<'d> ClockControl<'d> {
             },
         }
     }
-
-    /// Use the highest possible frequency for a particular chip
-    pub fn max(clock_control: impl Peripheral<P = SystemClockControl> + 'd) -> ClockControl<'d> {
-        Self::configure(clock_control, CpuClock::Clock120MHz)
-    }
 }
 
 #[cfg(esp32c3)]
-impl<'d> ClockControl<'d> {
+impl ClockControl {
-    /// Use what is considered the default settings after boot.
-    pub fn boot_defaults(
-        clock_control: impl Peripheral<P = SystemClockControl> + 'd,
-    ) -> ClockControl<'d> {
-        ClockControl {
-            _private: clock_control.into_ref(),
-            desired_rates: RawClocks {
-                cpu_clock: HertzU32::MHz(80),
-                apb_clock: HertzU32::MHz(80),
-                xtal_clock: HertzU32::MHz(40),
-            },
-        }
-    }
-
     /// Configure the CPU clock speed.
-    pub fn configure(
+    pub(crate) fn configure(cpu_clock_speed: CpuClock) -> ClockControl {
-        clock_control: impl Peripheral<P = SystemClockControl> + 'd,
-        cpu_clock_speed: CpuClock,
-    ) -> ClockControl<'d> {
-        let apb_freq;
         let xtal_freq = XtalClock::RtcXtalFreq40M;
-        let pll_freq = PllClock::Pll480MHz;
 
+        let apb_freq;
+        if cpu_clock_speed != CpuClock::default() {
             if cpu_clock_speed.mhz() <= xtal_freq.mhz() {
                 apb_freq = ApbClock::ApbFreqOther(cpu_clock_speed.mhz());
                 clocks_ll::esp32c3_rtc_update_to_xtal(xtal_freq, 1);
                 clocks_ll::esp32c3_rtc_apb_freq_update(apb_freq);
             } else {
+                let pll_freq = PllClock::Pll480MHz;
                 apb_freq = ApbClock::ApbFreq80MHz;
                 clocks_ll::esp32c3_rtc_bbpll_enable();
                 clocks_ll::esp32c3_rtc_bbpll_configure(xtal_freq, pll_freq);
                 clocks_ll::esp32c3_rtc_freq_to_pll_mhz(cpu_clock_speed);
                 clocks_ll::esp32c3_rtc_apb_freq_update(apb_freq);
             }
+        } else {
+            apb_freq = ApbClock::ApbFreq80MHz;
+        }
 
         ClockControl {
-            _private: clock_control.into_ref(),
             desired_rates: RawClocks {
                 cpu_clock: cpu_clock_speed.frequency(),
                 apb_clock: apb_freq.frequency(),
@@ -554,53 +492,33 @@ impl<'d> ClockControl<'d> {
             },
         }
     }
-
-    /// Use the highest possible frequency for a particular chip
-    pub fn max(clock_control: impl Peripheral<P = SystemClockControl> + 'd) -> ClockControl<'d> {
-        Self::configure(clock_control, CpuClock::Clock160MHz)
-    }
 }
 
 #[cfg(esp32c6)]
-impl<'d> ClockControl<'d> {
+impl ClockControl {
-    /// Use what is considered the default settings after boot.
-    pub fn boot_defaults(
-        clock_control: impl Peripheral<P = SystemClockControl> + 'd,
-    ) -> ClockControl<'d> {
-        ClockControl {
-            _private: clock_control.into_ref(),
-            desired_rates: RawClocks {
-                cpu_clock: HertzU32::MHz(80),
-                apb_clock: HertzU32::MHz(80),
-                xtal_clock: HertzU32::MHz(40),
-                crypto_clock: HertzU32::MHz(160),
-            },
-        }
-    }
-
     /// Configure the CPU clock speed.
-    pub fn configure(
+    pub(crate) fn configure(cpu_clock_speed: CpuClock) -> ClockControl {
-        clock_control: impl Peripheral<P = SystemClockControl> + 'd,
-        cpu_clock_speed: CpuClock,
-    ) -> ClockControl<'d> {
-        let apb_freq;
         let xtal_freq = XtalClock::RtcXtalFreq40M;
-        let pll_freq = PllClock::Pll480MHz;
 
+        let apb_freq;
+        if cpu_clock_speed != CpuClock::default() {
             if cpu_clock_speed.mhz() <= xtal_freq.mhz() {
                 apb_freq = ApbClock::ApbFreqOther(cpu_clock_speed.mhz());
                 clocks_ll::esp32c6_rtc_update_to_xtal(xtal_freq, 1);
                 clocks_ll::esp32c6_rtc_apb_freq_update(apb_freq);
             } else {
+                let pll_freq = PllClock::Pll480MHz;
                 apb_freq = ApbClock::ApbFreq80MHz;
                 clocks_ll::esp32c6_rtc_bbpll_enable();
                 clocks_ll::esp32c6_rtc_bbpll_configure(xtal_freq, pll_freq);
                 clocks_ll::esp32c6_rtc_freq_to_pll_mhz(cpu_clock_speed);
                 clocks_ll::esp32c6_rtc_apb_freq_update(apb_freq);
             }
+        } else {
+            apb_freq = ApbClock::ApbFreq80MHz;
+        }
 
         ClockControl {
-            _private: clock_control.into_ref(),
             desired_rates: RawClocks {
                 cpu_clock: cpu_clock_speed.frequency(),
                 apb_clock: apb_freq.frequency(),
@@ -609,55 +527,33 @@ impl<'d> ClockControl<'d> {
             },
         }
     }
-
-    /// Use the highest possible frequency for a particular chip
-    pub fn max(clock_control: impl Peripheral<P = SystemClockControl> + 'd) -> ClockControl<'d> {
-        Self::configure(clock_control, CpuClock::Clock160MHz)
-    }
 }
 
 #[cfg(esp32h2)]
-impl<'d> ClockControl<'d> {
+impl ClockControl {
-    /// Use what is considered the default settings after boot.
-    pub fn boot_defaults(
-        clock_control: impl Peripheral<P = SystemClockControl> + 'd,
-    ) -> ClockControl<'d> {
-        ClockControl {
-            _private: clock_control.into_ref(),
-            desired_rates: RawClocks {
-                cpu_clock: HertzU32::MHz(96),
-                apb_clock: HertzU32::MHz(32),
-                xtal_clock: HertzU32::MHz(32),
-                pll_48m_clock: HertzU32::MHz(48),
-                crypto_clock: HertzU32::MHz(96),
-                pll_96m_clock: HertzU32::MHz(96),
-            },
-        }
-    }
-
     /// Configure the CPU clock speed.
-    pub fn configure(
+    pub(crate) fn configure(cpu_clock_speed: CpuClock) -> ClockControl {
-        clock_control: impl Peripheral<P = SystemClockControl> + 'd,
-        cpu_clock_speed: CpuClock,
-    ) -> ClockControl<'d> {
-        let apb_freq;
         let xtal_freq = XtalClock::RtcXtalFreq32M;
-        let pll_freq = PllClock::Pll96MHz;
 
+        let apb_freq;
+        if cpu_clock_speed != CpuClock::default() {
             if cpu_clock_speed.mhz() <= xtal_freq.mhz() {
                 apb_freq = ApbClock::ApbFreqOther(cpu_clock_speed.mhz());
                 clocks_ll::esp32h2_rtc_update_to_xtal(xtal_freq, 1);
                 clocks_ll::esp32h2_rtc_apb_freq_update(apb_freq);
             } else {
+                let pll_freq = PllClock::Pll96MHz;
                 apb_freq = ApbClock::ApbFreq32MHz;
                 clocks_ll::esp32h2_rtc_bbpll_enable();
                 clocks_ll::esp32h2_rtc_bbpll_configure(xtal_freq, pll_freq);
                 clocks_ll::esp32h2_rtc_freq_to_pll_mhz(cpu_clock_speed);
                 clocks_ll::esp32h2_rtc_apb_freq_update(apb_freq);
             }
+        } else {
+            apb_freq = ApbClock::ApbFreq32MHz;
+        }
 
         ClockControl {
-            _private: clock_control.into_ref(),
             desired_rates: RawClocks {
                 cpu_clock: cpu_clock_speed.frequency(),
                 apb_clock: apb_freq.frequency(),
@@ -668,38 +564,17 @@ impl<'d> ClockControl<'d> {
             },
         }
     }
-
-    /// Use the highest possible frequency for a particular chip
-    pub fn max(clock_control: impl Peripheral<P = SystemClockControl> + 'd) -> ClockControl<'d> {
-        Self::configure(clock_control, CpuClock::Clock96MHz)
-    }
 }
 
 #[cfg(esp32s2)]
-impl<'d> ClockControl<'d> {
+impl ClockControl {
-    /// Use what is considered the default settings after boot.
-    pub fn boot_defaults(
-        clock_control: impl Peripheral<P = SystemClockControl> + 'd,
-    ) -> ClockControl<'d> {
-        ClockControl {
-            _private: clock_control.into_ref(),
-            desired_rates: RawClocks {
-                cpu_clock: HertzU32::MHz(80),
-                apb_clock: HertzU32::MHz(80),
-                xtal_clock: HertzU32::MHz(40),
-            },
-        }
-    }
-
     /// Configure the CPU clock speed.
-    pub fn configure(
+    pub(crate) fn configure(cpu_clock_speed: CpuClock) -> ClockControl {
-        clock_control: impl Peripheral<P = SystemClockControl> + 'd,
+        if cpu_clock_speed != CpuClock::default() {
-        cpu_clock_speed: CpuClock,
-    ) -> ClockControl<'d> {
             clocks_ll::set_cpu_clock(cpu_clock_speed);
+        }
 
         ClockControl {
-            _private: clock_control.into_ref(),
             desired_rates: RawClocks {
                 cpu_clock: cpu_clock_speed.frequency(),
                 apb_clock: HertzU32::MHz(80),
@@ -707,39 +582,17 @@ impl<'d> ClockControl<'d> {
             },
         }
     }
-
-    /// Use the highest possible frequency for a particular chip
-    pub fn max(clock_control: impl Peripheral<P = SystemClockControl> + 'd) -> ClockControl<'d> {
-        Self::configure(clock_control, CpuClock::Clock240MHz)
-    }
 }
 
 #[cfg(esp32s3)]
-impl<'d> ClockControl<'d> {
+impl ClockControl {
-    /// Use what is considered the default settings after boot.
-    pub fn boot_defaults(
-        clock_control: impl Peripheral<P = SystemClockControl> + 'd,
-    ) -> ClockControl<'d> {
-        ClockControl {
-            _private: clock_control.into_ref(),
-            desired_rates: RawClocks {
-                cpu_clock: HertzU32::MHz(80),
-                apb_clock: HertzU32::MHz(80),
-                xtal_clock: HertzU32::MHz(40),
-                crypto_pwm_clock: HertzU32::MHz(160),
-            },
-        }
-    }
-
     /// Configure the CPU clock speed.
-    pub fn configure(
+    pub(crate) fn configure(cpu_clock_speed: CpuClock) -> ClockControl {
-        clock_control: impl Peripheral<P = SystemClockControl> + 'd,
+        if cpu_clock_speed != CpuClock::default() {
-        cpu_clock_speed: CpuClock,
-    ) -> ClockControl<'d> {
             clocks_ll::set_cpu_clock(cpu_clock_speed);
+        }
 
         ClockControl {
-            _private: clock_control.into_ref(),
             desired_rates: RawClocks {
                 cpu_clock: cpu_clock_speed.frequency(),
                 apb_clock: HertzU32::MHz(80),
@@ -748,9 +601,4 @@ impl<'d> ClockControl<'d> {
             },
         }
     }
-
-    /// Use the highest possible frequency for a particular chip
-    pub fn max(clock_control: impl Peripheral<P = SystemClockControl> + 'd) -> ClockControl<'d> {
-        Self::configure(clock_control, CpuClock::Clock240MHz)
-    }
 }

esp-hal/src/delay.rs

@@ -1,16 +1,18 @@
 //! # Delay
 //!
 //! ## Overview
+//!
 //! The Delay driver provides blocking delay functionalities using the
-//! `SYSTIMER` peripheral for RISC-V devices and the built-in Xtensa timer for
+//! [current_time] function.
-//! Xtensa devices.
 //!
 //! ## Configuration
+//!
 //! The delays are implemented in a "best-effort" way, meaning that the CPU will
 //! block for at least the amount of time specified, but accuracy can be
 //! affected by many factors, including interrupt usage.
 //!
 //! ## Usage
+//!
 //! This module implements the blocking [DelayMs] and [DelayUs] traits from
 //! [embedded-hal], both 0.2.x and 1.x.x.
 //!
@@ -29,6 +31,7 @@
 //! [DelayMs]: embedded_hal_02::blocking::delay::DelayMs
 //! [DelayUs]: embedded_hal_02::blocking::delay::DelayUs
 //! [embedded-hal]: https://docs.rs/embedded-hal/1.0.0/embedded_hal/delay/index.html
+//! [current_time]: crate::time::current_time
 
 pub use fugit::MicrosDurationU64;
 

esp-hal/src/dma/mod.rs

@@ -21,7 +21,6 @@
 //! # use esp_hal::gpio::Io;
 //! # use esp_hal::spi::{master::Spi, SpiMode};
 //! # use esp_hal::dma::{Dma, DmaPriority};
-//! # use crate::esp_hal::prelude::_fugit_RateExtU32;
 //! let dma = Dma::new(peripherals.DMA);
 #![cfg_attr(any(esp32, esp32s2), doc = "let dma_channel = dma.spi2channel;")]
 #![cfg_attr(not(any(esp32, esp32s2)), doc = "let dma_channel = dma.channel0;")]
@@ -31,7 +30,12 @@
 //! let mosi = io.pins.gpio4;
 //! let cs = io.pins.gpio5;
 //!
-//! let mut spi = Spi::new(peripherals.SPI2, 100.kHz(), SpiMode::Mode0, &clocks)
+//! let mut spi = Spi::new(
+//!     peripherals.SPI2,
+//!     100.kHz(),
+//!     SpiMode::Mode0,
+//!     &clocks
+//! )
 //! .with_pins(Some(sclk), Some(mosi), Some(miso), Some(cs))
 //! .with_dma(dma_channel.configure(
 //!     false,
@@ -43,10 +47,10 @@
 //! ⚠️ Note: Descriptors should be sized as `(max_transfer_size + CHUNK_SIZE - 1) / CHUNK_SIZE`.
 //! I.e., to transfer buffers of size `1..=CHUNK_SIZE`, you need 1 descriptor.
 //!
-//! ⚠️ Note: For chips that support DMA to/from PSRAM (esp32s3) DMA transfers to/from PSRAM
+//! ⚠️ Note: For chips that support DMA to/from PSRAM (ESP32-S3) DMA transfers to/from PSRAM
 //! have extra alignment requirements. The address and size of the buffer pointed to by
 //! each descriptor must be a multiple of the cache line (block) size. This is 32 bytes
-//! on esp32s3.
+//! on ESP32-S3.
 //!
 //! For convenience you can use the [crate::dma_buffers] macro.
 
@@ -288,7 +292,7 @@ mod gdma;
 #[cfg(pdma)]
 mod pdma;
 
-/// Kinds of interrupt to listen to
+/// Kinds of interrupt to listen to.
 #[derive(EnumSetType)]
 pub enum DmaInterrupt {
     /// TX is done
@@ -297,15 +301,21 @@ pub enum DmaInterrupt {
     RxDone,
 }
 
-/// The default CHUNK_SIZE used for DMA transfers
+/// The default chunk size used for DMA transfers.
 pub const CHUNK_SIZE: usize = 4092;
 
-/// Convenience macro to create DMA buffers and descriptors
+/// Convenience macro to create DMA buffers and descriptors.
 ///
 /// ## Usage
-/// ```rust,ignore
+/// ```rust,no_run
-/// // TX and RX buffers are 32000 bytes - passing only one parameter makes TX and RX the same size
+#[doc = crate::before_snippet!()]
-/// let (tx_buffer, tx_descriptors, rx_buffer, rx_descriptors) = dma_buffers!(32000, 32000);
+/// use esp_hal::dma_buffers;
+///
+/// // TX and RX buffers are 32000 bytes - passing only one parameter makes TX
+/// // and RX the same size.
+/// let (tx_buffer, tx_descriptors, rx_buffer, rx_descriptors) =
+///     dma_buffers!(32000, 32000);
+/// # }
 /// ```
 #[macro_export]
 macro_rules! dma_buffers {
@@ -317,13 +327,18 @@ macro_rules! dma_buffers {
     };
 }
 
-/// Convenience macro to create circular DMA buffers and descriptors
+/// Convenience macro to create circular DMA buffers and descriptors.
 ///
 /// ## Usage
-/// ```rust,ignore
+/// ```rust,no_run
-/// // TX and RX buffers are 32000 bytes - passing only one parameter makes TX and RX the same size
+#[doc = crate::before_snippet!()]
+/// use esp_hal::dma_circular_buffers;
+///
+/// // TX and RX buffers are 32000 bytes - passing only one parameter makes TX
+/// // and RX the same size.
 /// let (tx_buffer, tx_descriptors, rx_buffer, rx_descriptors) =
 ///     dma_circular_buffers!(32000, 32000);
+/// # }
 /// ```
 #[macro_export]
 macro_rules! dma_circular_buffers {
@@ -336,12 +351,17 @@ macro_rules! dma_circular_buffers {
     };
 }
 
-/// Convenience macro to create DMA descriptors
+/// Convenience macro to create DMA descriptors.
 ///
 /// ## Usage
-/// ```rust,ignore
+/// ```rust,no_run
-/// // Create TX and RX descriptors for transactions up to 32000 bytes - passing only one parameter assumes TX and RX are the same size
+#[doc = crate::before_snippet!()]
+/// use esp_hal::dma_descriptors;
+///
+/// // Create TX and RX descriptors for transactions up to 32000 bytes - passing
+/// // only one parameter assumes TX and RX are the same size.
 /// let (tx_descriptors, rx_descriptors) = dma_descriptors!(32000, 32000);
+/// # }
 /// ```
 #[macro_export]
 macro_rules! dma_descriptors {
@@ -354,12 +374,18 @@ macro_rules! dma_descriptors {
     };
 }
 
-/// Convenience macro to create circular DMA descriptors
+/// Convenience macro to create circular DMA descriptors.
 ///
 /// ## Usage
-/// ```rust,ignore
+/// ```rust,no_run
-/// // Create TX and RX descriptors for transactions up to 32000 bytes - passing only one parameter assumes TX and RX are the same size
+#[doc = crate::before_snippet!()]
-/// let (tx_descriptors, rx_descriptors) = dma_circular_descriptors!(32000, 32000);
+/// use esp_hal::dma_circular_descriptors;
+///
+/// // Create TX and RX descriptors for transactions up to 32000
+/// // bytes - passing only one parameter assumes TX and RX are the same size.
+/// let (tx_descriptors, rx_descriptors) =
+///     dma_circular_descriptors!(32000, 32000);
+/// # }
 /// ```
 #[macro_export]
 macro_rules! dma_circular_descriptors {
@@ -373,12 +399,18 @@ macro_rules! dma_circular_descriptors {
 }
 
 /// Convenience macro to create DMA buffers and descriptors with specific chunk
-/// size
+/// size.
 ///
 /// ## Usage
-/// ```rust,ignore
+/// ```rust,no_run
-/// // TX and RX buffers are 32000 bytes - passing only one parameter makes TX and RX the same size
+#[doc = crate::before_snippet!()]
-/// let (tx_buffer, tx_descriptors, rx_buffer, rx_descriptors) = dma_buffers!(32000, 32000, 4032);
+/// use esp_hal::dma_buffers_chunk_size;
+///
+/// // TX and RX buffers are 32000 bytes - passing only one parameter makes TX
+/// // and RX the same size.
+/// let (tx_buffer, tx_descriptors, rx_buffer, rx_descriptors) =
+///     dma_buffers_chunk_size!(32000, 32000, 4032);
+/// # }
 /// ```
 #[macro_export]
 macro_rules! dma_buffers_chunk_size {
@@ -403,13 +435,18 @@ macro_rules! dma_buffers_chunk_size {
 }
 
 /// Convenience macro to create circular DMA buffers and descriptors with
-/// specific chunk size
+/// specific chunk size.
 ///
 /// ## Usage
-/// ```rust,ignore
+/// ```rust,no_run
-/// // TX and RX buffers are 32000 bytes - passing only one parameter makes TX and RX the same size
+#[doc = crate::before_snippet!()]
+/// use esp_hal::dma_circular_buffers_chunk_size;
+///
+/// // TX and RX buffers are 32000 bytes - passing only one parameter makes TX
+/// // and RX the same size.
 /// let (tx_buffer, tx_descriptors, rx_buffer, rx_descriptors) =
-///     dma_circular_buffers!(32000, 32000, 4032);
+///     dma_circular_buffers_chunk_size!(32000, 32000, 4032);
+/// # }
 /// ```
 #[macro_export]
 macro_rules! dma_circular_buffers_chunk_size {
@@ -436,9 +473,15 @@ macro_rules! dma_circular_buffers_chunk_size {
 /// Convenience macro to create DMA descriptors with specific chunk size
 ///
 /// ## Usage
-/// ```rust,ignore
+/// ```rust,no_run
-/// // Create TX and RX descriptors for transactions up to 32000 bytes - passing only one parameter assumes TX and RX are the same size
+#[doc = crate::before_snippet!()]
-/// let (tx_descriptors, rx_descriptors) = dma_descriptors_chunk_size!(32000, 32000, 4032);
+/// use esp_hal::dma_descriptors_chunk_size;
+///
+/// // Create TX and RX descriptors for transactions up to 32000 bytes - passing
+/// // only one parameter assumes TX and RX are the same size.
+/// let (tx_descriptors, rx_descriptors) =
+///     dma_descriptors_chunk_size!(32000, 32000, 4032);
+/// # }
 /// ```
 #[macro_export]
 macro_rules! dma_descriptors_chunk_size {
@@ -465,9 +508,15 @@ macro_rules! dma_descriptors_chunk_size {
 /// size
 ///
 /// ## Usage
-/// ```rust,ignore
+/// ```rust,no_run
-/// // Create TX and RX descriptors for transactions up to 32000 bytes - passing only one parameter assumes TX and RX are the same size
+#[doc = crate::before_snippet!()]
-/// let (tx_descriptors, rx_descriptors) = dma_circular_descriptors!(32000, 32000, 4032);
+/// use esp_hal::dma_circular_descriptors_chunk_size;
+///
+/// // Create TX and RX descriptors for transactions up to 32000 bytes - passing
+/// // only one parameter assumes TX and RX are the same size.
+/// let (tx_descriptors, rx_descriptors) =
+///     dma_circular_descriptors_chunk_size!(32000, 32000, 4032);
+/// # }
 /// ```
 #[macro_export]
 macro_rules! dma_circular_descriptors_chunk_size {

esp-hal/src/gpio/rtc_io.rs

@@ -1,10 +1,12 @@
 //! RTC IO
 //!
 //! # Overview
+//!
 //! The hardware provides a couple of GPIO pins with low power (LP)
 //! capabilities and analog functions.
 //!
 //! ## Configuration
+//!
 //! These pins can be controlled by either IO MUX or RTC IO.
 //!
 //! If controlled by RTC IO, these pins will bypass IO MUX and GPIO
@@ -14,12 +16,18 @@
 //! the peripherals in RTC system during chip Deep-sleep, and wake up the
 //! chip from Deep-sleep.
 //!
-//! # Example
+//! ## Example
-//! ## Configure a ULP Pin as Output
+//!
-//! ```rust, ignore
+//! ### Configure a ULP Pin as Output
+//!
+//! ```rust, no_run
+#![doc = crate::before_snippet!()]
+//! # use esp_hal::gpio::rtc_io::LowPowerOutput;
+//! # use esp_hal::gpio::Io;
 //! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 //! // configure GPIO 1 as ULP output pin
-//! let lp_pin = LowPowerOutput::new(io.pins.gpio1);
+//! let lp_pin = LowPowerOutput::<'static, 1>::new(io.pins.gpio1);
+//! # }
 //! ```
 
 use core::marker::PhantomData;

esp-hal/src/i2c.rs

@@ -5,54 +5,38 @@
 //! same bus. I2C uses two bidirectional open-drain lines: serial data line
 //! (SDA) and serial clock line (SCL), pulled up by resistors.
 //!
-//! Espressif devices sometimes have more than one I2C controller (also called
+//! Espressif devices sometimes have more than one I2C controller, responsible
-//! port), responsible for handling communication on the I2C bus. A single I2C
+//! for handling communication on the I2C bus. A single I2C controller can be
-//! controller can be a master or a slave.
+//! a master or a slave.
 //!
 //! Typically, an I2C slave device has a 7-bit address or 10-bit address.
-//! Espressif devices supports both I2C Standard-mode (Sm) and Fast-mode
+//! Devices supports both I2C Standard-mode (Sm) and Fast-mode (Fm) which can
-//! (Fm) which can go up to 100KHz and 400KHz respectively.
+//! go up to 100KHz and 400KHz respectively.
 //!
 //! ## Configuration
 //!
 //! Each I2C controller is individually configurable, and the usual setting
 //! such as frequency, timeout, and SDA/SCL pins can easily be configured.
 //!
-//! ```rust, no_run
-#![doc = crate::before_snippet!()]
-//! # use esp_hal::i2c::I2C;
-//! # use esp_hal::gpio::Io;
-//! # use crate::esp_hal::prelude::_fugit_RateExtU32;
-//! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
-//! // Create a new peripheral object with the described wiring
-//! // and standard I2C clock speed
-//! let mut i2c = I2C::new(
-//!     peripherals.I2C0,
-//!     io.pins.gpio1,
-//!     io.pins.gpio2,
-//!     100.kHz(),
-//!     &clocks,
-//! );
-//! # }
-//! ```
-//! 
 //! ## Usage
 //!
 //! The I2C driver implements a number of third-party traits, with the
 //! intention of making the HAL inter-compatible with various device drivers
 //! from the community. This includes the [embedded-hal] for both 0.2.x and
-//! 1.x.x versions.
+//! 1.0.x versions.
 //!
 //! ## Examples
+//!
 //! ### Read Data from a BMP180 Sensor
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::i2c::I2C;
 //! # use esp_hal::gpio::Io;
-//! # use crate::esp_hal::prelude::_fugit_RateExtU32;
 //! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
+//!
 //! // Create a new peripheral object with the described wiring
-//! // and standard I2C clock speed
+//! // and standard I2C clock speed.
 //! let mut i2c = I2C::new(
 //!     peripherals.I2C0,
 //!     io.pins.gpio1,
@@ -60,6 +44,7 @@
 //!     100.kHz(),
 //!     &clocks,
 //! );
+//!
 //! loop {
 //!     let mut data = [0u8; 22];
 //!     i2c.write_read(0x77, &[0xaa], &mut data).ok();

esp-hal/src/i2s.rs

@@ -1,14 +1,15 @@
 //! # Inter-IC Sound (I2S)
 //!
 //! ## Overview
+//!
 //! I2S (Inter-IC Sound) is a synchronous serial communication protocol usually
 //! used for transmitting audio data between two digital audio devices.
 //! Espressif devices may contain more than one I2S peripheral(s). These
 //! peripherals can be configured to input and output sample data via the I2S
 //! driver.
 //!
-//!
 //! ## Configuration
+//!
 //! I2S supports different data formats, including varying data and channel
 //! widths, different standards, such as the Philips standard and configurable
 //! pin mappings for I2S clock (BCLK), word select (WS), and data input/output
@@ -22,20 +23,19 @@
 //!   - `DMA`
 //!   - `system` (to configure and enable the I2S peripheral)
 //!
-//! ## Examples
+//! ## Example
+//!
 //! ### Initialization
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::i2s::I2s;
 //! # use esp_hal::i2s::Standard;
 //! # use esp_hal::i2s::DataFormat;
+//! # use esp_hal::i2s::I2sReadDma;
 //! # use esp_hal::gpio::Io;
 //! # use esp_hal::dma_buffers;
 //! # use esp_hal::dma::{Dma, DmaPriority};
-//! # use crate::esp_hal::prelude::_fugit_RateExtU32;
-//! # use crate::esp_hal::peripherals::Peripherals;
-//! # use crate::esp_hal::i2s::I2sReadDma;
-//! # use core::ptr::addr_of_mut;
 //! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 //! let dma = Dma::new(peripherals.DMA);
 #![cfg_attr(any(esp32, esp32s2), doc = "let dma_channel = dma.i2s0channel;")]

esp-hal/src/interrupt/mod.rs

@@ -30,20 +30,8 @@
 //!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
-//! # use core::cell::RefCell;
+//! let mut sw_int =
-//!
+//!     SoftwareInterruptControl::new(peripherals.SW_INTERRUPT);
-//! # use critical_section::Mutex;
-//! # use esp_hal::{
-//! #    prelude::*,
-//! #    system::{SoftwareInterrupt, SystemControl},
-//! # };
-//! # use esp_hal::interrupt::Priority;
-//! # use esp_hal::interrupt::InterruptHandler;
-//!
-//! static SWINT0: Mutex<RefCell<Option<SoftwareInterrupt<0>>>> =
-//! Mutex::new(RefCell::new(None));
-//!
-//! let mut sw_int = system.software_interrupt_control;
 //! critical_section::with(|cs| {
 //!     sw_int
 //!         .software_interrupt0
@@ -56,17 +44,21 @@
 //! critical_section::with(|cs| {
 //!     SWINT0.borrow_ref(cs).as_ref().unwrap().raise();
 //! });
+//! #
+//! # loop {}
+//! # }
 //!
-//!     loop {}
-//! }
-//!
-//! # use procmacros::handler;
-//! # use esp_hal::interrupt;
-//! # use critical_section::Mutex;
 //! # use core::cell::RefCell;
-//! # use esp_hal::system::SoftwareInterrupt;
+//! #
-//! # static SWINT0: Mutex<RefCell<Option<SoftwareInterrupt<0>>>> = Mutex::new(RefCell::new(None));
+//! # use critical_section::Mutex;
-//! #[handler(priority = esp_hal::interrupt::Priority::Priority1)]
+//! # use esp_hal::interrupt::software::{SoftwareInterrupt, SoftwareInterruptControl};
+//! # use esp_hal::interrupt::Priority;
+//! # use esp_hal::interrupt::InterruptHandler;
+//! #
+//! static SWINT0: Mutex<RefCell<Option<SoftwareInterrupt<0>>>> =
+//!     Mutex::new(RefCell::new(None));
+//!
+//! #[handler(priority = Priority::Priority1)]
 //! fn swint0_handler() {
 //!     // esp_println::println!("SW interrupt0");
 //!     critical_section::with(|cs| {
@@ -87,6 +79,8 @@ mod riscv;
 #[cfg(xtensa)]
 mod xtensa;
 
+pub mod software;
+
 /// An interrupt handler
 #[cfg_attr(
     multi_core,

esp-hal/src/interrupt/software.rs

@@ -0,0 +1,192 @@
+//! # Software Interrupts
+//!
+//! The [`SoftwareInterruptControl`] struct gives access to the available
+//! software interrupts.
+//!
+//! The [`SoftwareInterrupt`] struct allows raising or resetting software
+//! interrupts using the [`raise()`][SoftwareInterrupt::raise] and
+//! [`reset()`][SoftwareInterrupt::reset] methods.
+//!
+//! ## Examples
+//!
+//! ```rust, no_run
+#![doc = crate::before_snippet!()]
+//! let sw_ints =
+//!     SoftwareInterruptControl::new(peripherals.SW_INTERRUPT);
+//!
+//! // Take the interrupt you want to use.
+//! let mut int0 = sw_ints.software_interrupt0;
+//!
+//! // Set up the interrupt handler. Do this in a critical section so the global
+//! // contains the interrupt object before the interrupt is triggered.
+//! critical_section::with(|cs| {
+//!     int0.set_interrupt_handler(interrupt_handler);
+//!     SWINT0.borrow_ref_mut(cs).replace(int0);
+//! });
+//! # }
+//!
+//! # use core::cell::RefCell;
+//! # use critical_section::Mutex;
+//! # use esp_hal::interrupt::software::{SoftwareInterrupt, SoftwareInterruptControl};
+//! // ... somewhere outside of your main function
+//!
+//! // Define a shared handle to the software interrupt.
+//! static SWINT0: Mutex<RefCell<Option<SoftwareInterrupt<0>>>> =
+//!     Mutex::new(RefCell::new(None));
+//!
+//! #[handler]
+//! fn interrupt_handler() {
+//!     // esp_println::println!("SW interrupt0 handled");
+//!
+//!     // Clear the interrupt request.
+//!     critical_section::with(|cs| {
+//!         SWINT0.borrow_ref(cs).as_ref().unwrap().reset();
+//!     });
+//! }
+//! ```
+
+use crate::{interrupt::InterruptHandler, InterruptConfigurable};
+
+/// A software interrupt can be triggered by software.
+#[non_exhaustive]
+pub struct SoftwareInterrupt<const NUM: u8>;
+
+impl<const NUM: u8> SoftwareInterrupt<NUM> {
+    /// Sets the interrupt handler for this software-interrupt
+    pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
+        let interrupt = match NUM {
+            0 => crate::peripherals::Interrupt::FROM_CPU_INTR0,
+            1 => crate::peripherals::Interrupt::FROM_CPU_INTR1,
+            2 => crate::peripherals::Interrupt::FROM_CPU_INTR2,
+            3 => crate::peripherals::Interrupt::FROM_CPU_INTR3,
+            _ => unreachable!(),
+        };
+
+        unsafe {
+            crate::interrupt::bind_interrupt(interrupt, handler.handler());
+            crate::interrupt::enable(interrupt, handler.priority()).unwrap();
+        }
+    }
+
+    /// Trigger this software-interrupt
+    pub fn raise(&self) {
+        cfg_if::cfg_if! {
+            if #[cfg(any(esp32c6, esp32h2))] {
+                let system = unsafe { &*crate::peripherals::INTPRI::PTR };
+            } else {
+                let system = unsafe { &*crate::peripherals::SYSTEM::PTR };
+            }
+        }
+
+        match NUM {
+            0 => system
+                .cpu_intr_from_cpu_0()
+                .write(|w| w.cpu_intr_from_cpu_0().set_bit()),
+            1 => system
+                .cpu_intr_from_cpu_1()
+                .write(|w| w.cpu_intr_from_cpu_1().set_bit()),
+            2 => system
+                .cpu_intr_from_cpu_2()
+                .write(|w| w.cpu_intr_from_cpu_2().set_bit()),
+            3 => system
+                .cpu_intr_from_cpu_3()
+                .write(|w| w.cpu_intr_from_cpu_3().set_bit()),
+            _ => unreachable!(),
+        }
+    }
+
+    /// Resets this software-interrupt
+    pub fn reset(&self) {
+        cfg_if::cfg_if! {
+            if #[cfg(any(esp32c6, esp32h2))] {
+                let system = unsafe { &*crate::peripherals::INTPRI::PTR };
+            } else {
+                let system = unsafe { &*crate::peripherals::SYSTEM::PTR };
+            }
+        }
+
+        match NUM {
+            0 => system
+                .cpu_intr_from_cpu_0()
+                .write(|w| w.cpu_intr_from_cpu_0().clear_bit()),
+            1 => system
+                .cpu_intr_from_cpu_1()
+                .write(|w| w.cpu_intr_from_cpu_1().clear_bit()),
+            2 => system
+                .cpu_intr_from_cpu_2()
+                .write(|w| w.cpu_intr_from_cpu_2().clear_bit()),
+            3 => system
+                .cpu_intr_from_cpu_3()
+                .write(|w| w.cpu_intr_from_cpu_3().clear_bit()),
+            _ => unreachable!(),
+        }
+    }
+
+    /// Unsafely create an instance of this peripheral out of thin air.
+    ///
+    /// # Safety
+    ///
+    /// You must ensure that you're only using one instance of this type at a
+    /// time.
+    #[inline]
+    pub unsafe fn steal() -> Self {
+        Self
+    }
+}
+
+impl<const NUM: u8> crate::peripheral::Peripheral for SoftwareInterrupt<NUM> {
+    type P = SoftwareInterrupt<NUM>;
+
+    #[inline]
+    unsafe fn clone_unchecked(&mut self) -> Self::P {
+        Self::steal()
+    }
+}
+
+impl<const NUM: u8> crate::private::Sealed for SoftwareInterrupt<NUM> {}
+
+impl<const NUM: u8> InterruptConfigurable for SoftwareInterrupt<NUM> {
+    fn set_interrupt_handler(&mut self, handler: crate::interrupt::InterruptHandler) {
+        SoftwareInterrupt::set_interrupt_handler(self, handler);
+    }
+}
+
+/// This gives access to the available software interrupts.
+///
+/// This struct contains several instances of software interrupts that can be
+/// used for signaling between different parts of a program or system. Each
+/// interrupt is identified by an index (0 to 3).
+#[cfg_attr(
+    multi_core,
+    doc = r#"
+
+Please note: Software interrupt 3 is reserved
+for inter-processor communication when using
+`esp-hal-embassy`."#
+)]
+#[non_exhaustive]
+pub struct SoftwareInterruptControl {
+    /// Software interrupt 0.
+    pub software_interrupt0: SoftwareInterrupt<0>,
+    /// Software interrupt 1.
+    pub software_interrupt1: SoftwareInterrupt<1>,
+    /// Software interrupt 2.
+    pub software_interrupt2: SoftwareInterrupt<2>,
+    #[cfg(not(all(feature = "__esp_hal_embassy", multi_core)))]
+    /// Software interrupt 3. Only available when not using `esp-hal-embassy`,
+    /// or on single-core systems.
+    pub software_interrupt3: SoftwareInterrupt<3>,
+}
+
+impl SoftwareInterruptControl {
+    /// Create a new instance of the software interrupt control.
+    pub fn new(_peripheral: crate::peripherals::SW_INTERRUPT) -> Self {
+        SoftwareInterruptControl {
+            software_interrupt0: SoftwareInterrupt {},
+            software_interrupt1: SoftwareInterrupt {},
+            software_interrupt2: SoftwareInterrupt {},
+            #[cfg(not(all(feature = "__esp_hal_embassy", multi_core)))]
+            software_interrupt3: SoftwareInterrupt {},
+        }
+    }
+}

esp-hal/src/lcd_cam/lcd/i8080.rs

@@ -1,14 +1,17 @@
 //! # LCD - I8080/MOTO6800 Mode.
 //!
 //! ## Overview
+//!
 //! The LCD_CAM peripheral I8080 driver provides support for the I8080
-//! format/timing. The driver mandates DMA for DMA (Direct Memory Access) for
+//! format/timing. The driver mandates DMA (Direct Memory Access) for
 //! efficient data transfer.
 //!
-//! ## Examples
+//! ## Example
+//!
 //! ### MIPI-DSI Display
-//! Following code show how to send a command to a MIPI-DSI display over I8080
+//!
-//! protocol.
+//! The following example shows how to send a command to a MIPI-DSI display over
+//! the I8080 protocol.
 //!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
@@ -16,8 +19,6 @@
 //! # use esp_hal::lcd_cam::{LcdCam, lcd::i8080::{Config, I8080, TxEightBits}};
 //! # use esp_hal::dma_buffers;
 //! # use esp_hal::dma::{Dma, DmaPriority};
-//! # use fugit::RateExtU32;
-//!
 //! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 //!
 //! # let dma = Dma::new(peripherals.DMA);

esp-hal/src/ledc/mod.rs

@@ -18,8 +18,10 @@
 //! ## Examples
 //!
 //! ### Low Speed Channel
-//! The following will configure the Low Speed Channel0 to 24kHz output with
+//!
-//! 10% duty using the ABPClock
+//! The following example will configure the Low Speed Channel0 to 24kHz output
+//! with 10% duty using the ABPClock.
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::ledc::Ledc;
@@ -28,10 +30,6 @@
 //! # use esp_hal::ledc::LowSpeed;
 //! # use esp_hal::ledc::channel;
 //! # use esp_hal::gpio::Io;
-//! # use crate::esp_hal::prelude::_esp_hal_ledc_timer_TimerIFace;
-//! # use crate::esp_hal::prelude::_fugit_RateExtU32;
-//! # use crate::esp_hal::prelude::_esp_hal_ledc_channel_ChannelIFace;
-//!
 //! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 //! # let led = io.pins.gpio0;
 //!

esp-hal/src/lib.rs

@@ -17,7 +17,7 @@
 #![cfg_attr(esp32c3, doc = "**ESP32-C3**")]
 #![cfg_attr(esp32c6, doc = "**ESP32-C6**")]
 #![cfg_attr(esp32h2, doc = "**ESP32-H2**")]
-//! please ensure you are reading the correct [documentation] for your target
+//! . Please ensure you are reading the correct [documentation] for your target
 //! device.
 //!
 //! ## Choosing a Device
@@ -60,26 +60,20 @@
 //! #![no_std]
 //! #![no_main]
 //!
-//! // A panic - handler e.g. `use esp_backtrace as _;`
+//! // You'll need a panic handler e.g. `use esp_backtrace as _;`
-//!
-//! use esp_hal::{
-//!     clock::ClockControl,
-//!     delay::Delay,
-//!     gpio::{Io, Level, Output},
-//!     peripherals::Peripherals,
-//!     prelude::*,
-//!     system::SystemControl,
-//! };
 //! # #[panic_handler]
 //! # fn panic(_ : &core::panic::PanicInfo) -> ! {
 //! #     loop {}
 //! # }
+//! use esp_hal::{
+//!     delay::Delay,
+//!     gpio::{Io, Level, Output},
+//!     prelude::*,
+//! };
 //!
 //! #[entry]
 //! fn main() -> ! {
-//!     let peripherals = Peripherals::take();
+//!     let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-//!     let system = SystemControl::new(peripherals.SYSTEM);
-//!     let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 //!
 //!     // Set GPIO0 as an output, and set its state high initially.
 //!     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
@@ -95,14 +89,11 @@
 //! ```
 //!
 //! The steps here are:
-//! - Take all the peripherals from the PAC to pass them to the HAL drivers
+//! - Call [`init`] with the desired [`CpuClock`] configuration
-//!   later
+//! - Create [`gpio::Io`] which provides access to the GPIO pins
-//! - Create [system::SystemControl]
+//! - Create an [`gpio::Output`] pin driver which lets us control the logical
-//! - Configure the system clocks - in this case use the boot defaults
-//! - Create [gpio::Io] which provides access to the GPIO pins
-//! - Create an [gpio::Output] pin driver which lets us control the logical
 //!   level of an output pin
-//! - Create a [delay::Delay] driver
+//! - Create a [`delay::Delay`] driver
 //! - In a loop, toggle the output pin's logical level with a delay of 1000 ms
 //!
 //! ## `PeripheralRef` Pattern
@@ -111,7 +102,7 @@
 //! This means you can pass the pin/peripheral or a mutable reference to the
 //! pin/peripheral.
 //!
-//! The later can be used to regain access to the pin when the driver gets
+//! The latter can be used to regain access to the pin when the driver gets
 //! dropped. Then it's possible to reuse the pin/peripheral for a different
 //! purpose.
 //!
@@ -714,17 +705,38 @@ macro_rules! before_snippet {
     () => {
         r#"
 # #![no_std]
-# use esp_hal::peripherals::Peripherals;
+# use esp_hal::prelude::*;
-# use esp_hal::clock::ClockControl;
+# use procmacros::handler;
-# use esp_hal::system::SystemControl;
+# use esp_hal::interrupt;
 # #[panic_handler]
 # fn panic(_ : &core::panic::PanicInfo) -> ! {
 #     loop {}
 # }
 # fn main() {
-#   let peripherals = Peripherals::take();
+#     let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-#   let system = SystemControl::new(peripherals.SYSTEM);
-#   let mut clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 "#
     };
 }
+
+use crate::{
+    clock::{ClockControl, Clocks, CpuClock},
+    peripherals::Peripherals,
+};
+
+/// System configuration.
+#[non_exhaustive]
+#[derive(Default)]
+pub struct Config {
+    /// The CPU clock configuration.
+    pub cpu_clock: CpuClock,
+}
+
+/// Initialize the system.
+///
+/// This function sets up the CPU clock and returns the peripherals and clocks.
+pub fn init(config: Config) -> (Peripherals, Clocks<'static>) {
+    let peripherals = Peripherals::take();
+    let clocks = ClockControl::new(config.cpu_clock).freeze();
+
+    (peripherals, clocks)
+}

esp-hal/src/mcpwm/mod.rs

@@ -42,14 +42,16 @@
 #![cfg_attr(esp32h2, doc = "Clock source is XTAL")]
 #![doc = ""]
 //! ## Examples
+//!
 //! ### Output a 20 kHz signal
-//! Uses timer0 and operator0 of the MCPWM0 peripheral to output a 50% duty
+//!
-//! signal at 20 kHz. The signal will be output to the pin assigned to `pin`.
+//! This example uses timer0 and operator0 of the MCPWM0 peripheral to output a
+//! 50% duty signal at 20 kHz. The signal will be output to the pin assigned to
+//! `pin`.
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
-//! # use esp_hal::{mcpwm, prelude::*};
+//! # use esp_hal::mcpwm::{operator::{DeadTimeCfg, PWMStream, PwmPinConfig}, timer::PwmWorkingMode, McPwm, PeripheralClockConfig};
-//! # use esp_hal::mcpwm::operator::{DeadTimeCfg, PWMStream};
-//! # use mcpwm::{operator::PwmPinConfig, timer::PwmWorkingMode, McPwm, PeripheralClockConfig};
 //! # use esp_hal::gpio::Io;
 //!
 //! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);

esp-hal/src/mcpwm/operator.rs

@@ -479,6 +479,7 @@ impl<'d, Pin: OutputPin, PWM: PwmPeripheral, const OP: u8, const IS_A: bool>
 /// configured deadtime.
 ///
 /// # H-Bridge example
+///
 /// ```rust, no_run
 #[doc = crate::before_snippet!()]
 /// # use esp_hal::{mcpwm, prelude::*};

esp-hal/src/prelude.rs

@@ -38,4 +38,4 @@ pub use crate::timer::timg::{
 pub use crate::timer::Timer as _esp_hal_timer_Timer;
 #[cfg(any(uart0, uart1, uart2))]
 pub use crate::uart::Instance as _esp_hal_uart_Instance;
-pub use crate::{entry, macros::*, InterruptConfigurable};
+pub use crate::{clock::CpuClock, entry, macros::*, InterruptConfigurable};

esp-hal/src/rmt.rs

@@ -18,24 +18,25 @@
 //!   the input signal
 //!
 //! ### Channels
+//!
 //! There are
 #![cfg_attr(
     esp32,
-    doc = "8 channels, each of them can be either receiver or transmitter"
+    doc = "8 channels, each of them can be either receiver or transmitter."
 )]
 #![cfg_attr(
     esp32s2,
-    doc = "4 channels, each of them can be either receiver or transmitter"
+    doc = "4 channels, each of them can be either receiver or transmitter."
 )]
 #![cfg_attr(
     esp32s3,
-    doc = "8 channels, `Channel<0>`-`Channel<3>` hardcoded for transmitting signals and `Channel<4>`-`Channel<7>` hardcoded for receiving signals"
+    doc = "8 channels, `Channel<0>`-`Channel<3>` hardcoded for transmitting signals and `Channel<4>`-`Channel<7>` hardcoded for receiving signals."
 )]
 #![cfg_attr(
     any(esp32c3, esp32c6, esp32h2),
     doc = "4 channels, `Channel<0>` and `Channel<1>` hardcoded for transmitting signals and `Channel<2>` and `Channel<3>` hardcoded for receiving signals."
 )]
-#![doc = "  "]
+#![doc = ""]
 //! For more information, please refer to the
 #![doc = concat!("[ESP-IDF documentation](https://docs.espressif.com/projects/esp-idf/en/latest/", crate::soc::chip!(), "/api-reference/peripherals/rmt.html)")]
 //! ## Configuration
@@ -44,8 +45,10 @@
 //! channels are indicated by n which is used as a placeholder for the channel
 //! number, and by m for RX channels.
 //!
-//! ## Examples
+//! ## Example
+//!
 //! ### Initialization
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::peripherals::Peripherals;
@@ -54,7 +57,6 @@
 //! # use esp_hal::gpio::Io;
 //! # use esp_hal::clock::ClockControl;
 //! # use crate::esp_hal::rmt::TxChannelCreator;
-//! # use crate::esp_hal::prelude::_fugit_RateExtU32;
 //! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 #![cfg_attr(esp32h2, doc = "let freq = 32.MHz();")]
 #![cfg_attr(not(esp32h2), doc = "let freq = 80.MHz();")]
@@ -76,8 +78,8 @@
 //!     .unwrap();
 //! # }
 //! ```
-//! (on ESP32 and ESP32-S2 you cannot specify a base frequency other than 80
+//! 
-//! MHz)
+//! > Note: on ESP32 and ESP32-S2 you cannot specify a base frequency other than 80 MHz
 
 use core::marker::PhantomData;
 

esp-hal/src/rom/md5.rs

@@ -55,6 +55,7 @@
 //! # let mut uart0 = Uart::new(peripherals.UART0, &clocks, io.pins.gpio1, io.pins.gpio2).unwrap();
 //! # let data0 = "Dummy";
 //! # let data1 = "Dummy";
+//! #
 //! let mut ctx = md5::Context::new();
 //! ctx.consume(&data0);
 //! ctx.consume(&data1);

esp-hal/src/rtc_cntl/mod.rs

@@ -14,11 +14,10 @@
 //!    * Clock Configuration
 //!    * Calibration
 //!    * Low-Power Management
-//!    * Real-Time Clock
 //!    * Handling Watchdog Timers
 //!
-//! ## Examples
+//! ## Example
-//! ### Print Time in Milliseconds From the RTC Timer
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use core::cell::RefCell;
@@ -33,28 +32,23 @@
 //! let mut delay = Delay::new(&clocks);
 //!
 //! let mut rtc = Rtc::new(peripherals.LPWR);
+//!
 //! rtc.set_interrupt_handler(interrupt_handler);
 //! rtc.rwdt.set_timeout(2000.millis());
 //! rtc.rwdt.listen();
 //!
 //! critical_section::with(|cs| RWDT.borrow_ref_mut(cs).replace(rtc.rwdt));
-//!
-//!
-//! loop {}
 //! # }
 //!
 //! // Where the `LP_WDT` interrupt handler is defined as:
-//! // Handle the corresponding interrupt
 //! # use core::cell::RefCell;
 //!
 //! # use critical_section::Mutex;
-//! # use esp_hal::prelude::handler;
-//! # use esp_hal::interrupt::InterruptHandler;
-//! # use esp_hal::interrupt;
-//! # use esp_hal::interrupt::Priority;
-//! # use crate::esp_hal::prelude::_fugit_ExtU64;
 //! # use esp_hal::rtc_cntl::Rwdt;
+//!
 //! static RWDT: Mutex<RefCell<Option<Rwdt>>> = Mutex::new(RefCell::new(None));
+//!
+//! // Handle the corresponding interrupt
 //! #[handler]
 //! fn interrupt_handler() {
 //!     critical_section::with(|cs| {

esp-hal/src/soc/esp32/peripherals.rs

@@ -63,6 +63,7 @@ crate::peripherals! {
     SPI2 <= SPI2 (SPI2_DMA, SPI2),
     SPI3 <= SPI3 (SPI3_DMA, SPI3),
     SYSTEM <= DPORT,
+    SW_INTERRUPT <= virtual,
     TIMG0 <= TIMG0,
     TIMG1 <= TIMG1,
     TOUCH <= virtual,

esp-hal/src/soc/esp32c2/peripherals.rs

@@ -43,6 +43,7 @@ crate::peripherals! {
     SPI2 <= SPI2 (SPI2),
     SYSTEM <= SYSTEM,
     SYSTIMER <= SYSTIMER,
+    SW_INTERRUPT <= virtual,
     TIMG0 <= TIMG0,
     UART0 <= UART0,
     UART1 <= UART1,

esp-hal/src/soc/esp32c3/peripherals.rs

@@ -50,6 +50,7 @@ crate::peripherals! {
     SPI2 <= SPI2 (SPI2),
     SYSTEM <= SYSTEM,
     SYSTIMER <= SYSTIMER,
+    SW_INTERRUPT <= virtual,
     TIMG0 <= TIMG0,
     TIMG1 <= TIMG1,
     TWAI0 <= TWAI0,

esp-hal/src/soc/esp32c6/peripherals.rs

@@ -76,6 +76,7 @@ crate::peripherals! {
     SPI2 <= SPI2 (SPI2),
     SYSTEM <= PCR,
     SYSTIMER <= SYSTIMER,
+    SW_INTERRUPT <= virtual,
     TEE <= TEE,
     TIMG0 <= TIMG0,
     TIMG1 <= TIMG1,

esp-hal/src/soc/esp32h2/peripherals.rs

@@ -68,6 +68,7 @@ crate::peripherals! {
     SPI2 <= SPI2 (SPI2),
     SYSTEM <= PCR,
     SYSTIMER <= SYSTIMER,
+    SW_INTERRUPT <= virtual,
     TEE <= TEE,
     TIMG0 <= TIMG0,
     TIMG1 <= TIMG1,

esp-hal/src/soc/esp32s2/peripherals.rs

@@ -58,6 +58,7 @@ crate::peripherals! {
     SYSCON <= SYSCON,
     SYSTEM <= SYSTEM,
     SYSTIMER <= SYSTIMER,
+    SW_INTERRUPT <= virtual,
     TIMG0 <= TIMG0,
     TIMG1 <= TIMG1,
     TWAI0 <= TWAI0,

esp-hal/src/soc/esp32s2/ulp_core.rs

@@ -26,8 +26,12 @@
 //! // copy code to RTC ram
 //! let lp_ram = 0x5000_0000 as *mut u8;
 //! unsafe {
-//!     core::ptr::copy_nonoverlapping(CODE as *const _ as *const u8, lp_ram,
+//!     core::ptr::copy_nonoverlapping(
-//! CODE.len()); }
+//!         CODE as *const _ as *const u8,
+//!         lp_ram,
+//!         CODE.len(),
+//!     );
+//! }
 //!
 //! // start ULP core
 //! ulp_core.run(esp_hal::ulp_core::UlpCoreWakeupSource::HpCpu);

esp-hal/src/soc/esp32s3/cpu_control.rs

@@ -13,10 +13,8 @@
 //! # use esp_hal::cpu_control::{CpuControl, Stack};
 //! # use core::{cell::RefCell, ptr::addr_of_mut};
 //! # use critical_section::Mutex;
-//! # use esp_hal::prelude::*;
-//! static mut APP_CORE_STACK: Stack<8192> = Stack::new();
-//!
 //! # let delay = Delay::new(&clocks);
+//! static mut APP_CORE_STACK: Stack<8192> = Stack::new();
 //!
 //! let counter = Mutex::new(RefCell::new(0));
 //!
@@ -25,8 +23,10 @@
 //!     cpu1_task(&delay, &counter);
 //! };
 //! let _guard = cpu_control
-//!    .start_app_core(unsafe { &mut *addr_of_mut!(APP_CORE_STACK) },
+//!    .start_app_core(
-//! cpu1_fnctn)     .unwrap();
+//!         unsafe { &mut *addr_of_mut!(APP_CORE_STACK) },
+//!         cpu1_fnctn,
+//!     ).unwrap();
 //!
 //! loop {
 //!     delay.delay(1.secs());
@@ -37,7 +37,7 @@
 //! // Where `cpu1_task()` may be defined as:
 //! # use esp_hal::delay::Delay;
 //! # use core::cell::RefCell;
-//! # use esp_hal::prelude::*;
+//!
 //! fn cpu1_task(
 //!     delay: &Delay,
 //!     counter: &critical_section::Mutex<RefCell<i32>>,

esp-hal/src/soc/esp32s3/peripherals.rs

@@ -63,6 +63,7 @@ crate::peripherals! {
     SPI3 <= SPI3 (SPI3),
     SYSTEM <= SYSTEM,
     SYSTIMER <= SYSTIMER,
+    SW_INTERRUPT <= virtual,
     TIMG0 <= TIMG0,
     TIMG1 <= TIMG1,
     TWAI0 <= TWAI0,

esp-hal/src/soc/esp32s3/ulp_core.rs

@@ -1,6 +1,7 @@
 //! Control the ULP core
 //!
 //! ## Overview
+//!
 //! The `ULP CORE` peripheral allows control over the `Ultra-Low Power
 //! (ULP) core` in `ESP` chips. The ULP core is a low-power processor
 //! designed for executing tasks in deep sleep mode, enabling efficient power
@@ -11,13 +12,15 @@
 //! operation. The `UlpCore` struct is initialized with a peripheral reference
 //! to the `ULP CORE` instance.
 //!
-//! ## Examples
+//! ## Example
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! const CODE: &[u8] = &[
 //!     0x17, 0x05, 0x00, 0x00, 0x13, 0x05, 0x05, 0x01, 0x81, 0x45, 0x85, 0x05,
 //!     0x0c, 0xc1, 0xf5, 0xbf, 0x00, 0x00, 0x00, 0x00,
 //! ];
+//!
 //! let mut ulp_core =
 //!     esp_hal::ulp_core::UlpCore::new(peripherals.ULP_RISCV_CORE);
 //! ulp_core.stop();
@@ -25,8 +28,12 @@
 //! // copy code to RTC ram
 //! let lp_ram = 0x5000_0000 as *mut u8;
 //! unsafe {
-//!     core::ptr::copy_nonoverlapping(CODE as *const _ as *const u8, lp_ram,
+//!     core::ptr::copy_nonoverlapping(
-//! CODE.len()); }
+//!         CODE as *const _ as *const u8,
+//!         lp_ram,
+//!         CODE.len(),
+//!     );
+//! }
 //!
 //! // start ULP core
 //! ulp_core.run(esp_hal::ulp_core::UlpCoreWakeupSource::HpCpu);

esp-hal/src/spi/master.rs

@@ -38,7 +38,6 @@
 //! ### SPI Initialization
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
-//! # use crate::esp_hal::prelude::_fugit_RateExtU32;
 //! # use esp_hal::spi::SpiMode;
 //! # use esp_hal::spi::master::Spi;
 //! # use esp_hal::gpio::Io;
@@ -52,7 +51,7 @@
 //!     peripherals.SPI2,
 //!     100.kHz(),
 //!     SpiMode::Mode0,
-//!     &mut clocks,
+//!     &clocks,
 //! )
 //! .with_pins(Some(sclk), Some(mosi), Some(miso), Some(cs));
 //! # }

esp-hal/src/system.rs

@@ -1,46 +1,20 @@
 //! # System Control
 //!
 //! ## Overview
-//! This `system` driver provides an interface to control and configure various
-//! system-related features and peripherals on ESP chips. It includes
-//! functionality to control peripheral clocks, manage software interrupts,
-//! configure chip clocks, and control radio peripherals.
 //!
-//! ### Software Interrupts
+//! This `system` module defines the available radio peripherals and provides an
-//! The `SoftwareInterruptControl` struct gives access to the available software
+//! interface to control and configure radio clocks.
-//! interrupts.
-//!
-//! The `SoftwareInterrupt` struct allows raising or resetting software
-//! interrupts using the `raise()` and `reset()` methods.
-//!
-//! ### Peripheral Clock Control
-//! The `PeripheralClockControl` struct controls the enablement of peripheral
-//! clocks.
-//!
-//! It provides an `enable()` method to enable and reset specific peripherals.
-//! The available peripherals are represented by the `Peripheral` enum
-//!
-//! ## Examples
-//! ```rust, no_run
-#![doc = crate::before_snippet!()]
-//! let peripherals = Peripherals::take();
-//! let system = SystemControl::new(peripherals.SYSTEM);
-//! let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
-//! # }
-//! ```
 
-use crate::{
+use crate::peripherals::SYSTEM;
-    interrupt::InterruptHandler,
-    peripheral::PeripheralRef,
-    peripherals::SYSTEM,
-    InterruptConfigurable,
-};
 
 /// Peripherals which can be enabled via `PeripheralClockControl`.
 ///
 /// This enum represents various hardware peripherals that can be enabled
 /// by the system's clock control. Depending on the target device, different
 /// peripherals will be available for enabling.
+// FIXME: This enum needs to be public because it's exposed via a bunch of traits, but it's not
+// useful to users.
+#[doc(hidden)]
 pub enum Peripheral {
     /// SPI2 peripheral.
     #[cfg(spi2)]
@@ -146,183 +120,6 @@ pub enum Peripheral {
     Systimer,
 }
 
-/// The `DPORT`/`PCR`/`SYSTEM` peripheral split into its different logical
-/// components.
-pub struct SystemControl<'d> {
-    /// Inner reference to the SYSTEM peripheral.
-    _inner: PeripheralRef<'d, SYSTEM>,
-    /// Controls the system's clock settings and configurations.
-    pub clock_control: SystemClockControl,
-    /// Controls the system's software interrupt settings.
-    pub software_interrupt_control: SoftwareInterruptControl,
-}
-
-impl<'d> SystemControl<'d> {
-    /// Construct a new instance of [`SystemControl`].
-    pub fn new(system: impl crate::peripheral::Peripheral<P = SYSTEM> + 'd) -> Self {
-        crate::into_ref!(system);
-
-        Self {
-            _inner: system,
-            clock_control: SystemClockControl::new(),
-            software_interrupt_control: SoftwareInterruptControl::new(),
-        }
-    }
-}
-
-/// A software interrupt can be triggered by software.
-#[non_exhaustive]
-pub struct SoftwareInterrupt<const NUM: u8>;
-
-impl<const NUM: u8> SoftwareInterrupt<NUM> {
-    /// Sets the interrupt handler for this software-interrupt
-    pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
-        let interrupt = match NUM {
-            0 => crate::peripherals::Interrupt::FROM_CPU_INTR0,
-            1 => crate::peripherals::Interrupt::FROM_CPU_INTR1,
-            2 => crate::peripherals::Interrupt::FROM_CPU_INTR2,
-            3 => crate::peripherals::Interrupt::FROM_CPU_INTR3,
-            _ => unreachable!(),
-        };
-
-        unsafe {
-            crate::interrupt::bind_interrupt(interrupt, handler.handler());
-            crate::interrupt::enable(interrupt, handler.priority()).unwrap();
-        }
-    }
-
-    /// Trigger this software-interrupt
-    pub fn raise(&self) {
-        #[cfg(not(any(esp32c6, esp32h2)))]
-        let system = unsafe { &*SYSTEM::PTR };
-        #[cfg(any(esp32c6, esp32h2))]
-        let system = unsafe { &*crate::peripherals::INTPRI::PTR };
-
-        match NUM {
-            0 => {
-                system
-                    .cpu_intr_from_cpu_0()
-                    .write(|w| w.cpu_intr_from_cpu_0().set_bit());
-            }
-            1 => {
-                system
-                    .cpu_intr_from_cpu_1()
-                    .write(|w| w.cpu_intr_from_cpu_1().set_bit());
-            }
-            2 => {
-                system
-                    .cpu_intr_from_cpu_2()
-                    .write(|w| w.cpu_intr_from_cpu_2().set_bit());
-            }
-            3 => {
-                system
-                    .cpu_intr_from_cpu_3()
-                    .write(|w| w.cpu_intr_from_cpu_3().set_bit());
-            }
-            _ => unreachable!(),
-        }
-    }
-
-    /// Resets this software-interrupt
-    pub fn reset(&self) {
-        #[cfg(not(any(esp32c6, esp32h2)))]
-        let system = unsafe { &*SYSTEM::PTR };
-        #[cfg(any(esp32c6, esp32h2))]
-        let system = unsafe { &*crate::peripherals::INTPRI::PTR };
-
-        match NUM {
-            0 => {
-                system
-                    .cpu_intr_from_cpu_0()
-                    .write(|w| w.cpu_intr_from_cpu_0().clear_bit());
-            }
-            1 => {
-                system
-                    .cpu_intr_from_cpu_1()
-                    .write(|w| w.cpu_intr_from_cpu_1().clear_bit());
-            }
-            2 => {
-                system
-                    .cpu_intr_from_cpu_2()
-                    .write(|w| w.cpu_intr_from_cpu_2().clear_bit());
-            }
-            3 => {
-                system
-                    .cpu_intr_from_cpu_3()
-                    .write(|w| w.cpu_intr_from_cpu_3().clear_bit());
-            }
-            _ => unreachable!(),
-        }
-    }
-
-    /// Unsafely create an instance of this peripheral out of thin air.
-    ///
-    /// # Safety
-    ///
-    /// You must ensure that you're only using one instance of this type at a
-    /// time.
-    #[inline]
-    pub unsafe fn steal() -> Self {
-        Self
-    }
-}
-
-impl<const NUM: u8> crate::peripheral::Peripheral for SoftwareInterrupt<NUM> {
-    type P = SoftwareInterrupt<NUM>;
-
-    #[inline]
-    unsafe fn clone_unchecked(&mut self) -> Self::P {
-        Self::steal()
-    }
-}
-
-impl<const NUM: u8> crate::private::Sealed for SoftwareInterrupt<NUM> {}
-
-impl<const NUM: u8> InterruptConfigurable for SoftwareInterrupt<NUM> {
-    fn set_interrupt_handler(&mut self, handler: crate::interrupt::InterruptHandler) {
-        SoftwareInterrupt::set_interrupt_handler(self, handler);
-    }
-}
-
-/// This gives access to the available software interrupts.
-///
-/// This struct contains several instances of software interrupts that can be
-/// used for signaling between different parts of a program or system. Each
-/// interrupt is identified by an index (0 to 3).
-#[cfg_attr(
-    multi_core,
-    doc = r#"
-
-Please note: Software interrupt 3 is reserved
-for inter-processor communication when using
-`esp-hal-embassy`."#
-)]
-#[non_exhaustive]
-pub struct SoftwareInterruptControl {
-    /// Software interrupt 0.
-    pub software_interrupt0: SoftwareInterrupt<0>,
-    /// Software interrupt 1.
-    pub software_interrupt1: SoftwareInterrupt<1>,
-    /// Software interrupt 2.
-    pub software_interrupt2: SoftwareInterrupt<2>,
-    #[cfg(not(all(feature = "__esp_hal_embassy", multi_core)))]
-    /// Software interrupt 3. Only available when not using `esp-hal-embassy`,
-    /// or on single-core systems.
-    pub software_interrupt3: SoftwareInterrupt<3>,
-}
-
-impl SoftwareInterruptControl {
-    fn new() -> Self {
-        SoftwareInterruptControl {
-            software_interrupt0: SoftwareInterrupt {},
-            software_interrupt1: SoftwareInterrupt {},
-            software_interrupt2: SoftwareInterrupt {},
-            #[cfg(not(all(feature = "__esp_hal_embassy", multi_core)))]
-            software_interrupt3: SoftwareInterrupt {},
-        }
-    }
-}
-
 /// Controls the enablement of peripheral clocks.
 pub(crate) struct PeripheralClockControl;
 
@@ -1187,35 +984,6 @@ impl PeripheralClockControl {
     }
 }
 
-/// Controls the configuration of the chip's clocks.
-pub struct SystemClockControl {
-    _private: (),
-}
-
-impl SystemClockControl {
-    /// Creates new instance of `SystemClockControl`.
-    pub fn new() -> Self {
-        Self { _private: () }
-    }
-}
-
-impl Default for SystemClockControl {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-impl crate::peripheral::Peripheral for SystemClockControl {
-    type P = SystemClockControl;
-
-    #[inline]
-    unsafe fn clone_unchecked(&mut self) -> Self::P {
-        SystemClockControl { _private: () }
-    }
-}
-
-impl crate::private::Sealed for SystemClockControl {}
-
 /// Enumeration of the available radio peripherals for this chip.
 #[cfg(any(bt, ieee802154, wifi))]
 pub enum RadioPeripherals {

esp-hal/src/time.rs

@@ -1,17 +1,8 @@
 //! # Time
 //!
-//! ## Overview
 //! The `time` module offers a way to get the system uptime.
-//!
-//! ## Examples
-//! ```rust, no_run
-#![doc = crate::before_snippet!()]
-//! # use esp_hal::time;
-//! let time = time::current_time();
-//! # }
-//! ```
 
-/// Provides time since system start in microseconds precision
+/// Provides time since system start in microseconds precision.
 ///
 /// The counter won’t measure time in sleep-mode.
 ///

esp-hal/src/timer/mod.rs

@@ -17,7 +17,7 @@
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::timer::{OneShotTimer, PeriodicTimer, timg::TimerGroup};
-//! # use esp_hal::prelude::*;
+//! #
 //! let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
 //! let one_shot = OneShotTimer::new(timg0.timer0);
 //!
@@ -29,7 +29,7 @@
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::timer::{PeriodicTimer, timg::TimerGroup};
-//! # use esp_hal::prelude::*;
+//! #
 //! let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
 //! let mut periodic = PeriodicTimer::new(timg0.timer0);
 //!

esp-hal/src/timer/systimer.rs

@@ -15,58 +15,57 @@
 //! [Alarm]s can be configured in two modes: [Target] (one-shot) and [Periodic].
 //!
 //! ## Examples
+//!
+//! ### Splitting up the System Timer into three alarms
+//!
+//! Use the [split][SystemTimer::split] method to create three alarms from the
+//!  System Timer, contained in a [SysTimerAlarms] struct.
+//!
+//! ```rust, no_run
+#![doc = crate::before_snippet!()]
+//! use esp_hal::timer::systimer::{
+//!     SystemTimer,
+//!     Periodic,
+//! };
+//!
+//! let systimer = SystemTimer::new(
+//!     peripherals.SYSTIMER,
+//! ).split::<Periodic>();
+//!
+//! // Reconfigure a periodic alarm to be a target alarm
+//! let target_alarm = systimer.alarm0.into_target();
+//! # }
+//! ```
+//! 
 //! ### General-purpose Timer
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
-//! # use esp_hal::timer::systimer::SystemTimer;
+//! use esp_hal::timer::systimer::{
-//! # use esp_hal::timer::timg::TimerGroup;
+//!     Alarm,
-//! # use crate::esp_hal::prelude::_esp_hal_timer_Timer;
+//!     FrozenUnit,
-//! # use esp_hal::prelude::*;
+//!     SpecificUnit,
-//! let systimer = SystemTimer::new(peripherals.SYSTIMER);
+//!     SystemTimer,
+//! };
+//!
+//! let mut systimer = SystemTimer::new(peripherals.SYSTIMER);
 //!
 //! // Get the current timestamp, in microseconds:
 //! let now = SystemTimer::now();
 //!
-//! let timg0 = TimerGroup::new(
+//! let frozen_unit = FrozenUnit::new(&mut systimer.unit0);
-//!     peripherals.TIMG0,
+//! let alarm0 = Alarm::new(systimer.comparator0, &frozen_unit);
-//!     &clocks,
+//!
+//! alarm0.set_target(
+//!     SystemTimer::now() + SystemTimer::ticks_per_second() * 2
 //! );
+//! alarm0.enable_interrupt(true);
 //!
-//! let mut timer0 = timg0.timer0;
+//! while !alarm0.is_interrupt_set() {
-//! timer0.set_interrupt_handler(tg0_t0_level);
+//!     // Wait for the interrupt to be set
-//!
-//! // Wait for timeout:
-//! timer0.load_value(1.secs());
-//! timer0.start();
-//!
-//! while !timer0.is_interrupt_set() {
-//!     // Wait
 //! }
+//!
+//! alarm0.clear_interrupt();
 //! # }
-//!
-//!
-//! # use core::cell::RefCell;
-//! # use critical_section::Mutex;
-//! # use procmacros::handler;
-//! # use esp_hal::interrupt::InterruptHandler;
-//! # use esp_hal::interrupt;
-//! # use esp_hal::peripherals::TIMG0;
-//! # use esp_hal::timer::timg::{Timer, Timer0};
-//! # use crate::esp_hal::prelude::_esp_hal_timer_Timer;
-//! # static TIMER0: Mutex<RefCell<Option<Timer<Timer0<TIMG0>, esp_hal::Blocking>>>> = Mutex::new(RefCell::new(None));
-//! #[handler]
-//! fn tg0_t0_level() {
-//!     critical_section::with(|cs| {
-//!     let mut timer0 = TIMER0.borrow_ref_mut(cs);
-//!     let timer0 = timer0.as_mut().unwrap();
-//!
-//!     timer0.clear_interrupt();
-//!
-//!     // Counter value should be a very small number as the alarm triggered a
-//!     // counter reload to 0 and ETM stopped the counter quickly after
-//!     // esp_println::println!("counter in interrupt: {}", timer0.now());
-//!     });
-//! }
 //! ```
 
 use core::{

esp-hal/src/timer/timg.rs

@@ -27,8 +27,7 @@
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::timer::timg::TimerGroup;
-//! # use crate::esp_hal::prelude::_esp_hal_timer_Timer;
+//!
-//! # use esp_hal::prelude::*;
 //! let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
 //! let timer0 = timg0.timer0;
 //!
@@ -42,6 +41,8 @@
 //! while !timer0.is_interrupt_set() {
 //!     // Wait
 //! }
+//!
+//! timer0.clear_interrupt();
 //! # }
 //! ```
 //! 
@@ -49,7 +50,7 @@
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::timer::timg::TimerGroup;
-//! # use esp_hal::prelude::*;
+//!
 //! let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
 //! let mut wdt = timg0.wdt;
 //!

esp-hal/src/uart.rs

@@ -1,6 +1,7 @@
 //! # Universal Asynchronous Receiver/Transmitter (UART)
 //!
 //! ## Overview
+//!
 //! The UART is a hardware peripheral which handles communication using serial
 //! communication interfaces, such as RS232 and RS485. This peripheral provides
 //! a cheap and ubiquitous method for full- and half-duplex communication
@@ -13,6 +14,7 @@
 //! protocols.
 //!
 //! ## Configuration
+//!
 //! Each UART controller is individually configurable, and the usual setting
 //! such as baud rate, data bits, parity, and stop bits can easily be
 //! configured. Additionally, the transmit (TX) and receive (RX) pins need to
@@ -20,20 +22,26 @@
 //!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
-//! # use esp_hal::uart::{config::Config, Uart};
+//! # use esp_hal::uart::Uart;
 //! use esp_hal::gpio::Io;
+//!
 //! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 //!
-//! let mut uart1 = Uart::new(peripherals.UART1, &clocks, io.pins.gpio1,
+//! let mut uart1 = Uart::new(
-//!     io.pins.gpio2).unwrap();
+//!     peripherals.UART1,
+//!     &clocks,
+//!     io.pins.gpio1,
+//!     io.pins.gpio2,
+//! ).unwrap();
 //! # }
 //! ```
 //! 
 //! The UART controller can be configured to invert the polarity of the pins.
-//! This is achived by inverting the desired pins, and then constructing the
+//! This is achieved by inverting the desired pins, and then constructing the
 //! UART instance using the inverted pins.
 //!
 //! ## Usage
+//!
 //! The UART driver implements a number of third-party traits, with the
 //! intention of making the HAL inter-compatible with various device drivers
 //! from the community. This includes, but is not limited to, the [embedded-hal]
@@ -49,7 +57,7 @@
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::uart::{config::Config, Uart};
-//! use esp_hal::gpio::Io;
+//! # use esp_hal::gpio::Io;
 //! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 //! # let mut uart1 = Uart::new_with_config(
 //! #     peripherals.UART1,
@@ -67,7 +75,7 @@
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::uart::{config::Config, Uart};
-//! use esp_hal::gpio::Io;
+//! # use esp_hal::gpio::Io;
 //! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 //! # let mut uart1 = Uart::new_with_config(
 //! #     peripherals.UART1,
@@ -88,21 +96,28 @@
 //! ### Inverting TX and RX Pins
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
-//! # use esp_hal::uart::{config::Config, Uart};
+//! # use esp_hal::uart::Uart;
 //! use esp_hal::gpio::{AnyPin, Io};
+//!
 //! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 //!
 //! let tx = AnyPin::new_inverted(io.pins.gpio1);
 //! let rx = AnyPin::new_inverted(io.pins.gpio2);
-//! let mut uart1 = Uart::new(peripherals.UART1, &clocks, tx, rx).unwrap();
+//! let mut uart1 = Uart::new(
+//!     peripherals.UART1,
+//!     &clocks,
+//!     tx,
+//!     rx,
+//! ).unwrap();
 //! # }
 //! ```
 //! 
 //! ### Constructing TX and RX Components
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
-//! # use esp_hal::uart::{config::Config, UartTx, UartRx};
+//! # use esp_hal::uart::{UartTx, UartRx};
 //! use esp_hal::gpio::{AnyPin, Io};
+//!
 //! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 //!
 //! let tx = UartTx::new(peripherals.UART0, &clocks,
@@ -167,7 +182,7 @@ cfg_if::cfg_if! {
         /// Default RX pin for UART0 on ESP32-C3.
         /// Corresponds to GPIO20.
         pub type DefaultRxPin = crate::gpio::Gpio20;
-    }else if #[cfg(esp32c6)] {
+    } else if #[cfg(esp32c6)] {
         /// Default TX pin for UART0 on ESP32-C6.
         /// Corresponds to GPIO16.
         pub type DefaultTxPin = crate::gpio::Gpio16;
@@ -175,7 +190,7 @@ cfg_if::cfg_if! {
         /// Default RX pin for UART0 on ESP32-C6.
         /// Corresponds to GPIO17.
         pub type DefaultRxPin = crate::gpio::Gpio17;
-    }else if #[cfg(esp32h2)] {
+    } else if #[cfg(esp32h2)] {
         /// Default TX pin for UART0 on ESP32-H2.
         /// Corresponds to GPIO24.
         pub type DefaultTxPin = crate::gpio::Gpio24;

esp-hal/src/usb_serial_jtag.rs

@@ -45,17 +45,19 @@
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! use esp_hal::usb_serial_jtag::UsbSerialJtag;
+//!
 //! let mut usb_serial = UsbSerialJtag::new(peripherals.USB_DEVICE);
 //!
 //! // Write bytes out over the USB Serial/JTAG:
 //! usb_serial.write_bytes(b"Hello, world!").expect("write error!");
-//! }
+//! # }
 //! ```
 //! 
 //! ### Splitting the USB Serial/JTAG into TX and RX Components
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
-//! # use esp_hal::usb_serial_jtag::UsbSerialJtag;
+//! use esp_hal::usb_serial_jtag::UsbSerialJtag;
+//!
 //! let mut usb_serial = UsbSerialJtag::new(peripherals.USB_DEVICE);
 //! // The USB Serial/JTAG can be split into separate Transmit and Receive
 //! // components:

examples/src/bin/adc.rs

@@ -19,20 +19,15 @@
 use esp_backtrace as _;
 use esp_hal::{
     analog::adc::{Adc, AdcConfig, Attenuation},
-    clock::ClockControl,
     delay::Delay,
     gpio::Io,
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
 };
 use esp_println::println;
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
     cfg_if::cfg_if! {

examples/src/bin/adc_cal.rs

@@ -15,20 +15,15 @@
 use esp_backtrace as _;
 use esp_hal::{
     analog::adc::{Adc, AdcConfig, Attenuation},
-    clock::ClockControl,
     delay::Delay,
     gpio::Io,
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
 };
 use esp_println::println;
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
     cfg_if::cfg_if! {

examples/src/bin/advanced_serial.rs

@@ -13,23 +13,13 @@
 #![no_main]
 
 use esp_backtrace as _;
-use esp_hal::{
+use esp_hal::{delay::Delay, gpio::Io, prelude::*, uart::Uart};
-    clock::ClockControl,
-    delay::Delay,
-    gpio::Io,
-    peripherals::Peripherals,
-    prelude::*,
-    system::SystemControl,
-    uart::Uart,
-};
 use esp_println::println;
 use nb::block;
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 

examples/src/bin/blinky.rs

@@ -10,19 +10,14 @@
 
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     delay::Delay,
     gpio::{Io, Level, Output},
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
 };
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     // Set GPIO0 as an output, and set its state high initially.
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);

examples/src/bin/blinky_erased_pins.rs

@@ -13,19 +13,14 @@
 
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     delay::Delay,
     gpio::{AnyInput, AnyOutput, Io, Level, Pull},
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
 };
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 

examples/src/bin/dac.rs

@@ -19,21 +19,11 @@
 #![no_main]
 
 use esp_backtrace as _;
-use esp_hal::{
+use esp_hal::{analog::dac::Dac, delay::Delay, gpio::Io, prelude::*};
-    analog::dac::Dac,
-    clock::ClockControl,
-    delay::Delay,
-    gpio::Io,
-    peripherals::Peripherals,
-    prelude::*,
-    system::SystemControl,
-};
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 

examples/src/bin/debug_assist.rs

@@ -11,22 +11,14 @@ use core::cell::RefCell;
 
 use critical_section::Mutex;
 use esp_backtrace as _;
-use esp_hal::{
+use esp_hal::{assist_debug::DebugAssist, prelude::*};
-    assist_debug::DebugAssist,
-    clock::ClockControl,
-    peripherals::Peripherals,
-    prelude::*,
-    system::SystemControl,
-};
 use esp_println::println;
 
 static DA: Mutex<RefCell<Option<DebugAssist>>> = Mutex::new(RefCell::new(None));
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, _clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let _clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let mut da = DebugAssist::new(peripherals.ASSIST_DEBUG);
     da.set_interrupt_handler(interrupt_handler);

examples/src/bin/dma_extmem2mem.rs

@@ -9,13 +9,10 @@
 use aligned::{Aligned, A64};
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     delay::Delay,
     dma::{Dma, DmaPriority, Mem2Mem},
     dma_descriptors_chunk_size,
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
 };
 use log::{error, info};
 extern crate alloc;
@@ -65,10 +62,9 @@ fn init_heap(psram: impl esp_hal::peripheral::Peripheral<P = esp_hal::peripheral
 fn main() -> ! {
     esp_println::logger::init_logger(log::LevelFilter::Info);
 
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
+
     init_heap(peripherals.PSRAM);
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
     let delay = Delay::new(&clocks);
 
     let mut extram_buffer: &mut [u8] = dma_alloc_buffer!(DATA_SIZE, 64);

examples/src/bin/dma_mem2mem.rs

@@ -8,13 +8,10 @@
 
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     delay::Delay,
     dma::{Dma, DmaPriority, Mem2Mem},
     dma_buffers,
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
 };
 use log::{error, info};
 
@@ -24,9 +21,8 @@ const DATA_SIZE: usize = 1024 * 10;
 fn main() -> ! {
     esp_println::logger::init_logger(log::LevelFilter::Info);
 
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
+
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
     let delay = Delay::new(&clocks);
 
     let (tx_buffer, tx_descriptors, mut rx_buffer, rx_descriptors) = dma_buffers!(DATA_SIZE);

examples/src/bin/embassy_hello_world.rs

@@ -12,12 +12,7 @@
 use embassy_executor::Spawner;
 use embassy_time::{Duration, Timer};
 use esp_backtrace as _;
-use esp_hal::{
+use esp_hal::timer::timg::TimerGroup;
-    clock::ClockControl,
-    peripherals::Peripherals,
-    system::SystemControl,
-    timer::timg::TimerGroup,
-};
 
 #[embassy_executor::task]
 async fn run() {
@@ -30,11 +25,9 @@ async fn run() {
 #[esp_hal_embassy::main]
 async fn main(spawner: Spawner) {
     esp_println::logger::init_logger_from_env();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
 
     esp_println::println!("Init!");
-    let peripherals = Peripherals::take();
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
     esp_hal_embassy::init(&clocks, timg0.timer0);

examples/src/bin/embassy_i2c.rs

@@ -19,22 +19,12 @@
 use embassy_executor::Spawner;
 use embassy_time::{Duration, Timer};
 use esp_backtrace as _;
-use esp_hal::{
+use esp_hal::{gpio::Io, i2c::I2C, prelude::*, timer::timg::TimerGroup};
-    clock::ClockControl,
-    gpio::Io,
-    i2c::I2C,
-    peripherals::Peripherals,
-    prelude::*,
-    system::SystemControl,
-    timer::timg::TimerGroup,
-};
 use lis3dh_async::{Lis3dh, Range, SlaveAddr};
 
 #[esp_hal_embassy::main]
 async fn main(_spawner: Spawner) {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
     esp_hal_embassy::init(&clocks, timg0.timer0);

examples/src/bin/embassy_i2c_bmp180_calibration_data.rs

@@ -20,21 +20,11 @@
 use embassy_executor::Spawner;
 use embassy_time::{Duration, Timer};
 use esp_backtrace as _;
-use esp_hal::{
+use esp_hal::{gpio::Io, i2c::I2C, prelude::*, timer::timg::TimerGroup};
-    clock::ClockControl,
-    gpio::Io,
-    i2c::I2C,
-    peripherals::Peripherals,
-    prelude::*,
-    system::SystemControl,
-    timer::timg::TimerGroup,
-};
 
 #[esp_hal_embassy::main]
 async fn main(_spawner: Spawner) {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
     esp_hal_embassy::init(&clocks, timg0.timer0);

examples/src/bin/embassy_i2s_read.rs

@@ -20,14 +20,11 @@
 use embassy_executor::Spawner;
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     dma::{Dma, DmaPriority},
     dma_buffers,
     gpio::Io,
     i2s::{asynch::*, DataFormat, I2s, Standard},
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
     timer::timg::TimerGroup,
 };
 use esp_println::println;
@@ -35,9 +32,7 @@ use esp_println::println;
 #[esp_hal_embassy::main]
 async fn main(_spawner: Spawner) {
     println!("Init!");
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
     esp_hal_embassy::init(&clocks, timg0.timer0);

examples/src/bin/embassy_i2s_sound.rs

@@ -34,14 +34,11 @@
 use embassy_executor::Spawner;
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     dma::{Dma, DmaPriority},
     dma_buffers,
     gpio::Io,
     i2s::{asynch::*, DataFormat, I2s, Standard},
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
     timer::timg::TimerGroup,
 };
 use esp_println::println;
@@ -57,9 +54,7 @@ const SINE: [i16; 64] = [
 #[esp_hal_embassy::main]
 async fn main(_spawner: Spawner) {
     println!("Init!");
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
     esp_hal_embassy::init(&clocks, timg0.timer0);

examples/src/bin/embassy_multicore.rs

@@ -19,12 +19,9 @@ use embassy_sync::{blocking_mutex::raw::CriticalSectionRawMutex, signal::Signal}
 use embassy_time::{Duration, Ticker};
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     cpu_control::{CpuControl, Stack},
     get_core,
     gpio::{AnyOutput, Io, Level},
-    peripherals::Peripherals,
-    system::SystemControl,
     timer::{timg::TimerGroup, ErasedTimer},
 };
 use esp_hal_embassy::Executor;
@@ -54,9 +51,7 @@ async fn control_led(
 
 #[esp_hal_embassy::main]
 async fn main(_spawner: Spawner) {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 

examples/src/bin/embassy_multicore_interrupt.rs

@@ -18,14 +18,11 @@ use embassy_sync::{blocking_mutex::raw::CriticalSectionRawMutex, signal::Signal}
 use embassy_time::{Duration, Ticker};
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     cpu_control::{CpuControl, Stack},
     get_core,
     gpio::{AnyOutput, Io, Level},
-    interrupt::Priority,
+    interrupt::{software::SoftwareInterruptControl, Priority},
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
     timer::{timg::TimerGroup, ErasedTimer},
 };
 use esp_hal_embassy::InterruptExecutor;
@@ -74,9 +71,9 @@ async fn enable_disable_led(control: &'static Signal<CriticalSectionRawMutex, bo
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
+
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
+    let sw_ints = SoftwareInterruptControl::new(peripherals.SW_INTERRUPT);
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 
@@ -93,8 +90,7 @@ fn main() -> ! {
     let led = AnyOutput::new(io.pins.gpio0, Level::Low);
 
     static EXECUTOR_CORE_1: StaticCell<InterruptExecutor<1>> = StaticCell::new();
-    let executor_core1 =
+    let executor_core1 = InterruptExecutor::new(sw_ints.software_interrupt1);
-        InterruptExecutor::new(system.software_interrupt_control.software_interrupt1);
     let executor_core1 = EXECUTOR_CORE_1.init(executor_core1);
 
     let _guard = cpu_control
@@ -109,8 +105,7 @@ fn main() -> ! {
         .unwrap();
 
     static EXECUTOR_CORE_0: StaticCell<InterruptExecutor<0>> = StaticCell::new();
-    let executor_core0 =
+    let executor_core0 = InterruptExecutor::new(sw_ints.software_interrupt0);
-        InterruptExecutor::new(system.software_interrupt_control.software_interrupt0);
     let executor_core0 = EXECUTOR_CORE_0.init(executor_core0);
 
     let spawner = executor_core0.start(Priority::Priority1);

examples/src/bin/embassy_multiprio.rs

@@ -24,10 +24,7 @@ use embassy_executor::Spawner;
 use embassy_time::{Duration, Instant, Ticker, Timer};
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
+    interrupt::{software::SoftwareInterruptControl, Priority},
-    interrupt::Priority,
-    peripherals::Peripherals,
-    system::SystemControl,
     timer::{timg::TimerGroup, ErasedTimer},
 };
 use esp_hal_embassy::InterruptExecutor;
@@ -73,9 +70,10 @@ async fn low_prio_async() {
 async fn main(low_prio_spawner: Spawner) {
     esp_println::logger::init_logger_from_env();
     println!("Init!");
-    let peripherals = Peripherals::take();
+
-    let system = SystemControl::new(peripherals.SYSTEM);
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
+
+    let sw_ints = SoftwareInterruptControl::new(peripherals.SW_INTERRUPT);
 
     let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
     let timer0: ErasedTimer = timg0.timer0.into();
@@ -94,7 +92,7 @@ async fn main(low_prio_spawner: Spawner) {
     esp_hal_embassy::init(&clocks, [timer0, timer1]);
 
     static EXECUTOR: StaticCell<InterruptExecutor<2>> = StaticCell::new();
-    let executor = InterruptExecutor::new(system.software_interrupt_control.software_interrupt2);
+    let executor = InterruptExecutor::new(sw_ints.software_interrupt2);
     let executor = EXECUTOR.init(executor);
 
     let spawner = executor.start(Priority::Priority3);

examples/src/bin/embassy_parl_io_rx.rs

@@ -14,14 +14,11 @@ use embassy_executor::Spawner;
 use embassy_time::{Duration, Timer};
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     dma::{Dma, DmaPriority},
     dma_buffers,
     gpio::Io,
     parl_io::{no_clk_pin, BitPackOrder, ParlIoRxOnly, RxFourBits},
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
     timer::systimer::{SystemTimer, Target},
 };
 use esp_println::println;
@@ -29,9 +26,7 @@ use esp_println::println;
 #[esp_hal_embassy::main]
 async fn main(_spawner: Spawner) {
     esp_println::println!("Init!");
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let systimer = SystemTimer::new(peripherals.SYSTIMER).split::<Target>();
     esp_hal_embassy::init(&clocks, systimer.alarm0);

examples/src/bin/embassy_parl_io_tx.rs

@@ -18,7 +18,6 @@ use embassy_executor::Spawner;
 use embassy_time::{Duration, Timer};
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     dma::{Dma, DmaPriority},
     dma_buffers,
     gpio::Io,
@@ -30,9 +29,7 @@ use esp_hal::{
         TxFourBits,
         TxPinConfigWithValidPin,
     },
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
     timer::systimer::{SystemTimer, Target},
 };
 use esp_println::println;
@@ -40,9 +37,7 @@ use esp_println::println;
 #[esp_hal_embassy::main]
 async fn main(_spawner: Spawner) {
     esp_println::println!("Init!");
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let systimer = SystemTimer::new(peripherals.SYSTIMER).split::<Target>();
     esp_hal_embassy::init(&clocks, systimer.alarm0);

examples/src/bin/embassy_rmt_rx.rs

@@ -13,12 +13,9 @@ use embassy_executor::Spawner;
 use embassy_time::{Duration, Timer};
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     gpio::{Gpio5, Io, Level, Output},
-    peripherals::Peripherals,
     prelude::*,
     rmt::{asynch::RxChannelAsync, PulseCode, Rmt, RxChannelConfig, RxChannelCreatorAsync},
-    system::SystemControl,
     timer::timg::TimerGroup,
 };
 use esp_println::{print, println};
@@ -42,9 +39,7 @@ async fn signal_task(mut pin: Output<'static, Gpio5>) {
 #[esp_hal_embassy::main]
 async fn main(spawner: Spawner) {
     println!("Init!");
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
     esp_hal_embassy::init(&clocks, timg0.timer0);

examples/src/bin/embassy_rmt_tx.rs

@@ -15,12 +15,9 @@ use embassy_executor::Spawner;
 use embassy_time::{Duration, Timer};
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     gpio::Io,
-    peripherals::Peripherals,
     prelude::*,
     rmt::{asynch::TxChannelAsync, PulseCode, Rmt, TxChannelConfig, TxChannelCreatorAsync},
-    system::SystemControl,
     timer::timg::TimerGroup,
 };
 use esp_println::println;
@@ -28,9 +25,7 @@ use esp_println::println;
 #[esp_hal_embassy::main]
 async fn main(_spawner: Spawner) {
     println!("Init!");
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
     esp_hal_embassy::init(&clocks, timg0.timer0);

examples/src/bin/embassy_serial.rs

@@ -1,7 +1,7 @@
 //! embassy serial
 //!
 //! This is an example of running the embassy executor and asynchronously
-//! writing to and reading from uart
+//! writing to and reading from UART.
 
 //% CHIPS: esp32 esp32c2 esp32c3 esp32c6 esp32h2 esp32s2 esp32s3
 //% FEATURES: async embassy embassy-generic-timers
@@ -13,10 +13,8 @@ use embassy_executor::Spawner;
 use embassy_sync::{blocking_mutex::raw::NoopRawMutex, signal::Signal};
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     gpio::Io,
-    peripherals::{Peripherals, UART0},
+    peripherals::UART0,
-    system::SystemControl,
     timer::timg::TimerGroup,
     uart::{
         config::{AtCmdConfig, Config},
@@ -80,9 +78,7 @@ async fn reader(
 #[esp_hal_embassy::main]
 async fn main(spawner: Spawner) {
     esp_println::println!("Init!");
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
     esp_hal_embassy::init(&clocks, timg0.timer0);

examples/src/bin/embassy_spi.rs

@@ -22,23 +22,18 @@ use embassy_executor::Spawner;
 use embassy_time::{Duration, Timer};
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     dma::*,
     dma_buffers,
     gpio::Io,
-    peripherals::Peripherals,
     prelude::*,
     spi::{master::Spi, SpiMode},
-    system::SystemControl,
     timer::timg::TimerGroup,
 };
 
 #[esp_hal_embassy::main]
 async fn main(_spawner: Spawner) {
     esp_println::println!("Init!");
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
     esp_hal_embassy::init(&clocks, timg0.timer0);

examples/src/bin/embassy_touch.rs

@@ -17,11 +17,8 @@ use embassy_futures::select::{select, Either};
 use embassy_time::{Duration, Timer};
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     gpio::Io,
-    peripherals::Peripherals,
     rtc_cntl::Rtc,
-    system::SystemControl,
     timer::timg::TimerGroup,
     touch::{Touch, TouchConfig, TouchPad},
 };
@@ -30,10 +27,7 @@ use esp_println::println;
 #[esp_hal_embassy::main]
 async fn main(_spawner: Spawner) {
     esp_println::logger::init_logger_from_env();
-
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let peripherals = Peripherals::take();
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
     esp_hal_embassy::init(&clocks, timg0.timer0);

examples/src/bin/embassy_twai.rs

@@ -25,11 +25,9 @@ use embassy_sync::{blocking_mutex::raw::NoopRawMutex, channel::Channel};
 use embedded_can::{Frame, Id};
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     gpio::Io,
     interrupt,
-    peripherals::{self, Peripherals, TWAI0},
+    peripherals::{self, TWAI0},
-    system::SystemControl,
     timer::timg::TimerGroup,
     twai::{self, EspTwaiFrame, TwaiMode, TwaiRx, TwaiTx},
 };
@@ -84,9 +82,7 @@ async fn transmitter(
 
 #[esp_hal_embassy::main]
 async fn main(spawner: Spawner) {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
     esp_hal_embassy::init(&clocks, timg0.timer0);

examples/src/bin/embassy_usb_serial.rs

@@ -21,23 +21,18 @@ use embassy_usb::{
 };
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     gpio::Io,
     otg_fs::{
         asynch::{Config, Driver},
         Usb,
     },
-    peripherals::Peripherals,
-    system::SystemControl,
     timer::timg::TimerGroup,
 };
 
 #[esp_hal_embassy::main]
-async fn main(_spawner: Spawner) -> () {
+async fn main(_spawner: Spawner) {
     esp_println::println!("Init!");
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
     esp_hal_embassy::init(&clocks, timg0.timer0);

examples/src/bin/embassy_usb_serial_jtag.rs

@@ -12,9 +12,6 @@ use embassy_executor::Spawner;
 use embassy_sync::{blocking_mutex::raw::NoopRawMutex, signal::Signal};
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
-    peripherals::Peripherals,
-    system::SystemControl,
     timer::timg::TimerGroup,
     usb_serial_jtag::{UsbSerialJtag, UsbSerialJtagRx, UsbSerialJtagTx},
     Async,
@@ -64,11 +61,9 @@ async fn reader(
 }
 
 #[esp_hal_embassy::main]
-async fn main(spawner: Spawner) -> () {
+async fn main(spawner: Spawner) {
     esp_println::println!("Init!");
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
     esp_hal_embassy::init(&clocks, timg0.timer0);

examples/src/bin/embassy_wait.rs

@@ -12,28 +12,27 @@ use embassy_executor::Spawner;
 use embassy_time::{Duration, Timer};
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     gpio::{Input, Io, Pull},
-    peripherals::Peripherals,
-    system::SystemControl,
     timer::timg::TimerGroup,
 };
 
 #[esp_hal_embassy::main]
 async fn main(_spawner: Spawner) {
     esp_println::println!("Init!");
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
     esp_hal_embassy::init(&clocks, timg0.timer0);
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
-    #[cfg(any(feature = "esp32", feature = "esp32s2", feature = "esp32s3"))]
+
+    cfg_if::cfg_if! {
+        if #[cfg(any(feature = "esp32", feature = "esp32s2", feature = "esp32s3"))] {
             let mut input = Input::new(io.pins.gpio0, Pull::Down);
-    #[cfg(not(any(feature = "esp32", feature = "esp32s2", feature = "esp32s3")))]
+        } else {
             let mut input = Input::new(io.pins.gpio9, Pull::Down);
+        }
+    }
 
     loop {
         esp_println::println!("Waiting...");

examples/src/bin/etm_blinky_systimer.rs

@@ -17,7 +17,6 @@ use esp_hal::{
         Level,
         Pull,
     },
-    peripherals::Peripherals,
     prelude::*,
     timer::systimer::{etm::SysTimerEtmEvent, Periodic, SystemTimer},
 };
@@ -25,7 +24,7 @@ use fugit::ExtU32;
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, _clocks) = esp_hal::init(esp_hal::Config::default());
 
     let syst = SystemTimer::new(peripherals.SYSTIMER);
     let syst_alarms = syst.split::<Periodic>();

examples/src/bin/etm_gpio.rs

@@ -17,13 +17,12 @@ use esp_hal::{
         Level,
         Pull,
     },
-    peripherals::Peripherals,
     prelude::*,
 };
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, _clocks) = esp_hal::init(esp_hal::Config::default());
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
     let mut led = io.pins.gpio1;

examples/src/bin/etm_timer.rs

@@ -11,12 +11,10 @@ use core::cell::RefCell;
 use critical_section::Mutex;
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     delay::Delay,
     etm::Etm,
-    peripherals::{Peripherals, TIMG0},
+    peripherals::TIMG0,
     prelude::*,
-    system::SystemControl,
     timer::timg::{
         etm::{TimerEtmEvents, TimerEtmTasks},
         Timer,
@@ -30,9 +28,7 @@ static TIMER0: Mutex<RefCell<Option<Timer<Timer0<TIMG0>, esp_hal::Blocking>>>> =
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
     let timer0 = timg0.timer0;

examples/src/bin/gpio_interrupt.rs

@@ -16,13 +16,10 @@ use core::cell::RefCell;
 use critical_section::Mutex;
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     delay::Delay,
     gpio::{self, Event, Input, Io, Level, Output, Pull},
     macros::ram,
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
 };
 
 cfg_if::cfg_if! {
@@ -35,9 +32,7 @@ cfg_if::cfg_if! {
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     // Set GPIO2 as an output, and set its state high initially.
     let mut io = Io::new(peripherals.GPIO, peripherals.IO_MUX);

examples/src/bin/hello_rgb.rs

@@ -25,15 +25,7 @@
 #![no_main]
 
 use esp_backtrace as _;
-use esp_hal::{
+use esp_hal::{delay::Delay, gpio::Io, prelude::*, rmt::Rmt};
-    clock::ClockControl,
-    delay::Delay,
-    gpio::Io,
-    peripherals::Peripherals,
-    prelude::*,
-    rmt::Rmt,
-    system::SystemControl,
-};
 use esp_hal_smartled::{smartLedBuffer, SmartLedsAdapter};
 use smart_leds::{
     brightness,
@@ -44,9 +36,7 @@ use smart_leds::{
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 

examples/src/bin/hello_world.rs

@@ -15,21 +15,11 @@
 use core::fmt::Write;
 
 use esp_backtrace as _;
-use esp_hal::{
+use esp_hal::{delay::Delay, gpio::Io, prelude::*, uart::Uart};
-    clock::ClockControl,
-    delay::Delay,
-    gpio::Io,
-    peripherals::Peripherals,
-    prelude::*,
-    system::SystemControl,
-    uart::Uart,
-};
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let delay = Delay::new(&clocks);
 

examples/src/bin/hmac.rs

@@ -59,12 +59,9 @@
 
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     hmac::{Hmac, HmacPurpose, KeyId},
-    peripherals::Peripherals,
     prelude::*,
     rng::Rng,
-    system::SystemControl,
     timer::systimer::SystemTimer,
 };
 use esp_println::println;
@@ -76,9 +73,7 @@ type HmacSha256 = HmacSw<Sha256>;
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, _clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let _clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let mut rng = Rng::new(peripherals.RNG);
 

examples/src/bin/i2c_bmp180_calibration_data.rs

@@ -12,21 +12,12 @@
 #![no_main]
 
 use esp_backtrace as _;
-use esp_hal::{
+use esp_hal::{gpio::Io, i2c::I2C, prelude::*};
-    clock::ClockControl,
-    gpio::Io,
-    i2c::I2C,
-    peripherals::Peripherals,
-    prelude::*,
-    system::SystemControl,
-};
 use esp_println::println;
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 

examples/src/bin/i2c_display.rs

@@ -23,22 +23,12 @@ use embedded_graphics::{
     text::{Alignment, Text},
 };
 use esp_backtrace as _;
-use esp_hal::{
+use esp_hal::{delay::Delay, gpio::Io, i2c::I2C, prelude::*};
-    clock::ClockControl,
-    delay::Delay,
-    gpio::Io,
-    i2c::I2C,
-    peripherals::Peripherals,
-    prelude::*,
-    system::SystemControl,
-};
 use ssd1306::{prelude::*, I2CDisplayInterface, Ssd1306};
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let delay = Delay::new(&clocks);
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);

examples/src/bin/i2s_read.rs

@@ -18,22 +18,17 @@
 
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     dma::{Dma, DmaPriority},
     dma_buffers,
     gpio::Io,
     i2s::{DataFormat, I2s, I2sReadDma, Standard},
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
 };
 use esp_println::println;
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 

examples/src/bin/i2s_sound.rs

@@ -1,7 +1,7 @@
-//! This shows how to transmit data continously via I2S.
+//! This shows how to transmit data continuously via I2S.
 //!
 //! Without an additional I2S sink device you can inspect the MCLK, BCLK, WS
-//!  andDOUT with a logic analyzer.
+//!  and DOUT with a logic analyzer.
 //!
 //! You can also connect e.g. a PCM510x to hear an annoying loud sine tone (full
 //! scale), so turn down the volume before running this example.
@@ -32,14 +32,11 @@
 
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     dma::{Dma, DmaPriority},
     dma_buffers,
     gpio::Io,
     i2s::{DataFormat, I2s, I2sWriteDma, Standard},
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
 };
 
 const SINE: [i16; 64] = [
@@ -52,9 +49,7 @@ const SINE: [i16; 64] = [
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 

examples/src/bin/ieee802154_receive_all_frames.rs

@@ -4,13 +4,13 @@
 #![no_main]
 
 use esp_backtrace as _;
-use esp_hal::{peripherals::Peripherals, prelude::*};
+use esp_hal::prelude::*;
-use esp_ieee802154::*;
+use esp_ieee802154::{Config, Ieee802154};
 use esp_println::println;
 
 #[entry]
 fn main() -> ! {
-    let mut peripherals = Peripherals::take();
+    let (mut peripherals, _clocks) = esp_hal::init(esp_hal::Config::default());
     let mut ieee802154 = Ieee802154::new(peripherals.IEEE802154, &mut peripherals.RADIO_CLK);
 
     ieee802154.set_config(Config {
@@ -19,7 +19,7 @@ fn main() -> ! {
         rx_when_idle: true,
         auto_ack_rx: false,
         auto_ack_tx: false,
-        ..Config::default()
+        ..Default::default()
     });
 
     println!("Start receiving:");

examples/src/bin/ieee802154_receive_frame.rs

@@ -4,13 +4,13 @@
 #![no_main]
 
 use esp_backtrace as _;
-use esp_hal::{peripherals::Peripherals, prelude::*};
+use esp_hal::prelude::*;
-use esp_ieee802154::*;
+use esp_ieee802154::{Config, Ieee802154};
 use esp_println::println;
 
 #[entry]
 fn main() -> ! {
-    let mut peripherals = Peripherals::take();
+    let (mut peripherals, _clocks) = esp_hal::init(esp_hal::Config::default());
     let mut ieee802154 = Ieee802154::new(peripherals.IEEE802154, &mut peripherals.RADIO_CLK);
 
     ieee802154.set_config(Config {
@@ -21,7 +21,7 @@ fn main() -> ! {
         auto_ack_tx: true,
         pan_id: Some(0x4242),
         short_addr: Some(0x2323),
-        ..Config::default()
+        ..Default::default()
     });
 
     println!("Start receiving:");

examples/src/bin/ieee802154_send_broadcast_frame.rs

@@ -4,14 +4,8 @@
 #![no_main]
 
 use esp_backtrace as _;
-use esp_hal::{
+use esp_hal::{delay::Delay, prelude::*};
-    clock::ClockControl,
+use esp_ieee802154::{Config, Frame, Ieee802154};
-    delay::Delay,
-    peripherals::Peripherals,
-    prelude::*,
-    system::SystemControl,
-};
-use esp_ieee802154::*;
 use esp_println::println;
 use ieee802154::mac::{
     Address,
@@ -25,9 +19,7 @@ use ieee802154::mac::{
 
 #[entry]
 fn main() -> ! {
-    let mut peripherals = Peripherals::take();
+    let (mut peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::max(system.clock_control).freeze();
 
     let delay = Delay::new(&clocks);
 
@@ -38,7 +30,7 @@ fn main() -> ! {
         promiscuous: false,
         pan_id: Some(0x4242),
         short_addr: Some(0x2323),
-        ..Config::default()
+        ..Default::default()
     });
 
     let mut seq_number = 0u8;

examples/src/bin/ieee802154_send_frame.rs

@@ -4,14 +4,8 @@
 #![no_main]
 
 use esp_backtrace as _;
-use esp_hal::{
+use esp_hal::{delay::Delay, prelude::*};
-    clock::ClockControl,
+use esp_ieee802154::{Config, Frame, Ieee802154};
-    delay::Delay,
-    peripherals::Peripherals,
-    prelude::*,
-    system::SystemControl,
-};
-use esp_ieee802154::*;
 use esp_println::println;
 use ieee802154::mac::{
     Address,
@@ -25,9 +19,7 @@ use ieee802154::mac::{
 
 #[entry]
 fn main() -> ! {
-    let mut peripherals = Peripherals::take();
+    let (mut peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::max(system.clock_control).freeze();
 
     let delay = Delay::new(&clocks);
 
@@ -38,7 +30,7 @@ fn main() -> ! {
         promiscuous: false,
         pan_id: Some(0x4242),
         short_addr: Some(0x2222),
-        ..Config::default()
+        ..Default::default()
     });
 
     let mut seq_number = 0u8;

examples/src/bin/ieee802154_sniffer.rs

@@ -8,23 +8,13 @@
 #![no_main]
 
 use esp_backtrace as _;
-use esp_hal::{
+use esp_hal::{gpio::Io, prelude::*, reset::software_reset, uart::Uart};
-    clock::ClockControl,
+use esp_ieee802154::{Config, Ieee802154};
-    gpio::Io,
-    peripherals::Peripherals,
-    prelude::*,
-    reset::software_reset,
-    system::SystemControl,
-    uart::Uart,
-};
-use esp_ieee802154::*;
 use esp_println::println;
 
 #[entry]
 fn main() -> ! {
-    let mut peripherals = Peripherals::take();
+    let (mut peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::max(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 
@@ -69,7 +59,7 @@ fn main() -> ! {
         rx_when_idle: true,
         auto_ack_rx: false,
         auto_ack_tx: false,
-        ..Config::default()
+        ..Default::default()
     });
 
     ieee802154.start_receive();

examples/src/bin/lcd_cam_ov2640.rs

@@ -25,7 +25,6 @@
 
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     delay::Delay,
     dma::{Dma, DmaPriority},
     dma_buffers,
@@ -36,18 +35,14 @@ use esp_hal::{
         cam::{Camera, RxEightBits},
         LcdCam,
     },
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
     Blocking,
 };
 use esp_println::println;
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 

examples/src/bin/lcd_i8080.rs

@@ -23,7 +23,6 @@
 
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     delay::Delay,
     dma::{Dma, DmaPriority},
     dma_buffers,
@@ -32,17 +31,13 @@ use esp_hal::{
         lcd::i8080::{Config, TxEightBits, I8080},
         LcdCam,
     },
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
 };
 use esp_println::println;
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 

examples/src/bin/ledc.rs

@@ -11,7 +11,6 @@
 
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     gpio::Io,
     ledc::{
         channel::{self, ChannelIFace},
@@ -20,16 +19,12 @@ use esp_hal::{
         Ledc,
         LowSpeed,
     },
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
 };
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
     let led = io.pins.gpio0;

examples/src/bin/lp_core_basic.rs

@@ -17,14 +17,13 @@ use esp_backtrace as _;
 use esp_hal::{
     gpio::{lp_io::LowPowerOutput, Io},
     lp_core::{LpCore, LpCoreWakeupSource},
-    peripherals::Peripherals,
     prelude::*,
 };
 use esp_println::{print, println};
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, _clocks) = esp_hal::init(esp_hal::Config::default());
 
     // configure GPIO 1 as LP output pin
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);

examples/src/bin/lp_core_i2c.rs

@@ -19,14 +19,13 @@ use esp_hal::{
     gpio::{lp_io::LowPowerOutputOpenDrain, Io},
     i2c::lp_i2c::LpI2c,
     lp_core::{LpCore, LpCoreWakeupSource},
-    peripherals::Peripherals,
     prelude::*,
 };
 use esp_println::println;
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, _clocks) = esp_hal::init(esp_hal::Config::default());
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 

examples/src/bin/lp_core_uart.rs

@@ -16,24 +16,19 @@
 
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     gpio::{
         lp_io::{LowPowerInput, LowPowerOutput},
         Io,
     },
     lp_core::{LpCore, LpCoreWakeupSource},
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
     uart::{config::Config, lp_uart::LpUart, Uart},
 };
 use esp_println::println;
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 

examples/src/bin/mcpwm.rs

@@ -11,19 +11,14 @@
 
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     gpio::Io,
     mcpwm::{operator::PwmPinConfig, timer::PwmWorkingMode, McPwm, PeripheralClockConfig},
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
 };
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
     let pin = io.pins.gpio0;

examples/src/bin/multicore.rs

@@ -13,12 +13,9 @@ use core::{cell::RefCell, ptr::addr_of_mut};
 use critical_section::Mutex;
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     cpu_control::{CpuControl, Stack},
     delay::Delay,
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
 };
 use esp_println::println;
 
@@ -26,9 +23,7 @@ static mut APP_CORE_STACK: Stack<8192> = Stack::new();
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let delay = Delay::new(&clocks);
 

examples/src/bin/parl_io_rx.rs

@@ -11,23 +11,18 @@
 
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     delay::Delay,
     dma::{Dma, DmaPriority},
     dma_buffers,
     gpio::Io,
     parl_io::{no_clk_pin, BitPackOrder, ParlIoRxOnly, RxFourBits},
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
 };
 use esp_println::println;
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 

examples/src/bin/parl_io_tx.rs

@@ -15,7 +15,6 @@
 
 use esp_backtrace as _;
 use esp_hal::{
-    clock::ClockControl,
     delay::Delay,
     dma::{Dma, DmaPriority},
     dma_buffers,
@@ -28,17 +27,13 @@ use esp_hal::{
         TxFourBits,
         TxPinConfigWithValidPin,
     },
-    peripherals::Peripherals,
     prelude::*,
-    system::SystemControl,
 };
 use esp_println::println;
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, clocks) = esp_hal::init(esp_hal::Config::default());
-    let system = SystemControl::new(peripherals.SYSTEM);
-    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 

examples/src/bin/pcnt_encoder.rs

@@ -1,6 +1,6 @@
 //! PCNT Encoder Demo
 //!
-//! This example decodes a quadrature encoder
+//! This example decodes a quadrature encoder.
 //!
 //! Since the PCNT units reset to zero when they reach their limits
 //! we enable an interrupt on the upper and lower limits and
@@ -27,7 +27,6 @@ use esp_hal::{
         unit,
         Pcnt,
     },
-    peripherals::Peripherals,
     prelude::*,
 };
 use esp_println::println;
@@ -38,7 +37,7 @@ static VALUE: AtomicI32 = AtomicI32::new(0);
 
 #[entry]
 fn main() -> ! {
-    let peripherals = Peripherals::take();
+    let (peripherals, _clocks) = esp_hal::init(esp_hal::Config::default());
 
     let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 

examples/src/bin/psram_octal.rs

@@ -13,7 +13,7 @@ extern crate alloc;
 use alloc::{string::String, vec::Vec};
 
 use esp_backtrace as _;
-use esp_hal::{peripherals::Peripherals, prelude::*, psram};
+use esp_hal::{prelude::*, psram};
 use esp_println::println;
 
 #[global_allocator]
@@ -30,7 +30,7 @@ fn main() -> ! {
     #[cfg(debug_assertions)]
     compile_error!("This example MUST be built in release mode!");
 
-    let peripherals = Peripherals::take();
+    let (peripherals, _clocks) = esp_hal::init(esp_hal::Config::default());
 
     psram::init_psram(peripherals.PSRAM);
     init_psram_heap();