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::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService Class Referencefinal

Concrete implementation of IKernelService exposed to running tasks. More...

#include <stk.h>

Inheritance diagram for stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService:
Collaboration diagram for stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService:

Public Member Functions

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

Static Public Member Functions

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

Static Protected Member Functions

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

Private Member Functions

 KernelService ()
 Construct an uninitialized service instance (m_kernel = null, m_ticks = 0).
 ~KernelService ()=default
 Destructor.
void Initialize (Kernel *kernel)
 Bind this service to its kernel.
void IncrementTicks (Ticks advance)
 Increment counter by value.
Word GetCallerSP () const
 Get caller's Stack Pointer (SP).

Private Attributes

Kernel * m_kernel
 Pointer to the Kernel.
volatile Ticks m_ticks
 Global tick counter. Written via hw::WriteVolatile64() by IncrementTick() (ISR context); read via hw::ReadVolatile64() by GetTicks() (task context) for a lock-free consistent 64-bit read on 32-bit CPUs.

Friends

class Kernel

Detailed Description

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
class stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService

Concrete implementation of IKernelService exposed to running tasks.

Holds the global tick counter (m_ticks, advanced by IncrementTicks() from the tick ISR) and a pointer to the owning Kernel. Tasks access this object via IKernelService::GetInstance().

Definition at line 1032 of file stk.h.

Constructor & Destructor Documentation

◆ KernelService()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::KernelService ( )
inlineexplicitprivate

Construct an uninitialized service instance (m_kernel = null, m_ticks = 0).

Note
Fully initialized by Initialize(). Private; constructed only as a member of Kernel.

Definition at line 1340 of file stk.h.

1340 : m_kernel(nullptr), m_ticks(0)
1341 {}
volatile Ticks m_ticks
Global tick counter. Written via hw::WriteVolatile64() by IncrementTick() (ISR context); read via hw:...
Definition stk.h:1375
Kernel * m_kernel
Pointer to the Kernel.
Definition stk.h:1374

References m_kernel, and m_ticks.

◆ ~KernelService()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::~KernelService ( )
privatedefault

Destructor.

Note
MISRA deviation: [STK-DEV-005] Rule 10-3-2.

References STK_VIRT_DTOR.

Member Function Documentation

◆ Delay()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
void stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::Delay ( Timeout ticks)
inlineoverridevirtual

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.

Implements stk::IKernelService.

Definition at line 1047 of file stk.h.

1048 {
1050 STK_ASSERT(m_kernel->IsStarted());
1051 STK_ASSERT(ticks >= 0);
1052
1053 if (m_kernel->IsStarted())
1054 {
1055 Ticks now = GetTicks();
1056 const Ticks deadline = now + ticks;
1058
1059 for (; now < deadline; now = GetTicks())
1060 {
1062 }
1063 }
1064 }
#define STK_ASSERT(e)
Runtime assertion. Halts execution if the expression e evaluates to false.
Definition stk_defs.h:532
Concrete implementation of IKernel.
Definition stk.h:102
Ticks GetTicks() const override
Get number of ticks elapsed since kernel start.
Definition stk.h:1039

References GetTicks(), stk::hw::IsInsideISR(), m_kernel, and STK_ASSERT.

Here is the call graph for this function:

◆ ExitTask()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
void stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::ExitTask ( )
inlineoverridevirtual

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

Implements stk::IKernelService.

Definition at line 1147 of file stk.h.

1148 {
1150
1152 {
1153 KernelTask *const self = m_kernel->FindTaskBySP(GetCallerSP());
1154 STK_ASSERT(self != nullptr);
1155
1156 // same path as returning from ITask::Run() (exit trap): marks the task sleeping infinitely and
1157 // pending for removal, the kernel removes it on the next tick and calls ITask::OnExit()
1158 m_kernel->OnTaskExitImpl(self);
1159
1160 // switch out and never come back: the task is not scheduled anymore
1161 for (;;)
1162 {
1163 self->BusyWaitWhileSleeping(m_kernel);
1164 }
1165 }
1166 else
1167 {
1168 // kernel operating mode must be KERNEL_DYNAMIC for tasks to be able to exit
1170 }
1171 }
#define __stk_constexpr_cpp17
constexpr definition for C++17 and above.
Definition stk_defs.h:505
void STK_KERNEL_PANIC(stk::EKernelPanicId id)
Called when the kernel detects an unrecoverable internal fault.
Definition stk_arch.h:184
static constexpr bool IsDynamicMode()
Definition stk.h:3368
Word GetCallerSP() const
Get caller's Stack Pointer (SP).
Definition stk.h:1369

