stk_helper.h

Go to the documentation of this file.

/*
 * SuperTinyKernel(TM) RTOS: Lightweight High-Performance Deterministic C++ RTOS for Embedded Systems.
 *
 * Source: https://github.com/SuperTinyKernel-RTOS
 *
 * Copyright (c) 2022-2026 Neutron Code Limited <stk@neutroncode.com>. All Rights Reserved.
 * License: MIT License, see LICENSE for a full text.
 */
 
#ifndef STK_HELPER_H_
#define STK_HELPER_H_
 
#include "stk_common.h"
#include "stk_arch.h"
#ifdef _STK_CORTEX_M_TRUSTZONE_NON_SECURE
    #include "arch/arm/cortex-m/stk_arch_arm-tz.h"
#endif

 
namespace stk {

template <size_t TStackSize> struct StackMemoryDef
{
    enum EConsts : size_t
    {
        SIZE = TStackSize
    };

#if STK_MPU_STACK_GUARD
    #if STK_ARCH_ARMV8_M
        // ARMv8-M alignment is 32 bytes.
        typedef __stk_aligned(32U) Word Type[SIZE];
    #else
        // ARMv7-M alignment is a size of the memory region.
        typedef __stk_aligned(TStackSize * sizeof(Word)) Word Type[SIZE];
    #endif
#else
    typedef __stk_aligned(STK_STACK_MEMORY_ALIGN) Word Type[SIZE];
#endif
};

template <size_t _StackSize, EAccessMode _AccessMode>
class Task
#ifdef _STK_CORTEX_M_TRUSTZONE_NON_SECURE
    : public tz::nsec::NsTask
#else
    : public ITask
#endif
{
public:
    enum { STACK_SIZE = _StackSize }; 
 
    const Word *GetStack()      const override { return const_cast<Word *>(m_stack); }
    size_t GetStackSize()       const override { return _StackSize; }
    EAccessMode GetAccessMode() const override { return _AccessMode; }
 
    TId GetTid()                const          { return GetTidFromUserTask(this); }
 
protected:
    STK_NONCOPYABLE_CLASS(Task);

    Task() : m_stack()
    {}

    STK_VIRT_DTOR ~Task() = default;
 
private:
    typename StackMemoryDef<_StackSize>::Type m_stack; 
};

template <Weight _Weight, size_t _StackSize, EAccessMode _AccessMode>
class TaskW
#ifdef _STK_CORTEX_M_TRUSTZONE_NON_SECURE
    : public tz::nsec::NsTask
#else
    : public ITask
#endif
{
public:
    enum { STACK_SIZE = _StackSize }; 
 
    const Word *GetStack()      const override { return const_cast<Word *>(m_stack); }
    size_t GetStackSize()       const override { return _StackSize; }
    EAccessMode GetAccessMode() const override { return _AccessMode; }
    Weight GetWeight()          const override { return _Weight; }
 
    TId GetTid()                const          { return GetTidFromUserTask(this); }
 
protected:
    STK_NONCOPYABLE_CLASS(TaskW);

    TaskW() : m_stack() {}

    STK_VIRT_DTOR ~TaskW() = default;
 
private:
    typename StackMemoryDef<_StackSize>::Type m_stack; 
};

template <size_t _StackSize>
class StackMemoryWrapper : public IStackMemory
{
public:
    typedef typename StackMemoryDef<_StackSize>::Type MemoryType;

    explicit StackMemoryWrapper(MemoryType *stack) : m_stack(stack)
    {
        STK_STATIC_ASSERT(_StackSize >= STACK_SIZE_MIN);
    }

    STK_VIRT_DTOR ~StackMemoryWrapper() = default;

    const Word *GetStack() const override { return (*m_stack); }

