stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService Class Reference

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

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

Static Protected Member Functions
static IWaitObject::ListHeadType &	GetWaitList (ISyncObject *sobj)
	IWaitObject::GetWaitList() access helper.

Private Member Functions
	KernelService ()
	Construct an uninitialized service instance (m_platform = null, m_ticks = 0).
	~KernelService ()=default
	Destructor.
void	Initialize (Kernel *kernel)
	Initialize instance.
void	IncrementTicks (Ticks advance)
	Increment counter by value.

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, updated atomically by IncrementTick() each SysTick) and a typed pointer to the platform driver. Tasks access this object via IKernelService::GetInstance() which returns the singleton registered at Initialize().

Definition at line 799 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_platform = null, m_ticks = 0).

Note

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

Definition at line 953 of file stk.h.

                                 : m_kernel(nullptr), m_ticks(0)
        {}

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]

ticks

Delay time (ticks).

Warning

ISR-unsafe. Calling from an ISR context is not permitted and will trigger an assertion.

See also

Delay

Implements stk::IKernelService.

Definition at line 814 of file stk.h.

        {
            STK_ASSERT(!hw::IsInsideISR());
            STK_ASSERT(ticks >= 0);
 
            Ticks now = GetTicks();
            const Ticks deadline = now + ticks;
            STK_ASSERT(deadline >= now);
 
            for (; now < deadline; now = GetTicks())
            {
                __stk_relax_cpu();
            }
        }

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

Here is the call graph for this function:

GetInstance()

IKernelService * stk::IKernelService::GetInstance ( )

staticinherited

Get CPU-local instance of the kernel service.

Referenced by stk::Delay(), stk::GetSysTimerCount(), stk::GetSysTimerFrequency(), stk::GetTickResolution(), stk::GetTicks(), stk::GetTid(), stk::GetTimeNowMs(), osKernelResume(), osKernelSuspend(), stk::Sleep(), stk::SleepCancel(), stk::SleepUntil(), stk::sync::Mutex::TimedLock(), stk::sync::Mutex::Unlock(), stk::sync::ConditionVariable::Wait(), stk::sync::Event::Wait(), stk::sync::Semaphore::Wait(), stk::SyncObjectBase::WakeAll(), stk::SyncObjectBase::WakeOne(), and stk::Yield().

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 810 of file stk.h.

{ 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 812 of file stk.h.

{ 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 808 of file stk.h.

{ 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 806 of file stk.h.

{ return hw::ReadVolatile64(&m_ticks); }

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 804 of file stk.h.

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

References m_kernel.

GetWaitList()

IWaitObject::ListHeadType & stk::IKernelService::GetWaitList ( ISyncObject * sobj )

inlinestaticprotectedinherited

IWaitObject::GetWaitList() access helper.

Definition at line 1723 of file stk_common.h.

    {
        return sobj->GetWaitList();
    }

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

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:

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]

advance

Number of ticks to add to the counter.

Definition at line 974 of file stk.h.

        {
            // using WriteVolatile64() to guarantee correct lockless reading order by ReadVolatile64
            hw::WriteVolatile64(&m_ticks, m_ticks + advance);
        }

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]	tid	Task id.
[in]	weight	New weight, shall be higher than task's current weight (see ITask::GetWeight).

Note

ISR-safe.

Implements stk::IKernelService.

Definition at line 933 of file stk.h.

        {
            if __stk_constexpr_cpp17 (TStrategy::WEIGHT_API && TStrategy::PRIORITY_INHERITANCE_API)
            {
                m_kernel->OnInheritWeight(tid, weight);
            }
        }

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

Initialize instance.

Note

When call completes Singleton<IKernelService *> will start referencing this instance (see g_KernelService).

Parameters

[in]

kernel

Kernel instance.

Definition at line 966 of file stk.h.

        {
            m_kernel = kernel;
        }

References Kernel, and m_kernel.

Here is the call graph for this function:

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]	tid	Task id.
[in]	sobj	Optional, 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 941 of file stk.h.

        {
            if __stk_constexpr_cpp17 (TStrategy::WEIGHT_API && TStrategy::PRIORITY_INHERITANCE_API)
            {
                m_kernel->OnRestoreWeight(tid, sobj);
            }
        }

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_ticks