References __stk_constexpr_cpp17, stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::BusyWaitWhileSleeping(), GetCallerSP(), stk::Kernel< TMode, TSize, TStrategy, TPlatform >::IsDynamicMode(), stk::hw::IsInsideISR(), stk::KERNEL_PANIC_BAD_MODE, m_kernel, STK_ASSERT, and stk::STK_KERNEL_PANIC().

Here is the call graph for this function:

◆ GetCallerSP()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
Word stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::GetCallerSP ( ) const
inlineprivate

Get caller's Stack Pointer (SP).

Note
Valid for a Thread process only.
Returns
Current value of the Stack Pointer (SP) of the calling process.

Definition at line 1369 of file stk.h.

1370 {
1371 return m_kernel->m_platform.GetCallerSP();
1372 }

References __stk_forceinline, and m_kernel.

Referenced by ExitTask(), Sleep(), SleepUntil(), SwitchToNext(), and Wait().

Here is the caller graph for this function:

◆ GetInstance()

◆ GetMutableWaitList()

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

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()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
Cycles stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::GetSysTimerCount ( ) const
inlineoverridevirtual

Get system timer count value.

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

Implements stk::IKernelService.

Definition at line 1043 of file stk.h.

1043{ return m_kernel->m_platform.GetSysTimerCount(); }

References m_kernel.

◆ GetSysTimerFrequency()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
uint32_t stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::GetSysTimerFrequency ( ) const
inlineoverridevirtual

Get system timer frequency.

Note
ISR-safe.
Returns
Frequency (Hz).

Implements stk::IKernelService.

Definition at line 1045 of file stk.h.

1045{ return m_kernel->m_platform.GetSysTimerFrequency(); }

References m_kernel.

◆ GetTickResolution()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
uint32_t stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::GetTickResolution ( ) const
inlineoverridevirtual

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.

Implements stk::IKernelService.

Definition at line 1041 of file stk.h.

1041{ return m_kernel->m_platform.GetTickResolution(); }

References m_kernel.

◆ GetTicks()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
Ticks stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::GetTicks ( ) const
inlineoverridevirtual

Get number of ticks elapsed since kernel start.

Returns
Ticks.
Note
ISR-safe.

Implements stk::IKernelService.

Definition at line 1039 of file stk.h.

1039{ return hw::ReadVolatile64(&m_ticks); }
T ReadVolatile64(volatile const T *addr)
Atomically read a 64-bit volatile value.
Definition stk_arch.h:332

References m_ticks, and stk::hw::ReadVolatile64().

Referenced by Delay().

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

◆ GetTid()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
TId stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::GetTid ( ) const
inlineoverridevirtual

Get thread Id of the currently running task.

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

Implements stk::IKernelService.

Definition at line 1037 of file stk.h.

1037{ return m_kernel->m_platform.GetTid(); }

References m_kernel.

◆ IncrementTicks()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
void stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::IncrementTicks ( Ticks advance)
inlineprivate

Increment counter by value.

Parameters
[in]advanceNumber of ticks to add to the counter.

Definition at line 1359 of file stk.h.

1360 {
1361 // using WriteVolatile64() to guarantee correct lockless reading order by ReadVolatile64
1363 }
void WriteVolatile64(volatile T *addr, T value)
Atomically write a 64-bit volatile value.
Definition stk_arch.h:397

References m_ticks, and stk::hw::WriteVolatile64().

Here is the call graph for this function:

◆ InheritWeight()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
void stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::InheritWeight ( TId tid,
Weight weight )
inlineoverridevirtual

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.

Implements stk::IKernelService.

Definition at line 1241 of file stk.h.

