[−][src]Trait r3::kernel::Kernel

pub trait Kernel: Port + KernelCfg2 + Sized + 'static {
    type DebugPrinter: Debug + Send + Sync;
    pub fn debug() -> Self::DebugPrinter;
    pub fn acquire_cpu_lock() -> Result<(), CpuLockError>;
    pub unsafe fn release_cpu_lock() -> Result<(), CpuLockError>;
    pub fn has_cpu_lock() -> bool;
    pub fn boost_priority() -> Result<(), BoostPriorityError>;
    pub unsafe fn unboost_priority() -> Result<(), BoostPriorityError>;
    pub fn is_priority_boost_active() -> bool;
    pub fn time() -> Result<Time, TimeError>;
    pub fn set_time(time: Time) -> Result<(), TimeError>;
    pub fn adjust_time(delta: Duration) -> Result<(), AdjustTimeError>;
    pub unsafe fn exit_task() -> Result<!, ExitTaskError>;
    pub fn park() -> Result<(), ParkError>;
    pub fn park_timeout(timeout: Duration) -> Result<(), ParkTimeoutError>;
    pub fn sleep(duration: Duration) -> Result<(), SleepError>;
}

Provides access to the global API functions exposed by the kernel.

This trait is automatically implemented on "system" types that have sufficient trait impls to instantiate the kernel.

Associated Types

`type DebugPrinter: Debug + Send + Sync`[src]

Loading content...

Required methods

`pub fn debug() -> Self::DebugPrinter`[src]

Get an object that implements Debug for dumping the current kernel state.

Note that printing this object might consume a large amount of stack space.

`pub fn acquire_cpu_lock() -> Result<(), CpuLockError>`[src]

Activate CPU Lock.

Returns BadContext if CPU Lock is already active.

`pub unsafe fn release_cpu_lock() -> Result<(), CpuLockError>`[src]

Deactivate CPU Lock.

Returns BadContext if CPU Lock is already inactive.

Safety

CPU Lock is useful for creating a critical section. By making this method unsafe, safe code is prevented from interfering with a critical section.

Deactivating CPU Lock in a boot context is disallowed.

`pub fn has_cpu_lock() -> bool`[src]

Return a flag indicating whether CPU Lock is currently active.

`pub fn boost_priority() -> Result<(), BoostPriorityError>`[src]

This is supported on crate feature priority_boost only.

Activate Priority Boost.

Returns BadContext if Priority Boost is already active, the calling context is not a task context, or CPU Lock is active.

`pub unsafe fn unboost_priority() -> Result<(), BoostPriorityError>`[src]

Deactivate Priority Boost.

Returns BadContext if Priority Boost is already inactive, the calling context is not a task context, or CPU Lock is active.

Safety

Priority Boost is useful for creating a critical section. By making this method unsafe, safe code is prevented from interfering with a critical section.

`pub fn is_priority_boost_active() -> bool`[src]

Return a flag indicating whether Priority Boost is currently active.

`pub fn time() -> Result<Time, TimeError>`[src]

This is supported on crate feature system_time only.

Get the current system time.

This method will return TimeError::BadContext when called in a non-task context.

Rationale: This restriction originates from μITRON4.0. It's actually unnecessary in the current implementation, but allows headroom for potential changes in the implementation.

`pub fn set_time(time: Time) -> Result<(), TimeError>`[src]

Set the current system time.

This method does not change the relative arrival times of outstanding timed events nor the relative time of the frontier (a concept used in the definition of adjust_time).

This method will return TimeError::BadContext when called in a non-task context.

Rationale: This restriction originates from μITRON4.0. It's actually unnecessary in the current implementation, but allows headroom for potential changes in the implementation.

`pub fn adjust_time(delta: Duration) -> Result<(), AdjustTimeError>`[src]

Move the current system time forward or backward by the specified amount.

This method changes the relative arrival times of outstanding timed events.

The kernel uses a limited number of bits to represent the arrival times of outstanding timed events. This means that there's some upper bound on how far the system time can be moved away without breaking internal invariants. This method ensures this bound is not violated by the methods described below. This method will return BadObjectState if this check fails.

Moving Forward (delta > 0): If there are no outstanding time events, adjustment in this direction is unbounded. Otherwise, let t be the relative arrival time (in relation to the current time) of the earliest outstanding time event. If t - delta < -TIME_USER_HEADROOM (i.e., if the adjustment would make the event overdue by more than TIME_USER_HEADROOM), the check will fail.

The events made overdue by the call will be processed when the port timer driver announces a new tick. It's unspecified whether this happens before or after the call returns.

Moving Backward (delta < 0): First, we introduce the concept of a frontier. The frontier represents the point of time at which the system time advanced the most. Usually, the frontier is identical to the current system time because the system time keeps moving forward (a). However, adjusting the system time to past makes them temporarily separate from each other (b). In this case, the frontier stays in place until the system time eventually catches up with the frontier and they start moving together again (c).

Let frontier be the current relative time of the frontier (in relation to the current time). If frontier - delta > TIME_USER_HEADROOM (i.e., if the adjustment would move the frontier too far away), the check will fail.

Observation: Even under ideal circumstances, all timed events are bound to be overdue by a very small extent because of various factors such as an intrinsic interrupt latency, insufficient timer resolution, and uses of CPU Lock. This means the minimum value of t in the above explanation is not 0 but a somewhat smaller value. The consequence is that delta can never reliably be >= TIME_USER_HEADROOM.

Relation to Other Specifications: adj_tim from the TOPPERS 3rd generation kernels

Rationale: When moving the system time forward, capping by a frontier instead of an actual latest arrival time has advantages over other schemes that involve tracking the latest arrival time:

Linear-scanning all outstanding timed events to find the latest arrival time would take a linear time.

Using a double-ended data structure for an event queue, such as a balanced search tree and double heaps, would increase the runtime cost of maintaining the structure.

Also, the gap between the current time and the frontier is completely in control of the code that calls adjust_time, making the behavior more predictable.

`pub unsafe fn exit_task() -> Result<!, ExitTaskError>`[src]

Terminate the current task, putting it into the Dormant state.

The kernel (to be precise, the port) makes an implicit call to this function when a task entry point function returns.

Safety

On a successful call, this function destroys the current task's stack without running any destructors on stack-allocated objects and renders all references pointing to such objects invalid. The caller is responsible for taking this possibility into account and ensuring this doesn't lead to an undefined behavior.

`pub fn park() -> Result<(), ParkError>`[src]

Put the current task into the Waiting state until the task's token is made available by Task::unpark. The token is initially absent when the task is activated.

The token will be consumed when this method returns successfully.

This system service may block. Therefore, calling this method is not allowed in a non-waitable context and will return Err(BadContext).