Split embassy-time from embassy-executor.

embassy-executor/src/arch/cortex_m.rs

@@ -0,0 +1,59 @@
+use core::arch::asm;
+use core::marker::PhantomData;
+use core::ptr;
+
+use super::{raw, Spawner};
+
+/// Thread mode executor, using WFE/SEV.
+///
+/// This is the simplest and most common kind of executor. It runs on
+/// thread mode (at the lowest priority level), and uses the `WFE` ARM instruction
+/// to sleep when it has no more work to do. When a task is woken, a `SEV` instruction
+/// is executed, to make the `WFE` exit from sleep and poll the task.
+///
+/// This executor allows for ultra low power consumption for chips where `WFE`
+/// triggers low-power sleep without extra steps. If your chip requires extra steps,
+/// you may use [`raw::Executor`] directly to program custom behavior.
+pub struct Executor {
+    inner: raw::Executor,
+    not_send: PhantomData<*mut ()>,
+}
+
+impl Executor {
+    /// Create a new Executor.
+    pub fn new() -> Self {
+        Self {
+            inner: raw::Executor::new(|_| unsafe { asm!("sev") }, ptr::null_mut()),
+            not_send: PhantomData,
+        }
+    }
+
+    /// Run the executor.
+    ///
+    /// The `init` closure is called with a [`Spawner`] that spawns tasks on
+    /// this executor. Use it to spawn the initial task(s). After `init` returns,
+    /// the executor starts running the tasks.
+    ///
+    /// To spawn more tasks later, you may keep copies of the [`Spawner`] (it is `Copy`),
+    /// for example by passing it as an argument to the initial tasks.
+    ///
+    /// This function requires `&'static mut self`. This means you have to store the
+    /// Executor instance in a place where it'll live forever and grants you mutable
+    /// access. There's a few ways to do this:
+    ///
+    /// - a [Forever](crate::util::Forever) (safe)
+    /// - a `static mut` (unsafe)
+    /// - 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());
+
+        loop {
+            unsafe {
+                self.inner.poll();
+                asm!("wfe");
+            };
+        }
+    }
+}

embassy-executor/src/arch/riscv32.rs

@@ -0,0 +1,74 @@
+use core::marker::PhantomData;
+use core::ptr;
+
+use atomic_polyfill::{AtomicBool, Ordering};
+
+use super::{raw, Spawner};
+
+/// global atomic used to keep track of whether there is work to do since sev() is not available on RISCV
+///
+static SIGNAL_WORK_THREAD_MODE: AtomicBool = AtomicBool::new(false);
+
+/// RISCV32 Executor
+pub struct Executor {
+    inner: raw::Executor,
+    not_send: PhantomData<*mut ()>,
+}
+
+impl Executor {
+    /// Create a new Executor.
+    pub fn new() -> Self {
+        Self {
+            // use Signal_Work_Thread_Mode as substitute for local interrupt register
+            inner: raw::Executor::new(
+                |_| {
+                    SIGNAL_WORK_THREAD_MODE.store(true, Ordering::SeqCst);
+                },
+                ptr::null_mut(),
+            ),
+            not_send: PhantomData,
+        }
+    }
+
+    /// Run the executor.
+    ///
+    /// The `init` closure is called with a [`Spawner`] that spawns tasks on
+    /// this executor. Use it to spawn the initial task(s). After `init` returns,
+    /// the executor starts running the tasks.
+    ///
+    /// To spawn more tasks later, you may keep copies of the [`Spawner`] (it is `Copy`),
+    /// for example by passing it as an argument to the initial tasks.
+    ///
+    /// This function requires `&'static mut self`. This means you have to store the
+    /// Executor instance in a place where it'll live forever and grants you mutable
+    /// access. There's a few ways to do this:
+    ///
+    /// - a [Forever](crate::util::Forever) (safe)
+    /// - a `static mut` (unsafe)
+    /// - 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());
+
+        loop {
+            unsafe {
+                self.inner.poll();
+                // we do not care about race conditions between the load and store operations, interrupts
+                //will only set this value to true.
+                critical_section::with(|_| {
+                    // if there is work to do, loop back to polling
+                    // TODO can we relax this?
+                    if SIGNAL_WORK_THREAD_MODE.load(Ordering::SeqCst) {
+                        SIGNAL_WORK_THREAD_MODE.store(false, Ordering::SeqCst);
+                    }
+                    // if not, wait for interrupt
+                    else {
+                        core::arch::asm!("wfi");
+                    }
+                });
+                // if an interrupt occurred while waiting, it will be serviced here
+            }
+        }
+    }
+}

