Merge remote-tracking branch 'upstream/main' into dpi_driver

Author: Dominaezzz

documentation/API-GUIDELINES.md

@@ -28,15 +28,14 @@ The following paragraphs contain additional recommendations.
 
 ## API Surface
 
-- Add `#[deny(missing_docs)]` to new modules or when reworking a larger part of a module. In the end we will require this for whole crates.
-- API documentation shouldn't be an afterthought
+- API documentation shouldn't be an afterthought.
 - Private details shouldn't leak into the public API, and should be made private where technically possible.
-- Implementation details that _need_ to be public should be marked with `#[doc(hidden)]` and a comment as to why it needs to be public.
-- Functions which technically need to be public but shouldn't be callable by the user need to be sealed.
+  - Implementation details that _need_ to be public should be marked with `#[doc(hidden)]` and a comment as to why it needs to be public.
+  - Functions which technically need to be public but shouldn't be callable by the user need to be sealed.
     - see [this example in Rust's core library](https://github.com/rust-lang/rust/blob/044a28a4091f2e1a5883f7fa990223f8b200a2cd/library/core/src/error.rs#L89-L100)
-- Any public traits, that **must not** be implemented downstream need to be `Sealed`
+- Any public traits, that **must not** be implemented downstream need to be `Sealed`.
 - Prefer compile-time checks over runtime checks where possible, prefer a fallible API over panics.
-- Follow naming conventions in order to be consistent across drivers - take inspiration from existing drivers
+- Follow naming conventions in order to be consistent across drivers - take inspiration from existing drivers.
 - Design APIs in a way that they are easy to use.
 - Driver API decisions should be assessed individually, don't _not_ just follow embedded-hal or other ecosystem trait crates. Expose the capabilities of the hardware. (Ecosystem traits are implemented on top of the inherent API)
 - Avoid type states and extraneous generics whenever possible
@@ -45,6 +44,7 @@ The following paragraphs contain additional recommendations.
 - Avoiding `&mut self` when `&self` is safe to use. `&self` is generally easier to use as an API. Typical applications of this are where the methods just do writes to registers which don't have side effects.
     - 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.
 
 ## Maintainability
 

esp-hal-embassy/CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `ESP_HAL_EMBASSY_LOW_POWER_WAIT` configuration option. (#2329)
+
 ### Changed
 
 - Reduce memory footprint by 4 bytes on multi-core MCUs.

esp-hal-embassy/Cargo.toml

@@ -25,6 +25,7 @@ static_cell         = "2.1.0"
 
 [build-dependencies]
 esp-build    = { version = "0.1.0", path = "../esp-build" }
+esp-config   = { version = "0.1.0", path = "../esp-config", features = ["build"] }
 esp-metadata = { version = "0.4.0", path = "../esp-metadata" }
 
 [features]

esp-hal-embassy/build.rs

@@ -1,6 +1,7 @@
 use std::{error::Error, str::FromStr};
 
 use esp_build::assert_unique_used_features;
+use esp_config::{generate_config, Value};
 use esp_metadata::{Chip, Config};
 
 fn main() -> Result<(), Box<dyn Error>> {
@@ -37,5 +38,16 @@ fn main() -> Result<(), Box<dyn Error>> {
     // Define all necessary configuration symbols for the configured device:
     config.define_symbols();
 
+    // emit config
+    generate_config(
+        "esp_hal_embassy",
+        &[(
+            "low-power-wait",
+            Value::Bool(true),
+            "Enables the lower-power wait if no tasks are ready to run on the thread-mode executor. This allows the MCU to use less power if the workload allows. Recommended for battery-powered systems. May impact analog performance.",
+        )],
+        true,
+    );
+
     Ok(())
 }

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

@@ -6,6 +6,7 @@ use embassy_executor::{raw, Spawner};
 use esp_hal::{get_core, Cpu};
 #[cfg(multi_core)]
 use esp_hal::{interrupt::software::SoftwareInterrupt, macros::handler};
+#[cfg(low_power_wait)]
 use portable_atomic::{AtomicBool, Ordering};
 
 pub(crate) const THREAD_MODE_CONTEXT: usize = 16;
@@ -15,7 +16,7 @@ pub(crate) const THREAD_MODE_CONTEXT: usize = 16;
 static SIGNAL_WORK_THREAD_MODE: [AtomicBool; Cpu::COUNT] =
     [const { AtomicBool::new(false) }; Cpu::COUNT];
 
-#[cfg(multi_core)]
+#[cfg(all(multi_core, low_power_wait))]
 #[handler]
 fn software3_interrupt() {
     // This interrupt is fired when the thread-mode executor's core needs to be
@@ -25,30 +26,33 @@ fn software3_interrupt() {
     unsafe { SoftwareInterrupt::<3>::steal().reset() };
 }
 
-pub(crate) fn pend_thread_mode(core: usize) {
-    // Signal that there is work to be done.
-    SIGNAL_WORK_THREAD_MODE[core].store(true, Ordering::SeqCst);
-
-    // If we are pending a task on the current core, we're done. Otherwise, we
-    // need to make sure the other core wakes up.
-    #[cfg(multi_core)]
-    if core != get_core() as usize {
-        // We need to clear the interrupt from software. We don't actually
-        // need it to trigger and run the interrupt handler, we just need to
-        // kick waiti to return.
-        unsafe { SoftwareInterrupt::<3>::steal().raise() };
+pub(crate) fn pend_thread_mode(_core: usize) {
+    #[cfg(low_power_wait)]
+    {
+        // Signal that there is work to be done.
+        SIGNAL_WORK_THREAD_MODE[_core].store(true, Ordering::SeqCst);
+
+        // If we are pending a task on the current core, we're done. Otherwise, we
+        // need to make sure the other core wakes up.
+        #[cfg(multi_core)]
+        if _core != get_core() as usize {
+            // We need to clear the interrupt from software. We don't actually
+            // need it to trigger and run the interrupt handler, we just need to
+            // kick waiti to return.
+            unsafe { SoftwareInterrupt::<3>::steal().raise() };
+        }
     }
 }
 
-/// A thread aware Executor
+/// Thread mode executor.
+///
+/// This is the simplest and most common kind of executor. It runs on thread
+/// mode (at the lowest priority level).
+#[cfg_attr(multi_core, doc = "")]
 #[cfg_attr(
     multi_core,
-    doc = r#"
-This executor is capable of waking an
-executor running on another core if work
-needs to be completed there for a task to
-progress on this core.
-"#
+    doc = "This executor is safe to use on multiple cores. You need to
+create one instance per core. The executors don't steal tasks from each other."
 )]
 pub struct Executor {
     inner: raw::Executor,
@@ -64,7 +68,7 @@ impl Executor {
 This will use software-interrupt 3 which isn't available for anything else to wake the other core(s)."#
     )]
     pub fn new() -> Self {
-        #[cfg(multi_core)]
+        #[cfg(all(multi_core, low_power_wait))]
         unsafe {
             SoftwareInterrupt::<3>::steal().set_interrupt_handler(software3_interrupt);
         }
@@ -90,28 +94,27 @@ This will use software-interrupt 3 which isn't available for anything else to wa
     /// you mutable access. There's a few ways to do this:
     ///
     /// - a [StaticCell](https://docs.rs/static_cell/latest/static_cell/) (safe)
-    /// - a `static mut` (unsafe)
+    /// - a `static mut` (unsafe, not recommended)
     /// - a local variable in a function you know never returns (like `fn main()
     ///   -> !`), upgrading its lifetime with `transmute`. (unsafe)
     ///
     /// This function never returns.
     pub fn run(&'static mut self, init: impl FnOnce(Spawner)) -> ! {
         init(self.inner.spawner());
 
+        #[cfg(low_power_wait)]
         let cpu = get_core() as usize;
 
         loop {
-            unsafe {
-                self.inner.poll();
+            unsafe { self.inner.poll() };
 
-                Self::wait_impl(cpu);
-            }
+            #[cfg(low_power_wait)]
+            Self::wait_impl(cpu);
         }
     }
 
-    #[doc(hidden)]
-    #[cfg(xtensa)]
-    pub fn wait_impl(cpu: usize) {
+    #[cfg(all(xtensa, low_power_wait))]
+    fn wait_impl(cpu: usize) {
         // Manual critical section implementation that only masks interrupts handlers.
         // We must not acquire the cross-core on dual-core systems because that would
         // prevent the other core from doing useful work while this core is sleeping.
@@ -140,9 +143,8 @@ This will use software-interrupt 3 which isn't available for anything else to wa
         }
     }
 
-    #[doc(hidden)]
-    #[cfg(riscv)]
-    pub fn wait_impl(cpu: usize) {
+    #[cfg(all(riscv, low_power_wait))]
+    fn wait_impl(cpu: usize) {
         // we do not care about race conditions between the load and store operations,
         // interrupts will only set this value to true.
         critical_section::with(|_| {

esp-hal/CHANGELOG.md

@@ -8,7 +8,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-
 - A new config option `PLACE_SWITCH_TABLES_IN_RAM` to improve performance (especially for interrupts) at the cost of slightly more RAM usage (#2331)
 - A new config option `PLACE_ANON_IN_RAM` to improve performance (especially for interrupts) at the cost of RAM usage (#2331)
 - Add burst transfer support to DMA buffers (#2336)
@@ -23,6 +22,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `Cpu::COUNT` and `Cpu::current()` (#?)
 - Add RGB/DPI driver (#2415)
 - Add `DmaLoopBuf` (#2415)
+- `Cpu::COUNT` and `Cpu::current()` (#2411)
+- `UartInterrupt` and related functions (#2406)
+- I2S Parallel output driver for esp32. (#2348)
+- Add an option to configure `WDT` action (#2330)
 
 ### Changed
 
@@ -33,11 +36,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The SPI driver has been rewritten to allow using half-duplex and full-duplex functionality on the same bus. See the migration guide for details. (#2373)
 - Renamed `SpiDma` functions: `dma_transfer` to `transfer`, `dma_write` to `write`, `dma_read` to `read`. (#2373)
 - Peripheral type erasure for UART (#2381)
+- Changed listening for UART events (#2406)
+- Circular DMA transfers now correctly error, `available` returns `Result<usize,DmaError>` now (#2409)
 
 ### Fixed
 
 - Fix conflict between `RtcClock::get_xtal_freq` and `Rtc::disable_rom_message_printing` (#2360)
 - Fixed an issue where interrupts enabled before `esp_hal::init` were disabled. This issue caused the executor created by `#[esp_hal_embassy::main]` to behave incorrectly in multi-core applications. (#2377)
+- Fixed `TWAI::transmit_async`: bus-off state is not reached when CANH and CANL are shorted. (#2421)
 
 ### Removed
 

esp-hal/MIGRATING-0.21.md

@@ -118,3 +118,61 @@ The `Spi<'_, SPI, HalfDuplexMode>::read` and `Spi<'_, SPI, HalfDuplexMode>::writ
      )
      .unwrap();
 ```
+
+## UART event listening
+
+The following functions have been removed:
+
+- `listen_at_cmd`
+- `unlisten_at_cmd`
+- `listen_tx_done`
+- `unlisten_tx_done`
+- `listen_rx_fifo_full`
+- `unlisten_rx_fifo_full`
+- `at_cmd_interrupt_set`
+- `tx_done_interrupt_set`
+- `rx_fifo_full_interrupt_set`
+- `reset_at_cmd_interrupt`
+- `reset_tx_done_interrupt`
+- `reset_rx_fifo_full_interrupt`
+
+You can now use the `UartInterrupt` enum and the corresponding `listen`, `unlisten`, `interrupts` and `clear_interrupts` functions.
+
+Use `interrupts` in place of `<INTERRUPT>_interrupt_set` and `clear_interrupts` in place of the old `reset_` functions.
+
+`UartInterrupt`:
+- `AtCmd`
+- `TxDone`
+- `RxFifoFull`
+
+Checking interrupt bits is now done using APIs provided by [enumset](https://docs.rs/enumset/1.1.5/enumset/index.html). For example, to see if
+a particular interrupt bit is set, use `contains`:
+
+```diff
+-serial.at_cmd_interrupt_set()
++serial.interupts().contains(UartInterrupt::AtCmd)
+```
+
+You can now listen/unlisten multiple interrupt bits at once:
+
+```diff
+-uart0.listen_at_cmd();
+-uart0.listen_rx_fifo_full();
++uart0.listen(UartInterrupt::AtCmd | UartConterrupt::RxFifoFull);
+```˛
+## Circular DMA transfer's `available` returns `Result<usize, DmaError>` now
+
+In case of any error you should drop the transfer and restart it.
+
+```diff
+     loop {
+-        let avail = transfer.available();
++        let avail = match transfer.available() {
++            Ok(avail) => avail,
++            Err(_) => {
++                core::mem::drop(transfer);
++                transfer = i2s_tx.write_dma_circular(&tx_buffer).unwrap();
++                continue;
++            },
++        };
+```

esp-hal/src/dma/gdma.rs

@@ -151,6 +151,12 @@ impl<C: GdmaChannel> RegisterAccess for ChannelTxImpl<C> {
 }
 
 impl<C: GdmaChannel> TxRegisterAccess for ChannelTxImpl<C> {
+    fn set_auto_write_back(&self, enable: bool) {
+        self.ch()
+            .out_conf0()
+            .modify(|_, w| w.out_auto_wrback().bit(enable));
+    }
+
     fn last_dscr_address(&self) -> usize {
         self.ch()
             .out_eof_des_addr()