executor: add Pender, rework Cargo features.

This introduces a `Pender` struct with enum cases for thread-mode, interrupt-mode and
custom callback executors. This avoids calls through function pointers when using only
the thread or interrupt executors. Faster, and friendlier to `cargo-call-stack`.

`embassy-executor` now has `arch-xxx` Cargo features to select the arch and to enable
the builtin executors (thread and interrupt).

1 files changed, 194 insertions, 44 deletions

diff --git a/embassy-executor/src/arch/cortex_m.rs b/embassy-executor/src/arch/cortex_m.rs
index 4b27a264e..d6a55c4c7 100644
--- a/embassy-executor/src/arch/cortex_m.rs
+++ b/embassy-executor/src/arch/cortex_m.rs
@@ -1,59 +1,209 @@
-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 ()>,
+#[cfg(feature = "executor-thread")]
+pub use thread::*;
+#[cfg(feature = "executor-thread")]
+mod thread {
+    use core::arch::asm;
+    use core::marker::PhantomData;
+
+    #[cfg(feature = "nightly")]
+    pub use embassy_macros::main_cortex_m as main;
+
+    use crate::raw::{Pender, PenderInner};
+    use crate::{raw, Spawner};
+
+    #[derive(Copy, Clone)]
+    pub(crate) struct ThreadPender;
+
+    impl ThreadPender {
+        pub(crate) fn pend(self) {
+            unsafe { core::arch::asm!("sev") }
+        }
+    }
+
+    /// 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(Pender(PenderInner::Thread(ThreadPender))),
+                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 [StaticCell](https://docs.rs/static_cell/latest/static_cell/) (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");
+                };
+            }
+        }
+    }
 }
 
-impl Executor {
-    /// Create a new Executor.
-    pub fn new() -> Self {
-        Self {
-            inner: raw::Executor::new(|_| unsafe { asm!("sev") }, ptr::null_mut()),
-            not_send: PhantomData,
+#[cfg(feature = "executor-interrupt")]
+pub use interrupt::*;
+#[cfg(feature = "executor-interrupt")]
+mod interrupt {
+    use core::cell::UnsafeCell;
+    use core::mem::MaybeUninit;
+
+    use atomic_polyfill::{AtomicBool, Ordering};
+    use cortex_m::interrupt::InterruptNumber;
+    use cortex_m::peripheral::NVIC;
+
+    use crate::raw::{self, Pender, PenderInner};
+
+    #[derive(Clone, Copy)]
+    pub(crate) struct InterruptPender(u16);
+
+    impl InterruptPender {
+        pub(crate) fn pend(self) {
+            // STIR is faster, but is only available in v7 and higher.
+            #[cfg(not(armv6m))]
+            {
+                let mut nvic: cortex_m::peripheral::NVIC = unsafe { core::mem::transmute(()) };
+                nvic.request(self);
+            }
+
+            #[cfg(armv6m)]
+            cortex_m::peripheral::NVIC::pend(self);
         }
     }
 
-    /// Run the executor.
+    unsafe impl cortex_m::interrupt::InterruptNumber for InterruptPender {
+        fn number(self) -> u16 {
+            self.0
+        }
+    }
+
+    /// Interrupt mode 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.
+    /// This executor runs tasks in interrupt mode. The interrupt handler is set up
+    /// to poll tasks, and when a task is woken the interrupt is pended from software.
     ///
-    /// 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 allows running async tasks at a priority higher than thread mode. One
+    /// use case is to leave thread mode free for non-async tasks. Another use case is
+    /// to run multiple executors: one in thread mode for low priority tasks and another in
+    /// interrupt mode for higher priority tasks. Higher priority tasks will preempt lower
+    /// priority ones.
     ///
-    /// 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:
+    /// It is even possible to run multiple interrupt mode executors at different priorities,
+    /// by assigning different priorities to the interrupts. For an example on how to do this,
+    /// See the 'multiprio' example for 'embassy-nrf'.
     ///
-    /// - a [StaticCell](https://docs.rs/static_cell/latest/static_cell/) (safe)
-    /// - a `static mut` (unsafe)
-    /// - a local variable in a function you know never returns (like `fn main() -> !`), upgrading its lifetime with `transmute`. (unsafe)
+    /// To use it, you have to pick an interrupt that won't be used by the hardware.
+    /// Some chips reserve some interrupts for this purpose, sometimes named "software interrupts" (SWI).
+    /// If this is not the case, you may use an interrupt from any unused peripheral.
     ///
-    /// This function never returns.
-    pub fn run(&'static mut self, init: impl FnOnce(Spawner)) -> ! {
-        init(self.inner.spawner());
+    /// It is somewhat more complex to use, it's recommended to use the thread-mode
+    /// [`Executor`] instead, if it works for your use case.
+    pub struct InterruptExecutor {
+        started: AtomicBool,
+        executor: UnsafeCell<MaybeUninit<raw::Executor>>,
+    }
+
+    unsafe impl Send for InterruptExecutor {}
+    unsafe impl Sync for InterruptExecutor {}
+
+    impl InterruptExecutor {
+        /// Create a new, not started `InterruptExecutor`.
+        #[inline]
+        pub const fn new() -> Self {
+            Self {
+                started: AtomicBool::new(false),
+                executor: UnsafeCell::new(MaybeUninit::uninit()),
+            }
+        }
+
+        /// Executor interrupt callback.
+        ///
+        /// # Safety
+        ///
+        /// You MUST call this from the interrupt handler, and from nowhere else.
+        pub unsafe fn on_interrupt(&'static self) {
+            let executor = unsafe { (&*self.executor.get()).assume_init_ref() };
+            executor.poll();
+        }
+
+        /// Start the executor.
+        ///
+        /// This initializes the executor, enables the interrupt, and returns.
+        /// The executor keeps running in the background through the interrupt.
+        ///
+        /// This returns a [`SendSpawner`] you can use to spawn tasks on it. A [`SendSpawner`]
+        /// is returned instead of a [`Spawner`](embassy_executor::Spawner) because the executor effectively runs in a
+        /// different "thread" (the interrupt), so spawning tasks on it is effectively
+        /// sending them.
+        ///
+        /// To obtain a [`Spawner`](embassy_executor::Spawner) for this executor, use [`Spawner::for_current_executor()`](embassy_executor::Spawner::for_current_executor()) from
+        /// a task running in it.
+        ///
+        /// # Interrupt requirements
+        ///
+        /// You must write the interrupt handler yourself, and make it call [`on_interrupt()`](Self::on_interrupt).
+        ///
+        /// This method already enables (unmasks) the interrupt, you must NOT do it yourself.
+        ///
+        /// You must set the interrupt priority before calling this method. You MUST NOT
+        /// do it after.
+        ///
+        pub fn start(&'static self, irq: impl InterruptNumber) -> crate::SendSpawner {
+            if self
+                .started
+                .compare_exchange(false, true, Ordering::Acquire, Ordering::Relaxed)
+                .is_err()
+            {
+                panic!("InterruptExecutor::start() called multiple times on the same executor.");
+            }
 
-        loop {
             unsafe {
-                self.inner.poll();
-                asm!("wfe");
-            };
+                (&mut *self.executor.get())
+                    .as_mut_ptr()
+                    .write(raw::Executor::new(Pender(PenderInner::Interrupt(InterruptPender(
+                        irq.number(),
+                    )))))
+            }
+
+            let executor = unsafe { (&*self.executor.get()).assume_init_ref() };
+
+            unsafe { NVIC::unmask(irq) }
+
+            executor.spawner().make_send()
         }
     }
 }