zephyr: Add initial support for embassy

Adds the Cargo.toml framework for initial support of using Embassy's
executor on Zephyr.  This implements a time driver for Embassy using a
`k_timer` from Zephyr.

Signed-off-by: David Brown <[email protected]>

Author: d3zd3z

zephyr/Cargo.toml

@@ -45,8 +45,30 @@ version = "0.2.2"
 # should be safe to build the crate even if the Rust code doesn't use it because of configs.
 features = ["alloc"]
 
+[dependencies.embassy-time-driver]
+version = "0.2"
+# Someone needs to tell embassy what our clock frequency is.  Until we have support from cmake for
+# this, we'll have to leave this up to the app to provide, since it is heavily board specific.
+optional = true
+
+[dependencies.embassy-time-queue-utils]
+version = "0.1"
+optional = true
+
+[dependencies.embassy-sync]
+version = "0.6.2"
+optional = true
+
 # These are needed at build time.
 # Whether these need to be vendored is an open question.  They are not
 # used by the core Zephyr tree, but are needed by zephyr applications.
 [build-dependencies]
 zephyr-build = { version = "0.1.0", path = "../zephyr-build" }
+
+[features]
+# Provide an implementation of embassy-time-driver.
+time-driver = [
+  "dep:embassy-time-driver",
+  "dep:embassy-time-queue-utils",
+  "dep:embassy-sync",
+]

zephyr/src/embassy.rs

@@ -0,0 +1,88 @@
+//! Support for Embassy on Rust+Zephyr
+//!
+//! [Embassy](https://embassy.dev/) is: "The next-generation framework for embedded applications".
+//! From a typical RTOS perspective it is perhaps a little difficult to explain what exactly it is,
+//! and why it makes sense to discuss it in the context of supporting Rust on Zephyr.
+//!
+//! At a core level, Embassy is a set of crates that implement various functionality that is used
+//! when writing bare metal applications in Rust.  Combined, these provide most of the functionality
+//! that is needed for an embedded application.  However, the crates are largely independent, and as
+//! such find use when combined with Zephyr.
+//!
+//! ## Executor
+//!
+//! A significant aspect of Embassy's functionality revolves around providing one or more executors
+//! for coordinating async code in Rust.  The Rust language transforms code annotated with
+//! async/await into state machines that allow these operations to be run cooperatively.  A bare
+//! metal system with one or more of these executors managing async tasks can indeed solve many of
+//! the types of scheduling solutions needed for embedded systems.
+//!
+//! Although Zephyr does have a thread scheduler, there are still some advantages to running an
+//! executor on one or more Zephyr threads:
+//!
+//! - Because the async code is transformed into a state machine, this code only uses stack while
+//!   evaluating to the next stopping point.  This allows a large number of async operations to
+//!   happen on a single thread, without requiring additional stack.  The state machines themselves
+//!   do take memory, but this usage is known at compile time (with the stable Rust compiler, it is
+//!   allocated from a pool, and with the nightly compiler, can be completely compile time
+//!   determined).
+//! - Context switches between async threads can be very fast.  When running a single executor
+//!   thread, there is no need for locking for data that is entirely kept within that thread, and
+//!   these context switches have similar cost to a function call.  Even with multiple threads
+//!   involved, many switches will happen on the same underlying Zephyr thread, reducing the need to
+//!   reschedule.
+//! - Embassy provides a lot of mechanisms for coordinating between these tasks, all that work in
+//!   the context of async/await.  Some may be thought of as redundant with Zephyr primitives, but
+//!   they serve a different purpose, and provide more streamlined coordination for things entirely
+//!   within the Rust world.
+//!
+//! ## Use
+//!
+//! To best use this module, it is best to look at the various examples under `samples/embassy*` in
+//! this repo.  Some of the embassy crates, especially embassy-executor have numerous features that
+//! must be configured correctly for proper operation.  To use the 'executor-thread' feature, it is
+//! also necessary to configure embassy for the proper platform.  Future versions of the Cmake files
+//! for Rust on Zephyr may provide assistance with this, but for now, this does limit a given
+//! application to running on a specific architecture.  For using the `executor-zephyr` feature
+//! provided by this module, it easier to allow the code to run on multiple platforms.
+//!
+//! The following features in the `zephyr` crate configure what is supported:
+//!
+//! - **`executor-zephyr`**: This implements an executor that uses Zephyr's thread primitives
+//!   (`k_thread_suspend` and `k_thread_resume`) to suspend the executor thread when there is no work
+//!   to perform.  This feature is incompatible with either `embassy-thread` or `embassy-interrupt`
+//!   in the `embassy-executor` crate.
+//! - **`embassy-time-driver`**: This feature causes the `zephyr` crate to provide a time driver to
+//!   Embassy.  This driver uses a single `k_timer` in Zephyr to wake async operations that are
+//!   dependent on time.  This enables the `embassy-time` crate's functionality to be used freely
+//!   within async tasks on Zephyr.
+//!
+//! Future versions of this support will provide async interfaces to various driver systems in
+//! Zephyr, allowing the use of Zephyr drivers freely from async code.
+//!
+//! It is perfectly permissible to use the `executor-thread` feature from embassy-executor on
+//! Zephyr, within the following guidelines:
+//!
+//! - The executor is incompatible with the async executor provided within [`crate::kio`], and
+//!   because there are no features to enable this, this functions will still be accessible.  Be
+//!   careful.  You should enable `no-kio` in the zephyr crate to hide these functions.
+//! - This executor does not coordinate with the scheduler on Zephyr, but uses an
+//!   architecture-specific mechanmism when there is no work. On Cortex-M, this is the 'wfe'
+//!   instruction, on riscv32, the 'wfi' instruction.  This means that no tasks of lower priority
+//!   will ever run, so this should only be started from the lowest priority task on the system.
+//! - Because the 'idle' thread in Zephyr will never run, some platforms will not enter low power
+//!   mode, when the system is idle.  This is very platform specific.
+//!
+//! ## Caveats
+//!
+//! The executor provided by Embassy is fundamentally incompatible with the executor provided by
+//! this crate's [`crate::kio`] and [`crate::work::futures`].  Trying to use the functionality
+//! provided by operations, such as [`Semaphore::take_async`], will generally result in a panic.
+//! These routines are conditionally compiled out when `executor-zephyr` is enabled, but there is no
+//! way for this crate to detect the use of embassy's `executor-threaded`.  Combining these will
+//! result in undefined behavior, likely difficult to debug crashes.
+//!
+//! [`Semaphore::take_async`]: crate::sys::sync::Semaphore::take_async
+
+#[cfg(feature = "time-driver")]
+mod time_driver;

