ax_task/
lib.rs

1//! [ArceOS](https://github.com/arceos-org/arceos) task management module.
2//!
3//! This module provides primitives for task management, including task
4//! creation, scheduling, sleeping, termination, etc. The scheduler algorithm
5//! is configurable by cargo features.
6//!
7//! # Cargo Features
8//!
9//! - `multitask`: Enable multi-task support. If it's enabled, complex task
10//!   management and scheduling is used, as well as more task-related APIs.
11//!   Otherwise, only a few APIs with naive implementation is available.
12//! - `irq`: Interrupts are enabled. If this feature is enabled, timer-based
13//!   APIs can be used, such as [`sleep`], [`sleep_until`], and
14//!   [`WaitQueue::wait_timeout`].
15//! - `preempt`: Enable preemptive scheduling.
16//! - FIFO cooperative scheduler is the default when no scheduler feature is
17//!   selected.
18//! - `sched-rr`: Use the [Round-robin preemptive scheduler][2]. It also enables
19//!   the `multitask` and `preempt` features if it is enabled.
20//! - `sched-cfs`: Use the [Completely Fair Scheduler][3]. It also enables the
21//!   the `multitask` and `preempt` features if it is enabled.
22//! - `host-test`: Use host-safe fallbacks for unit tests.
23//!
24//! [1]: ax_sched::FifoScheduler
25//! [2]: ax_sched::RRScheduler
26//! [3]: ax_sched::CFScheduler
27
28#![cfg_attr(any(not(test), target_os = "none"), no_std)]
29#![cfg_attr(all(test, target_os = "none"), no_main)]
30#![cfg_attr(all(test, target_os = "none"), feature(custom_test_frameworks))]
31#![cfg_attr(doc, feature(doc_cfg))]
32#![cfg_attr(
33    all(test, target_os = "none"),
34    test_runner(crate::bare_metal_test_runner)
35)]
36
37#[cfg(all(feature = "host-test", not(target_os = "none")))]
38extern crate std;
39
40/// Native ArceOS synchronization primitives.
41pub mod sync;
42
43#[cfg(all(test, target_os = "none"))]
44fn bare_metal_test_runner(_tests: &[&dyn Fn()]) {}
45
46#[cfg(all(test, target_os = "none"))]
47#[unsafe(no_mangle)]
48extern "C" fn _start() -> ! {
49    loop {
50        core::hint::spin_loop();
51    }
52}
53
54#[cfg(all(test, target_os = "none"))]
55#[panic_handler]
56fn panic(_info: &core::panic::PanicInfo<'_>) -> ! {
57    loop {
58        core::hint::spin_loop();
59    }
60}
61
62#[cfg(feature = "multitask")]
63mod build_info {
64    include!(concat!(env!("OUT_DIR"), "/build_info.rs"));
65}
66
67cfg_if::cfg_if! {
68    if #[cfg(feature = "multitask")] {
69        #[macro_use]
70        extern crate log;
71        extern crate alloc;
72
73        #[macro_use]
74        mod run_queue;
75        mod interrupt;
76        mod task;
77        mod api;
78        #[doc(hidden)]
79        pub mod runtime_preempt;
80        #[cfg(feature = "lockdep")]
81        mod lockdep;
82        #[cfg(feature = "tracepoint-hooks")]
83        mod sched_tracepoint;
84        #[cfg(feature = "irq")]
85        mod irq_notify;
86        mod wait_queue;
87
88        #[cfg(feature = "irq")]
89        mod timers;
90
91        #[cfg(feature = "multitask")]
92        pub mod future;
93
94        #[cfg_attr(doc, doc(cfg(feature = "multitask")))]
95        pub use self::api::*;
96        #[cfg(feature = "irq")]
97        pub use self::irq_notify::IrqNotify;
98        pub use self::api::{sleep, sleep_until, yield_now};
99        #[cfg(feature = "tracepoint-hooks")]
100        pub use self::sched_tracepoint::SchedTracepoint;
101        #[cfg(all(feature = "smp", feature = "ipi"))]
102        pub use self::run_queue::handle_ipi_reschedule;
103    } else {
104        mod api_s;
105        pub use self::api_s::{sleep, sleep_until, yield_now};
106    }
107}
108
109/// Runtime checks that require a bound ArceOS CPU-local area.
110#[cfg(all(axtest, feature = "multitask"))]
111#[doc(hidden)]
112pub mod axtest_support {
113    /// Checks the live atomic-context query and target stack configuration.
114    #[cfg(feature = "axtest")]
115    pub fn atomic_context_and_stack_configuration_hold() -> bool {
116        super::api::axtask_api_atomic_context_structs_hold_for_test()
117    }
118
119    /// Marks the current task for a deterministic preemption safe-point test.
120    #[cfg(feature = "preempt")]
121    pub fn request_current_preemption() {
122        super::api::request_current_preemption_for_test();
123    }
124
125    /// Records that the current task consumed its first-entry scheduler frame.
126    ///
127    /// This hook remains available without the `preempt` feature because the
128    /// runtime completes the first-entry scheduler handoff for every multitask
129    /// axtest configuration, including non-preemptive workspace consumers.
130    pub fn record_initial_scheduler_frame_consumed() {
131        super::api::record_initial_scheduler_frame_consumed_for_test();
132    }
133
134    /// Reports whether the current task consumed its first-entry scheduler frame.
135    pub fn initial_scheduler_frame_consumed() -> bool {
136        super::api::initial_scheduler_frame_consumed_for_test()
137    }
138}
ax_task/lib.rs

ax_task/
lib.rs
