Interface for a platform driver. More...

#include <stk_common.h>

Inheritance diagram for stk::IPlatform:

Classes
class	IEventHandler
	Interface for a back-end event handler. More...
class	IEventOverrider
	Interface for a platform event overrider. More...

Public Member Functions
virtual void	Initialize (IEventHandler event_handler, IKernelService service, uint32_t resolution_us, Stack *exit_trap)=0
	Initialize scheduler's context.
virtual void	Start ()=0
	Start scheduling.
virtual void	Stop ()=0
	Stop scheduling.
virtual void	InitStack (EStackType stack_type, Stack stack, IStackMemory stack_memory, ITask *user_task)=0
	Initialize stack memory of the user task.
virtual uint32_t	GetTickResolution () const =0
	Get resolution of the system tick timer in microseconds. Resolution means a number of microseconds between system tick timer ISRs.
virtual Cycles	GetSysTimerCount () const =0
	Get system timer count value.
virtual uint32_t	GetSysTimerFrequency () const =0
	Get system timer frequency.
virtual void	SwitchToNext ()=0
	Switch to a next task.
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 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 void	ProcessTick ()=0
	Process one tick.
virtual void	ProcessHardFault ()=0
	Cause a hard fault of the system.
virtual void	SetEventOverrider (IEventOverrider *overrider)=0
	Set platform event overrider.
virtual Word	GetCallerSP () const =0
	Get caller's Stack Pointer (SP).
virtual TId	GetTid () const =0
	Get thread Id.
virtual Timeout	Suspend ()=0
	Suspend scheduling.
virtual void	Resume (Timeout elapsed_ticks)=0
	Resume scheduling after a prior Suspend() call.

Protected Member Functions
	~IPlatform ()=default
	Destructor.

Detailed Description

Interface for a platform driver.

Note: Bridge design pattern. Do not put implementation details in the header of the concrete class to avoid breaking this pattern.

Platform driver represents an underlying hardware and implements the following logic:

time tick
context switching
hardware access from the user task

All functions are called by the kernel implementation.

Definition at line 762 of file stk_common.h.

Constructor & Destructor Documentation

◆ ~IPlatform()

stk::IPlatform::~IPlatform ( )

protecteddefault

Destructor.

Member Function Documentation

◆ GetCallerSP()

virtual Word stk::IPlatform::GetCallerSP ( ) const

pure virtual

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.

Implemented in stk::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

◆ GetSysTimerCount()

virtual Cycles stk::IPlatform::GetSysTimerCount ( ) const

pure virtual

Get system timer count value.

Note: ISR-safe.

Returns: 64-bit count value.

Implemented in stk::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

◆ GetSysTimerFrequency()

virtual uint32_t stk::IPlatform::GetSysTimerFrequency ( ) const

pure virtual

Get system timer frequency.

Note: ISR-safe.

Returns: Frequency (Hz).

Implemented in stk::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

◆ GetTickResolution()

virtual uint32_t stk::IPlatform::GetTickResolution ( ) const

pure virtual

Get resolution of the system tick timer in microseconds. Resolution means a number of microseconds between system tick timer ISRs.

Returns: Microseconds.

Implemented in stk::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

◆ GetTid()

virtual TId stk::IPlatform::GetTid ( ) const

pure virtual

Get thread Id.

Returns: Thread Id.

Warning: ISR-safe.

See also: TID_ISR_N, TID_NONE, IsIsrTid

Implemented in stk::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

◆ Initialize()

virtual void stk::IPlatform::Initialize	(	IEventHandler *	event_handler,
		IKernelService *	service,
		uint32_t	resolution_us,
		Stack *	exit_trap )

pure virtual

Initialize scheduler's context.

Parameters

[in]	event_handler	Event handler.
[in]	service	Kernel service.
[in]	resolution_us	Tick resolution in microseconds (for example 1000 equals to 1 millisecond resolution).
[in]	exit_trap	Stack of the Exit trap (optional, provided if kernel is operating in KERNEL_DYNAMIC mode).

