ax-task 0.6.9

ArceOS task management module
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

//! [ArceOS](https://github.com/arceos-org/arceos) task management module.
//!
//! This module provides primitives for task management, including task
//! creation, scheduling, sleeping, termination, etc. The scheduler algorithm
//! is configurable by cargo features.
//!
//! # Cargo Features
//!
//! - `multitask`: Enable multi-task support. If it's enabled, complex task
//!   management and scheduling is used, as well as more task-related APIs.
//!   Otherwise, only a few APIs with naive implementation is available.
//! - `irq`: Interrupts are enabled. If this feature is enabled, timer-based
//!   APIs can be used, such as [`sleep`], [`sleep_until`], and
//!   [`WaitQueue::wait_timeout`].
//! - `preempt`: Enable preemptive scheduling.
//! - FIFO cooperative scheduler is the default when no scheduler feature is
//!   selected.
//! - `sched-rr`: Use the [Round-robin preemptive scheduler][2]. It also enables
//!   the `multitask` and `preempt` features if it is enabled.
//! - `sched-cfs`: Use the [Completely Fair Scheduler][3]. It also enables the
//!   the `multitask` and `preempt` features if it is enabled.
//! - `host-test`: Use host-safe fallbacks for unit tests.
//!
//! [1]: ax_sched::FifoScheduler
//! [2]: ax_sched::RRScheduler
//! [3]: ax_sched::CFScheduler

#![cfg_attr(any(not(test), target_os = "none"), no_std)]
#![cfg_attr(all(test, target_os = "none"), no_main)]
#![cfg_attr(all(test, target_os = "none"), feature(custom_test_frameworks))]
#![cfg_attr(doc, feature(doc_cfg))]
#![cfg_attr(
    all(test, target_os = "none"),
    test_runner(crate::bare_metal_test_runner)
)]

#[cfg(all(feature = "host-test", not(target_os = "none")))]
extern crate std;

/// Native ArceOS synchronization primitives.
pub mod sync;

#[cfg(all(test, target_os = "none"))]
fn bare_metal_test_runner(_tests: &[&dyn Fn()]) {}

#[cfg(all(test, target_os = "none"))]
#[unsafe(no_mangle)]
extern "C" fn _start() -> ! {
    loop {
        core::hint::spin_loop();
    }
}

#[cfg(all(test, target_os = "none"))]
#[panic_handler]
fn panic(_info: &core::panic::PanicInfo<'_>) -> ! {
    loop {
        core::hint::spin_loop();
    }
}

#[cfg(feature = "multitask")]
mod build_info {
    include!(concat!(env!("OUT_DIR"), "/build_info.rs"));
}

cfg_if::cfg_if! {
    if #[cfg(feature = "multitask")] {
        #[macro_use]
        extern crate log;
        extern crate alloc;

        #[macro_use]
        mod run_queue;
        mod interrupt;
        mod task;
        mod api;
        #[doc(hidden)]
        pub mod runtime_preempt;
        #[cfg(feature = "lockdep")]
        mod lockdep;
        #[cfg(feature = "tracepoint-hooks")]
        mod sched_tracepoint;
        #[cfg(feature = "irq")]
        mod irq_notify;
        mod wait_queue;

        #[cfg(feature = "irq")]
        mod timers;

        #[cfg(feature = "multitask")]
        pub mod future;

        #[cfg_attr(doc, doc(cfg(feature = "multitask")))]
        pub use self::api::*;
        #[cfg(feature = "irq")]
        pub use self::irq_notify::IrqNotify;
        pub use self::api::{sleep, sleep_until, yield_now};
        #[cfg(feature = "tracepoint-hooks")]
        pub use self::sched_tracepoint::SchedTracepoint;
        #[cfg(all(feature = "smp", feature = "ipi"))]
        pub use self::run_queue::handle_ipi_reschedule;
    } else {
        mod api_s;
        pub use self::api_s::{sleep, sleep_until, yield_now};
    }
}

/// Runtime checks that require a bound ArceOS CPU-local area.
#[cfg(all(axtest, feature = "multitask"))]
#[doc(hidden)]
pub mod axtest_support {
    /// Checks the live atomic-context query and target stack configuration.
    #[cfg(feature = "axtest")]
    pub fn atomic_context_and_stack_configuration_hold() -> bool {
        super::api::axtask_api_atomic_context_structs_hold_for_test()
    }

    /// Marks the current task for a deterministic preemption safe-point test.
    #[cfg(feature = "preempt")]
    pub fn request_current_preemption() {
        super::api::request_current_preemption_for_test();
    }

    /// Records that the current task consumed its first-entry scheduler frame.
    ///
    /// This hook remains available without the `preempt` feature because the
    /// runtime completes the first-entry scheduler handoff for every multitask
    /// axtest configuration, including non-preemptive workspace consumers.
    pub fn record_initial_scheduler_frame_consumed() {
        super::api::record_initial_scheduler_frame_consumed_for_test();
    }

    /// Reports whether the current task consumed its first-entry scheduler frame.
    pub fn initial_scheduler_frame_consumed() -> bool {
        super::api::initial_scheduler_frame_consumed_for_test()
    }
}