1242 {
1244 {
1245 m_kernel->OnInheritWeight(tid, weight);
1246 }
1247 }

References __stk_constexpr_cpp17, and m_kernel.

◆ Initialize()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
void stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::Initialize ( Kernel * kernel)
inlineprivate

Bind this service to its kernel.

Parameters
[in]kernelKernel instance.

Definition at line 1351 of file stk.h.

1352 {
1353 m_kernel = kernel;
1354 }

References Kernel, and m_kernel.

Here is the call graph for this function:

◆ LockScheduler()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
ELockResult stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::LockScheduler ( )
inlineoverridevirtual

Disable task switching (CMSIS-RTOS2 osKernelLock equivalent).

Returns
Previous lock state, or LOCK_FAIL / LOCK_FAIL_ISR.
See also
IKernel::SetSchedulerLock

Implements stk::IKernelService.

Definition at line 1310 of file stk.h.

1310{ return m_kernel->SetSchedulerLock(true); }

References m_kernel.

◆ RestoreSchedulerLock()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
ELockResult stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::RestoreSchedulerLock ( bool locked)
inlineoverridevirtual

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

Parameters
[in]lockedtrue to lock, false to unlock.
Returns
New lock state, or LOCK_FAIL / LOCK_FAIL_ISR.
See also
IKernel::SetSchedulerLock

Implements stk::IKernelService.

Definition at line 1323 of file stk.h.

1324 {
1325 ELockResult result = m_kernel->SetSchedulerLock(locked);
1326
1327 // SetSchedulerLock() reports the previous state, RestoreSchedulerLock() reports the new one
1329 {
1331 }
1332
1333 return result;
1334 }

References stk::LOCK_WAS_LOCKED, stk::LOCK_WAS_UNLOCKED, and m_kernel.

◆ RestoreWeight()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
void stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::RestoreWeight ( TId tid,
ISyncObject * sobj )
inlineoverridevirtual

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.

Implements stk::IKernelService.

Definition at line 1249 of file stk.h.

1250 {
1252 {
1253 m_kernel->OnRestoreWeight(tid, sobj);
1254 }
1255 }

References __stk_constexpr_cpp17, and m_kernel.

◆ Resume()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
void stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::Resume ( Timeout elapsed_ticks)
inlineoverridevirtual

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

Implements stk::IKernelService.

Definition at line 1229 of file stk.h.

1230 {
1232 {
1233 return m_kernel->m_platform.Resume(elapsed_ticks);
1234 }
1235 else
1236 {
1237 STK_ASSERT(false);
1238 }
1239 }
static constexpr bool IsTicklessMode()
Definition stk.h:3371

References __stk_constexpr_cpp17, stk::Kernel< TMode, TSize, TStrategy, TPlatform >::IsTicklessMode(), m_kernel, and STK_ASSERT.

Here is the call graph for this function:

◆ SetTimeSlice()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
Timeout stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::SetTimeSlice ( TId tid,
Timeout ticks )
inlineoverridevirtual

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

Implements stk::IKernelService.

Definition at line 1282 of file stk.h.

1283 {
1285
1287 {
1288 // critical section: avoid race with OnTick
1289
1291
1292 result = m_kernel->OnSetTimeSlice(tid, ticks);
1293 }
1294 else
1295 {
1296 STK_UNUSED(tid);
1298 STK_ASSERT(false);
1299
1301 }
1302
1303 return result;
1304 }
#define STK_UNUSED(X)
Explicitly marks a variable as unused to suppress compiler warnings.
Definition stk_defs.h:715
static constexpr bool IsTimesliceMode()
Definition stk.h:3372

References __stk_constexpr_cpp17, stk::Kernel< TMode, TSize, TStrategy, TPlatform >::IsTimesliceMode(), m_kernel, stk::NO_TIME_SLICE, STK_ASSERT, and STK_UNUSED.

Here is the call graph for this function:

◆ SetWeight()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
Weight stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::SetWeight ( TId tid,
Weight weight )
inlineoverridevirtual

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

Implements stk::IKernelService.

Definition at line 1257 of file stk.h.