Note: Must be called once before Start().

Implemented in stk::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

◆ InitStack()

virtual void stk::IPlatform::InitStack	(	EStackType	stack_type,
		Stack *	stack,
		IStackMemory *	stack_memory,
		ITask *	user_task )

pure virtual

Initialize stack memory of the user task.

Parameters

[in]	stack_type	Stack type.
[in]	stack	Stack descriptor.
[in]	stack_memory	Stack memory.
[in]	user_task	User task to which Stack belongs.

Implemented in stk::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

◆ ProcessHardFault()

virtual void stk::IPlatform::ProcessHardFault ( )

pure virtual

Cause a hard fault of the system.

Note: Normally called by the Kernel when one of the scheduled tasks missed its deadline (see stk::KERNEL_HRT).

Implemented in stk::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

Referenced by stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::HrtHardFailDeadline(), and stk_kernel_process_hard_fault().

Here is the caller graph for this function:

◆ ProcessTick()

virtual void stk::IPlatform::ProcessTick ( )

pure virtual

Process one tick.

Note: Normally system tick is processed by the platform driver implementation. In case system tick handler is used by the application and should not be implemented by the driver then disable driver's handler in stk_config.h like this:
#define STK_SYSTICK_HANDLER _STK_SYSTICK_HANDLER_DISABLE

and then call ProcessTick() from your custom tick handler.

Implemented in stk::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

Referenced by stk_kernel_process_tick().

Here is the caller graph for this function:

◆ Resume()

virtual void stk::IPlatform::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.

Note: ISR-safe.

Implemented in stk::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

Referenced by stk_kernel_resume().

Here is the caller graph for this function:

◆ SetEventOverrider()

virtual void stk::IPlatform::SetEventOverrider ( IEventOverrider * overrider )

pure virtual

Set platform event overrider.

Note: Must be set prior call to IKernel::Start.

Parameters

[in] overrider Platform event overrider.

Implemented in stk::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

Referenced by SetEventOverrider().

Here is the caller graph for this function:

◆ Sleep()

virtual void stk::IPlatform::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.

Parameters

[in] ticks Time to sleep (ticks).

Implemented in stk::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

◆ SleepUntil()

virtual bool stk::IPlatform::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::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

◆ Start()

virtual void stk::IPlatform::Start ( )

pure virtual

Start scheduling.

Note: This function never returns if kernel is initialized as KERNEL_STATIC. Must be called after Initialize().

Implemented in stk::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

◆ Stop()

virtual void stk::IPlatform::Stop ( )

pure virtual

Stop scheduling.

Implemented in stk::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

◆ Suspend()

virtual Timeout stk::IPlatform::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 use this value to program a hardware timer for the tickless sleep interval.

Note: ISR-safe. Pair with Resume().

Implemented in stk::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

Referenced by stk_kernel_suspend().

Here is the caller graph for this function:

◆ SwitchToNext()

virtual void stk::IPlatform::SwitchToNext ( )

pure virtual

Switch to a next task.

Implemented in stk::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

◆ Wait()

virtual IWaitObject * stk::IPlatform::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::PlatformArmCortexM, stk::PlatformRiscV, and stk::PlatformX86Win32.

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

stk_common.h

Classes

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~IPlatform()

Member Function Documentation

◆ GetCallerSP()

◆ GetSysTimerCount()

◆ GetSysTimerFrequency()

◆ GetTickResolution()

◆ GetTid()

◆ Initialize()

◆ InitStack()

◆ ProcessHardFault()

◆ ProcessTick()

◆ Resume()

◆ SetEventOverrider()

◆ Sleep()

◆ SleepUntil()

◆ Start()

◆ Stop()

◆ Suspend()

◆ SwitchToNext()

◆ Wait()