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

@@ -84,11 +84,11 @@ By taking these extra steps to test your contributions, you help maintain the hi
 
 Ensuring the quality and reliability of `esp-hal` is a shared responsibility, and testing plays a critical role in this process. Our GitHub CI automatically checks the buildability of all examples and drivers within the project. However, automated tests can't catch everything, especially when it comes to the nuanced behavior of hardware interactions. So make sure that the example affected by your change works as expected. 
 
-Further steps that can (or should) be taken in testing: 
+Further steps that can (or should) be taken in testing:
 
-* Using [xtask], build examples for the specified chip. 
+* Using [xtask], build examples for the specified chip.
 * Build the documentation and run the doctests if they have been modified using the `build-documentation` and  `run-doc-test` commands in [xtask].
-* Run the [HIL] tests locally if changes have been made to them. 
+* Run the [HIL] tests locally if changes have been made to them.
 
 [xtask]: https://github.com/esp-rs/esp-hal/tree/main/xtask
 
@@ -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,8 +55,10 @@
 //! }
 //! # }
 //! ```
+//! 
 //! ## Implementation State
-//! - [ADC calibration is not implemented for all targets].
+//!
+//!  - [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
 use core::marker::PhantomData;

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,72 +365,51 @@ 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
         };
 
-        let pll_freq = match cpu_clock_speed {
+        if cpu_clock_speed != CpuClock::default() {
-            CpuClock::Clock80MHz => PllClock::Pll320MHz,
+            let pll_freq = match cpu_clock_speed {
-            CpuClock::Clock160MHz => PllClock::Pll320MHz,
+                CpuClock::Clock80MHz => PllClock::Pll320MHz,
-            CpuClock::Clock240MHz => PllClock::Pll480MHz,
+                CpuClock::Clock160MHz => PllClock::Pll320MHz,
-        };
+                CpuClock::Clock240MHz => PllClock::Pll480MHz,
+            };
 
-        clocks_ll::esp32_rtc_update_to_xtal(xtal_freq, 1);
+            clocks_ll::esp32_rtc_update_to_xtal(xtal_freq, 1);
-        clocks_ll::esp32_rtc_bbpll_enable();
+            clocks_ll::esp32_rtc_bbpll_enable();
-        clocks_ll::esp32_rtc_bbpll_configure(xtal_freq, pll_freq);
+            clocks_ll::esp32_rtc_bbpll_configure(xtal_freq, pll_freq);
-        clocks_ll::set_cpu_freq(cpu_clock_speed);
+            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,22 +431,26 @@ impl<'d> ClockControl<'d> {
         };
         XTAL_FREQ_MHZ.store(xtal_freq.mhz(), Ordering::Relaxed);
 
-        let pll_freq = PllClock::Pll480MHz;
+        let apb_freq;
+        if cpu_clock_speed != CpuClock::default() {
+            let pll_freq = PllClock::Pll480MHz;
 
-        if cpu_clock_speed.mhz() <= xtal_freq.mhz() {
+            if cpu_clock_speed.mhz() <= xtal_freq.mhz() {
-            apb_freq = ApbClock::ApbFreqOther(cpu_clock_speed.mhz());
+                apb_freq = ApbClock::ApbFreqOther(cpu_clock_speed.mhz());
-            clocks_ll::esp32c2_rtc_update_to_xtal(xtal_freq, 1);
+                clocks_ll::esp32c2_rtc_update_to_xtal(xtal_freq, 1);
-            clocks_ll::esp32c2_rtc_apb_freq_update(apb_freq);
+                clocks_ll::esp32c2_rtc_apb_freq_update(apb_freq);
+            } else {
+                apb_freq = ApbClock::ApbFreq40MHz;
+                clocks_ll::esp32c2_rtc_bbpll_enable();
+                clocks_ll::esp32c2_rtc_bbpll_configure(xtal_freq, pll_freq);
+                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;
-            clocks_ll::esp32c2_rtc_bbpll_enable();
-            clocks_ll::esp32c2_rtc_bbpll_configure(xtal_freq, pll_freq);
-            clocks_ll::esp32c2_rtc_freq_to_pll_mhz(cpu_clock_speed);
-            clocks_ll::esp32c2_rtc_apb_freq_update(apb_freq);
         }
 
         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;
 
-        if cpu_clock_speed.mhz() <= xtal_freq.mhz() {
+        let apb_freq;
-            apb_freq = ApbClock::ApbFreqOther(cpu_clock_speed.mhz());
+        if cpu_clock_speed != CpuClock::default() {
-            clocks_ll::esp32c3_rtc_update_to_xtal(xtal_freq, 1);
+            if cpu_clock_speed.mhz() <= xtal_freq.mhz() {
-            clocks_ll::esp32c3_rtc_apb_freq_update(apb_freq);
+                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;
-            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);
         }
 
         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;
 
-        if cpu_clock_speed.mhz() <= xtal_freq.mhz() {
+        let apb_freq;
-            apb_freq = ApbClock::ApbFreqOther(cpu_clock_speed.mhz());
+        if cpu_clock_speed != CpuClock::default() {
-            clocks_ll::esp32c6_rtc_update_to_xtal(xtal_freq, 1);
+            if cpu_clock_speed.mhz() <= xtal_freq.mhz() {
-            clocks_ll::esp32c6_rtc_apb_freq_update(apb_freq);
+                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;
-            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);
         }
 
         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;
 
-        if cpu_clock_speed.mhz() <= xtal_freq.mhz() {
+        let apb_freq;
-            apb_freq = ApbClock::ApbFreqOther(cpu_clock_speed.mhz());
+        if cpu_clock_speed != CpuClock::default() {
-            clocks_ll::esp32h2_rtc_update_to_xtal(xtal_freq, 1);
+            if cpu_clock_speed.mhz() <= xtal_freq.mhz() {
-            clocks_ll::esp32h2_rtc_apb_freq_update(apb_freq);
+                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;
-            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);
         }
 
         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,
+            clocks_ll::set_cpu_clock(cpu_clock_speed);
-    ) -> 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,
+            clocks_ll::set_cpu_clock(cpu_clock_speed);
-    ) -> 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
@@ -18,24 +19,23 @@
 //! supports various configurations, such as different data formats, standards
 //! (e.g., Philips) and pin configurations. It relies on other peripheral
 //! modules, such as
-//!     - `GPIO`
+//!   - `GPIO`
-//!     - `DMA`
+//!   - `DMA`
-//!     - `system` (to configure and enable the I2S peripheral)
+//!   - `system` (to configure and enable the I2S peripheral)
+//!
+//! ## Example
 //!
-//! ## Examples
 //! ### 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,43 +30,35 @@
 //!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
-//! # use core::cell::RefCell;
+//! let mut sw_int =
+//!     SoftwareInterruptControl::new(peripherals.SW_INTERRUPT);
+//! critical_section::with(|cs| {
+//!     sw_int
+//!         .software_interrupt0
+//!         .set_interrupt_handler(swint0_handler);
+//!     SWINT0
+//!         .borrow_ref_mut(cs)
+//!         .replace(sw_int.software_interrupt0);
+//! });
 //!
+//! critical_section::with(|cs| {
+//!     SWINT0.borrow_ref(cs).as_ref().unwrap().raise();
+//! });
+//! #
+//! # loop {}
+//! # }
+//!
+//! # use core::cell::RefCell;
+//! #
 //! # use critical_section::Mutex;
-//! # use esp_hal::{
+//! # use esp_hal::interrupt::software::{SoftwareInterrupt, SoftwareInterruptControl};
-//! #    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));
+//!     Mutex::new(RefCell::new(None));
 //!
-//! let mut sw_int = system.software_interrupt_control;
+//! #[handler(priority = Priority::Priority1)]
-//!     critical_section::with(|cs| {
-//!         sw_int
-//!             .software_interrupt0
-//!             .set_interrupt_handler(swint0_handler);
-//!         SWINT0
-//!             .borrow_ref_mut(cs)
-//!             .replace(sw_int.software_interrupt0);
-//!     });
-//!
-//!     critical_section::with(|cs| {
-//!         SWINT0.borrow_ref(cs).as_ref().unwrap().raise();
-//!     });
-//!
-//!     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));
-//! #[handler(priority = esp_hal::interrupt::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

@@ -17,17 +17,21 @@
 #![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,
+//!     0x0c, 0xc1, 0xf5, 0xbf, 0x00, 0x00, 0x00, 0x00,
-//!     ];
+//! ];
 //! let mut ulp_core =
-//! esp_hal::ulp_core::UlpCore::new(peripherals.ULP_RISCV_CORE);
+//!     esp_hal::ulp_core::UlpCore::new(peripherals.ULP_RISCV_CORE);
 //! // ulp_core.stop(); currently not implemented
 //!
 //! // 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,22 +12,28 @@
 //! 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,
+//!     0x0c, 0xc1, 0xf5, 0xbf, 0x00, 0x00, 0x00, 0x00,
-//!     ];
+//! ];
+//!
 //! let mut ulp_core =
-//! esp_hal::ulp_core::UlpCore::new(peripherals.ULP_RISCV_CORE);
+//!     esp_hal::ulp_core::UlpCore::new(peripherals.ULP_RISCV_CORE);
 //! ulp_core.stop();
 //!
 //! // 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/spi/slave.rs

@@ -48,8 +48,8 @@
 //! let mut receive = rx_buffer;
 //!
 //! let transfer = spi
-//! .dma_transfer(&mut send, &mut receive)
+//!     .dma_transfer(&mut send, &mut receive)
-//! .unwrap();
+//!     .unwrap();
 //!
 //! transfer.wait().unwrap();
 //! # }

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"))]
+
-    let mut input = Input::new(io.pins.gpio0, Pull::Down);
+    cfg_if::cfg_if! {
-    #[cfg(not(any(feature = "esp32", feature = "esp32s2", feature = "esp32s3")))]
+        if #[cfg(any(feature = "esp32", feature = "esp32s2", feature = "esp32s3"))] {
-    let mut input = Input::new(io.pins.gpio9, Pull::Down);
+            let mut input = Input::new(io.pins.gpio0, Pull::Down);
+        } 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);