StkThread Class Reference

Inheritance diagram for StkThread:

Collaboration diagram for StkThread:

Public Types
enum class	JoinState : uint8_t {   Detached ,   Joinable ,   Exited ,   Joined }

Public Member Functions
	StkThread ()
virtual	~StkThread ()
void	Run () override
	Entry point of the user task.
void	OnExit () override
	Called by the kernel before removal from the scheduling (see stk::KERNEL_DYNAMIC).
const stk::Word *	GetStack () const override
	Get pointer to the stack memory.
size_t	GetStackSize () const override
	Get number of elements of the stack memory array.
stk::EAccessMode	GetAccessMode () const override
	Get hardware access mode of the user task.
void	OnDeadlineMissed (uint32_t) override
	Called by the scheduler if deadline of the task is missed when Kernel is operating in Hard Real-Time mode (see stk::KERNEL_HRT).
int32_t	GetWeight () const override
	Get static base weight of the task.
const char *	GetTraceName () const override
	Get task trace name set by application.
virtual IStackMemory *	GetSecureStackMemory ()
	Get pointer to the stack memory.
virtual const MpuRegionList *	GetMpuRegions () const
	Get up to (STK_MPU_TASK_REGIONS - 1) application-defined MPU regions for this task.
virtual size_t	GetStackSpace () const
	Get available stack space.

Static Public Member Functions
static osThreadId_t	ConvertTIdToThreadId (const stk::TId tid)

Public Attributes
osThreadFunc_t	m_func
void *	m_argument
const char *	m_name
volatile int32_t	m_stk_priority
stk::Word *	m_stack
size_t	m_stack_size
volatile JoinState	m_join_state
stk::sync::ConditionVariable	m_join_cv
stk::sync::EventFlags	m_thread_flags
bool	m_stack_owned
bool	m_suspended
bool	m_cb_owned

Private Member Functions
	STK_NONCOPYABLE_CLASS (StkThread)

Detailed Description

Definition at line 175 of file cmsis_os2_stk.cpp.

Member Enumeration Documentation

JoinState

enum class StkThread::JoinState : uint8_t

strong

Enumerator
Detached
Joinable
Exited
Joined

Definition at line 181 of file cmsis_os2_stk.cpp.

    {
        Detached, // osThreadDetach() was called, or created with osThreadDetached
        Joinable, // created with osThreadJoinable, not yet joined or exited
        Exited,   // Run() has returned; OnExit() has fired; not yet joined
        Joined,   // a joiner has already collected the result; further joins are errors
    };

Constructor & Destructor Documentation

StkThread()

StkThread::StkThread ( )

inlineexplicit

Definition at line 189 of file cmsis_os2_stk.cpp.

        : m_func(nullptr), m_argument(nullptr), m_name(nullptr),
          m_stk_priority(CmsisPrioToStk(osPriorityNormal)),
          m_stack(nullptr), m_stack_size(0U), m_join_state(JoinState::Detached),
          m_stack_owned(false), m_suspended(false), m_cb_owned(true)
    {}

References CmsisPrioToStk(), m_argument, m_cb_owned, m_func, m_join_state, m_name, m_stack, m_stack_owned, m_stack_size, m_stk_priority, m_suspended, and osPriorityNormal.

Referenced by ConvertTIdToThreadId(), and STK_NONCOPYABLE_CLASS().

Here is the call graph for this function:

Here is the caller graph for this function:

~StkThread()

virtual StkThread::~StkThread ( )

inlinevirtual

Definition at line 196 of file cmsis_os2_stk.cpp.

    {
        if (m_stack_owned && (m_stack != nullptr))
        {
            delete[] m_stack;
            m_stack = nullptr;
        }
    }

References m_stack, and m_stack_owned.

Member Function Documentation

ConvertTIdToThreadId()

osThreadId_t StkThread::ConvertTIdToThreadId ( const stk::TId tid )

inlinestatic

Definition at line 230 of file cmsis_os2_stk.cpp.

    {
        // tid is hw::PtrToWord(this) where 'this' is the StkThread* - cast it back.
        return reinterpret_cast<osThreadId_t>(static_cast<void *>(
            reinterpret_cast<StkThread *>(static_cast<uintptr_t>(tid))));
    }

References StkThread().

Referenced by osMutexGetOwner(), and osThreadGetId().

Here is the call graph for this function:

Here is the caller graph for this function:

GetAccessMode()

stk::EAccessMode StkThread::GetAccessMode ( ) const

inlineoverridevirtual

Get hardware access mode of the user task.

Implements stk::ITask.

Definition at line 225 of file cmsis_os2_stk.cpp.

{ return stk::ACCESS_PRIVILEGED; }

References stk::ACCESS_PRIVILEGED.

GetMpuRegions()

virtual const MpuRegionList * stk::ITask::GetMpuRegions ( ) const

inlinevirtualinherited

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 or 4, 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

Definition at line 801 of file stk_common.h.

    {
        return nullptr;
    }

GetSecureStackMemory()

virtual IStackMemory * stk::ITask::GetSecureStackMemory ( )

inlinevirtualinherited

Get pointer to the stack memory.

Note

Optional. ARM TrustZone only.

Returns

Pointer to the Secure stack memory.

Definition at line 756 of file stk_common.h.

{ return nullptr; }

GetStack()

const stk::Word * StkThread::GetStack ( ) const

inlineoverridevirtual

Get pointer to the stack memory.

Implements stk::IStackMemory.

Definition at line 221 of file cmsis_os2_stk.cpp.

{ return m_stack; }

References m_stack.

GetStackSize()

size_t StkThread::GetStackSize ( ) const

