Trait r3::kernel::PortThreading [−][src]
pub unsafe trait PortThreading: KernelCfg1 {
type PortTaskState: Send + Sync + Init + Debug + 'static;
const PORT_TASK_STATE_INIT: Self::PortTaskState;
const STACK_DEFAULT_SIZE: usize;
const STACK_ALIGN: usize;
unsafe fn dispatch_first_task() -> !;
unsafe fn yield_cpu();
unsafe fn exit_and_dispatch(task: &'static TaskCb<Self>) -> !;
unsafe fn enter_cpu_lock();
unsafe fn leave_cpu_lock();
unsafe fn initialize_task_state(task: &'static TaskCb<Self>);
fn is_cpu_lock_active() -> bool;
fn is_task_context() -> bool;
unsafe fn try_enter_cpu_lock() -> bool { ... }
}
Expand description
Implemented by a port. This trait contains items related to low-level operations for controlling CPU states and context switching.
Safety
Implementing a port is inherently unsafe because it’s responsible for initializing the execution environment and providing a dispatcher implementation.
These methods are only meant to be called by the kernel.
Associated Types
Associated Constants
const PORT_TASK_STATE_INIT: Self::PortTaskState
const PORT_TASK_STATE_INIT: Self::PortTaskState
The initial value of TaskCb::port_task_state
for all tasks.
const STACK_DEFAULT_SIZE: usize
const STACK_DEFAULT_SIZE: usize
The default stack size for tasks.
const STACK_ALIGN: usize
const STACK_ALIGN: usize
The alignment requirement for task stack regions.
Both ends of stack regions are aligned by STACK_ALIGN
. It’s
automatically enforced by the kernel configurator for automatically
allocated stack regions (this applies to tasks created without
stack_hunk
). The kernel configurator does not check the alignemnt
for manually-allocated stack regions.
Required methods
unsafe fn dispatch_first_task() -> !
unsafe fn dispatch_first_task() -> !
Transfer the control to the dispatcher, discarding the current
(startup) context. *state.
running_task_ptr
()
is None
at this
point. The dispatcher should call PortToKernel::choose_running_task
to find the next task to run and transfer the control to that task.
Precondition: CPU Lock active, a boot context
Yield the processor.
In a task context, this method immediately transfers the control to
a dispatcher. The dispatcher should call
PortToKernel::choose_running_task
to find the next task to run and
transfer the control to that task.
In an interrupt context, the effect of this method will be deferred until the processor completes the execution of all active interrupt handler threads.
Precondition: CPU Lock inactive
Port Implementation Note: One way to handle the interrupt context case is to set a flag variable and check it in the epilogue of a first-level interrupt handler. Another way is to raise a low-priority interrupt (such as PendSV in Arm-M) and implement dispatching in the handler.
unsafe fn exit_and_dispatch(task: &'static TaskCb<Self>) -> !
unsafe fn exit_and_dispatch(task: &'static TaskCb<Self>) -> !
Destroy the state of the previously running task (task
, which has
already been removed from *state.
running_task_ptr
()
) and proceed
to the dispatcher.
Precondition: CPU Lock active
unsafe fn enter_cpu_lock()
unsafe fn enter_cpu_lock()
Disable all kernel-managed interrupts (this state is called CPU Lock).
Precondition: CPU Lock inactive
unsafe fn leave_cpu_lock()
unsafe fn leave_cpu_lock()
Re-enable kernel-managed interrupts previously disabled by
enter_cpu_lock
, thus deactivating the CPU Lock state.
Precondition: CPU Lock active
unsafe fn initialize_task_state(task: &'static TaskCb<Self>)
unsafe fn initialize_task_state(task: &'static TaskCb<Self>)
Prepare the task for activation. More specifically, set the current
program counter to TaskAttr::entry_point
and the current stack
pointer to either end of TaskAttr::stack
, ensuring the task will
start execution from entry_point
next time the task receives the
control.
Do not call this for a running task. Calling this for a dormant task is
always safe. For tasks in other states, whether this method is safe is
dependent on how the programming language the task code is written in
is implemented. In particular, this is unsafe for Rust task code because
it might violate the requirement of Pin
if there’s a Pin
pointing
to something on the task’s stack.
Precondition: CPU Lock active
fn is_cpu_lock_active() -> bool
fn is_cpu_lock_active() -> bool
Return a flag indicating whether a CPU Lock state is active.
fn is_task_context() -> bool
fn is_task_context() -> bool
Return a flag indicating whether the current context is an task context.
Provided methods
unsafe fn try_enter_cpu_lock() -> bool
unsafe fn try_enter_cpu_lock() -> bool
Activate CPU Lock. Return true
iff CPU Lock was inactive before the
call.