SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
Loading...
Searching...
No Matches
stk::IKernelService Class Referenceabstract

Interface for the kernel services exposed to the user processes during run-time when Kernel started scheduling the processes. More...

#include <stk_common.h>

Inheritance diagram for stk::IKernelService:
Collaboration diagram for stk::IKernelService:

Classes

class  ScopedSchedulerLock
 Disable task switching (equivalent of CMSIS-RTOS2 osKernelLock). Ticks, timeouts and ISRs keep running. Ensures the lock is always unlocked when leaving the scope, even when exceptions are thrown. More...

Public Member Functions

virtual TId GetTid () const =0
 Get thread Id of the currently running task.
virtual Ticks GetTicks () const =0
 Get number of ticks elapsed since kernel start.
virtual uint32_t GetTickResolution () const =0
 Get number of microseconds in one tick.
virtual Cycles GetSysTimerCount () const =0
 Get system timer count value.
virtual uint32_t GetSysTimerFrequency () const =0
 Get system timer frequency.
virtual void Delay (Timeout ticks)=0
 Delay calling process.
virtual bool Sleep (Timeout ticks)=0
 Put calling process into a sleep state.
virtual bool SleepUntil (Ticks timestamp)=0
 Put calling process into a sleep state until the specified timestamp.
virtual void SleepCancel (TId task_id)=0
 Cancel sleep of the task.
virtual void SwitchToNext ()=0
 Notify scheduler to switch to the next task (yield).
virtual void ExitTask ()=0
 Terminate the calling task: schedule its removal and switch it out. Does not return.
virtual EWaitResult Wait (ISyncObject *sobj, IMutex *mutex, Timeout timeout)=0
 Put calling process into a waiting state until synchronization object is signaled or timeout occurs.
virtual void Wake (ISyncObject *sobj, bool all)=0
 Wake one or all tasks currently waiting on a synchronization object.
virtual Timeout Suspend ()=0
 Suspend scheduling.
virtual void Resume (Timeout elapsed_ticks)=0
 Resume scheduling after a prior Suspend() call.
virtual void InheritWeight (TId tid, Weight weight)=0
 Inherit weight for the task.
virtual void RestoreWeight (TId tid, ISyncObject *sobj=nullptr)=0
 Restore weight of the task to the original value.
virtual Weight SetWeight (TId tid, Weight weight)=0
 Change the base weight of the task at run-time (replaces ITask::GetWeight() value).
virtual Timeout SetTimeSlice (TId tid, Timeout ticks)=0
 Change the time-slice quantum of the task at run-time and reload its slice.
virtual ELockResult LockScheduler ()=0
 Disable task switching (equivalent of CMSIS-RTOS2 osKernelLock). Ticks, timeouts and ISRs keep running.
virtual ELockResult UnlockScheduler ()=0
 Enable task switching (equivalent of CMSIS-RTOS2 osKernelUnlock).
virtual ELockResult RestoreSchedulerLock (bool locked)=0
 Set the lock state (equivalent of CMSIS-RTOS2 osKernelRestoreLock).

Static Public Member Functions

static IKernelService * GetInstance ()
 Get CPU-local instance of the kernel service.

Protected Member Functions

 ~IKernelService ()=default
 Destructor.

Static Protected Member Functions

static IWaitObject::ListHeadType & GetMutableWaitList (ISyncObject *sobj)
 Access helper to the mutable IWaitObject::GetWaitList().

Detailed Description

Interface for the kernel services exposed to the user processes during run-time when Kernel started scheduling the processes.

Note
State design pattern: this interface represents the kernel's active running state. It becomes valid only after IKernel::Start() is called. Before that point the kernel is in an idle/unstarted state and this interface must not be used. Obtain the CPU-local instance via IKernelService::GetInstance().
Examples
low_power/example.cpp.

Definition at line 1812 of file stk_common.h.

Constructor & Destructor Documentation

◆ ~IKernelService()

stk::IKernelService::~IKernelService ( )
protecteddefault

Destructor.

Note
Protected by design. Prevents unsafe polymorphic delete.

Member Function Documentation

◆ Delay()

virtual void stk::IKernelService::Delay ( Timeout ticks)
pure virtual

Delay calling process.

