#[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"); }; } } } } #[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); } } unsafe impl cortex_m::interrupt::InterruptNumber for InterruptPender { fn number(self) -> u16 { self.0 } } /// Interrupt mode executor. /// /// 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. /// /// 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. /// /// 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'. /// /// 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. /// /// 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>, } 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."); } unsafe { (&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() } /// Get a SendSpawner for this executor /// /// This returns a [`SendSpawner`] you can use to spawn tasks on this /// executor. /// /// This MUST only be called on an executor that has already been spawned. /// The function will panic otherwise. pub fn spawner(&'static self) -> crate::SendSpawner { if !self.started.load(Ordering::Acquire) { panic!("InterruptExecutor::spawner() called on uninitialized executor."); } let executor = unsafe { (&*self.executor.get()).assume_init_ref() }; executor.spawner().make_send() } } }