stk_common.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_COMMON_H_
#define STK_COMMON_H_
 
#include "stk_defs.h"
#include "stk_linked_list.h"

 
namespace stk {
 
// Forward declarations:
class IKernelService;
class IKernelTask;
class ITask;
class ISyncObject;
namespace tz { namespace nsec { namespace util {
    class CmseISyncObjectWrapper;
}}}
 
// ARM TrustZone
#ifdef _STK_CORTEX_M_TRUSTZONE_NON_SECURE
extern "C" void NSC_stk_ISyncObject_WakeOne(ISyncObject *sobj);
extern "C" void NSC_stk_ISyncObject_WakeAll(ISyncObject *sobj);
#endif

enum EAccessMode : uint32_t
{
    ACCESS_USER       = 0,        
    ACCESS_PRIVILEGED = (1 << 0), 
    ACCESS_SECURE     = (1 << 1), 
};

enum EKernelMode : uint8_t
{
    KERNEL_STATIC   = (1 << 0), 
    KERNEL_DYNAMIC  = (1 << 1), 
    KERNEL_HRT      = (1 << 2), 
    KERNEL_SYNC     = (1 << 3), 
    KERNEL_TICKLESS = (1 << 4), 
};

enum EKernelPanicId : uint32_t
{
    KERNEL_PANIC_NONE                = 0U,  
    KERNEL_PANIC_SPINLOCK_DEADLOCK   = 1U,  
    KERNEL_PANIC_STACK_CORRUPT       = 2U,  
    KERNEL_PANIC_ASSERT              = 3U,  
    KERNEL_PANIC_HRT_HARD_FAULT      = 4U,  
    KERNEL_PANIC_CPU_EXCEPTION       = 5U,  
    KERNEL_PANIC_CS_NESTING_OVERFLOW = 6U,  
    KERNEL_PANIC_UNKNOWN_SVC         = 7U,  
    KERNEL_PANIC_BAD_STATE           = 8U,  
    KERNEL_PANIC_BAD_MODE            = 9U,  
    KERNEL_PANIC_BAD_STACK_TYPE      = 10U  
};

enum EStackType
{
    STACK_USER_TASK = 0, 
    STACK_SLEEP_TRAP,    
    STACK_EXIT_TRAP      
};

enum EConsts
{
    PERIODICITY_MAX      = 99000,             
    PERIODICITY_DEFAULT  = 1000,              
    STACK_SIZE_MIN       = STK_STACK_SIZE_MIN 
};

enum ESystemTaskId
{
    SYS_TASK_ID_SLEEP = 0xFFFFFFFF, 
    SYS_TASK_ID_EXIT  = 0xFFFFFFFE  
};

enum ETraceEventId
{
    TRACE_EVENT_UNKNOWN = 0,        
    TRACE_EVENT_SWITCH  = 1000 + 1, 
    TRACE_EVENT_SLEEP   = 1000 + 2  
};

enum EWaitResult
{
    WAIT_RESULT_FAIL    = -1, 
    WAIT_RESULT_SIGNAL  = 0,  
    WAIT_RESULT_TIMEOUT = 1   
};

typedef uintptr_t Word;

typedef Word TId;

typedef int32_t Timeout;

typedef int64_t Ticks;

typedef int64_t Time;

typedef uint64_t Cycles;

typedef int32_t Weight;

constexpr TId TID_ISR_N = static_cast<TId>(0xFFFFF000U);

constexpr TId TID_NONE = static_cast<TId>(0U);

constexpr Timeout WAIT_INFINITE = INT32_MAX;

constexpr Timeout NO_WAIT = 0;

constexpr Weight NO_WEIGHT = -1;

constexpr Weight DEFAULT_WEIGHT = 1;

static __stk_forceinline bool IsIsrTid(TId id) { return ((id & TID_ISR_N) == TID_ISR_N); }

template <typename T> class ArrayView
{
public:
    ArrayView(T *ptr, size_t size) : m_ptr(ptr), m_size(size)
    {}
    
    T &operator[](size_t index) const
    {
        STK_ASSERT(index < m_size);
        //MISRA 5-0-15 deviation: bounds are checked via STK_ASSERT
        return m_ptr[index];
    }
    
    size_t GetSize() const { return m_size; }
 
private:
    T     *m_ptr;  
    size_t m_size; 
};

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