Number 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 921 of file stk.h.

        {
            if __stk_constexpr_cpp17 (IsTicklessMode())
            {
                return m_kernel->m_platform.Resume(elapsed_ticks);
            }
            else
            {
                STK_ASSERT(false);
            }
        }

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

Here is the call graph for this function:

Sleep()

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

void 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]

ticks

Sleep time (ticks).

Warning

ISR-unsafe. Calling from an ISR context is not permitted and will trigger an assertion.

Implements stk::IKernelService.

Definition at line 829 of file stk.h.

        {
            STK_ASSERT(!hw::IsInsideISR());
            STK_ASSERT(ticks >= 0);
 
            if __stk_constexpr_cpp17 (!IsHrtMode())
            {
                m_kernel->m_platform.Sleep(ticks);
            }
            else
            {
                // sleeping is not supported in HRT mode, task will sleep according to its periodicity and workload
                STK_ASSERT(false);
            }
        }

References __stk_constexpr_cpp17, 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_id

Id of the task.

Note

No-op if task was not in a sleeping state.

ISR-safe.

Implements stk::IKernelService.

Definition at line 861 of file stk.h.

        {
            if __stk_constexpr_cpp17 (!IsHrtMode())
            {
                m_kernel->OnTaskSleepCancel(task_id);
            }
        }

References __stk_constexpr_cpp17, 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]

timestamp

Absolute timestamp (ticks).

Warning

ISR-unsafe. Calling from an ISR context is not permitted and will trigger an assertion.

Returns

True if sleep succeeded, false otherwise.

Implements stk::IKernelService.

Definition at line 845 of file stk.h.

        {
            STK_ASSERT(!hw::IsInsideISR());
 
            if __stk_constexpr_cpp17 (!IsHrtMode())
            {
                return m_kernel->m_platform.SleepUntil(timestamp);
            }
            else
            {
                // sleeping is not supported in HRT mode, task will sleep according to its periodicity and workload
                STK_ASSERT(false);
                return false;
            }
        }

References __stk_constexpr_cpp17, 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 908 of file stk.h.

        {
            if __stk_constexpr_cpp17 (IsTicklessMode())
            {
                return m_kernel->m_platform.Suspend();
            }
            else
            {
                STK_ASSERT(false);
                return 0;
            }
        }

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

A cooperation mechanism in HRT mode (see stk::KERNEL_HRT).

Warning

ISR-unsafe.

Implements stk::IKernelService.

Definition at line 869 of file stk.h.

        {
            STK_ASSERT(!hw::IsInsideISR());
 
            m_kernel->m_platform.SwitchToNext();
        }

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

Here is the call graph for this function:

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]	sobj	Synchronization object to wait on.
[in]	mutex	Mutex protecting the state of the synchronization object.
[in]	timeout	Maximum wait time (ticks). Use WAIT_INFINITE to block indefinitely, use NO_WAIT to poll without blocking.

Returns

Wait result (see EWaitResult).

Warning

ISR-unsafe.

Implements stk::IKernelService.

Definition at line 876 of file stk.h.

        {
            if __stk_constexpr_cpp17 (IsSyncMode())
            {
                return m_kernel->m_platform.Wait(sobj, mutex, ticks);
            }
            else
            {
                STK_ASSERT(false);
                return WAIT_RESULT_FAIL;
            }
        }

References __stk_constexpr_cpp17, 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]	sobj	Synchronization object whose waiting queue will be notified.
[in]	all	If 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 889 of file stk.h.

        {
            if __stk_constexpr_cpp17 (IsSyncMode())
            {
                if (all)
                {
                    ISyncObject::WakeAll(GetWaitList(sobj));
                }
                else
                {
                    ISyncObject::WakeOne(GetWaitList(sobj));
                }
            }
            else
            {
                STK_ASSERT(false);
            }
        }

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

Here is the call graph for this function:

Friends And Related Symbol Documentation

Kernel

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

friend class Kernel

friend

Definition at line 801 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

Pointer to the Kernel.

Definition at line 980 of file stk.h.

Referenced by GetSysTimerCount(), GetSysTimerFrequency(), GetTickResolution(), GetTid(), InheritWeight(), Initialize(), KernelService(), RestoreWeight(), Resume(), Sleep(), SleepCancel(), SleepUntil(), Suspend(), SwitchToNext(), and Wait().

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 981 of file stk.h.

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

---

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

• stk.h