inlineoverridevirtual

Get number of elements of the stack memory array.

Implements stk::IStackMemory.

Definition at line 222 of file cmsis_os2_stk.cpp.

{ return m_stack_size; }

References m_stack_size.

Referenced by osThreadGetStackSize().

Here is the caller graph for this function:

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 418 of file stk_common.h.

    {
        const ArrayView<const Word> stack(GetStack(), GetStackSize());
        const size_t total_size = stack.GetSize();
        size_t space = 0U;
 
        for (size_t i = 0U; i < total_size; ++i)
        {
            if (stack[i] == STK_STACK_MEMORY_FILLER)
            {
                space = i + 1U;
            }
            else
            {
                break; // terminate loop as soon as watermark ends
            }
        }
 
        return space;
    }

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

Referenced by FrtosTask::GetStackHighWaterMark(), and osThreadGetStackSpace().

Here is the call graph for this function:

Here is the caller graph for this function:

GetTraceName()

const char * StkThread::GetTraceName ( ) const

inlineoverridevirtual

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 from stk::ITask.

Definition at line 228 of file cmsis_os2_stk.cpp.

{ return m_name; }

References m_name.

GetWeight()

int32_t StkThread::GetWeight ( ) const

inlineoverridevirtual

Get static base weight of the task.

Returns

Static weight value of the task (must be non-zero, positive 24-bit number).

See also

SwitchStrategyFixedPriority, SwitchStrategySmoothWeightedRoundRobin, IKernelTask::GetWeight, IKernelService::InheritWeight, IKernelService::RestoreWeight

Reimplemented from stk::ITask.

Definition at line 227 of file cmsis_os2_stk.cpp.

{ return m_stk_priority; }

References m_stk_priority.

OnDeadlineMissed()

void StkThread::OnDeadlineMissed ( uint32_t duration )

inlineoverridevirtual

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]

duration

Elapsed 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 from stk::ITask.

Definition at line 226 of file cmsis_os2_stk.cpp.

{}

OnExit()

void StkThread::OnExit ( )

inlineoverridevirtual

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.

Reimplemented from stk::ITask.

Definition at line 212 of file cmsis_os2_stk.cpp.

    {
        m_join_state = JoinState::Exited;
 
        // wake any osThreadJoin() caller
        m_join_cv.NotifyAll();
    }

References Exited, m_join_cv, and m_join_state.

Run()

void StkThread::Run ( )

inlineoverridevirtual

Entry point of the user task.

Note

Called by the Kernel when the task is scheduled for execution. Implement this method with the task's main logic.

Warning

If Kernel is configured as KERNEL_STATIC, the body must contain an infinite loop.

void Run( override)
{
    while (true)
    {
        // task logic here
    }
}

Implements stk::ITask.

Definition at line 205 of file cmsis_os2_stk.cpp.

    {
        m_func(m_argument);
 
        // KERNEL_DYNAMIC: returning from Run() removes the task automatically.
    }

References m_argument, and m_func.

STK_NONCOPYABLE_CLASS()

StkThread::STK_NONCOPYABLE_CLASS ( StkThread )

private

References StkThread().

Here is the call graph for this function:

Member Data Documentation

m_argument

void* StkThread::m_argument

Definition at line 239 of file cmsis_os2_stk.cpp.

Referenced by osThreadNew(), Run(), and StkThread().

m_cb_owned

bool StkThread::m_cb_owned

Definition at line 249 of file cmsis_os2_stk.cpp.

Referenced by StkThread().

m_func

osThreadFunc_t StkThread::m_func

Definition at line 238 of file cmsis_os2_stk.cpp.

Referenced by osThreadNew(), Run(), and StkThread().

m_join_cv

stk::sync::ConditionVariable StkThread::m_join_cv

Definition at line 245 of file cmsis_os2_stk.cpp.

Referenced by OnExit(), and osThreadJoin().

m_join_state

volatile JoinState StkThread::m_join_state

Definition at line 244 of file cmsis_os2_stk.cpp.

Referenced by OnExit(), osThreadDetach(), osThreadJoin(), osThreadNew(), osThreadTerminate(), and StkThread().

m_name

const char* StkThread::m_name

Definition at line 240 of file cmsis_os2_stk.cpp.

Referenced by GetTraceName(), osThreadNew(), and StkThread().

m_stack

stk::Word* StkThread::m_stack

Definition at line 242 of file cmsis_os2_stk.cpp.

Referenced by GetStack(), osThreadNew(), StkThread(), and ~StkThread().

m_stack_owned

bool StkThread::m_stack_owned

Definition at line 247 of file cmsis_os2_stk.cpp.

Referenced by osThreadNew(), StkThread(), and ~StkThread().

m_stack_size

size_t StkThread::m_stack_size

Definition at line 243 of file cmsis_os2_stk.cpp.

Referenced by GetStackSize(), osThreadNew(), and StkThread().

m_stk_priority

volatile int32_t StkThread::m_stk_priority

Definition at line 241 of file cmsis_os2_stk.cpp.

Referenced by GetWeight(), osThreadGetPriority(), osThreadNew(), osThreadSetPriority(), and StkThread().

m_suspended

bool StkThread::m_suspended

Definition at line 248 of file cmsis_os2_stk.cpp.

Referenced by osThreadGetState(), osThreadResume(), osThreadSuspend(), and StkThread().

m_thread_flags

stk::sync::EventFlags StkThread::m_thread_flags

Definition at line 246 of file cmsis_os2_stk.cpp.

Referenced by osThreadFlagsClear(), osThreadFlagsSet(), and osThreadFlagsWait().

---

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

• cmsis_os2_stk.cpp