embassy-executor/src/arch/std.rs

@@ -0,0 +1,84 @@
+use std::marker::PhantomData;
+use std::sync::{Condvar, Mutex};
+
+use super::{raw, Spawner};
+
+/// Single-threaded std-based executor.
+pub struct Executor {
+    inner: raw::Executor,
+    not_send: PhantomData<*mut ()>,
+    signaler: &'static Signaler,
+}
+
+impl Executor {
+    /// Create a new Executor.
+    pub fn new() -> Self {
+        let signaler = &*Box::leak(Box::new(Signaler::new()));
+        Self {
+            inner: raw::Executor::new(
+                |p| unsafe {
+                    let s = &*(p as *const () as *const Signaler);
+                    s.signal()
+                },
+                signaler as *const _ as _,
+            ),
+            not_send: PhantomData,
+            signaler,
+        }
+    }
+
+    /// Run the executor.
+    ///
+    /// The `init` closure is called with a [`Spawner`] that spawns tasks on
+    /// this executor. Use it to spawn the initial task(s). After `init` returns,
+    /// the executor starts running the tasks.
+    ///
+    /// To spawn more tasks later, you may keep copies of the [`Spawner`] (it is `Copy`),
+    /// for example by passing it as an argument to the initial tasks.
+    ///
+    /// This function requires `&'static mut self`. This means you have to store the
+    /// Executor instance in a place where it'll live forever and grants you mutable
+    /// access. There's a few ways to do this:
+    ///
+    /// - a [Forever](crate::util::Forever) (safe)
+    /// - a `static mut` (unsafe)
+    /// - 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());
+
+        loop {
+            unsafe { self.inner.poll() };
+            self.signaler.wait()
+        }
+    }
+}
+
+struct Signaler {
+    mutex: Mutex<bool>,
+    condvar: Condvar,
+}
+
+impl Signaler {
+    fn new() -> Self {
+        Self {
+            mutex: Mutex::new(false),
+            condvar: Condvar::new(),
+        }
+    }
+
+    fn wait(&self) {
+        let mut signaled = self.mutex.lock().unwrap();
+        while !*signaled {
+            signaled = self.condvar.wait(signaled).unwrap();
+        }
+        *signaled = false;
+    }
+
+    fn signal(&self) {
+        let mut signaled = self.mutex.lock().unwrap();
+        *signaled = true;
+        self.condvar.notify_one();
+    }
+}

embassy-executor/src/arch/wasm.rs

