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:

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

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

Protected Member Functions
	~IKernelService ()=default
	Destructor.

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

Definition at line 1280 of file stk_common.h.

Constructor & Destructor Documentation

◆ ~IKernelService()

stk::IKernelService::~IKernelService ( )

protecteddefault

Destructor.

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] ticks Delay time (ticks).

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

See also: Delay

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

Referenced by stk::Delay().

Here is the caller graph for this function:

◆ GetInstance()

IKernelService * stk::IKernelService::GetInstance ( )

static

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

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(), and stk::sync::Mutex::TimedLock().

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]	tid	Task id.
[in]	weight	New 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::Mutex::TimedLock(), and stk::sync::Mutex::Unlock().

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

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

Referenced by stk::sync::Mutex::TimedLock(), 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_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

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

Referenced by osKernelResume().

Here is the caller graph for this function:

◆ Sleep()

virtual void 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] ticks Sleep 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::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_id Id of the task.

Note: No-op if task was not in a sleeping state.; ISR-safe.

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

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

See also: IKernel::EState::STATE_SUSPENDED

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

Referenced by 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: A cooperation mechanism in HRT mode (see stk::KERNEL_HRT).

Warning: ISR-unsafe.

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

Referenced by stk::Yield().

Here is the caller graph for this function:

◆ Wait()

virtual IWaitObject * 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]	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.

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

Referenced by stk::sync::Mutex::TimedLock(), stk::sync::ConditionVariable::Wait(), stk::sync::Event::Wait(), and stk::sync::Semaphore::Wait().

Here is the caller graph for this function:

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

stk_common.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~IKernelService()

Member Function Documentation

◆ Delay()

◆ GetInstance()

◆ GetSysTimerCount()

◆ GetSysTimerFrequency()

◆ GetTickResolution()

◆ GetTicks()

◆ GetTid()

◆ InheritWeight()

◆ RestoreWeight()

◆ Resume()

◆ Sleep()

◆ SleepCancel()

◆ SleepUntil()

◆ Suspend()

◆ SwitchToNext()

◆ Wait()