    typedef __stk_aligned(STK_STACK_MEMORY_ALIGN) Word Type[TStackSize];
};

struct Stack
{
    Word        SP;          
    uint32_t    access_mode; 
#if STK_STACK_NEEDS_TASK_ID
    TId         tid;         
#endif
#ifdef _STK_ARCH_ARM_CORTEX_M
#if STK_TLS && !STK_TLS_PREFER_REGISTER
    Word        tls;        
#endif
#endif
};

class IStackMemory
{
public:
    virtual const Word *GetStack() const = 0;

    virtual size_t GetStackSize() const = 0;

    virtual size_t GetStackSpace() const
    {
        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;
    }
};

class IWaitObject : public util::DListEntry<IWaitObject, false>
{
public:
    typedef DLHeadType ListHeadType;

    typedef DLEntryType ListEntryType;

    virtual TId GetTid() const = 0;

    virtual void Wake(bool timeout) = 0;

    virtual bool IsTimeout() const = 0;

    virtual bool Tick(Timeout elapsed_ticks) = 0;
    
protected:
    ~IWaitObject() = default;
};

class ITraceable
{
public:
#if STK_SYNC_DEBUG_NAMES
    ITraceable() : m_trace_name(nullptr)
    {}
#endif

    void SetTraceName(const char *name)
    {
    #if STK_SYNC_DEBUG_NAMES
        m_trace_name = name;
    #else
        STK_UNUSED(name);
    #endif
    }

    const char *GetTraceName() const
    {
    #if STK_SYNC_DEBUG_NAMES
        return m_trace_name;
    #else
        return nullptr;
    #endif
    }
 
protected:
    ~ITraceable() = default;
  
#if STK_SYNC_DEBUG_NAMES
    const char *m_trace_name; 
#endif
};

class ISyncObject : public util::DListEntry<ISyncObject, false>
{
    friend class IKernel;
    friend class tz::nsec::util::CmseISyncObjectWrapper;
 
public:
    typedef DLHeadType ListHeadType;

    typedef DLEntryType ListEntryType;

    static inline void AddWaitObject(IWaitObject::ListHeadType &wlist, IWaitObject *wobj)
    {
        STK_ASSERT(wobj->GetHead() == nullptr);
        wlist.LinkBack(wobj);
    }

    virtual void AddWaitObject(IWaitObject *wobj)
    {
        AddWaitObject(m_wait_list, wobj);
    }

    static inline void RemoveWaitObject(IWaitObject::ListHeadType &wlist, IWaitObject *wobj)
    {
        STK_ASSERT(wobj->GetHead() == &wlist);
        wlist.Unlink(wobj);
    }

    virtual void RemoveWaitObject(IWaitObject *wobj)
    {
        RemoveWaitObject(m_wait_list, wobj);
    }

    virtual bool Tick(Timeout elapsed_ticks);

    Weight FindWeightHigherThan(Weight comp) const;
    
    static inline void WakeOne(IWaitObject::ListHeadType &wlist)
    {
        if (IWaitObject *const obj = util::DListCast::ListEntryToParent<IWaitObject>(wlist.GetFirst()))
        {
            obj->Wake(false);
        }
    }

    static inline void WakeAll(IWaitObject::ListHeadType &wlist)
    {
        while (IWaitObject *const obj = util::DListCast::ListEntryToParent<IWaitObject>(wlist.GetFirst()))
        {
            obj->Wake(false);
        }
    }
 
protected:
    explicit ISyncObject() : m_wait_list()
    {}

    ~ISyncObject() = default;

    virtual void WakeOne()
    {
    #ifdef _STK_CORTEX_M_TRUSTZONE_NON_SECURE
        NSC_stk_ISyncObject_WakeOne(this);
    #else
        WakeOne(m_wait_list);
    #endif
    }

    virtual void WakeAll()
    {
    #ifdef _STK_CORTEX_M_TRUSTZONE_NON_SECURE
        NSC_stk_ISyncObject_WakeAll(this);
    #else
        WakeAll(m_wait_list);
    #endif
    }
 
