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;
}}}

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), 
    KERNEL_TIMESLICE = (1 << 5), 
    KERNEL_TELEMETRY = (1 << 6)  
};

enum EKernelPanicId : uint8_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, 
    KERNEL_PANIC_NS_ACCESS           = 11U, 
    KERNEL_PANIC_BAD_MEMORY_REGION   = 12U, 
    KERNEL_PANIC_SYNC_DEADLOCK       = 13U  
};

enum ETaskState : uint8_t
{
    TASK_STATE_REMOVED = 0, 
    TASK_STATE_READY,       
    TASK_STATE_SLEEPING,    
    TASK_STATE_WAITING,     
    TASK_STATE_SUSPENDED,   
    TASK_STATE_EXITING      
};

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

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

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

enum ETraceEventId : uint32_t
{
    TRACE_EVENT_UNKNOWN = 0,        
    TRACE_EVENT_SWITCH  = 1000 + 0, 
    TRACE_EVENT_SLEEP   = 1000 + 1, 
    TRACE_EVENT_WAIT    = 1000 + 2, 
    TRACE_EVENT_SUSPEND = 1000 + 3, 
};

enum EWaitResult : int8_t
{
    WAIT_RESULT_FAIL     = -1, 
    WAIT_RESULT_SIGNAL   = 0,  
    WAIT_RESULT_TIMEOUT  = 1,  
    WAIT_RESULT_CANCELED = 2   
};

enum EHwException : int8_t
{
    HW_EXCEPT_FATAL     = 0, 
    HW_EXCEPT_MEMACCESS = 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;

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

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

static constexpr Timeout WAIT_INFINITE = INT32_MAX;

static constexpr Timeout NO_WAIT = 0;

static constexpr Weight NO_WEIGHT = -1;

static constexpr Weight DEFAULT_WEIGHT = 1;

static constexpr Timeout NO_TIME_SLICE = 0;

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

template <typename T> class ArrayView
{
public:
    typedef T value_type;

    ArrayView() : m_ptr(nullptr), m_size(0U)
    {}

    ArrayView(T *ptr, size_t size) : m_ptr(ptr), m_size(size)
    {}
    
    T &operator[](size_t index) const
    {
        STK_ASSERT(index < m_size); // enforces MISRA Rule 5-0-16
        return UncheckedAt(index);  // MISRA Rule 5-0-15 deviation centralized
    }
    
    T *GetPtr() { return m_ptr; }

    const T *GetPtr() const { return m_ptr; }

    size_t GetSize() const { return m_size; }
 
private:
    __stk_forceinline T &UncheckedAt(size_t index) const
    {
        return m_ptr[index]; // deviation: indexing non-array pointer
    }
 
    T     *m_ptr;  
    size_t m_size; 
};

struct TaskStateInfo
{
    ETaskState   state;     
    ISyncObject *wait_obj;  
    Timeout      remaining; 
};

#if STK_MPU
struct MpuRegion
{
    Word addr; 
    Word attr; 
};
#endif

#if STK_MPU && STK_MPU_STACK_GUARD
template <uint8_t REGIONS_COUNT>
struct TaskMpuT
{
    static constexpr uint8_t NUM_REGIONS = REGIONS_COUNT;
 
    MpuRegion region[NUM_REGIONS]; 
};
typedef TaskMpuT<STK_MPU_TASK_REGIONS> TaskMpu;
typedef TaskMpuT<STK_MPU_TASK_REGIONS_NS> TaskMpuNs;
#endif // STK_MPU && STK_MPU_STACK_GUARD

#if STK_MPU
typedef ArrayView<const struct MpuRegionConfig> MpuRegionList;
#endif

#if STK_MPU
struct MpuConfig
{
    static constexpr uint32_t MPU_OFF = 0U;

    MpuConfig() : regions(), mode(MPU_OFF)
    {}

    MpuConfig(const MpuRegionList &regions_, uint32_t mode_) : regions(regions_), mode(mode_)
    {}
 
