[chore]: add related info

Author: lvyuemeng

modules/axembassy/src/asynch.rs

@@ -9,6 +9,7 @@ use axtask::yield_now;
 
 pub use embassy_executor::{SendSpawner, Spawner};
 
+/// Global spawner for multi-thread executor
 pub(crate) static SPAWNER: Mutex<OnceCell<SendSpawner>> = Mutex::new(OnceCell::new());
 
 fn init_spawn() {
@@ -17,7 +18,7 @@ fn init_spawn() {
 }
 
 fn init() {
-    use crate::executor_thread::Executor;
+    use crate::executor::Executor;
     use static_cell::StaticCell;
 
     static EXECUTOR: StaticCell<Executor> = StaticCell::new();
@@ -60,7 +61,7 @@ pub(crate) fn set_spawner(spawner: SendSpawner) {
     let _ = sp.set(spawner);
 }
 
-fn wake(ctx: *const ()) {
+fn wake(_ctx: *const ()) {
     // let id = ctx as u64;
     // unpark_task(id, true);
 }

modules/axembassy/src/delegate.rs

@@ -148,6 +148,9 @@ unsafe impl<T> Sync for Delegate<T> {}
 
 impl<T> Delegate<T> {
     #[must_use]
+    /// Creates a new `Delegate`
+    /// 
+    /// **NOT** thread safe and only executor safe
     pub const fn new() -> Self {
         Self {
             send: Signal::new(),
@@ -157,7 +160,8 @@ impl<T> Delegate<T> {
         }
     }
 
-    /// lend
+    /// lend target `T` to other task in the same executor 
+    /// with lifetime longer than delegate itself
     pub async fn lend<'a, 'b: 'a>(&'a self, target: &'b mut T) -> Result<(), DelegateError> {
         use DelegateError::*;
         use DelegateState::*;
@@ -183,7 +187,10 @@ impl<T> Delegate<T> {
         Ok(())
     }
 
-    /// lend and reset
+    /// lend target `T` to other task in the same executor
+    /// with lifetime longer than delegate itself
+    /// 
+    /// reset state afterwards for reuse
     pub async fn lend_new<'a, 'b: 'a>(&'a self, target: &'b mut T) -> Result<(), DelegateError> {
         match self.lend(target).await {
             Ok(()) => {
@@ -194,6 +201,8 @@ impl<T> Delegate<T> {
         }
     }
 
+    /// Returns a mutable reference to the inner value lent 
+    /// by other task in the same executor
     pub async fn with<U>(&self, func: impl FnOnce(&mut T) -> U) -> Result<U, DelegateError> {
         use DelegateError::*;
         use DelegateState::*;
@@ -219,6 +228,7 @@ impl<T> Delegate<T> {
         Ok(res)
     }
 
+    /// Reset the delegate to reuse
     pub fn reset(&self) {
         use DelegateState::*;
 

modules/axembassy/src/executor.rs

@@ -1,12 +1,23 @@
-use core::sync::atomic::{AtomicBool, Ordering};
 use core::marker::PhantomData;
+use core::sync::atomic::{AtomicBool, Ordering};
 use embassy_executor::raw;
 
-static SIGNAL_WORK_THREAD_MODE: AtomicBool = AtomicBool::new(false);
+#[cfg(feature = "executor-single")]
+static SIGNAL_SINGLE: AtomicBool = AtomicBool::new(false);
+
+#[cfg(feature = "executor-thread")]
+#[percpu::def_percpu]
+static SINGAL_THREAD: AtomicBool = AtomicBool::new(false);
 
 #[unsafe(export_name = "__pender")]
 fn __pender(_context: *mut ()) {
-    SIGNAL_WORK_THREAD_MODE.store(true, Ordering::SeqCst);
+    #[cfg(feature = "executor-single")]
+    SIGNAL_SINGLE.store(true, Ordering::SeqCst);
+
+    #[cfg(feature = "executor-thread")]
+    SINGAL_THREAD.with_current(|m| {
+        m.store(true, Ordering::SeqCst);
+    });
 }
 
 pub struct Executor {
@@ -36,10 +47,26 @@ impl Executor {
             unsafe {
                 self.inner.poll();
 
-                if SIGNAL_WORK_THREAD_MODE.load(Ordering::SeqCst) {
-                    SIGNAL_WORK_THREAD_MODE.store(false, Ordering::SeqCst);
-                } else {
-                    axhal::arch::wait_for_irqs();
+                #[cfg(feature = "executor-single")]
+                {
+                    if SIGNAL_SINGLE.load(Ordering::SeqCst) {
+                        SIGNAL_SINGLE.store(false, Ordering::SeqCst);
+                    } else {
+                        axhal::arch::wait_for_irqs();
+                    }
+                }
+
+                #[cfg(feature = "executor-thread")]
+                {
+                    let polled = SINGAL_THREAD.with_current(|m| m.load(Ordering::Acquire));
+                    if polled {
+                        SINGAL_THREAD.with_current(|m| {
+                            m.store(false, Ordering::Release);
+                        });
+                    } else {
+                        // park_current_task();
+                        axtask::yield_now();
+                    }
                 }
             };
         }

modules/axembassy/src/executor_thread.rs

@@ -1,3 +1,25 @@
+//! [ArceOS](https://github.com/arceos-org/arceos) embassy integration
+//!
+//! This module provides embassy asynchronous runtime integration, including
+//! time driver, and executor with single-thread, multi-thread, preemptive(partially)
+//! which are configurable by cargo features.
+//!
+//! # Cargo Features
+//!
+//! - `driver`: Enable time driver support. If it's enabled, time driver is used.
+//!   Usually used by `axruntime` module in `irq` initiation.
+//! - `executor-single`: Use the [single-thread executor][1]. It also enables the
+//!   related utils modules.
+//! - `executor-thread`: Use the [multi-thread executor][2]. It also enables the
+//!   related utils modules and enables the `multitask` feature if it is enabled.
+//! - `executor-preempt`: Use the [preemptive executor][3]. It also enables the
+//!   related utils modules and enables the `executor-thread` feature if it is
+//!   enabled.
+//!
+//! [1]: single-thread executor
+//! [2]: multi-thread executor(`spawner`, `block_on`)
+//! [3]: preemptive executor(`PrioFuture`)
+
 #![cfg_attr(not(test), no_std)]
 #![feature(doc_cfg)]
 #![feature(doc_auto_cfg)]
@@ -7,30 +29,21 @@ cfg_if::cfg_if! {
         extern crate alloc;
         extern crate log;
 
-        pub mod delegate;
-
-        #[cfg(feature = "executor-thread")]
-        mod executor_thread;
-        #[cfg(feature = "executor-thread")]
         mod asynch;
-        #[cfg(feature = "executor-thread")]
-        mod executor_thread_exports {
-            pub use crate::executor_thread::Executor;
-            pub use crate::asynch::{spawner,block_on,Spawner,SendSpawner};
-            #[cfg(feature = "executor-preempt")]
-            pub use crate::preempt::PrioFuture;
-        }
-        #[cfg(feature = "executor-thread")]
-        pub use executor_thread_exports::*;
+        pub mod delegate;
 
-        #[cfg(feature = "executor-single")]
         mod executor;
-        #[cfg(feature = "executor-single")]
         mod executor_exports {
             pub use crate::executor::Executor;
             pub use crate::asynch::Spawner;
+
+            #[cfg(feature = "executor-thread")]
+            pub use crate::asynch::{spawner,block_on,SendSpawner};
+
+            #[cfg(feature = "executor-preempt")]
+            pub use crate::preempt::PrioFuture;
         }
-        #[cfg(feature = "executor-single")]
+
         pub use executor_exports::*;
     }
 }

modules/axembassy/src/lib.rs

@@ -206,12 +206,6 @@ pub fn exit(exit_code: i32) -> ! {
     current_run_queue::<NoPreemptIrqSave>().exit_current(exit_code)
 }
 
-/// Park the current task.
-pub fn park_current_task() {
-    let mut cur_rq = current_run_queue::<NoPreemptIrqSave>();
-    cur_rq.park_current_task();
-}
-
 /// The idle task routine.
 ///
 /// It runs an infinite loop that keeps calling [`yield_now()`].

modules/axtask/src/api.rs

@@ -420,20 +420,6 @@ impl<G: BaseGuard> CurrentRunQueueRef<'_, G> {
         self.inner.resched();
     }
 
-    /// Park the current task, and reschedule.
-    pub fn park_current_task(&mut self) {
-        let curr = &self.current_task;
-        assert!(curr.is_running());
-        assert!(!curr.is_idle());
-
-        // Ensure preemption is disabled
-        #[cfg(feature = "preempt")]
-        assert!(curr.can_preempt(1));
-
-        curr.set_state(TaskState::Parked);
-        self.inner.resched();
-    }
-
     #[cfg(feature = "irq")]
     pub fn sleep_until(&mut self, deadline: axhal::time::TimeValue) {
         let curr = &self.current_task;

modules/axtask/src/run_queue.rs

@@ -6,8 +6,6 @@
 pub mod executor {
     use arceos_api::embassy_async as api;
 
-    pub use embassy_executor::{main, task};
-
     pub use api::AxExecutor as Executor;
     pub use embassy_executor::*;
     pub use embassy_futures::*;