    IWaitObject::ListHeadType &GetWaitList()
    {
        return m_wait_list;
    }
 
    IWaitObject::ListHeadType m_wait_list; 
};

class IMutex
{
public:
    class ScopedLock
    {
    public:
        explicit ScopedLock(IMutex &mutex) : m_mutex(mutex) { m_mutex.Lock(); }
        ~ScopedLock() { m_mutex.Unlock(); }
 
    private:
        STK_NONCOPYABLE_CLASS(ScopedLock);
 
        IMutex &m_mutex;
    };

    virtual void Lock() = 0;

    virtual void Unlock() = 0;
    
protected:
    ~IMutex() = default;
};

class ITask : public IStackMemory
{
public:
    virtual void Run() = 0;

    virtual IStackMemory *GetSecureStackMemory() { return nullptr; }

    virtual EAccessMode GetAccessMode() const = 0;

    virtual void OnDeadlineMissed(uint32_t duration) { STK_UNUSED(duration); }

    virtual void OnExit() {}

    virtual Weight GetWeight() const { return DEFAULT_WEIGHT; }

    TId GetId() const;

    virtual const char *GetTraceName() const { return nullptr; }
};

class IKernelTask : public util::DListEntry<IKernelTask, true>
{
public:
    typedef DLHeadType ListHeadType;

    typedef DLEntryType ListEntryType;

    virtual ITask *GetUserTask() = 0;
    
    virtual Stack GetUserStack() const = 0;

    virtual Weight GetWeight() const = 0;

    virtual void SetCurrentWeight(Weight weight) = 0;

    virtual Weight GetCurrentWeight() const = 0;

    virtual Timeout GetHrtPeriodicity() const = 0;

    virtual Timeout GetHrtDeadline() const = 0;

    virtual Timeout GetHrtRelativeDeadline() const = 0;

    virtual bool IsSleeping() const = 0;

    virtual void Wake() = 0;
    
protected:
    ~IKernelTask() = default;
};

class IPlatform
{
public:
    class IEventHandler
    {
    public:
        virtual void OnStart(Stack *&active) = 0;

        virtual void OnStop() = 0;

        virtual bool OnTick(Stack *&idle, Stack *&active
        #if STK_TICKLESS_IDLE
            , Timeout &ticks
        #endif
        ) = 0;

        virtual void OnTaskSwitch(Word caller_SP) = 0;

        virtual void OnTaskSleep(Word caller_SP, Timeout ticks) = 0;

        virtual bool OnTaskSleepUntil(Word caller_SP, Ticks timestamp) = 0;

        virtual void OnTaskExit(Stack *stack) = 0;

        virtual EWaitResult OnTaskWait(Word caller_SP, ISyncObject *sync_obj, IMutex *mutex, Timeout timeout) = 0;

        virtual TId OnGetTid(Word caller_SP) = 0;

        virtual void OnSuspend(bool suspended) = 0;
    };

    class IEventOverrider
    {
    public:
        virtual bool OnSleep(Timeout sleep_ticks) { STK_UNUSED(sleep_ticks); return false; }

        virtual bool OnHardFault() { return false; }
    };

    virtual void Initialize(IEventHandler *event_handler, IKernelService *service, uint32_t resolution_us, Stack *exit_trap) = 0;

    virtual void Start() = 0;

    virtual void Stop() = 0;

    virtual void InitStack(EStackType stack_type, Stack *stack, IStackMemory *stack_memory, ITask *user_task) = 0;

    virtual uint32_t GetTickResolution() const = 0;

    virtual Cycles GetSysTimerCount() const = 0;

    virtual uint32_t GetSysTimerFrequency() const = 0;

    virtual void SwitchToNext() = 0;

    virtual void Sleep(Timeout ticks) = 0;

    virtual bool SleepUntil(Ticks timestamp) = 0;

    virtual EWaitResult Wait(ISyncObject *sobj, IMutex *mutex, Timeout timeout) = 0;

    virtual void ProcessTick() = 0;

    virtual void ProcessHardFault() = 0;

    virtual void SetEventOverrider(IEventOverrider *overrider) = 0;