    size_t GetStackSize() const override { return _StackSize; }
 
private:
    MemoryType *m_stack; 
};

class SyncObjectBase
#ifdef _STK_CORTEX_M_TRUSTZONE_NON_SECURE
    : public tz::nsec::NsSyncObject
#else
    : public ISyncObject
#endif
{
    friend class IKernelService;
 
public:
    void AddWaitObject(IWaitObject *wobj) override
    {
        ISyncObject::AddWaitObject(m_wait_list, wobj);
    }
 
    void RemoveWaitObject(IWaitObject *wobj) override
    {
        ISyncObject::RemoveWaitObject(m_wait_list, wobj);
    }
 
    const IWaitObject::ListHeadType &GetWaitList() const override
    {
        return m_wait_list;
    }
 
protected:
    explicit SyncObjectBase() : m_wait_list()
    {}

    ~SyncObjectBase()
    {
        const hw::CriticalSection::ScopedLock cs_;
 
        ISyncObject::ListHeadType *const head = GetHead();
        if (head != nullptr)
        {
            head->Unlink(this);
        }
    }
 
    void WakeOne() override
    {
        IKernelService::GetInstance()->Wake(this, false);
    }
 
    void WakeAll() override
    {
        IKernelService::GetInstance()->Wake(this, true);
    }
 
    IWaitObject::ListHeadType &GetMutableWaitList() override
    {
        return m_wait_list;
    }
 
    IWaitObject::ListHeadType m_wait_list; 
};

inline bool ISyncObject::Tick(Timeout elapsed_ticks)
{
    IWaitObject::ListHeadType &wlist = GetMutableWaitList();
 
    // note: ScopedCriticalSection usage
    //
    // Single-core: no critical section needed - Tick() runs inside the
    // SysTick ISR which already executes with interrupts disabled, making
    // re-entrancy impossible on the local core.
    //
    // Multi-core: critical section is required because the tick handler on
    // each core may call Tick() concurrently for the same Semaphore instance,
    // and ISyncObject::Tick() is not re-entrant.
#if (STK_ARCH_CPU_COUNT > 1)
    const hw::CriticalSection::ScopedLock cs_;
#endif
 
    IWaitObject *itr = util::DListCast::ListEntryToParent<IWaitObject>(wlist.GetFirst());
 
    while (itr != nullptr)
    {
        IWaitObject *const next = util::DListCast::ListEntryToParent<IWaitObject>(itr->GetNext());
 
        if (!itr->Tick(elapsed_ticks))
        {
            itr->Wake(true);
        }
 
        itr = next;
    }
 
    return !wlist.IsEmpty();
}

inline Weight ISyncObject::FindWeightHigherThan(Weight comp) const
{
    Weight max_weight = NO_WEIGHT;
    const IWaitObject *itr = util::DListCast::ListEntryToParent<const IWaitObject>(GetWaitList().GetFirst());
 
    while (itr != nullptr)
    {
        const Weight w = GetUserTaskFromTid(itr->GetTid())->GetWeight();
        if (w > max_weight)
        {
            max_weight = w;
        }
            
        itr = util::DListCast::ListEntryToParent<const IWaitObject>(itr->GetNext());
    }
 
    return ((max_weight > comp) ? max_weight : NO_WEIGHT);
}

static __stk_forceinline TId GetTid()
{
    return IKernelService::GetInstance()->GetTid();
}

static __stk_forceinline uint32_t GetTickResolution()
{
    return IKernelService::GetInstance()->GetTickResolution();
}

static __stk_forceinline Time GetMsFromTicks(Ticks tick_count, uint32_t resolution)
{
    return static_cast<Time>((tick_count * static_cast<Time>(resolution)) / 1000LL);
}

static __stk_forceinline Ticks GetTicksFromMs(Time ms, uint32_t resolution)
{
    Ticks tick_count = 0LL;
 
    if (resolution != 0U)
    {
        tick_count = static_cast<Ticks>((ms * 1000LL) / static_cast<Time>(resolution));
    }
 
    return tick_count;
}

static __stk_forceinline Ticks GetTicksFromMs(Time ms)
{
    return GetTicksFromMs(ms, GetTickResolution());
}

static __stk_forceinline Timeout GetTicksFromMsClampedToTimeout(Timeout ms)
{
    const Time time_ms = static_cast<Time>(ms);
    const Ticks tick_count = GetTicksFromMs(time_ms);    
    
    const Ticks final_ticks = (tick_count < static_cast<Ticks>(WAIT_INFINITE)) ? 
        tick_count : static_cast<Ticks>(WAIT_INFINITE);
        
    return static_cast<Timeout>(final_ticks);
}

static __stk_forceinline Ticks GetTicks()
{
    return IKernelService::GetInstance()->GetTicks();
}

static __stk_forceinline Time GetTimeNowMs()
{
    const IKernelService *const service = IKernelService::GetInstance();
    const uint32_t resolution = service->GetTickResolution();
    const Ticks tick_count = service->GetTicks();
 
    return ((resolution == 1000U) ? tick_count : 
        ((tick_count * static_cast<Ticks>(resolution)) / 1000LL));
}

static __stk_forceinline Cycles GetSysTimerCount()
{
    return IKernelService::GetInstance()->GetSysTimerCount();
}

static __stk_forceinline uint32_t GetSysTimerFrequency()
{
    return IKernelService::GetInstance()->GetSysTimerFrequency();
}

static __stk_forceinline void Sleep(Timeout tick_count)
{
    IKernelService::GetInstance()->Sleep(tick_count);
}

static __stk_forceinline void SleepMs(Timeout ms)
{
    Sleep(GetTicksFromMsClampedToTimeout(ms));
}

static __stk_forceinline bool SleepUntil(Ticks timestamp)
{
    return IKernelService::GetInstance()->SleepUntil(timestamp);
}

static __stk_forceinline void SleepCancel(TId task_id)
{
    IKernelService::GetInstance()->SleepCancel(task_id);
}

static __stk_forceinline void Yield()
{
    IKernelService::GetInstance()->SwitchToNext();
}

static __stk_forceinline Weight SetWeight(TId tid, Weight weight)
{
    return IKernelService::GetInstance()->SetWeight(tid, weight);
}

static __stk_forceinline Weight SetWeight(Weight weight)
{
    return SetWeight(GetTid(), weight);
}

static __stk_forceinline Timeout SetTimeSlice(TId tid, Timeout ticks)
{
    return IKernelService::GetInstance()->SetTimeSlice(tid, ticks);
}

static __stk_forceinline Timeout SetTimeSlice(Timeout ticks)
{
    return SetTimeSlice(GetTid(), ticks);
}

static __stk_forceinline void Delay(Timeout tick_count)
{
    IKernelService::GetInstance()->Delay(tick_count);
}

static __stk_forceinline void DelayMs(Timeout ms)
{
    Delay(GetTicksFromMsClampedToTimeout(ms));
}
 
} // namespace stk
 
#endif /* STK_HELPER_H_ */