Merge branch 'main' into esp-phy-crate

.cargo/config.toml

@@ -1,2 +1,3 @@
 [alias]
 xtask = "run --package xtask --"
+xfmt = "xtask fmt-packages"

.github/workflows/changelog.yml

@@ -2,16 +2,13 @@ name: Changelog check
 
 on:
   pull_request:
-    # We will not track changes for the following packages.
+    # We will not track changes for the following packages/directories.
     paths-ignore:
-      - "/xtask/"
-      - "/esp-build/"
-      - "/esp-hal-procmacros/"
-      - "/esp-metadata/"
       - "/examples/"
-      - "/hil-tests/"
       - "/extras/"
+      - "/hil-tests/"
       - "/resources/"
+      - "/xtask/"
     # Run on labeled/unlabeled in addition to defaults to detect
     # adding/removing skip-changelog labels.
     types: [opened, reopened, labeled, unlabeled, synchronize]
@@ -33,24 +30,34 @@ jobs:
               - 'esp-alloc/**'
             esp-backtrace:
               - 'esp-backtrace/**'
+            esp-build:
+              - 'esp-build/**'
+            esp-config:
+              - 'esp-config/**'
             esp-hal:
               - 'esp-hal/**'
             esp-hal-embassy:
               - 'esp-hal-embassy/**'
+            esp-hal-procmacros:
+              - 'esp-hal-procmacros/**'
             esp-ieee802154:
               - 'esp-ieee802154/**'
             esp-lp-hal:
               - 'esp-lp-hal/**'
+            esp-metadata:
+              - 'esp-metadata/**'
             esp-println:
               - 'esp-println/**'
             esp-riscv-rt:
               - 'esp-riscv-rt/**'
-            xtensa-lx-rt:
-              - 'xtensa-lx-rt/**'
             esp-storage:
               - 'esp-storage/**'
             esp-wifi:
               - 'esp-wifi/**'
+            xtensa-lx:
+              - 'xtensa-lx/**'
+            xtensa-lx-rt:
+              - 'xtensa-lx-rt/**'
 
       - name: Check that changelog updated (esp-alloc)
         if: steps.changes.outputs.esp-alloc == 'true'
@@ -68,6 +75,22 @@ jobs:
           skipLabels: "skip-changelog"
           missingUpdateErrorMessage: "Please add a changelog entry in the esp-backtrace/CHANGELOG.md file."
 
+      - name: Check that changelog updated (esp-build)
+        if: steps.changes.outputs.esp-build == 'true'
+        uses: dangoslen/changelog-enforcer@v3
+        with:
+          changeLogPath: esp-build/CHANGELOG.md
+          skipLabels: "skip-changelog"
+          missingUpdateErrorMessage: "Please add a changelog entry in the esp-build/CHANGELOG.md file."
+
+      - name: Check that changelog updated (esp-config)
+        if: steps.changes.outputs.esp-config == 'true'
+        uses: dangoslen/changelog-enforcer@v3
+        with:
+          changeLogPath: esp-config/CHANGELOG.md
+          skipLabels: "skip-changelog"
+          missingUpdateErrorMessage: "Please add a changelog entry in the esp-config/CHANGELOG.md file."
+
       - name: Check that changelog updated (esp-hal)
         if: steps.changes.outputs.esp-hal == 'true'
         uses: dangoslen/changelog-enforcer@v3
@@ -84,6 +107,14 @@ jobs:
           skipLabels: "skip-changelog"
           missingUpdateErrorMessage: "Please add a changelog entry in the esp-hal-embassy/CHANGELOG.md file."
 
+      - name: Check that changelog updated (esp-hal-procmacros)
+        if: steps.changes.outputs.esp-hal-procmacros == 'true'
+        uses: dangoslen/changelog-enforcer@v3
+        with:
+          changeLogPath: esp-hal-procmacros/CHANGELOG.md
+          skipLabels: "skip-changelog"
+          missingUpdateErrorMessage: "Please add a changelog entry in the esp-hal-procmacros/CHANGELOG.md file."
+
       - name: Check that changelog updated (esp-ieee802154)
         if: steps.changes.outputs.esp-ieee802154 == 'true'
         uses: dangoslen/changelog-enforcer@v3
@@ -131,3 +162,19 @@ jobs:
           changeLogPath: esp-wifi/CHANGELOG.md
           skipLabels: "skip-changelog"
           missingUpdateErrorMessage: "Please add a changelog entry in the esp-wifi/CHANGELOG.md file."
