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::ITask Class Referenceabstract

Interface for a user task. More...

#include <stk_common.h>

Inheritance diagram for stk::ITask:
Collaboration diagram for stk::ITask:

Public Member Functions

virtual void Run ()=0
 Entry point of the user task.
virtual EAccessMode GetAccessMode () const =0
 Get pointer to the stack memory.
virtual void OnDeadlineMissed (uint32_t duration)
 Called by the scheduler if deadline of the task is missed when Kernel is operating in Hard Real-Time mode (see stk::KERNEL_HRT).
virtual void OnExit ()
 Called by the kernel before removal from the scheduling (see stk::KERNEL_DYNAMIC).
virtual Weight GetWeight () const
 Get static base weight of the task.
virtual Timeout GetTimeSlice () const
 Get time-slice quantum of the task (ticks). KERNEL_TIMESLICE only.
virtual const char * GetTraceName () const
 Get task trace name set by application.
virtual const Word * GetStack () const =0
 Get pointer to the stack memory.
virtual size_t GetStackSize () const =0
 Get number of elements of the stack memory array.
virtual size_t GetStackSpace () const
 Get available stack space.

Protected Member Functions

 ~ITask ()=default
 Destructor.

Detailed Description

Interface for a user task.

Note
Inherit this interface by your thread/task class to make it schedulable by the Kernel.

Usage example:

class MyTask : public stk::Task<256, ACCESS_USER>
{
void Run() override
{
while (true)
{
// task logic here
}
}
};
MyTask task1, task2;
kernel.AddTask(&task1);
kernel.AddTask(&task2);
virtual void Run()=0
Entry point of the user task.
Partial implementation of the user task.
Definition stk_helper.h:98
Examples
blinky_mpu-hard/example.cpp, blinky_mpu-trustzone-ns/example.cpp, and blinky_mpu_armv8/example.cpp.

Definition at line 885 of file stk_common.h.

Constructor & Destructor Documentation

◆ ~ITask()

stk::ITask::~ITask ( )
protecteddefault

Destructor.

Note
Protected by design. Prevents unsafe polymorphic delete.

Member Function Documentation

◆ GetAccessMode()

virtual EAccessMode stk::ITask::GetAccessMode ( ) const
pure virtual

Get pointer to the stack memory.

Note
Optional. ARM TrustZone only.
Returns
Pointer to the Secure stack memory.

Get up to (STK_MPU_TASK_REGIONS - 1) application-defined MPU regions for this task.

When STK_MPU_STACK_GUARD is enabled, each task owns STK_MPU_TASK_REGIONS (2, 4, 6, 8, 12 or 16, see STK_MPU_TASK_REGIONS) hardware MPU region slots. Slot 0 is always the automatic stack guard, computed by the driver from the task's own stack memory (see IStackMemory::GetStack/GetStackSize). This hook supplies the remaining STK_MPU_TASK_REGIONS-1 slots, letting an application additionally sandbox a task to e.g. a private data buffer, a specific peripheral block, or a shared IPC region - on top of its stack guard.

Returns
Pointer to a constant MpuRegionList containing up to (STK_MPU_TASK_REGIONS - 1) region descriptors, or nullptr if no extra task regions are configured. Array element i is applied at task-relative region index i +1 (i.e. the slots following the stack guard).
Note
Optional. Only consulted when STK_MPU_STACK_GUARD is enabled; a no-op on platforms/builds without MPU stack-guard support.
Read once, when the task is bound via Kernel::AddTask() (through IPlatform::InitStack()), not re-evaluated on every context switch. The underlying MpuRegionList instance referenced by the returned pointer must remain valid (e.g. a static const instance); a stack-local temporary is invalid once this function returns.
Warning
An element count greater than (STK_MPU_TASK_REGIONS - 1) is clamped by the driver (STK_ASSERT fires in debug builds); only the first STK_MPU_TASK_REGIONS-1 entries are ever applied.
class MyTask : public stk::Task<256, stk::ACCESS_USER>
{
static constexpr stk::MpuRegionConfig s_extra_regions[] =
{
{ .addr = MY_BUFFER_ADDR, .size = MY_BUFFER_SIZE,
.access_perm = stk::hw::mpu::ACCESS_FULL,
.mem_type = stk::hw::mpu::TYPE_NORMAL_CACHEABLE,
.exec = stk::hw::mpu::EXEC_NEVER },
};
const stk::MpuRegionList *GetMpuRegions() const override
{
static const stk::MpuRegionList mpu_regions(s_extra_regions, 1U);
return &mpu_regions;
}
void Run() override { ... }
};
See also
TaskMpu::Configure, IPlatform::InitStack, MpuRegionList