1258 {
1259 Weight result;
1260
1262 {
1263 // critical section: avoid race with OnTick
1264
1266
1267 result = m_kernel->OnSetWeight(tid, weight);
1268 }
1269 else
1270 {
1271 // strategy must handle OnTaskWeightChange() events
1272 STK_UNUSED(tid);
1274 STK_ASSERT(false);
1275
1276 result = NO_WEIGHT;
1277 }
1278
1279 return result;
1280 }

References __stk_constexpr_cpp17, m_kernel, stk::NO_WEIGHT, STK_ASSERT, and STK_UNUSED.

◆ Sleep()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
bool stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::Sleep ( Timeout ticks)
inlineoverridevirtual

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).

Implements stk::IKernelService.

Definition at line 1066 of file stk.h.

1067 {
1069 STK_ASSERT(m_kernel->IsStarted());
1070 STK_ASSERT(ticks >= 0);
1071
1072 bool result = false;
1073
1075 {
1076 if (!m_kernel->IsLocked())
1077 {
1078 return m_kernel->OnTaskSleep(GetCallerSP(), ticks);
1079 }
1080 else
1081 {
1082 // contract violation: the lock holder must not give up the CPU (no-op in release), see IKernelService::LockScheduler
1083 STK_ASSERT(false);
1084 }
1085 }
1086 else
1087 {
1088 // sleeping is not supported in HRT mode, task will sleep according to its periodicity and workload
1089 STK_ASSERT(false);
1090 }
1091
1092 return result;
1093 }
static constexpr bool IsHrtMode()
Definition stk.h:3369

References __stk_constexpr_cpp17, GetCallerSP(), stk::Kernel< TMode, TSize, TStrategy, TPlatform >::IsHrtMode(), stk::hw::IsInsideISR(), m_kernel, and STK_ASSERT.

Here is the call graph for this function:

◆ SleepCancel()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
void stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::SleepCancel ( TId task_id)
inlineoverridevirtual

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

Implements stk::IKernelService.

Definition at line 1124 of file stk.h.

1125 {
1127 {
1128 m_kernel->CancelTaskWait(GetUserTaskFromTid(task_id));
1129 }
1130 }
ITask * GetUserTaskFromTid(TId task_id) noexcept
Get task instance from its identifier.
Definition stk_arch.h:784

References __stk_constexpr_cpp17, stk::GetUserTaskFromTid(), stk::Kernel< TMode, TSize, TStrategy, TPlatform >::IsHrtMode(), and m_kernel.

Here is the call graph for this function:

◆ SleepUntil()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
bool stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::SleepUntil ( Ticks timestamp)
inlineoverridevirtual

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.

Implements stk::IKernelService.

Definition at line 1095 of file stk.h.

1096 {
1098 STK_ASSERT(m_kernel->IsStarted());
1099 STK_ASSERT(timestamp >= 0);
1100
1101 bool result = false;
1102
1104 {
1105 if (!m_kernel->IsLocked())
1106 {
1107 result = m_kernel->OnTaskSleepUntil(GetCallerSP(), timestamp);
1108 }
1109 else
1110 {
1111 // contract violation, see IKernelService::LockScheduler: no-op in release, reported as "did not sleep"
1112 STK_ASSERT(false);
1113 }
1114 }
1115 else
1116 {
1117 // sleeping is not supported in HRT mode, task will sleep according to its periodicity and workload
1118 STK_ASSERT(false);
1119 }
1120
1121 return result;
1122 }

References __stk_constexpr_cpp17, GetCallerSP(), stk::Kernel< TMode, TSize, TStrategy, TPlatform >::IsHrtMode(), stk::hw::IsInsideISR(), m_kernel, and STK_ASSERT.

Here is the call graph for this function:

◆ Suspend()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
Timeout stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::Suspend ( )
inlineoverridevirtual

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

Implements stk::IKernelService.

Definition at line 1216 of file stk.h.

1217 {
1219 {
1220 return m_kernel->m_platform.Suspend();
1221 }
1222 else
1223 {
1224 STK_ASSERT(false);
1225 return 0;
1226 }
1227 }