+
+      - name: Check that changelog updated (xtensa-lx)
+        if: steps.changes.outputs.xtensa-lx == 'true'
+        uses: dangoslen/changelog-enforcer@v3
+        with:
+          changeLogPath: xtensa-lx/CHANGELOG.md
+          skipLabels: "skip-changelog"
+          missingUpdateErrorMessage: "Please add a changelog entry in the xtensa-lx/CHANGELOG.md file."
+
+      - name: Check that changelog updated (xtensa-lx-rt)
+        if: steps.changes.outputs.xtensa-lx-rt == 'true'
+        uses: dangoslen/changelog-enforcer@v3
+        with:
+          changeLogPath: xtensa-lx-rt/CHANGELOG.md
+          skipLabels: "skip-changelog"
+          missingUpdateErrorMessage: "Please add a changelog entry in the xtensa-lx-rt/CHANGELOG.md file."

.github/workflows/ci.yml

@@ -137,10 +137,10 @@ jobs:
 
       - name: msrv RISCV (esp-wifi)
         run: |
-          cargo xtask build-package --features=esp32c2,wifi,ble,async --target=riscv32imc-unknown-none-elf   esp-wifi
-          cargo xtask build-package --features=esp32c3,wifi,ble,async --target=riscv32imc-unknown-none-elf   esp-wifi
-          cargo xtask build-package --features=esp32c6,wifi,ble,async --target=riscv32imac-unknown-none-elf  esp-wifi
-          cargo xtask build-package --features=esp32h2,ble,async --target=riscv32imac-unknown-none-elf  esp-wifi
+          cargo xtask build-package --features=esp32c2,wifi,ble --target=riscv32imc-unknown-none-elf   esp-wifi
+          cargo xtask build-package --features=esp32c3,wifi,ble --target=riscv32imc-unknown-none-elf   esp-wifi
+          cargo xtask build-package --features=esp32c6,wifi,ble --target=riscv32imac-unknown-none-elf  esp-wifi
+          cargo xtask build-package --features=esp32h2,ble --target=riscv32imac-unknown-none-elf  esp-wifi
 
         # Verify the MSRV for all Xtensa chips:
       - name: msrv Xtensa (esp-hal)
@@ -151,9 +151,9 @@ jobs:
 
       - name: msrv Xtensa (esp-wifi)
         run: |
-          cargo xtask build-package --toolchain=esp --features=esp32,wifi,ble,async   --target=xtensa-esp32-none-elf   esp-wifi
-          cargo xtask build-package --toolchain=esp --features=esp32s2,wifi,async --target=xtensa-esp32s2-none-elf esp-wifi
-          cargo xtask build-package --toolchain=esp --features=esp32s3,wifi,ble,async --target=xtensa-esp32s3-none-elf esp-wifi
+          cargo xtask build-package --toolchain=esp --features=esp32,wifi,ble   --target=xtensa-esp32-none-elf   esp-wifi
+          cargo xtask build-package --toolchain=esp --features=esp32s2,wifi --target=xtensa-esp32s2-none-elf esp-wifi
+          cargo xtask build-package --toolchain=esp --features=esp32s3,wifi,ble --target=xtensa-esp32s3-none-elf esp-wifi
 
       - name: msrv (esp-lp-hal)
         run: |

documentation/API-GUIDELINES.md

@@ -15,16 +15,29 @@ The following paragraphs contain additional recommendations.
 
 ## Construction and Destruction of Drivers
 
-- Drivers take peripherals and pins via the `PeripheralRef` pattern - they don't consume peripherals/pins.
+- Drivers should take peripherals via the `PeripheralRef` pattern - they don't consume peripherals directly.
+- If a driver requires pins, those pins should be configured using `fn with_signal_name(self, pin: impl Peripheral<P = InputConnection> + 'd) -> Self)` or `fn with_signal_name(self, pin: impl Peripheral<P = OutputConnection> + 'd) -> Self)`
+- If a driver supports multiple peripheral instances (for example, I2C0 is one such instance):
+  - The peripheral instance type should be positioned as the last type parameter of the driver type.
+  - The peripheral instance type should default to a type that supports any of the peripheral instances.
+  - The author is encouraged to use `crate::any_peripheral` to define the "any" peripheral instance type.
+  - The driver should implement a `new` constructor that automatically converts the peripheral instance into the any type, and a `new_typed` that preserves the peripheral type.
+- If a driver only supports a single peripheral instance, no instance type parameter is necessary.
+- If a driver implements both blocking and async operations, or only implements blocking operations, but may support asynchronous ones in the future, the driver's type signature should include a `crate::Mode` type parameter.
+- By default, constructors should configure the driver for blocking mode. The driver should implement `into_async` (and a matching `into_blocking`) function that reconfigures the driver.
+  - `into_async` should configure the driver and/or the associated DMA channels. This most often means enabling an interrupt handler.
+  - `into_blocking` should undo the configuration done by `into_async`.
+- The asynchronous driver implemntation should also expose the blocking methods (except for interrupt related functions).
 - Consider adding a `Drop` implementation resetting the peripheral to idle state.