    MpuRegionList regions; 
    uint32_t      mode;    
};
#endif

struct Stack
{
    Word      SP;          
    uint32_t  access_mode; 
#if STK_MPU && STK_MPU_STACK_GUARD
    TaskMpu   mpu;         
    #ifdef _STK_CORTEX_M_TRUSTZONE
    TaskMpuNs mpu_ns;      
    #endif
#endif
#if STK_TLS && !STK_TLS_PREFER_REGISTER
    Word      tls;         
#endif
#if STK_STACK_NEEDS_TASK_ID
    TId       tid;         
#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;
    }
 
protected:
    ~IStackMemory() = default;
};

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

    typedef DLEntryType ListEntryType;

    enum EState : uint8_t
    {
        STATE_NONE = 0U,
        STATE_WAIT,      
        STATE_SIGNALED,  
        STATE_TIMEOUT,   
        STATE_CANCELLED  
    };

    virtual TId GetTid() const = 0;

    virtual void Wake(bool timeout) = 0;

    virtual EState GetState() 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 IKernelService;
    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) = 0;

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

    virtual void RemoveWaitObject(IWaitObject *wobj) = 0;

    virtual bool Tick(Timeout elapsed_ticks);

    Weight FindWeightHigherThan(Weight comp) const;

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

    static inline void WakeAll(IWaitObject::ListHeadType &wlist)
    {
        for (IWaitObject *obj = util::DListCast::ListEntryToParent<IWaitObject>(wlist.GetFirst());
             obj != nullptr;
             obj = util::DListCast::ListEntryToParent<IWaitObject>(wlist.GetFirst()))
        {
            obj->Wake(false);
        }
    }

    virtual const IWaitObject::ListHeadType &GetWaitList() const = 0;

    TId GetFirstWaiterTid() const
    {
        const IWaitObject *const obj = util::DListCast::ListEntryToParent<const IWaitObject>(
                GetWaitList().GetFirst());
 
        return ((obj != nullptr) ? obj->GetTid() : TID_NONE);
    }
 
protected:
    ~ISyncObject() = default;

    virtual void WakeOne() = 0;

    virtual void WakeAll() = 0;

    virtual IWaitObject::ListHeadType &GetMutableWaitList() = 0;
};

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;

#if STK_TZ_SECURE
    virtual IStackMemory *GetSecureStackMemory() { return nullptr; }
#endif

#if STK_MPU
    virtual const MpuRegionList *GetMpuRegions() const
    {
        return nullptr;
    }
#endif

    virtual EAccessMode GetAccessMode() const = 0;

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

    virtual void OnExit() {}

    virtual Weight GetWeight() const { return DEFAULT_WEIGHT; }

    virtual Timeout GetTimeSlice() const { return NO_TIME_SLICE; }

    virtual const char *GetTraceName() const { return nullptr; }
 
protected:
    ~ITask() = default;
};

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 Weight GetBaseWeight() 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 *&enable) = 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;

        virtual bool OnForceContextSwitch(TId id, Stack *&idle, Stack *&active) = 0;
    };

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

        virtual bool OnHardFault()
        {
            return false;
        }

    #if STK_MPU
        virtual const MpuConfig *OnConfigureMpu() const
        {
            return nullptr;
        }
    #endif

        virtual bool OnException(EHwException exc_id, TId tid, const struct FaultContext *const ctx)
        {
            STK_UNUSED(exc_id);
            STK_UNUSED(tid);
            STK_UNUSED(ctx);
            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 ForceContextSwitch(TId id) = 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, bool non_secure = false) = 0;

    virtual Word GetCallerSP() const = 0;

    virtual TId GetTid() const = 0;

    virtual Timeout Suspend() = 0;

    virtual void Resume(Timeout elapsed_ticks) = 0;
    
    virtual void SetCpuFrequency(uint8_t core_id, uint32_t frequency) = 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 OnTaskYield(IKernelTask *task)
    {
        STK_UNUSED(task);
        return false;
    }

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

    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 void CancelTaskWait(ITask *user_task) = 0;

    virtual bool GetTaskState(ITask *user_task, TaskStateInfo &info) const = 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 void Wake(ISyncObject *sobj, bool all) = 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;

    virtual Weight SetWeight(TId tid, Weight weight) = 0;

    virtual Timeout SetTimeSlice(TId tid, Timeout ticks) = 0;
    
protected:
    ~IKernelService() = default;

    static __stk_forceinline IWaitObject::ListHeadType &GetMutableWaitList(ISyncObject *sobj)
    {
        return sobj->GetMutableWaitList();
    }
};
 
} // namespace stk
 
#endif /* STK_COMMON_H_ */