ax_std/
os.rs

1//! OS-specific functionality.
2
3/// ArceOS-specific definitions.
4///
5/// `api` re-exports the public ArceOS API surface. Prefer this entry for
6/// ArceOS-specific operations that do not have a std-like wrapper.
7///
8/// `modules` re-exports lower-level ArceOS modules as an escape hatch for
9/// complex systems such as Axvisor. Ordinary applications should prefer
10/// `ax_std::{fs, io, thread, sync, time, net}`.
11pub mod arceos {
12    /// ArceOS public API facade.
13    pub use ax_api as api;
14
15    /// Guards for ArceOS interrupt and preemption contexts.
16    pub mod guard {
17        pub use ax_runtime::task::sync::{IrqSaveGuard, PreemptGuard, PreemptIrqSaveGuard};
18    }
19
20    /// Lower-level ArceOS module facade for system components.
21    #[doc(no_inline)]
22    pub use ax_api::modules;
23    /// ArceOS host driver registry and firmware discovery capabilities.
24    #[doc(no_inline)]
25    pub use ax_driver as driver;
26    /// ArceOS per-CPU storage and CPU-pinning capabilities.
27    #[doc(no_inline)]
28    pub use ax_percpu as percpu;
29
30    /// Non-sleeping synchronization for ArceOS kernel contexts.
31    pub mod sync {
32        pub use ax_runtime::task::sync::*;
33
34        /// A mutex that disables preemption and local interrupts while held.
35        #[repr(transparent)]
36        pub struct IrqSafeMutex<T: ?Sized>(ax_runtime::task::sync::SpinLock<T>);
37
38        impl<T> IrqSafeMutex<T> {
39            /// Creates an unlocked IRQ-safe mutex.
40            #[track_caller]
41            pub const fn new(value: T) -> Self {
42                Self(ax_runtime::task::sync::SpinLock::new(value))
43            }
44
45            /// Acquires the lock after saving and disabling local interrupts.
46            #[track_caller]
47            pub fn lock(&self) -> IrqSafeMutexGuard<'_, T> {
48                self.0.lock_irqsave()
49            }
50
51            /// Attempts to acquire the lock with IRQ-save semantics.
52            #[track_caller]
53            pub fn try_lock(&self) -> Option<IrqSafeMutexGuard<'_, T>> {
54                self.0.try_lock_irqsave()
55            }
56        }
57
58        impl<T: Default> Default for IrqSafeMutex<T> {
59            fn default() -> Self {
60                Self::new(T::default())
61            }
62        }
63
64        impl<T: core::fmt::Debug> core::fmt::Debug for IrqSafeMutex<T> {
65            fn fmt(&self, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
66                self.0.fmt(formatter)
67            }
68        }
69
70        /// A guard returned by [`IrqSafeMutex::lock`].
71        pub type IrqSafeMutexGuard<'a, T> = ax_runtime::task::sync::SpinLockIrqSaveGuard<'a, T>;
72
73        /// A mutex that disables preemption while held.
74        ///
75        /// Callers must ensure the lock is not used by an interrupt handler.
76        pub type NoPreemptMutex<T> = ax_runtime::task::sync::SpinLock<T>;
77        /// A guard returned by [`NoPreemptMutex::lock`].
78        pub type NoPreemptMutexGuard<'a, T> = ax_runtime::task::sync::SpinLockGuard<'a, T>;
79
80        /// A raw spin lock that does not alter interrupt or preemption state.
81        ///
82        /// Callers must disable preemption and local interrupts before taking
83        /// this lock, or prove that interrupt handlers never acquire it.
84        pub type RawSpinLock<T> = ax_runtime::task::sync::SpinLock<T>;
85        /// A guard returned by [`RawSpinLock::lock_raw`].
86        pub type RawSpinLockGuard<'a, T> = ax_runtime::task::sync::RawSpinLockGuard<'a, T>;
87    }
88
89    /// OS-independent task scheduler types and ArceOS runtime operations.
90    pub use ax_runtime::{diagnostics, irq, task, thread};
91}
92
93#[cfg(feature = "std-compat")]
94pub mod libc_compat;
95
96#[cfg(any(feature = "std-compat", all(test, feature = "host-test")))]
97mod futex;
ax_std/os.rs

ax_std/
os.rs