-- Consider using a builder-like pattern for configuration which must be done during initialization.
+- Consider using a builder-like pattern for driver construction.
 
 ## Interoperability
 
 - `cfg` gated `defmt` derives and impls are added to new structs and enums.
     - see [this example](https://github.com/esp-rs/esp-hal/blob/df2b7bd8472cc1d18db0d9441156575570f59bb3/esp-hal/src/spi/mod.rs#L15)
     - e.g. `#[cfg_attr(feature = "defmt", derive(defmt::Format))]`
 - Don't use `log::XXX!` macros directly - use the wrappers in `fmt.rs` (e.g. just `info!` instead of `log::info!` or importing `log::*`)!
+- Consider implementing common ecosystem traits, like the ones in `embedded-hal` or `embassy-embedded-hal`.
 
 ## API Surface
 
@@ -45,6 +58,9 @@ The following paragraphs contain additional recommendations.
     - For example starting a timer is fine for `&self`, worst case a timer will be started twice if two parts of the program call it. You can see a real example of this [here](https://github.com/esp-rs/esp-hal/pull/1500#pullrequestreview-2015911974)
 - Maintain order consistency in the API, such as in the case of pairs like RX/TX.
 - If your driver provides a way to listen for interrupts, the interrupts should be listed in a `derive(EnumSetType)` enum as opposed to one function per interrupt flag.
+- If a driver only implements a subset of a peripheral's capabilities, it should be placed in the `peripheral::subcategory` module.
+  - For example, if a driver implements the slave-mode I2C driver, it should be placed into `i2c::slave`.
+  - This helps us reducing the need of introducing breaking changes if we implement additional functionalities.
 
 ## Maintainability
 
@@ -56,6 +72,15 @@ The following paragraphs contain additional recommendations.
 - All `Future` objects (public or private) must be marked with ``#[must_use = "futures do nothing unless you `.await` or poll them"]``.
 - Prefer `cfg_if!` over multiple exclusive `#[cfg]` attributes. `cfg_if!` visually divides the options, often results in simpler conditions and simplifies adding new branches in the future.
 
+## Driver implementation
+
+- If a common `Instance` trait is used for multiple peripherals, those traits should not have any logic implemented in them.
+- The `Instance` traits should only be used to access information about a peripheral instance.
+- The internal implementation of the driver should be non-generic over the peripheral instance. This helps the compiler produce smaller code.
+- The author is encouraged to return a static shared reference to an `Info` and a `State` structure from the `Instance` trait.
+  - The `Info` struct should describe the peripheral. Do not use any interior mutability.
+  - The `State` struct should contain counters, wakers and other, mutable state. As this is accessed via a shared reference, interior mutability and atomic variables are preferred.
+
 ## Modules Documentation
 
 Modules should have the following documentation format:
@@ -88,4 +113,5 @@ Modules should have the following documentation format:
     ```
     #![doc = concat!("[ESP-IDF documentation](https://docs.espressif.com/projects/esp-idf/en/latest/", crate::soc::chip!(), "/api-reference/peripherals/etm.html)")]
     ```
-- Documentation examples should be short and basic, for more complex scenarios, create an example.
+  - In case of referencing a TRM chapter, use the `crate::trm_markdown_link!()` macro. If you are referring to a particular chapter, you may use `crate::trm_markdown_link!("#chapter_anchor")`.
+- Documentation examples should be short and basic. For more complex scenarios, create an example.

esp-build/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+### Fixed
+
+### Changed
+
+- Use `panic` instead of `process::exit` in esp-build (#2402 )
+
+### Removed
+
+## [0.1.0] - 2024-04-17
+
+- Initial release
+
+[Unreleased]: https://github.com/esp-rs/esp-hal/commits/main/esp-build?since=2024-04-17

esp-config/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+### Fixed
+
+### Changed
+
+### Removed
+
+## [0.1.0] - 2024-10-10
+
+- Initial release
+
+[Unreleased]: https://github.com/esp-rs/esp-hal/commits/main/esp-config?since=2024-10-10