@@ -0,0 +1,74 @@
+use core::marker::PhantomData;
+
+use js_sys::Promise;
+use wasm_bindgen::prelude::*;
+
+use super::raw::util::UninitCell;
+use super::raw::{self};
+use super::Spawner;
+
+/// WASM executor, wasm_bindgen to schedule tasks on the JS event loop.
+pub struct Executor {
+    inner: raw::Executor,
+    ctx: &'static WasmContext,
+    not_send: PhantomData<*mut ()>,
+}
+
+pub(crate) struct WasmContext {
+    promise: Promise,
+    closure: UninitCell<Closure<dyn FnMut(JsValue)>>,
+}
+
+impl WasmContext {
+    pub fn new() -> Self {
+        Self {
+            promise: Promise::resolve(&JsValue::undefined()),
+            closure: UninitCell::uninit(),
+        }
+    }
+}
+
+impl Executor {
+    /// Create a new Executor.
+    pub fn new() -> Self {
+        let ctx = &*Box::leak(Box::new(WasmContext::new()));
+        let inner = raw::Executor::new(
+            |p| unsafe {
+                let ctx = &*(p as *const () as *const WasmContext);
+                let _ = ctx.promise.then(ctx.closure.as_mut());
+            },
+            ctx as *const _ as _,
+        );
+        Self {
+            inner,
+            not_send: PhantomData,
+            ctx,
+        }
+    }
+
+    /// Run the executor.
+    ///
+    /// The `init` closure is called with a [`Spawner`] that spawns tasks on
+    /// this executor. Use it to spawn the initial task(s). After `init` returns,
+    /// the executor starts running the tasks.
+    ///
+    /// To spawn more tasks later, you may keep copies of the [`Spawner`] (it is `Copy`),
+    /// for example by passing it as an argument to the initial tasks.
+    ///
+    /// This function requires `&'static mut self`. This means you have to store the
+    /// Executor instance in a place where it'll live forever and grants you mutable
+    /// access. There's a few ways to do this:
+    ///
+    /// - a [Forever](crate::util::Forever) (safe)
+    /// - a `static mut` (unsafe)
+    /// - a local variable in a function you know never returns (like `fn main() -> !`), upgrading its lifetime with `transmute`. (unsafe)
+    pub fn start(&'static mut self, init: impl FnOnce(Spawner)) {
+        unsafe {
+            let executor = &self.inner;
+            self.ctx.closure.write(Closure::new(move |_| {
+                executor.poll();
+            }));
+            init(self.inner.spawner());
+        }
+    }
+}

embassy-executor/src/arch/xtensa.rs

@@ -0,0 +1,75 @@
+use core::marker::PhantomData;
+use core::ptr;
+
+use atomic_polyfill::{AtomicBool, Ordering};
+
+use super::{raw, Spawner};
+
+/// global atomic used to keep track of whether there is work to do since sev() is not available on Xtensa
+///
+static SIGNAL_WORK_THREAD_MODE: AtomicBool = AtomicBool::new(false);
+
+/// Xtensa Executor
+pub struct Executor {
+    inner: raw::Executor,
+    not_send: PhantomData<*mut ()>,
+}
+
+impl Executor {
+    /// Create a new Executor.
+    pub fn new() -> Self {
+        Self {
+            // use Signal_Work_Thread_Mode as substitute for local interrupt register
+            inner: raw::Executor::new(
+                |_| {
+                    SIGNAL_WORK_THREAD_MODE.store(true, Ordering::SeqCst);
+                },
+                ptr::null_mut(),
+            ),
+            not_send: PhantomData,
+        }
+    }
+
+    /// Run the executor.
+    ///
+    /// The `init` closure is called with a [`Spawner`] that spawns tasks on
+    /// this executor. Use it to spawn the initial task(s). After `init` returns,
+    /// the executor starts running the tasks.
+    ///
+    /// To spawn more tasks later, you may keep copies of the [`Spawner`] (it is `Copy`),
+    /// for example by passing it as an argument to the initial tasks.
+    ///
+    /// This function requires `&'static mut self`. This means you have to store the
+    /// Executor instance in a place where it'll live forever and grants you mutable
+    /// access. There's a few ways to do this:
+    ///
+    /// - a [Forever](crate::util::Forever) (safe)
+    /// - a `static mut` (unsafe)
+    /// - 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());
+
+        loop {
+            unsafe {
+                self.inner.poll();
+                // we do not care about race conditions between the load and store operations, interrupts
+                // will only set this value to true.
+                // if there is work to do, loop back to polling
+                // TODO can we relax this?
+                critical_section::with(|_| {
+                    if SIGNAL_WORK_THREAD_MODE.load(Ordering::SeqCst) {
+                        SIGNAL_WORK_THREAD_MODE.store(false, Ordering::SeqCst);
+                    } else {
+                        // waiti sets the PS.INTLEVEL when slipping into sleep
+                        // because critical sections in Xtensa are implemented via increasing
+                        // PS.INTLEVEL the critical section ends here
+                        // take care not add code after `waiti` if it needs to be inside the CS
+                        core::arch::asm!("waiti 0"); // critical section ends here
+                    }
+                });
+            }
+        }
+    }
+}