Get hardware access mode of the user task.

Implemented in cy_stk_thread, MyTask< _AccessMode >, NonSecureLedTask< _AccessMode >, NonSecureLedTask< _AccessMode >, SecureHwCommandQueueTask< _AccessMode >, stk::pthread::PthreadTask, stk::pthread::ReaperTask, stk::Task< _StackSize, _AccessMode >, stk::Task< 128U, stk::ACCESS_PRIVILEGED >, stk::Task< 128U, stk::ACCESS_USER >, stk::Task< 2048, _AccessMode >, stk::Task< 256, _AccessMode >, stk::Task< TASK_STACK_SIZE, _AccessMode >, stk::Task< TASK_STACK_SIZE, stk::ACCESS_PRIVILEGED >, stk::Task<((4U *128U/2U) *(CFG_TUSB_DEBUG ? 2U :1U)), stk::ACCESS_PRIVILEGED >, stk::TaskW< _Weight, _StackSize, _AccessMode >, stk::TaskW< _Priority, TASK_STACK_SIZE, _AccessMode >, stk::TaskW< _Weight, TASK_STACK_SIZE, _AccessMode >, and stk::time::TimerHost::TimerWorkerTask.

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

Here is the caller graph for this function:

◆ GetStack()

◆ GetStackSize()

◆ GetStackSpace()

virtual size_t stk::IStackMemory::GetStackSpace ( ) const
inlinevirtualinherited

Get available stack space.

Returns
Number of elements of the stack memory array remaining on the stack (computed via the watermark pattern). Returns 0 if the stack has been fully used or the watermark STK_STACK_MEMORY_FILLER was overwritten.
Warning
Stack type: Bottom to Top (index[0]).

Definition at line 511 of file stk_common.h.

512 {
513 const ArrayView<const Word> stack(GetStack(), GetStackSize());
514 const size_t total_size = stack.GetSize();
515 size_t space = 0U;
516
517 for (size_t i = 0U; i < total_size; ++i)
518 {
519 if (stack[i] == STK_STACK_MEMORY_FILLER)
520 {
521 space = i + 1U;
522 }
523 else
524 {
525 break; // terminate loop as soon as watermark ends
526 }
527 }
528
529 return space;
530 }
#define STK_STACK_MEMORY_FILLER
Sentinel value written to the entire stack region at initialization (stack watermark pattern).
Definition stk_defs.h:570
virtual size_t GetStackSize() const =0
Get number of elements of the stack memory array.
virtual const Word * GetStack() const =0
Get pointer to the stack memory.

References stk::ArrayView< T >::GetSize(), GetStack(), GetStackSize(), and STK_STACK_MEMORY_FILLER.

Here is the call graph for this function:

◆ GetTimeSlice()

virtual Timeout stk::ITask::GetTimeSlice ( ) const
inlinevirtual

Get time-slice quantum of the task (ticks). KERNEL_TIMESLICE only.

Returns
Number of ticks the task may run before being rotated behind its same-priority peers, or NO_TIME_SLICE (default) to run until it blocks, yields or is preempted.
Note
Read once when the task is bound by Kernel::AddTask(). Use IKernelService::SetTimeSlice() to change it at run-time.
See also
stk::KERNEL_TIMESLICE, IKernelService::SetTimeSlice

Reimplemented in LedTaskT< _AccessMode >, and LedTaskT< stk::ACCESS_PRIVILEGED >.

Definition at line 1006 of file stk_common.h.

