Restore multiple-integrated timer queues (#3166)

Author: bugadani

esp-hal-embassy/CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Re-added the `multiple-integrated` timer queue flavour (#3166)
+
 ### Changed
 
 ### Fixed

esp-hal-embassy/build.rs

@@ -49,8 +49,7 @@ fn main() -> Result<(), Box<dyn StdError>> {
         ),
         (
             "timer-queue",
-            //"<p>The flavour of the timer queue provided by this crate. Accepts one of `single-integrated`, `multiple-integrated` or `generic`. Integrated queues require the `executors` feature to be enabled.</p><p>If you use embassy-executor, the `single-integrated` queue is recommended for ease of use, while the `multiple-integrated` queue is recommended for performance. The `multiple-integrated` option needs one timer per executor.</p><p>The `generic` queue allows using embassy-time without the embassy executors.</p>",
-            "<p>The flavour of the timer queue provided by this crate. Accepts either `single-integrated` or `generic`. Integrated queues require the `executors` feature to be enabled.</p><p>If you use embassy-executor, the `single-integrated` queue is recommended.</p><p>The `generic` queue allows using embassy-time without the embassy executors.</p>",
+            "<p>The flavour of the timer queue provided by this crate. Accepts one of `single-integrated`, `multiple-integrated` or `generic`. Integrated queues require the `executors` feature to be enabled.</p><p>If you use embassy-executor, the `single-integrated` queue is recommended for ease of use, while the `multiple-integrated` queue is recommended for performance. The `multiple-integrated` option needs one timer per executor.</p><p>The `generic` queue allows using embassy-time without the embassy executors.</p>",
             Value::String(if cfg!(feature = "executors") {
                 String::from("single-integrated")
             } else {
@@ -70,10 +69,9 @@ fn main() -> Result<(), Box<dyn StdError>> {
 
                 match string.as_str() {
                     "single-integrated" => Ok(()), // preferred for ease of use
-                    //"multiple-integrated" => Ok(()), // preferred for performance
+                    "multiple-integrated" => Ok(()), // preferred for performance
                     "generic" => Ok(()), // allows using embassy-time without the embassy executors
-                    //_ => Err(Error::Validation(format!("Expected 'single-integrated', 'multiple-integrated' or 'generic', found {string}")))
-                    _ => Err(Error::Validation(format!("Expected 'single-integrated' or 'generic', found {string}")))
+                    _ => Err(Error::Validation(format!("Expected 'single-integrated', 'multiple-integrated' or 'generic', found {string}")))
                 }
             })))
         ),
@@ -96,9 +94,9 @@ fn main() -> Result<(), Box<dyn StdError>> {
             println!("cargo:rustc-cfg=integrated_timers");
             println!("cargo:rustc-cfg=single_queue");
         }
-        // Value::String(s) if s.as_str() == "multiple-integrated" => {
-        //    println!("cargo:rustc-cfg=integrated_timers");
-        //}
+        Value::String(s) if s.as_str() == "multiple-integrated" => {
+            println!("cargo:rustc-cfg=integrated_timers");
+        }
         Value::String(s) if s.as_str() == "generic" => {
             println!("cargo:rustc-cfg=generic_timers");
             println!("cargo:rustc-cfg=single_queue");

esp-hal-embassy/src/lib.rs

@@ -31,11 +31,10 @@
 //!
 //! Initialization requires a number of timers to be passed in. The number of
 //! timers required depends on the timer queue flavour used, as well as the
-//! number of executors started.
-// TODO restore this:
-// If you use the `multiple-integrated` timer
-// queue flavour, then you need to pass as many timers as you start executors.
-// In other cases, you can pass a single timer.
+//! number of executors started. If you use the `multiple-integrated` timer
+//! queue flavour, then you need to pass as many timers as you start executors.
+//! In other cases, you can pass a single timer.
+//!
 //! ## Configuration
 //!
 //! You can configure the behaviour of the embassy runtime by using the
@@ -156,10 +155,11 @@ impl_array!(4);
 /// - A mutable static slice of `OneShotTimer` instances
 /// - A mutable static array of `OneShotTimer` instances
 /// - A 2, 3, 4 element array of `AnyTimer` instances
-// TODO: restore this:
-// /// Note that if you use the `multiple-integrated` timer-queue flavour, then
-// /// you need to pass as many timers as you start executors. In other cases,
-// /// you can pass a single timer.
+///
+/// Note that if you use the `multiple-integrated` timer-queue flavour, then
+/// you need to pass as many timers as you start executors. In other cases,
+/// you can pass a single timer.
+///
 /// # Examples
 ///
 /// ```rust, no_run

esp-hal-embassy/src/time_driver.rs

@@ -93,20 +93,19 @@ impl Alarm {
 /// as well as to schedule a wake-up at a certain time.
 ///
 /// We are free to choose how we implement these features, and we provide
-/// two options:
+/// three options:
 ///
 /// - If the `generic` feature is enabled, we implement a single timer queue,
 ///   using the implementation provided by embassy-time-queue-driver.
 /// - If the `single-integrated` feature is enabled, we implement a single timer
 ///   queue, using our own integrated timer implementation. Our implementation
 ///   is a copy of the embassy integrated timer queue, with the addition of
 ///   clearing the "owner" information upon dequeueing.
-// TODO: restore this and update the "two options" above:
-// - If the `multiple-integrated` feature is enabled, we provide a separate
-//   timer queue for each executor. We store a separate timer queue for each
-//   executor, and we use the scheduled task's owner to determine which queue to
-//   use. This mode allows us to use less disruptive locks around the timer
-//   queue, but requires more timers - one per timer queue.
+/// - If the `multiple-integrated` feature is enabled, we provide a separate
+///   timer queue for each executor. We store a separate timer queue for each
+///   executor, and we use the scheduled task's owner to determine which queue
+///   to use. This mode allows us to use less disruptive locks around the timer
+///   queue, but requires more timers - one per timer queue.
 pub(super) struct EmbassyTimer {
     /// The timer queue, if we use a single one (single-integrated, or generic).
     #[cfg(single_queue)]

hil-test/.cargo/config.toml

@@ -18,9 +18,7 @@ rustflags = [
 
 [env]
 DEFMT_LOG = "info"
-# TODO restore multiple-integrated
-#ESP_HAL_EMBASSY_CONFIG_TIMER_QUEUE="multiple-integrated"
-ESP_HAL_EMBASSY_CONFIG_TIMER_QUEUE="single-integrated"
+ESP_HAL_EMBASSY_CONFIG_TIMER_QUEUE="multiple-integrated"
 
 [unstable]
 build-std = ["core", "alloc"]

hil-test/tests/embassy_interrupt_executor.rs

@@ -4,8 +4,7 @@
 //% CHIPS: esp32 esp32c2 esp32c3 esp32c6 esp32h2 esp32s2 esp32s3
 //% FEATURES: unstable embassy
 //% ENV(single_integrated):   ESP_HAL_EMBASSY_CONFIG_TIMER_QUEUE = single-integrated
-// TODO restore multiple-integrated
-// ENV(multiple_integrated): ESP_HAL_EMBASSY_CONFIG_TIMER_QUEUE = multiple-integrated
+//% ENV(multiple_integrated): ESP_HAL_EMBASSY_CONFIG_TIMER_QUEUE = multiple-integrated
 //% ENV(generic_queue):       ESP_HAL_EMBASSY_CONFIG_TIMER_QUEUE = generic
 //% ENV(generic_queue):       ESP_HAL_EMBASSY_CONFIG_GENERIC_QUEUE_SIZE = 16
 //% ENV(default_with_waiti):  ESP_HAL_EMBASSY_CONFIG_LOW_POWER_WAIT = true

hil-test/tests/embassy_interrupt_spi_dma.rs

@@ -3,8 +3,7 @@
 //% CHIPS: esp32 esp32s2 esp32s3 esp32c3 esp32c6 esp32h2
 //% FEATURES: unstable embassy
 //% ENV(single_integrated):   ESP_HAL_EMBASSY_CONFIG_TIMER_QUEUE = single-integrated
-// TODO restore multiple-integrated
-// ENV(multiple_integrated): ESP_HAL_EMBASSY_CONFIG_TIMER_QUEUE = multiple-integrated
+//% ENV(multiple_integrated): ESP_HAL_EMBASSY_CONFIG_TIMER_QUEUE = multiple-integrated
 //% ENV(generic_queue):       ESP_HAL_EMBASSY_CONFIG_TIMER_QUEUE = generic
 //% ENV(generic_queue):       ESP_HAL_EMBASSY_CONFIG_GENERIC_QUEUE_SIZE = 16
 

qa-test/.cargo/config.toml

@@ -28,9 +28,7 @@ rustflags = [
 
 [env]
 ESP_LOG = "info"
-# TODO restore multiple-integrated
-#ESP_HAL_EMBASSY_CONFIG_TIMER_QUEUE="multiple-integrated"
-ESP_HAL_EMBASSY_CONFIG_TIMER_QUEUE="single-integrated"
+ESP_HAL_EMBASSY_CONFIG_TIMER_QUEUE="multiple-integrated"
 
 [unstable]
 build-std = ["alloc", "core"]