executor/spin: introduce an architecture agnostic executor

Spin polls the raw executor and never sleeps. It is useful for disabling
any power features associated with wfi/wfe-like instructions.

When implementing support for the CH32V30x MCU, the wfi instruction
had issues interacting with the USB OTG peripheral and appeared to be
non-spec-compliant.

1. When sending a USB Data-in packet, the USB peripheral appears to be
unable to read the system main memory while in WFI. This manifests in
the USB peripheral sending all or partially zeroed DATA packets.
Disabling WFI works around this issue.

2. The WFI instruction does not wake up the processor when MIE is
disabled. The MCU provides a WFITOWFE bit to emulate the WFE instruction
on arm, which, when enabled, ignores the MIE and allows the processor to
wake up. This works around the non-compliant WFI implementation.

Co-authored-by: Codetector <[email protected]>
Co-authored-by: Dummyc0m <[email protected]>

5 files changed, 126 insertions, 2 deletions

diff --git a/embassy-executor-macros/src/lib.rs b/embassy-executor-macros/src/lib.rs
index 5461fe04c..61d388b9e 100644
--- a/embassy-executor-macros/src/lib.rs
+++ b/embassy-executor-macros/src/lib.rs
@@ -94,6 +94,35 @@ pub fn main_cortex_m(args: TokenStream, item: TokenStream) -> TokenStream {
     main::run(&args.meta, f, main::cortex_m()).unwrap_or_else(|x| x).into()
 }
 
+/// Creates a new `executor` instance and declares an architecture agnostic application entry point spawning
+/// the corresponding function body as an async task.
+///
+/// The following restrictions apply:
+///
+/// * The function must accept exactly 1 parameter, an `embassy_executor::Spawner` handle that it can use to spawn additional tasks.
+/// * The function must be declared `async`.
+/// * The function must not use generics.
+/// * Only a single `main` task may be declared.
+///
+/// A user-defined entry macro must provided via the `entry` argument
+///
+/// ## Examples
+/// Spawning a task:
+/// ``` rust
+/// #[embassy_executor::main(entry = "qingke_rt::entry")]
+/// async fn main(_s: embassy_executor::Spawner) {
+///     // Function body
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn main_spin(args: TokenStream, item: TokenStream) -> TokenStream {
+    let args = syn::parse_macro_input!(args as Args);
+    let f = syn::parse_macro_input!(item as syn::ItemFn);
+    main::run(&args.meta, f, main::spin(&args.meta))
+        .unwrap_or_else(|x| x)
+        .into()
+}
+
 /// Creates a new `executor` instance and declares an application entry point for RISC-V spawning the corresponding function body as an async task.
 ///
 /// The following restrictions apply:
diff --git a/embassy-executor-macros/src/macros/main.rs b/embassy-executor-macros/src/macros/main.rs
index 26dfa2397..66a3965d0 100644
--- a/embassy-executor-macros/src/macros/main.rs
+++ b/embassy-executor-macros/src/macros/main.rs
@@ -1,5 +1,5 @@
 use darling::export::NestedMeta;
-use darling::FromMeta;
+use darling::{Error, FromMeta};
 use proc_macro2::TokenStream;
 use quote::quote;
 use syn::{Expr, ReturnType, Type};
@@ -50,6 +50,33 @@ pub fn riscv(args: &[NestedMeta]) -> TokenStream {
     }
 }
 
+pub fn spin(args: &[NestedMeta]) -> TokenStream {
+    let maybe_entry = match Args::from_list(args) {
+        Ok(args) => args.entry,
+        Err(e) => return e.write_errors(),
+    };
+
+    let entry = match maybe_entry {
+        Some(str) => str,
+        None => return Error::missing_field("entry").write_errors(),
+    };
+    let entry = match Expr::from_string(&entry) {
+        Ok(expr) => expr,
+        Err(e) => return e.write_errors(),
+    };
+
+    quote! {
+        #[#entry]
+        fn main() -> ! {
+            let mut executor = ::embassy_executor::Executor::new();
+            let executor = unsafe { __make_static(&mut executor) };
+            executor.run(|spawner| {
+                spawner.must_spawn(__embassy_main(spawner));
+            })
+        }
+    }
+}
+
 pub fn cortex_m() -> TokenStream {
     quote! {
         #[cortex_m_rt::entry]
diff --git a/embassy-executor/Cargo.toml b/embassy-executor/Cargo.toml
index 01fa28b88..e2fedce3c 100644
--- a/embassy-executor/Cargo.toml
+++ b/embassy-executor/Cargo.toml
@@ -82,6 +82,8 @@ arch-riscv32 = ["_arch"]
 arch-wasm = ["_arch", "dep:wasm-bindgen", "dep:js-sys", "critical-section/std"]
 ## AVR
 arch-avr = ["_arch", "dep:portable-atomic", "dep:avr-device"]
+## spin (architecture agnostic; never sleeps)
+arch-spin = ["_arch"]
 
 #! ### Executor
 
diff --git a/embassy-executor/src/arch/spin.rs b/embassy-executor/src/arch/spin.rs
new file mode 100644
index 000000000..340023620
--- /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::{raw, Spawner};
+
+    #[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/lib.rs b/embassy-executor/src/lib.rs
index 6a2e493a2..d816539ac 100644
--- a/embassy-executor/src/lib.rs
+++ b/embassy-executor/src/lib.rs
@@ -23,7 +23,14 @@ macro_rules! check_at_most_one {
         check_at_most_one!(@amo [$($f)*] [$($f)*] []);
     };
 }
-check_at_most_one!("arch-avr", "arch-cortex-m", "arch-riscv32", "arch-std", "arch-wasm",);
+check_at_most_one!(
+    "arch-avr",
+    "arch-cortex-m",
+    "arch-riscv32",
+    "arch-std",
+    "arch-wasm",
+    "arch-spin",
+);
 
 #[cfg(feature = "_arch")]
 #[cfg_attr(feature = "arch-avr", path = "arch/avr.rs")]
@@ -31,6 +38,7 @@ check_at_most_one!("arch-avr", "arch-cortex-m", "arch-riscv32", "arch-std", "arc
 #[cfg_attr(feature = "arch-riscv32", path = "arch/riscv32.rs")]
 #[cfg_attr(feature = "arch-std", path = "arch/std.rs")]
 #[cfg_attr(feature = "arch-wasm", path = "arch/wasm.rs")]
+#[cfg_attr(feature = "arch-spin", path = "arch/spin.rs")]
 mod arch;
 
 #[cfg(feature = "_arch")]