1006{ return NO_TIME_SLICE; }
static constexpr Timeout NO_TIME_SLICE
Time-slice quantum value: no time-slicing for the task (it runs until it blocks, yields or is preempt...
Definition stk_common.h:296

References stk::NO_TIME_SLICE.

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

Here is the caller graph for this function:

◆ GetTraceName()

virtual const char * stk::ITask::GetTraceName ( ) const
inlinevirtual

Get task trace name set by application.

Returns
Null-terminated name string, or NULL if unused.
Note
Used for debugging and tracing only (e.g. SEGGER SystemView). Kernel does not interpret this value.

Reimplemented in AudioIsrTask, BlinkyTask, cy_stk_thread, LedTask< _Priority, _AccessMode >, LogTask< _AccessMode >, stk::pthread::PthreadTask, stk::pthread::ReaperTask, stk::time::TimerHost::TimerWorkerTask, and UsbDeviceTask.

Definition at line 1013 of file stk_common.h.

1013{ return nullptr; }

◆ GetWeight()

virtual Weight stk::ITask::GetWeight ( ) const
inlinevirtual

Get static base weight of the task.

Returns
Static weight value of the task (must be positive, the valid range is defined by the strategy).
See also
sched::SwitchStrategyFixedPriority, sched::SwitchStrategySmoothWeightedRoundRobin, IKernelTask::GetWeight, IKernelService::InheritWeight, IKernelService::RestoreWeight

Reimplemented in AudioIsrTask, BlinkyTask, cy_stk_thread, LedTaskT< _AccessMode >, LedTaskT< stk::ACCESS_PRIVILEGED >, stk::pthread::PthreadTask, stk::pthread::ReaperTask, stk::TaskW< _Weight, _StackSize, _AccessMode >, stk::TaskW< _Priority, TASK_STACK_SIZE, _AccessMode >, stk::TaskW< _Weight, TASK_STACK_SIZE, _AccessMode >, stk::time::TimerHost::TimerWorkerTask, and UsbDeviceTask.

Definition at line 997 of file stk_common.h.

997{ return DEFAULT_WEIGHT; }
static constexpr Weight DEFAULT_WEIGHT
Weight value: default weight of value (1) (see SwitchStrategySmoothWeightedRoundRobin).
Definition stk_common.h:290

References stk::DEFAULT_WEIGHT.

Referenced by stk::ISyncObject::FindWeightHigherThan().

Here is the caller graph for this function:

◆ OnDeadlineMissed()

virtual void stk::ITask::OnDeadlineMissed ( uint32_t duration)
inlinevirtual

Called by the scheduler if deadline of the task is missed when Kernel is operating in Hard Real-Time mode (see stk::KERNEL_HRT).

Parameters
[in]durationElapsed active time in ticks at the point the deadline was detected. Always greater than the task's configured deadline (ticks).
Note
Optional handler. Use it for fault logging.
After this call returns, IPlatform::ProcessHardFault() is invoked and the system enters a safe state. This function should not attempt to recover scheduling.

Reimplemented in CtrlTask< _AccessMode >, HwLedTask< _AccessMode >, and stk::time::TimerHost::TimerWorkerTask.

Definition at line 973 of file stk_common.h.

973{ STK_UNUSED(duration); }
#define STK_UNUSED(X)
Explicitly marks a variable as unused to suppress compiler warnings.
Definition stk_defs.h:715

References STK_UNUSED.

◆ OnExit()

virtual void stk::ITask::OnExit ( )
inlinevirtual

Called by the kernel before removal from the scheduling (see stk::KERNEL_DYNAMIC).

Note
The task's stack is no longer in use but the ITask object itself is still valid.
The default no-op implementation is sufficient for detached tasks. Override to implement join semantics (signal a waiting joiner).
Called in kernel/tick context - keep it short. ISR-safe primitives only (e.g. stk::sync::Semaphore::Signal(), stk::sync::EventFlags::Set()).
KERNEL_DYNAMIC only. Never called in KERNEL_STATIC mode.
This is the completion notification of a task removal (returning from Run(), IKernelService::ExitTask() or IKernel::ScheduleTaskRemoval()): after it has been observed by another task the kernel no longer references the ITask object, its stack and its slot, so they can be released or reused, and the same ITask can be added again with IKernel::AddTask() (a restart, e.g. tx_thread_reset()). The removal is an atomic step of the kernel tick: the slot is freed right after this call, before any other task can run (single-core kernel). Until then IKernel::AddTask() of the same task fails with ADD_FAIL_DUPLICATE.

Reimplemented in cy_stk_thread, stk::pthread::PthreadTask, and stk::time::TimerHost::TimerWorkerTask.

Definition at line 990 of file stk_common.h.

990{}

Referenced by stk::Kernel< TMode, TSize, TStrategy, TPlatform >::RemoveTask().

Here is the caller graph for this function:

◆ Run()


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