Merge branch 'main' into improve_systimer

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,10 +7,10 @@ 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.
-- [ ] My changes are in accordance to the [esp-rs API guidelines](https://github.com/esp-rs/esp-hal/blob/main/API-GUIDELINES.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:
-- [ ] I have read the [CONTRIBUTING.md guide](https://github.com/esp-rs/esp-hal/blob/main/CONTRIBUTING.md) and followed its instructions.
+- [ ] I have read the [CONTRIBUTING.md guide](https://github.com/esp-rs/esp-hal/blob/main/documentation/CONTRIBUTING.md) and followed its instructions.
 
 ### Pull Request Details 📖
 

.github/workflows/hil.yml

@@ -18,8 +18,48 @@ env:
   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
 jobs:
+  build-xtasks:
+    name: Build xtasks | ${{ matrix.host.arch }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        host:
+          - arch: armv7
+            rust-target: armv7-unknown-linux-gnueabihf
+          - arch: aarch64
+            rust-target: aarch64-unknown-linux-gnu
+
+    steps:
+      - uses: actions/checkout@v4
+        if: github.event_name != 'workflow_dispatch'
+      - uses: actions/checkout@v4
+        if: github.event_name == 'workflow_dispatch'
+        with:
+          repository: ${{ github.event.inputs.repository }}
+          ref: ${{ github.event.inputs.branch }}
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@v1
+        with:
+          toolchain: stable
+          components: rust-src
+
+      - name: Install cross
+        run: cargo install cross
+
+      - name: Build xtasks
+        run: cross build --release --target ${{ matrix.host.rust-target }}
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: xtask-${{ matrix.host.arch }}
+          path: target/${{ matrix.host.rust-target }}/release/xtask
+
   build-tests:
-    name: HIL Test | ${{ matrix.target.soc }}
+    name: Build HIL Tests | ${{ matrix.target.soc }}
     runs-on: ubuntu-latest
 
     strategy:
@@ -92,8 +132,8 @@ jobs:
           overwrite: true
 
   hil:
-    name: HIL Test | ${{ matrix.target.soc }}
-    needs: build-tests
+    name: Run HIL Tests | ${{ matrix.target.soc }}
+    needs: [build-tests, build-xtasks]
     runs-on:
       labels: [self-hosted, "${{ matrix.target.runner }}"]
     strategy:
@@ -104,38 +144,41 @@ jobs:
           - soc: esp32c2
             runner: esp32c2-jtag
             usb: USB2
+            host: aarch64
           - soc: esp32c3
             runner: esp32c3-usb
             usb: ACM0
+            host: armv7
           - soc: esp32c6
             runner: esp32c6-usb
             usb: ACM0
+            host: armv7
           - soc: esp32h2
             runner: esp32h2-usb
             usb: USB0
+            host: armv7
           # Xtensa devices:
           - soc: esp32s2
             runner: esp32s2-jtag
             usb: USB1
+            host: armv7
           - soc: esp32s3
             runner: esp32s3-usb
             usb: USB0
+            host: armv7
     steps:
-      - uses: actions/checkout@v4
       - uses: actions/download-artifact@v4
         with:
           name: tests-${{ matrix.target.soc }}
           path: tests-${{ matrix.target.soc }}
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: xtask-${{ matrix.target.host }}
+
       - name: Run Tests
         id: run-tests
         run: |
           export PATH=$PATH:/home/espressif/.cargo/bin
-          cargo xtask run-elfs ${{ matrix.target.soc }} tests-${{ matrix.target.soc }}
-
-      - name: Erase Flash on Failure
-        if: ${{ failure() && steps.run-tests.conclusion == 'failure' }}
-        env:
-          ESPFLASH_PORT: /dev/tty${{ matrix.target.usb }}
-        run: |
-          export PATH=$PATH:/home/espressif/.cargo/bin
-          espflash erase-flash
+          chmod +x xtask
+          ./xtask run-elfs ${{ matrix.target.soc }} tests-${{ matrix.target.soc }}

README.md

@@ -20,7 +20,7 @@ If you have any questions, comments, or concerns, please [open an issue], [start
 
 > [!NOTE]
 >
-> This project is still in the relatively early stages of development, and as such there should be no expectation of API stability. A significant number of peripherals currently have drivers implemented but have varying levels of functionality. For most basic tasks, this should be usable already, however some more advanced or uncommon features may not yet be implemented.
+> This project is still in the relatively early stages of development, and as such there should be no expectation of API stability. A significant number of peripherals currently have drivers implemented but have varying levels of functionality. For most tasks, this should be usable already, however some more advanced or uncommon features may not yet be implemented.
 
 [esp-lp-hal]: https://github.com/esp-rs/esp-hal/tree/main/esp-lp-hal
 [esp-idf-svc]: https://github.com/esp-rs/esp-idf-svc
@@ -49,6 +49,13 @@ For information about the HAL and how to use it in your own projects, please ref
 
 This repository is home to a number of different packages; for more information regarding a particular package, please refer to its `README.md` and/or documentation.
 
+## Contributing
+
+We have a number of living documents to aid contributing to the project, please give these a read before modifying code:
+
+- [API-GUIDELINES](https://github.com/esp-rs/esp-hal/blob/main/documentation/API-GUIDELINES.md)
+- [CONTRIBUTING-GUIDE](https://github.com/esp-rs/esp-hal/blob/main/documentation/CONTRIBUTING.md)
+
 ## License
 
 Licensed under either of:
@@ -58,10 +65,8 @@ Licensed under either of:
 
 at your option.
 
-### Contribution
+### Contribution notice
 
 Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in
 the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without
 any additional terms or conditions.
-
-If you consider contributing, please make sure you have read and understood our [contributing guide](./CONTRIBUTING.md) and [API guidelines](https://github.com/esp-rs/esp-hal/blob/main/API-GUIDELINES.md).

CONTRIBUTING.md → documentation/CONTRIBUTING.md

@@ -41,7 +41,7 @@ Before adding or changing code, review the [esp-rs API guidelines].
 [Setting Up Git]: https://docs.github.com/en/get-started/quickstart/set-up-git
 [GitHub Flow]: https://docs.github.com/en/get-started/quickstart/github-flow
 [Pull Requests]: https://docs.github.com/en/github/collaborating-with-pull-requests
-[esp-rs API guidelines]: ./API-GUIDELINES.md
+[esp-rs API guidelines]: ./documentation/API-GUIDELINES.md
 
 ## Getting Started
 

esp-hal-embassy/CHANGELOG.md

@@ -13,9 +13,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Updated to latest release (`0.6.0`) for `embassy-executor` (#1942)
+
 ### Fixed
 
 - Fixed a bug where the timeout was huge whenever the timestamp at the time of scheduling was already in the past (#1875)
+- Fixed interrupt executors looping endlessly when `integrated-timers` is used. (#1936)
 
 ### Removed
 

esp-hal-embassy/Cargo.toml

@@ -15,7 +15,7 @@ features       = ["esp32c6"]
 critical-section    = "1.1.2"
 defmt               = { version = "0.3.8", optional = true }
 document-features   = "0.2.10"
-embassy-executor    = { version = "0.5.0", optional = true }
+embassy-executor    = { version = "0.6.0", optional = true }
 embassy-time-driver = { version = "0.1.0", features = [ "tick-hz-1_000_000" ] }
 esp-hal             = { version = "0.19.0", path = "../esp-hal" }
 log                 = { version = "0.4.22", optional = true }

esp-hal-embassy/src/time_driver.rs

@@ -156,10 +156,11 @@ impl Driver for EmbassyTimer {
     }
 
     fn set_alarm(&self, alarm: AlarmHandle, timestamp: u64) -> bool {
-        // we sometimes get called with `u64::MAX` for apparently not yet initialized
-        // timers which would fail later on
+        // If `embassy-executor/integrated-timers` is enabled and there are no pending
+        // timers, embassy still calls `set_alarm` with `u64::MAX`. By returning
+        // `true` we signal that no re-polling is necessary.
         if timestamp == u64::MAX {
-            return false;
+            return true;
         }
 
         // The hardware fires the alarm even if timestamp is lower than the current

esp-hal/CHANGELOG.md

@@ -11,14 +11,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Added new `Io::new_no_bind_interrupt` constructor (#1861)
 - Added touch pad support for esp32 (#1873)
+- Allow configuration of period updating method for MCPWM timers (#1898)
+- Add self-testing mode for TWAI peripheral. (#1929)
+- Added a `PeripheralClockControl::reset` to the driver constructors where missing (#1893)
 
 ### Changed
 
 - Peripheral driver constructors don't take `InterruptHandler`s anymore. Use `set_interrupt_handler` to explicitly set the interrupt handler now. (#1819)
 - Use the peripheral ref pattern for `OneShotTimer` and `PeriodicTimer` (#1855)
 - Improve SYSTIMER API (#1870)
+- DMA: don't require `Sealed` to implement `ReadBuffer` and `WriteBuffer` (#1921)
 - Allow DMA to/from psram for esp32s3 (#1827)
 - DMA buffers now don't require a static lifetime. Make sure to never `mem::forget` an in-progress DMA transfer (consider using `#[deny(clippy::mem_forget)]`) (#1837)
+- Peripherals (where possible) are now explicitly reset and enabled in their constructors (#1893)
 
 ### Fixed
 
@@ -28,6 +33,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - SPI: Clear DMA interrupts before (not after) DMA starts (#1859)
 - SPI: disable and re-enable MISO and MOSI in `start_transfer_dma`, `start_read_bytes_dma` and `start_write_bytes_dma` accordingly (#1894)
 - TWAI: GPIO pins are not configured as input and output (#1906)
+- ESP32C6: Make ADC usable after TRNG deinicialization (#1945)
 
 ### Removed
 

esp-hal/Cargo.toml

@@ -53,13 +53,13 @@ xtensa-lx                = { version = "0.9.0", optional = true }
 # IMPORTANT:
 # Each supported device MUST have its PAC included below along with a
 # corresponding feature.
-esp32   = { git = "https://github.com/esp-rs/esp-pacs", rev = "27dd7e5", features = ["critical-section", "rt"], optional = true }
-esp32c2 = { git = "https://github.com/esp-rs/esp-pacs", rev = "27dd7e5", features = ["critical-section", "rt"], optional = true }
-esp32c3 = { git = "https://github.com/esp-rs/esp-pacs", rev = "27dd7e5", features = ["critical-section", "rt"], optional = true }
-esp32c6 = { git = "https://github.com/esp-rs/esp-pacs", rev = "27dd7e5", features = ["critical-section", "rt"], optional = true }
-esp32h2 = { git = "https://github.com/esp-rs/esp-pacs", rev = "27dd7e5", features = ["critical-section", "rt"], optional = true }
-esp32s2 = { git = "https://github.com/esp-rs/esp-pacs", rev = "27dd7e5", features = ["critical-section", "rt"], optional = true }
-esp32s3 = { git = "https://github.com/esp-rs/esp-pacs", rev = "27dd7e5", features = ["critical-section", "rt"], optional = true }
+esp32   = { git = "https://github.com/esp-rs/esp-pacs", rev = "e3741e6", features = ["critical-section", "rt"], optional = true }
+esp32c2 = { git = "https://github.com/esp-rs/esp-pacs", rev = "e3741e6", features = ["critical-section", "rt"], optional = true }
+esp32c3 = { git = "https://github.com/esp-rs/esp-pacs", rev = "e3741e6", features = ["critical-section", "rt"], optional = true }
+esp32c6 = { git = "https://github.com/esp-rs/esp-pacs", rev = "e3741e6", features = ["critical-section", "rt"], optional = true }
+esp32h2 = { git = "https://github.com/esp-rs/esp-pacs", rev = "e3741e6", features = ["critical-section", "rt"], optional = true }
+esp32s2 = { git = "https://github.com/esp-rs/esp-pacs", rev = "e3741e6", features = ["critical-section", "rt"], optional = true }
+esp32s3 = { git = "https://github.com/esp-rs/esp-pacs", rev = "e3741e6", features = ["critical-section", "rt"], optional = true }
 
 [target.'cfg(target_arch = "riscv32")'.dependencies]
 esp-riscv-rt = { version = "0.9.0", path = "../esp-riscv-rt" }

esp-hal/src/aes/mod.rs

@@ -46,8 +46,6 @@
 //! * AES-DMA mode is currently not supported on ESP32 and ESP32S2
 //! * AES-DMA Initialization Vector (IV) is currently not supported
 
-#![deny(missing_docs)]
-
 use crate::{
     peripheral::{Peripheral, PeripheralRef},
     peripherals::AES,
@@ -135,6 +133,10 @@ impl<'d> Aes<'d> {
     /// Constructs a new `Aes` instance.
     pub fn new(aes: impl Peripheral<P = AES> + 'd) -> Self {
         crate::into_ref!(aes);
+
+        crate::system::PeripheralClockControl::reset(crate::system::Peripheral::Aes);
+        crate::system::PeripheralClockControl::enable(crate::system::Peripheral::Aes);
+
         let mut ret = Self {
             aes,
             alignment_helper: AlignmentHelper::native_endianess(),

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

@@ -66,7 +66,7 @@ mod implementation;
 
 /// The attenuation of the ADC pin.
 ///
-/// The effective measurement range for a given attuenation is dependent on the
+/// The effective measurement range for a given attenuation is dependent on the
 /// device being targeted. Please refer to "ADC Characteristics" section of your
 /// device's datasheet for more information.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]

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

@@ -408,6 +408,7 @@ where
         adc_instance: impl crate::peripheral::Peripheral<P = ADCI> + 'd,
         config: AdcConfig<ADCI>,
     ) -> Self {
+        PeripheralClockControl::reset(Peripheral::ApbSarAdc);
         PeripheralClockControl::enable(Peripheral::ApbSarAdc);
 
         unsafe { &*APB_SARADC::PTR }.ctrl().modify(|_, w| unsafe {

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

@@ -6,6 +6,7 @@ use crate::efuse::Efuse;
 use crate::{
     peripheral::PeripheralRef,
     peripherals::{APB_SARADC, SENS},
+    system::{Peripheral, PeripheralClockControl},
 };
 
 mod calibration;
@@ -400,6 +401,9 @@ where
         adc_instance: impl crate::peripheral::Peripheral<P = ADCI> + 'd,
         config: AdcConfig<ADCI>,
     ) -> Self {
+        PeripheralClockControl::reset(Peripheral::ApbSarAdc);
+        PeripheralClockControl::enable(Peripheral::ApbSarAdc);
+
         let sensors = unsafe { &*SENS::ptr() };
 
         // Set attenuation for pins

esp-hal/src/analog/mod.rs

@@ -5,8 +5,6 @@
 //! available on the device. For more information about a peripheral driver,
 //! please refer to the relevant module documentation.
 
-#![deny(missing_docs)]
-
 #[cfg(adc)]
 pub mod adc;
 #[cfg(dac)]

esp-hal/src/clock/mod.rs

@@ -70,8 +70,6 @@
 //! # }
 //! ```
 
-#![deny(missing_docs)]
-
 use fugit::HertzU32;
 
 #[cfg(any(esp32, esp32c2))]