zephyr/src/embassy/time_driver.rs

@@ -0,0 +1,97 @@
+//! Embassy time driver for Zephyr.
+//!
+//! Implements the time driver for Embassy using a `k_timer` in Zephyr.
+
+use core::{cell::{RefCell, UnsafeCell}, mem};
+
+use embassy_sync::blocking_mutex::{raw::CriticalSectionRawMutex, Mutex};
+use embassy_time_driver::Driver;
+use embassy_time_queue_utils::Queue;
+
+use crate::raw::{
+    k_timer,
+    k_timer_init,
+    k_timer_start,
+    k_timeout_t,
+};
+use crate::sys::K_FOREVER;
+
+embassy_time_driver::time_driver_impl!(static DRIVER: ZephyrTimeDriver = ZephyrTimeDriver {
+    queue: Mutex::new(RefCell::new(Queue::new())),
+    timer: Mutex::new(RefCell::new(unsafe { mem::zeroed() })),
+});
+
+struct ZephyrTimeDriver {
+    queue: Mutex<CriticalSectionRawMutex, RefCell<Queue>>,
+    timer: Mutex<CriticalSectionRawMutex, RefCell<ZTimer>>,
+}
+
+/// A wrapper around `k_timer`.  In this case, the implementation is a little simpler than the one
+/// in the timer module, as we are always called from within a critical section.
+struct ZTimer {
+    item: UnsafeCell<k_timer>,
+    initialized: bool,
+}
+
+impl ZTimer {
+    fn set_alarm(&mut self, next: u64, now: u64) -> bool {
+        if next <= now {
+            return false;
+        }
+
+        // Otherwise, initialize our timer, and handle it.
+        if !self.initialized {
+            unsafe { k_timer_init(self.item.get(), Some(Self::timer_tick), None); }
+            self.initialized = true;
+        }
+
+        // There is a +1 here as the `k_timer_start()` for historical reasons, subtracts one from
+        // the time, effectively rounding down, whereas we want to wait at least long enough.
+        let delta = k_timeout_t { ticks: (next - now + 1) as i64 };
+        let period = K_FOREVER;
+        unsafe { k_timer_start(self.item.get(), delta, period); }
+
+        true
+    }
+
+    unsafe extern "C" fn timer_tick(_k_timer: *mut k_timer) {
+        DRIVER.check_alarm();
+    }
+}
+
+impl Driver for ZephyrTimeDriver {
+    fn now(&self) -> u64 {
+        crate::time::now().ticks()
+    }
+
+    fn schedule_wake(&self, at: u64, waker: &core::task::Waker) {
+        critical_section::with(|cs| {
+            let mut queue = self.queue.borrow(cs).borrow_mut();
+            let mut timer = self.timer.borrow(cs).borrow_mut();
+
+            if queue.schedule_wake(at, waker) {
+                let mut next = queue.next_expiration(self.now());
+                while !timer.set_alarm(next, self.now()) {
+                    next = queue.next_expiration(self.now());
+                }
+            }
+        })
+    }
+}
+
+impl ZephyrTimeDriver {
+    fn check_alarm(&self) {
+        critical_section::with(|cs| {
+            let mut queue = self.queue.borrow(cs).borrow_mut();
+            let mut timer = self.timer.borrow(cs).borrow_mut();
+
+            let mut next = queue.next_expiration(self.now());
+            while !timer.set_alarm(next, self.now()) {
+                next = queue.next_expiration(self.now());
+            }
+        })
+    }
+}
+
+// SAFETY: The timer access is always coordinated through a critical section.
+unsafe impl Send for ZTimer { }

zephyr/src/lib.rs

@@ -78,6 +78,7 @@
 
 pub mod align;
 pub mod device;
+pub mod embassy;
 pub mod error;
 #[cfg(CONFIG_RUST_ALLOC)]
 pub mod kio;