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).
IWaitObject *	Wait (ISyncObject sobj, IMutex mutex, Timeout ticks) override
	Put calling process into a waiting state until synchronization object is signaled or timeout occurs.
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.

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

890 : m_kernel(nullptr), m_ticks(0)

891 {}

stk::Kernel::KernelService::m_ticks

volatile Ticks m_ticks

Global tick counter. Written via hw::WriteVolatile64() by IncrementTick() (ISR context); read via hw:...

Definition stk.h:918

stk::Kernel::KernelService::m_kernel

Kernel * m_kernel

Pointer to the Kernel.

Definition stk.h:917

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 770 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(), 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 766 of file stk.h.

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

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

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

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

stk::hw::ReadVolatile64

static __stk_forceinline T ReadVolatile64(volatile const T *addr)

Atomically read a 64-bit volatile value.

Definition stk_arch.h:379

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

760{ 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] advance Number of ticks to add to the counter.

Definition at line 911 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 870 of file stk.h.

        {
            if __stk_constexpr_cpp17 (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 903 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 878 of file stk.h.

        {
            if __stk_constexpr_cpp17 (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.

See also: IKernel::EState::STATE_SUSPENDED

Implements stk::IKernelService.

Definition at line 858 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 785 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 817 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 801 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().

See also: IKernel::EState::STATE_SUSPENDED

Implements stk::IKernelService.

Definition at line 845 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 825 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>

IWaitObject * 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: Pointer to the wait object representing this wait operation (always non-NULL). The caller must check IWaitObject::IsTimeout() after this function returns to determine whether the wake was caused by a signal or by timeout expiry. The returned pointer is valid until the calling task re-enters a wait or the wait object is explicitly released by the kernel. The return value is guaranteed non nullptr and points to a valid IWaitObject.

Warning: ISR-unsafe.

Implements stk::IKernelService.

Definition at line 832 of file stk.h.

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

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

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 757 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 917 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 918 of file stk.h.

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

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

stk.h

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ KernelService()

◆ ~KernelService()

Member Function Documentation

◆ Delay()

◆ GetInstance()

◆ GetSysTimerCount()

◆ GetSysTimerFrequency()

◆ GetTickResolution()

◆ GetTicks()

◆ GetTid()

◆ IncrementTicks()

◆ InheritWeight()

◆ Initialize()

◆ RestoreWeight()

◆ Resume()

◆ Sleep()

◆ SleepCancel()

◆ SleepUntil()

◆ Suspend()

◆ SwitchToNext()

◆ Wait()

Friends And Related Symbol Documentation

◆ Kernel

Member Data Documentation

◆ m_kernel

◆ m_ticks