| # | Module Path | API Name | Type | Full Doc | Safety Doc | Tags | Confirmed |
|---|---|---|---|---|---|---|---|
| 1 | crate::cpu::id | PinCurrentCpu | trait | A marker trait for guard types that can "pin" the current task to the current CPU. Such guard types include [`DisabledLocalIrqGuard`] and [`DisabledPreemptGuard`]. When such guards exist, the CPU executing the current task is pinned. So getting the current CPU ID or CPU-local variables are safe. # Safety The implementor must ensure that the current task is pinned to the current CPU while any one of the instances of the implemented structure exists. [`DisabledLocalIrqGuard`]: crate::irq::DisabledLocalIrqGuard [`DisabledPreemptGuard`]: crate::task::DisabledPreemptGuard | # Safety The implementor must ensure that the current task is pinned to the current CPU while any one of the instances of the implemented structure exists. [`DisabledLocalIrqGuard`]: crate::irq::DisabledLocalIrqGuard [`DisabledPreemptGuard`]: crate::task::DisabledPreemptGuard | CurThread | |
| 2 | crate::cpu::local | AnyStorage | trait | A trait to abstract any type that can be used as a slot for a CPU-local variable of type `T`. Each slot provides the memory space for storing `num_cpus` instances of type `T`. # Safety The implementor must ensure that the returned pointer refers to the variable on the correct CPU. | # Safety The implementor must ensure that the returned pointer refers to the variable on the correct CPU. | CurThread | |
| 3 | crate::mm::frame::meta | AnyFrameMeta | trait | All frame metadata types must implement this trait. If a frame type needs specific drop behavior, it should specify when implementing this trait. When we drop the last handle to this frame, the `on_drop` method will be called. The `on_drop` method is called with the physical address of the frame. The implemented structure should have a size less than or equal to [`FRAME_METADATA_MAX_SIZE`] and an alignment less than or equal to [`FRAME_METADATA_MAX_ALIGN`]. Otherwise, the metadata type cannot be used because storing it will fail compile-time assertions. # Safety If `on_drop` reads the page using the provided `VmReader`, the implementer must ensure that the frame is safe to read. | # Safety If `on_drop` reads the page using the provided `VmReader`, the implementer must ensure that the frame is safe to read. | InBound, ValidRead | |
| 4 | crate::mm::io | from_kernel_space | method | Constructs a `VmReader` from a pointer and a length, which represents a memory range in kernel space. # Safety `ptr` must be [valid] for reads of `len` bytes during the entire lifetime `a`. [valid]: crate::mm::io#safety | # Safety `ptr` must be [valid] for reads of `len` bytes during the entire lifetime `a`. [valid]: crate::mm::io#safety | ||
| 5 | crate::mm::io | from_kernel_space | method | Constructs a `VmWriter` from a pointer and a length, which represents a memory range in kernel space. # Safety `ptr` must be [valid] for writes of `len` bytes during the entire lifetime `a`. [valid]: crate::mm::io#safety | # Safety `ptr` must be [valid] for writes of `len` bytes during the entire lifetime `a`. [valid]: crate::mm::io#safety | ||
| 6 | crate::mm::io | from_user_space | method | Constructs a `VmReader` from a pointer and a length, which represents a memory range in user space. # Safety The virtual address range `ptr..ptr + len` must be in user space. | # Safety The virtual address range `ptr..ptr + len` must be in user space. | UserSpace | |
| 7 | crate::mm::io | from_user_space | method | Constructs a `VmWriter` from a pointer and a length, which represents a memory range in user space. The current context should be consistently associated with valid user space during the entire lifetime `'a`. This is for correct semantics and is not a safety requirement. # Safety `ptr` must be in user space for `len` bytes. | # Safety `ptr` must be in user space for `len` bytes. | Assoc, UserSpace | |
| 8 | crate::sync::rcu::non_null | NonNullPtr | trait | A trait that abstracts non-null pointers. All common smart pointer types such as `Box<T>`, `Arc<T>`, and `Weak<T>` implement this trait as they can be converted to and from the raw pointer type of `*const T`. # Safety This trait must be implemented correctly (according to the doc comments for each method). Types like [`Rcu`] rely on this assumption to safely use the raw pointers. [`Rcu`]: super::Rcu | # Safety This trait must be implemented correctly (according to the doc comments for each method). Types like [`Rcu`] rely on this assumption to safely use the raw pointers. [`Rcu`]: super::Rcu | NonNull | |
| 9 | crate::sync::rcu::non_null | NonNullPtr::from_raw | trait_method | Converts back from a raw pointer. # Safety 1. The raw pointer must have been previously returned by a call to `into_raw`. 2. The raw pointer must not be used after calling `from_raw`. Note that the second point is a hard requirement: Even if the resulting value has not (yet) been dropped, the pointer cannot be used because it may break Rust aliasing rules (e.g., `Box<T>` requires the pointer to be unique and thus _never_ aliased). | # Safety 1. The raw pointer must have been previously returned by a call to `into_raw`. 2. The raw pointer must not be used after calling `from_raw`. Note that the second point is a hard requirement: Even if the resulting value has not (yet) been dropped, the pointer cannot be used because it may break Rust aliasing rules (e.g., `Box<T>` requires the pointer to be unique and thus _never_ aliased). | Alias, NonAccessable, OriginateFrom, Forgotten | |
| 10 | crate::sync::rcu::non_null | NonNullPtr::raw_as_ref | trait_method | Obtains a shared reference to the original pointer. # Safety The original pointer must outlive the lifetime parameter `'a`, and during `'a` no mutable references to the pointer will exist. | # Safety The original pointer must outlive the lifetime parameter `'a`, and during `'a` no mutable references to the pointer will exist. | Alive, NonMutRef | |
| 11 | crate::task::atomic_mode | InAtomicMode | trait | A marker trait for guard types that enforce the atomic mode. Key kernel primitives such as `SpinLock` and `Rcu` rely on [the atomic mode](crate::task::atomic_mode) for correctness or soundness. The existence of such a guard guarantees that the current task is executing in the atomic mode. It requires [`core::fmt::Debug`] by default to make it easier to derive [`Debug`] for types with `&dyn InAtomicMode`. # Safety The implementer must ensure that the atomic mode is maintained while the guard type is alive. | # Safety The implementer must ensure that the atomic mode is maintained while the guard type is alive. | ||
| 12 | crate::util::id_set | Id | trait | A trait to abstract an ID type. # Safety There must be a 1:1 mapping between this ID type and the integers from 0 to `Self::cardinality()` (exclusive). This implies that the implementation must ensure that if one invokes `Into::<u32>::into()` for an `Id` value, then the returned integer always falls within `0..Id::cardinality()`. Furthermore, the implementation must ensure that for any `id_value` of type `MyId: Id`, the following assertion always succeed ```rust assert!(id_value == MyId::new(id_value.into())); ``` There are also constraints on the implementation of `self::cardinality`. For one thing, the cardinality of the ID type must not change, i.e., different calls to `self::cardinality` return the same value. In addition, the value of a cardinality must be greater than zero. | # Safety There must be a 1:1 mapping between this ID type and the integers from 0 to `Self::cardinality()` (exclusive). This implies that the implementation must ensure that if one invokes `Into::<u32>::into()` for an `Id` value, then the returned integer always falls within `0..Id::cardinality()`. Furthermore, the implementation must ensure that for any `id_value` of type `MyId: Id`, the following assertion always succeed ```rust assert!(id_value == MyId::new(id_value.into())); ``` There are also constraints on the implementation of `self::cardinality`. For one thing, the cardinality of the ID type must not change, i.e., different calls to `self::cardinality` return the same value. In addition, the value of a cardinality must be greater than zero. | ValidNum, NonZero | |
| 13 | crate::util::id_set | Id::new_unchecked | trait_method | Creates an ID instance given a raw ID number. # Safety The given number must be less than `Self::cardinality()`. | # Safety The given number must be less than `Self::cardinality()`. | ValidNum |