References __stk_constexpr_cpp17, stk::Kernel< TMode, TSize, TStrategy, TPlatform >::IsTicklessMode(), m_kernel, and STK_ASSERT.

Here is the call graph for this function:

◆ SwitchToNext()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
void stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::SwitchToNext ( )
inlineoverridevirtual

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.

Implements stk::IKernelService.

Definition at line 1132 of file stk.h.

1133 {
1135
1136 if (!m_kernel->IsLocked())
1137 {
1138 m_kernel->OnTaskSwitch(GetCallerSP());
1139 }
1140 else
1141 {
1142 // contract violation, see IKernelService::LockScheduler: no-op in release
1143 STK_ASSERT(false);
1144 }
1145 }

References GetCallerSP(), stk::hw::IsInsideISR(), m_kernel, and STK_ASSERT.

Here is the call graph for this function:

◆ UnlockScheduler()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
ELockResult stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::UnlockScheduler ( )
inlineoverridevirtual

Enable task switching (CMSIS-RTOS2 osKernelUnlock equivalent).

Returns
Previous lock state, or LOCK_FAIL / LOCK_FAIL_ISR.
See also
IKernel::SetSchedulerLock

Implements stk::IKernelService.

Definition at line 1316 of file stk.h.

1316{ return m_kernel->SetSchedulerLock(false); }

References m_kernel.

◆ Wait()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
EWaitResult stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::Wait ( ISyncObject * sobj,
IMutex * mutex,
Timeout timeout )
inlineoverridevirtual

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.

Implements stk::IKernelService.

Definition at line 1173 of file stk.h.

1174 {
1176
1178 {
1179 if (!m_kernel->IsLocked())
1180 {
1181 result = m_kernel->OnTaskWait(GetCallerSP(), sobj, mutex, ticks);
1182 }
1183 else
1184 {
1185 // contract violation, see IKernelService::LockScheduler: blocking would never be woken, result stays WAIT_RESULT_FAIL in release
1186 STK_ASSERT(false);
1187 }
1188 }
1189 else
1190 {
1191 STK_ASSERT(false);
1192 }
1193
1194 return result;
1195 }
static constexpr bool IsSyncMode()
Definition stk.h:3370

References __stk_constexpr_cpp17, GetCallerSP(), stk::Kernel< TMode, TSize, TStrategy, TPlatform >::IsSyncMode(), m_kernel, STK_ASSERT, and stk::WAIT_RESULT_FAIL.

Here is the call graph for this function:

◆ Wake()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
void stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::Wake ( ISyncObject * sobj,
bool all )
inlineoverridevirtual

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.

Implements stk::IKernelService.

Definition at line 1197 of file stk.h.

1198 {
1200 {
1201 if (all)
1202 {
1204 }
1205 else
1206 {
1208 }
1209 }
1210 else
1211 {
1212 STK_ASSERT(false);
1213 }
1214 }
virtual void WakeAll()=0
Wake all tasks currently in the wait list.
virtual void WakeOne()=0
Wake the first task in the wait list (FIFO order).
static IWaitObject::ListHeadType & GetMutableWaitList(ISyncObject *sobj)
Access helper to the mutable IWaitObject::GetWaitList().

References __stk_constexpr_cpp17, stk::IKernelService::GetMutableWaitList(), stk::Kernel< TMode, TSize, TStrategy, TPlatform >::IsSyncMode(), STK_ASSERT, stk::ISyncObject::WakeAll(), and stk::ISyncObject::WakeOne().

Here is the call graph for this function:

◆ Kernel

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
friend class Kernel
friend

Definition at line 1034 of file stk.h.

References Kernel.

Referenced by Initialize(), and Kernel.

Member Data Documentation

◆ m_kernel

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
Kernel* stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::m_kernel
private

◆ m_ticks

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
volatile Ticks stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::m_ticks
private

Global tick counter. Written via hw::WriteVolatile64() by IncrementTick() (ISR context); read via hw::ReadVolatile64() by GetTicks() (task context) for a lock-free consistent 64-bit read on 32-bit CPUs.

Definition at line 1375 of file stk.h.

Referenced by GetTicks(), IncrementTicks(), and KernelService().


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