Note
Unlike Sleep this function delays code execution by spinning in a loop until deadline expiry.
Use with care in HRT mode to avoid missed deadline (see stk::KERNEL_HRT, ITask::OnDeadlineMissed).
Parameters
[in]ticksDelay time (ticks).
Warning
ISR-unsafe. Calling from an ISR context is not permitted and will trigger an assertion.

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::Delay().

Here is the caller graph for this function:

◆ ExitTask()

virtual void stk::IKernelService::ExitTask ( )
pure virtual

Terminate the calling task: schedule its removal and switch it out. Does not return.

Note
Equivalent to returning from ITask::Run(): the kernel completes the removal on the next tick, calls ITask::OnExit() and releases the kernel slot. Use it to end a task from a nested call, without unwinding (C++ destructors of the task's local objects are NOT run).
The task, its stack and the kernel slot are no longer referenced by the kernel once ITask::OnExit() has been called, see ITask::OnExit() for re-adding the task.
Warning
KERNEL_DYNAMIC mode only: panics with KERNEL_PANIC_BAD_MODE otherwise.
ISR-unsafe. Calling from an ISR context is not permitted and will trigger an assertion.
Should not be called while the scheduler is locked (see LockScheduler): asserts in debug builds. The exit can not be refused, in release builds the task exits and the lock is released.
See also
IKernel::ScheduleTaskRemoval, ITask::OnExit

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::ExitTask().

Here is the caller graph for this function:

◆ GetInstance()

◆ GetMutableWaitList()

IWaitObject::ListHeadType & stk::IKernelService::GetMutableWaitList ( ISyncObject * sobj)
inlinestaticprotected

Access helper to the mutable IWaitObject::GetWaitList().

Definition at line 2091 of file stk_common.h.

2092 {
2093 return sobj->GetMutableWaitList();
2094 }

References __stk_forceinline, and stk::ISyncObject::GetMutableWaitList().

Referenced by stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::Wake().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ GetSysTimerCount()

virtual Cycles stk::IKernelService::GetSysTimerCount ( ) const
pure virtual

Get system timer count value.

Note
ISR-safe.
Returns
64-bit count value.

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::GetSysTimerCount().

Here is the caller graph for this function:

◆ GetSysTimerFrequency()

virtual uint32_t stk::IKernelService::GetSysTimerFrequency ( ) const
pure virtual

Get system timer frequency.

Note
ISR-safe.
Returns
Frequency (Hz).

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::GetSysTimerFrequency().

Here is the caller graph for this function:

◆ GetTickResolution()

virtual uint32_t stk::IKernelService::GetTickResolution ( ) const
pure virtual

Get number of microseconds in one tick.

Note
Tick is a periodicity of the system timer expressed in microseconds.
ISR-safe.
Returns
Microseconds in one tick.

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::GetTickResolution(), and stk::GetTimeNowMs().

Here is the caller graph for this function:

◆ GetTicks()

virtual Ticks stk::IKernelService::GetTicks ( ) const
pure virtual

Get number of ticks elapsed since kernel start.

Returns
Ticks.
Note
ISR-safe.

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::GetTicks(), and stk::GetTimeNowMs().

Here is the caller graph for this function:

◆ GetTid()

virtual TId stk::IKernelService::GetTid ( ) const
pure virtual

Get thread Id of the currently running task.

Returns
Thread Id.
Warning
ISR-safe.
See also
TID_ISR_N, TID_NONE, IsIsrTid

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::GetTid(), stk::sync::FastMutex::TimedLockEx(), and stk::sync::Mutex::TimedLockEx().

Here is the caller graph for this function:

◆ InheritWeight()

virtual void stk::IKernelService::InheritWeight ( TId tid,
Weight weight )
pure virtual

Inherit weight for the task.

Parameters
[in]tidTask id.
[in]weightNew weight, shall be higher than task's current weight (see ITask::GetWeight).
Note
ISR-safe.

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::sync::FastMutex::TimedLockEx(), stk::sync::Mutex::TimedLockEx(), stk::sync::FastMutex::Unlock(), and stk::sync::Mutex::Unlock().

Here is the caller graph for this function:

◆ LockScheduler()

virtual ELockResult stk::IKernelService::LockScheduler ( )
pure virtual

Disable task switching (equivalent of CMSIS-RTOS2 osKernelLock). Ticks, timeouts and ISRs keep running.

Returns
Previous lock state (LOCK_WAS_UNLOCKED / LOCK_WAS_LOCKED), or LOCK_FAIL / LOCK_FAIL_ISR.
Note
Not nested: pass the returned value to RestoreSchedulerLock() to emulate nesting.
Task context only. Not available in KERNEL_HRT mode (LOCK_FAIL).
While locked the kernel state is KSTATE_LOCKED.
Warning
The lock holder must keep the CPU. While locked, Sleep(), SleepUntil(), Yield(), IKernelService::Wait() and SuspendTask() of the calling task must not be called: they assert in debug builds. In release builds they are no-ops (SleepUntil() returns false, Wait() returns WAIT_RESULT_FAIL, SuspendTask() returns SUSPEND_FAIL). Delay() is allowed. Suspending another task is allowed.
Blocking on a synchronization object that is owned by another task would never complete, because no other task can run while locked. A synchronization object which is free can be used.
Synchronization primitives (stk::sync): only non-blocking use is valid while locked, i.e. calls with NO_WAIT / Try*() variants and acquisitions which succeed immediately (free Mutex, signaled Event, available Semaphore token, ...). A call which would have to block asserts in debug builds; in release builds the timed / bool / EWaitResult variants fail with WAIT_RESULT_FAIL, while the void Lock() / ReadLock() of Mutex, FastMutex and RWMutex can not report a failure and panic (KERNEL_PANIC_ASSERT) instead of no-op, because a contended lock under a scheduler lock is a deadlock.
Note
Exiting (IKernelService::ExitTask() or returning from ITask::Run()) can not be refused: it asserts in debug builds, in release builds the task exits and the lock is released when it leaves the CPU, so the lock never passes on to another task.
Time-slice accounting (KERNEL_TIMESLICE) continues while locked, rotation of an expired slice is deferred until the lock is released.
Entering tickless suspend (IKernelService::Suspend()) drops the lock, the kernel state becomes KSTATE_SUSPENDED.
See also
UnlockScheduler, RestoreSchedulerLock, IKernel::SetSchedulerLock

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::LockScheduler(), and stk::IKernelService::ScopedSchedulerLock::ScopedSchedulerLock().

Here is the caller graph for this function:

◆ RestoreSchedulerLock()

virtual ELockResult stk::IKernelService::RestoreSchedulerLock ( bool locked)
pure virtual

Set the lock state (equivalent of CMSIS-RTOS2 osKernelRestoreLock).

Parameters
[in]lockedtrue to lock, false to unlock.
Returns
New lock state (LOCK_WAS_LOCKED if now locked, LOCK_WAS_UNLOCKED if now unlocked), or LOCK_FAIL / LOCK_FAIL_ISR.
Note
Unlike LockScheduler() and UnlockScheduler() it reports the NEW state, not the previous one.
Use with the value returned by LockScheduler() to emulate nesting.
Task context only. Not available in KERNEL_HRT mode (LOCK_FAIL).
See also
LockScheduler, UnlockScheduler, IKernel::SetSchedulerLock

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::RestoreSchedulerLock(), and stk::IKernelService::ScopedSchedulerLock::~ScopedSchedulerLock().

Here is the caller graph for this function:

◆ RestoreWeight()

virtual void stk::IKernelService::RestoreWeight ( TId tid,
ISyncObject * sobj = nullptr )
pure virtual

Restore weight of the task to the original value.

Parameters
[in]tidTask id.
[in]sobjOptional, if provided than weight will be restored to the highest weight of the task in the wait list, otherwise to the original value.
Note
ISR-safe.

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::sync::FastMutex::TimedLockEx(), stk::sync::Mutex::TimedLockEx(), stk::sync::FastMutex::Unlock(), and stk::sync::Mutex::Unlock().

Here is the caller graph for this function:

◆ Resume()

virtual void stk::IKernelService::Resume ( Timeout elapsed_ticks)
pure virtual

Resume scheduling after a prior Suspend() call.

Parameters
[in]elapsed_ticksNumber of ticks that elapsed during the suspended period. The kernel uses this value to advance internal time counters and wake tasks whose sleep deadlines have expired.
Note
When resuming, the timer will start with a current CPU frequency, therefore you can change CPU frequency after Suspend() and restart scheduler with a new frequency with Resume().
ISR-safe.
Warning
Requires the kernel to be instantiated with stk::KERNEL_TICKLESS; asserts otherwise.
See also
IKernel::EKernelState::KSTATE_SUSPENDED

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Examples
low_power/example.cpp.

Referenced by EXTI0_IRQHandler(), LowPowerOverrider::OnSleep(), and osKernelResume().

Here is the caller graph for this function:

◆ SetTimeSlice()

virtual Timeout stk::IKernelService::SetTimeSlice ( TId tid,
Timeout ticks )
pure virtual

Change the time-slice quantum of the task at run-time and reload its slice.

Parameters
[in]tidTask id.
[in]ticksNew quantum (ticks), NO_TIME_SLICE disables time-slicing for the task.
Returns
Previous quantum (can be passed back to restore it).
Note
Requires KERNEL_TIMESLICE, asserts otherwise.
Enters the critical section internally; may be called from task context.
See also
ITask::GetTimeSlice, stk::KERNEL_TIMESLICE

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::SetTimeSlice().

Here is the caller graph for this function:

◆ SetWeight()

virtual Weight stk::IKernelService::SetWeight ( TId tid,
Weight weight )
pure virtual

Change the base weight of the task at run-time (replaces ITask::GetWeight() value).

Parameters
[in]tidTask id.
[in]weightNew base weight. Must not be NO_WEIGHT; must satisfy the constraints of the active strategy (see e.g. SwitchStrategyPreemptionThreshold::MakeWeight).
Returns
Previous base weight (can be passed back to restore it).
Note
Requires a strategy with WEIGHT_API = 1 and PRIORITY_INHERITANCE_API = 1 (the strategy must handle OnTaskWeightChange()); asserts otherwise.
If the task currently inherits a higher weight the new base weight takes effect once the inheritance ends, unless it is higher than the inherited weight.
Enters the critical section internally; may be called from task context.
See also
SwitchStrategyPreemptionThreshold::ChangeThreshold

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::sched::SwitchStrategyPreemptionThreshold< 32 >::ChangeThreshold(), and stk::SetWeight().

Here is the caller graph for this function:

◆ Sleep()

virtual bool stk::IKernelService::Sleep ( Timeout ticks)
pure virtual

Put calling process into a sleep state.

Note
Unlike Delay this function does not waste CPU cycles and allows kernel to put CPU into a low-power state.
Unsupported in HRT mode (see stk::KERNEL_HRT); in HRT mode tasks sleep automatically according to their periodicity and workload.
Parameters
[in]ticksSleep time (ticks).
Warning
ISR-unsafe. Calling from an ISR context is not permitted and will trigger an assertion.
Must not be called while the scheduler is locked (see LockScheduler): asserts in debug builds, no-op in release builds.
Returns
True if the task slept, false otherwise (ticks is 0, HRT mode, or scheduler locked).

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::Sleep().

Here is the caller graph for this function:

◆ SleepCancel()

virtual void stk::IKernelService::SleepCancel ( TId task_id)
pure virtual

Cancel sleep of the task.

Parameters
[in]task_idId of the task.

Ends a sleep started by Sleep()/SleepUntil() early. If the task is instead blocked on a synchronization object (KERNEL_SYNC mode), the wait is cancelled the same way as IKernel::CancelTaskWait() does: the task is removed from the object's wait list and its Wait() returns WAIT_RESULT_CANCELED (not WAIT_RESULT_TIMEOUT or WAIT_RESULT_SIGNAL, no resource is acquired or consumed).

Note
No-op if task was neither sleeping nor waiting on a synchronization object, or is suspended.
ISR-safe.
See also
IKernel::CancelTaskWait, EWaitResult

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::SleepCancel().

Here is the caller graph for this function:

◆ SleepUntil()

virtual bool stk::IKernelService::SleepUntil ( Ticks timestamp)
pure virtual

Put calling process into a sleep state until the specified timestamp.

Note
Unlike Delay this function does not waste CPU cycles and allows kernel to put CPU into a low-power state.
Unsupported in HRT mode (see stk::KERNEL_HRT); in HRT mode tasks sleep automatically according to their periodicity and workload.
Parameters
[in]timestampAbsolute timestamp (ticks).
Warning
ISR-unsafe. Calling from an ISR context is not permitted and will trigger an assertion.
Must not be called while the scheduler is locked (see LockScheduler): asserts in debug builds, no-op in release builds (returns false).
Returns
True if sleep succeeded, false otherwise.

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::SleepUntil().

Here is the caller graph for this function:

◆ Suspend()

virtual Timeout stk::IKernelService::Suspend ( )
pure virtual

Suspend scheduling.

Returns
Number of ticks available for the suspension period, as determined by the nearest pending wake-up. The caller may program a hardware timer with this value to avoid unnecessary wakeups (tickless idle).
Note
After suspending the scheduler you can change the CPU frequency and then resume scheduling by calling Resume().
ISR-safe. Pair with Resume().
Warning
Requires the kernel to be instantiated with stk::KERNEL_TICKLESS; asserts otherwise.
See also
IKernel::EKernelState::KSTATE_SUSPENDED

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Examples
low_power/example.cpp.

Referenced by EXTI0_IRQHandler(), LowPowerOverrider::OnSleep(), and osKernelSuspend().

Here is the caller graph for this function:

◆ SwitchToNext()

virtual void stk::IKernelService::SwitchToNext ( )
pure virtual

Notify scheduler to switch to the next task (yield).

Note
In HRT mode (see stk::KERNEL_HRT) it signals completion of the current job. In other modes the strategy may keep the task runnable (NOSLEEP_YIELD_API), otherwise the task sleeps for one tick, see stk::Yield().
Warning
ISR-unsafe.
Must not be called while the scheduler is locked (see LockScheduler): asserts in debug builds, no-op in release builds.

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::Yield().

Here is the caller graph for this function:

◆ UnlockScheduler()

virtual ELockResult stk::IKernelService::UnlockScheduler ( )
pure virtual

Enable task switching (equivalent of CMSIS-RTOS2 osKernelUnlock).

Returns
Previous lock state (LOCK_WAS_UNLOCKED / LOCK_WAS_LOCKED), or LOCK_FAIL / LOCK_FAIL_ISR.
Note
A ready task is switched in on the next tick (not immediately).
Task context only. Not available in KERNEL_HRT mode (LOCK_FAIL).
See also
LockScheduler, RestoreSchedulerLock, IKernel::SetSchedulerLock

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::UnlockScheduler().

Here is the caller graph for this function:

◆ Wait()

virtual EWaitResult stk::IKernelService::Wait ( ISyncObject * sobj,
IMutex * mutex,
Timeout timeout )
pure virtual

Put calling process into a waiting state until synchronization object is signaled or timeout occurs.

Note
This function implements core blocking logic using the Monitor pattern to ensure atomicity between state check and suspension.
The kernel automatically unlocks the provided mutex before the task is suspended and re-locks it before this function returns.
Parameters
[in]sobjSynchronization object to wait on.
[in]mutexMutex protecting the state of the synchronization object.
[in]timeoutMaximum wait time (ticks). Use WAIT_INFINITE to block indefinitely, use NO_WAIT to poll without blocking.
Returns
Wait result (see EWaitResult).
Warning
ISR-unsafe.
Must not be called while the scheduler is locked (see LockScheduler), whatever the timeout: asserts in debug builds, in release builds returns WAIT_RESULT_FAIL without waiting.

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::sync::FastMutex::TimedLockEx(), stk::sync::Mutex::TimedLockEx(), stk::sync::ConditionVariable::WaitEx(), stk::sync::Event::WaitEx(), and stk::sync::SemaphoreT< T >::WaitEx().

Here is the caller graph for this function:

◆ Wake()

virtual void stk::IKernelService::Wake ( ISyncObject * sobj,
bool all )
pure virtual

Wake one or all tasks currently waiting on a synchronization object.

Parameters
[in]sobjSynchronization object whose waiting queue will be notified.
[in]allIf true, unblocks all waiting tasks (broadcast mode); if false, unblocks only the next waiting task (signal mode).
See also
Wait
Warning
ISR-unsafe.

Implemented in stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService.

Referenced by stk::SyncObjectBase::WakeAll(), and stk::SyncObjectBase::WakeOne().

Here is the caller graph for this function:

The documentation for this class was generated from the following file: