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,13 +122,15 @@ 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.
 
 [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},
-    system::SoftwareInterrupt,
+    interrupt::{self, software::SoftwareInterrupt, InterruptHandler},
 };
 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 = block_buf.clone();
+//! #
+//! let mut block = [0_u8; 16];
+//! 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,
-//!               Attenuation::Attenuation11dB);
+//! let mut pin = adc1_config.enable_pin(
+//!     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;