ax_task/runtime/
mod.rs

1//! Operating-system capability boundary owned by the scheduler runtime.
2//!
3//! Runtime resources, clock-domain values, and provider operations are split
4//! by owned invariant while retaining one trait-FFI table at the OS boundary.
5
6use crate::runtime::cpu::{IrqGuardToken, PreemptGuardToken};
7
8pub(crate) mod clock;
9mod handle;
10mod interface;
11
12pub use interface::*;
13
14#[derive(Clone, Copy)]
15#[repr(usize)]
16pub(crate) enum PreemptGuardSource {
17    TicketLock,
18    ExplicitScope,
19    SyncContext,
20    SchedulerActivity,
21    IrqReturn,
22}
23
24#[derive(Clone, Copy)]
25#[repr(usize)]
26pub(crate) enum IrqGuardSource {
27    ThreadSchedTicket,
28    DeadlineServerTicket,
29    CpuRunQueueTransactionTicket,
30    CpuRunQueueOwnerCurrentThreadObservationTicket,
31    CpuRunQueueOwnerCurrentCoreObservationTicket,
32    CpuRunQueueOwnerRunnableObservationTicket,
33    CpuRunQueueTimerDeadlineDerivationObservationTicket,
34    CpuRunQueueRtAccountingTicket,
35    CpuRunQueueDeadlineAccountingTicket,
36    CpuRunQueueMembarrierTicket,
37    CpuRunQueueLifecycleTicket,
38    CpuRtBandwidthTicket,
39    #[cfg(feature = "qperf-metrics")]
40    CpuDeadlineObservationTicket,
41    CpuDeadlinePublicationTicket,
42    CpuDeadlineRegistrationTicket,
43    CpuDeadlineHardExpiryTicket,
44    CpuDeadlineSoftExpiryTicket,
45    CpuDeadlineLifecycleTicket,
46    RootRtRuntimeTicket,
47    RootRtPeriodTicket,
48    RootDeadlineIndexTicket,
49    ExplicitScope,
50    RuntimeCpu,
51    Executor,
52}
53
54pub(crate) fn enter_preempt_guard(source: PreemptGuardSource) -> PreemptGuardToken {
55    let token = task_runtime::preempt_guard_enter();
56    #[cfg(feature = "qperf-metrics")]
57    crate::diagnostics::counters::record_runtime_preempt_guard_entry(source, token.is_none());
58    #[cfg(not(feature = "qperf-metrics"))]
59    let _ = source;
60    token
61}
62
63pub(crate) fn enter_irq_guard(source: IrqGuardSource) -> IrqGuardToken {
64    let token = task_runtime::irq_guard_enter();
65    #[cfg(feature = "qperf-metrics")]
66    crate::diagnostics::counters::record_runtime_irq_guard_entry(source, token.is_none());
67    #[cfg(not(feature = "qperf-metrics"))]
68    let _ = source;
69    token
70}
71
72pub use crate::sched::system::TaskSystem;
73
74pub mod cpu;
75
76pub mod resource;
77
78pub mod switch;
79
80pub mod service;
81
82pub mod sync;
83
84pub(crate) mod context;
85
86use crate::runtime::handle::opaque_handle;
87
88opaque_handle!(
89    /// Opaque pointer-sized handle to the runtime-owned task system.
90    TaskSystemHandle,
91    "runtime"
92);
93
94/// Stable runtime operation status used across the trait-ffi boundary.
95#[derive(Clone, Copy, Debug, Eq, PartialEq)]
96#[repr(u32)]
97pub enum RuntimeStatus {
98    /// The operation completed successfully.
99    Success         = 0,
100    /// The runtime capability has not been initialized.
101    NotInitialized  = 1,
102    /// A supplied handle is stale or unknown to the runtime.
103    InvalidHandle   = 2,
104    /// A supplied value violates the runtime contract.
105    InvalidArgument = 3,
106    /// The runtime cannot allocate the requested resource.
107    NoMemory        = 4,
108    /// The runtime does not implement this optional capability.
109    Unsupported     = 5,
110    /// The requested resource is temporarily busy.
111    Busy            = 6,
112    /// A platform operation failed.
113    Platform        = 7,
114    /// The caller holds an IRQ/preemption guard or is otherwise non-sleepable.
115    UnsafeContext   = 8,
116}
117
118/// Result of an operation that creates one opaque runtime resource.
119#[derive(Clone, Copy, Debug, Eq, PartialEq)]
120#[repr(C)]
121pub struct RuntimeHandleResult {
122    /// Completion status.
123    pub status: RuntimeStatus,
124    /// New resource handle when `status` is [`RuntimeStatus::Success`].
125    pub handle: usize,
126}
127
128impl RuntimeHandleResult {
129    /// Creates a successful handle result.
130    pub const fn success(handle: usize) -> Self {
131        Self {
132            status: RuntimeStatus::Success,
133            handle,
134        }
135    }
136
137    /// Creates a failed handle result.
138    pub const fn failure(status: RuntimeStatus) -> Self {
139        Self { status, handle: 0 }
140    }
141}
142
143pub mod config;
144
145pub(crate) mod lock;
146
147pub(crate) mod delivery;
ax_task/runtime/mod.rs

ax_task/runtime/
mod.rs