    virtual Word GetCallerSP() const = 0;

    virtual TId GetTid() const = 0;

    virtual Timeout Suspend() = 0;

    virtual void Resume(Timeout elapsed_ticks) = 0;
    
protected:
    ~IPlatform() = default;
};

class ITaskSwitchStrategy
{
public:
    virtual void AddTask(IKernelTask *task) = 0;

    virtual void RemoveTask(IKernelTask *task) = 0;

    virtual IKernelTask *GetFirst() = 0;
    
    virtual IKernelTask *GetNext() = 0;

    virtual size_t GetSize() const = 0;

    virtual void OnTaskSleep(IKernelTask *task) = 0;

    virtual void OnTaskWake(IKernelTask *task) = 0;

    virtual bool OnTaskDeadlineMissed(IKernelTask *task)
    {
        STK_UNUSED(task);
        return false;
    }

    virtual void OnTaskWeightChange(IKernelTask *task, Weight old_weight)
    {
        STK_UNUSED(task);
        STK_UNUSED(old_weight);
    }
    
protected:
    ~ITaskSwitchStrategy() = default;
};

class IKernel
{
public:
    enum EKernelState : uint8_t
    {
        KSTATE_INACTIVE = 0, 
        KSTATE_READY,        
        KSTATE_RUNNING,      
        KSTATE_SUSPENDED     
    };

    virtual void Initialize(uint32_t resolution_us = PERIODICITY_DEFAULT) = 0;

    virtual void AddTask(ITask *user_task) = 0;

    virtual void AddTask(ITask *user_task, Timeout periodicity_tc, Timeout deadline_tc, Timeout start_delay_tc) = 0;

    virtual void RemoveTask(ITask *user_task) = 0;

    virtual void ScheduleTaskRemoval(ITask *user_task) = 0;

    virtual void SuspendTask(ITask *user_task, bool &suspended) = 0;

    virtual void ResumeTask(ITask *user_task) = 0;

    virtual size_t EnumerateKernelTasks(ArrayView<IKernelTask *> tasks) = 0;

    virtual size_t EnumerateTasks(ArrayView<ITask *> user_tasks) = 0;

    template <size_t TMaxCount, typename TCallback>
    size_t EnumerateTasksT(TCallback &&callback)
    {
        STK_STATIC_ASSERT(TMaxCount > 0U);
 
        ITask *tasks[TMaxCount] = {};        
        size_t count = EnumerateTasks(ArrayView<ITask *>(tasks, TMaxCount));
        size_t i = 0U;
        bool fetch_next = true;
 
        while ((i < count) && fetch_next)
        {
            fetch_next = callback(tasks[i]);
            ++i;
        }
 
        return i;
    }

    virtual void Start() = 0;

    virtual EKernelState GetState() const = 0;

    virtual IPlatform *GetPlatform() = 0;

    virtual ITaskSwitchStrategy *GetSwitchStrategy() = 0;
    
protected:
    ~IKernel() = default;
};

class IKernelService
{
public:
    static IKernelService *GetInstance();

    virtual TId GetTid() const = 0;

    virtual Ticks GetTicks() const = 0;

    virtual uint32_t GetTickResolution() const = 0;

    virtual Cycles GetSysTimerCount() const = 0;

    virtual uint32_t GetSysTimerFrequency() const = 0;

    virtual void Delay(Timeout ticks) = 0;

    virtual void Sleep(Timeout ticks) = 0;

    virtual bool SleepUntil(Ticks timestamp) = 0;

    virtual void SleepCancel(TId task_id) = 0;

    virtual void SwitchToNext() = 0;

    virtual EWaitResult Wait(ISyncObject *sobj, IMutex *mutex, Timeout timeout) = 0;

    virtual Timeout Suspend() = 0;

    virtual void Resume(Timeout elapsed_ticks) = 0;

    virtual void InheritWeight(TId tid, Weight weight) = 0;

    virtual void RestoreWeight(TId tid, ISyncObject *sobj = nullptr) = 0;
    
protected:
    ~IKernelService() = default;
};
 
} // namespace stk
 
#endif /* STK_COMMON_H_ */