Merge branch 'main' into u0-lcd

7 files changed, 160 insertions, 14 deletions

diff --git a/embassy-executor/src/arch/avr.rs b/embassy-executor/src/arch/avr.rs
index 70085d04d..a841afe15 100644
--- a/embassy-executor/src/arch/avr.rs
+++ b/embassy-executor/src/arch/avr.rs
@@ -10,11 +10,11 @@ mod thread {
     pub use embassy_executor_macros::main_avr as main;
     use portable_atomic::{AtomicBool, Ordering};
 
-    use crate::{raw, Spawner};
+    use crate::{Spawner, raw};
 
     static SIGNAL_WORK_THREAD_MODE: AtomicBool = AtomicBool::new(false);
 
-    #[export_name = "__pender"]
+    #[unsafe(export_name = "__pender")]
     fn __pender(_context: *mut ()) {
         SIGNAL_WORK_THREAD_MODE.store(true, Ordering::SeqCst);
     }
diff --git a/embassy-executor/src/arch/cortex_ar.rs b/embassy-executor/src/arch/cortex_ar.rs
new file mode 100644
index 000000000..ce572738a
--- /dev/null
+++ b/embassy-executor/src/arch/cortex_ar.rs
@@ -0,0 +1,87 @@
+#[cfg(arm_profile = "legacy")]
+compile_error!("`arch-cortex-ar` does not support the legacy ARM profile, WFE/SEV are not available.");
+
+#[cfg(feature = "executor-interrupt")]
+compile_error!("`executor-interrupt` is not supported with `arch-cortex-ar`.");
+
+#[unsafe(export_name = "__pender")]
+#[cfg(any(feature = "executor-thread", feature = "executor-interrupt"))]
+fn __pender(context: *mut ()) {
+    // `context` is always `usize::MAX` created by `Executor::run`.
+    let context = context as usize;
+
+    #[cfg(feature = "executor-thread")]
+    // Try to make Rust optimize the branching away if we only use thread mode.
+    if !cfg!(feature = "executor-interrupt") || context == THREAD_PENDER {
+        aarch32_cpu::asm::sev();
+        return;
+    }
+}
+
+#[cfg(feature = "executor-thread")]
+pub use thread::*;
+#[cfg(feature = "executor-thread")]
+mod thread {
+    pub(super) const THREAD_PENDER: usize = usize::MAX;
+
+    use core::marker::PhantomData;
+
+    use aarch32_cpu::asm::wfe;
+    pub use embassy_executor_macros::main_cortex_ar as main;
+
+    use crate::{Spawner, raw};
+
+    /// 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(THREAD_PENDER as *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 [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();
+                }
+                wfe();
+            }
+        }
+    }
+}
diff --git a/embassy-executor/src/arch/cortex_m.rs b/embassy-executor/src/arch/cortex_m.rs
index 5c517e0a2..1ce96d1d5 100644
--- a/embassy-executor/src/arch/cortex_m.rs
+++ b/embassy-executor/src/arch/cortex_m.rs
@@ -1,4 +1,4 @@
-#[export_name = "__pender"]
+#[unsafe(export_name = "__pender")]
 #[cfg(any(feature = "executor-thread", feature = "executor-interrupt"))]
 fn __pender(context: *mut ()) {
     unsafe {
@@ -53,7 +53,7 @@ mod thread {
 
     pub use embassy_executor_macros::main_cortex_m as main;
 
-    use crate::{raw, Spawner};
+    use crate::{Spawner, raw};
 
     /// Thread mode executor, using WFE/SEV.
     ///
@@ -143,7 +143,7 @@ mod interrupt {
     /// 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.
+    /// [`Executor`](crate::Executor) instead, if it works for your use case.
     pub struct InterruptExecutor {
         started: Mutex<Cell<bool>>,
         executor: UnsafeCell<MaybeUninit<raw::Executor>>,
@@ -179,11 +179,11 @@ mod interrupt {
         /// 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
+        /// is returned instead of a [`Spawner`](crate::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
+        /// To obtain a [`Spawner`](crate::Spawner) for this executor, use [`Spawner::for_current_executor()`](crate::Spawner::for_current_executor()) from
         /// a task running in it.
         ///
         /// # Interrupt requirements
@@ -195,6 +195,7 @@ mod interrupt {
         /// You must set the interrupt priority before calling this method. You MUST NOT
         /// do it after.
         ///
+        /// [`SendSpawner`]: crate::SendSpawner
         pub fn start(&'static self, irq: impl InterruptNumber) -> crate::SendSpawner {
             if critical_section::with(|cs| self.started.borrow(cs).replace(true)) {
                 panic!("InterruptExecutor::start() called multiple times on the same executor.");
@@ -215,7 +216,7 @@ mod interrupt {
 
         /// Get a SendSpawner for this executor
         ///
-        /// This returns a [`SendSpawner`] you can use to spawn tasks on this
+        /// This returns a [`SendSpawner`](crate::SendSpawner) you can use to spawn tasks on this
         /// executor.
         ///
         /// This MUST only be called on an executor that has already been started.
diff --git a/embassy-executor/src/arch/riscv32.rs b/embassy-executor/src/arch/riscv32.rs
index 01e63a9fd..c70c1344a 100644
--- a/embassy-executor/src/arch/riscv32.rs
+++ b/embassy-executor/src/arch/riscv32.rs
@@ -10,12 +10,12 @@ mod thread {
 
     pub use embassy_executor_macros::main_riscv as main;
 
-    use crate::{raw, Spawner};
+    use crate::{Spawner, raw};
 
     /// 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);
 
-    #[export_name = "__pender"]
+    #[unsafe(export_name = "__pender")]
     fn __pender(_context: *mut ()) {
         SIGNAL_WORK_THREAD_MODE.store(true, Ordering::SeqCst);
     }
diff --git a/embassy-executor/src/arch/spin.rs b/embassy-executor/src/arch/spin.rs
new file mode 100644
index 000000000..49f3356a6
--- /dev/null
+++ b/embassy-executor/src/arch/spin.rs
@@ -0,0 +1,58 @@
+#[cfg(feature = "executor-interrupt")]
+compile_error!("`executor-interrupt` is not supported with `arch-spin`.");
+
+#[cfg(feature = "executor-thread")]
+pub use thread::*;
+#[cfg(feature = "executor-thread")]
+mod thread {
+    use core::marker::PhantomData;
+
+    pub use embassy_executor_macros::main_spin as main;
+
+    use crate::{Spawner, raw};
+
+    #[unsafe(export_name = "__pender")]
+    fn __pender(_context: *mut ()) {}
+
+    /// Spin Executor
+    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(core::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 [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() };
+            }
+        }
+    }
+}
diff --git a/embassy-executor/src/arch/std.rs b/embassy-executor/src/arch/std.rs
index b02b15988..c62ab723b 100644
--- a/embassy-executor/src/arch/std.rs
+++ b/embassy-executor/src/arch/std.rs
@@ -10,9 +10,9 @@ mod thread {
 
     pub use embassy_executor_macros::main_std as main;
 
-    use crate::{raw, Spawner};
+    use crate::{Spawner, raw};
 
-    #[export_name = "__pender"]
+    #[unsafe(export_name = "__pender")]
     fn __pender(context: *mut ()) {
         let signaler: &'static Signaler = unsafe { std::mem::transmute(context) };
         signaler.signal()
diff --git a/embassy-executor/src/arch/wasm.rs b/embassy-executor/src/arch/wasm.rs
index f9d0f935c..d2ff2fe51 100644
--- a/embassy-executor/src/arch/wasm.rs
+++ b/embassy-executor/src/arch/wasm.rs
@@ -13,9 +13,9 @@ mod thread {
     use wasm_bindgen::prelude::*;
 
     use crate::raw::util::UninitCell;
-    use crate::{raw, Spawner};
+    use crate::{Spawner, raw};
 
-    #[export_name = "__pender"]
+    #[unsafe(export_name = "__pender")]
     fn __pender(context: *mut ()) {
         let signaler: &'static WasmContext = unsafe { std::mem::transmute(context) };
         let _ = signaler.promise.then(unsafe { signaler.closure.as_mut() });