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;

enum EAccessMode : int32_t
{
    ACCESS_USER = 0,  
    ACCESS_PRIVILEGED 
};

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                = 0, 
    KERNEL_PANIC_SPINLOCK_DEADLOCK   = 1, 
    KERNEL_PANIC_STACK_CORRUPT       = 2, 
    KERNEL_PANIC_ASSERT              = 3, 
    KERNEL_PANIC_HRT_HARD_FAULT      = 4, 
    KERNEL_PANIC_CPU_EXCEPTION       = 5, 
    KERNEL_PANIC_CS_NESTING_OVERFLOW = 6, 
    KERNEL_PANIC_UNKNOWN_SVC         = 7, 
    KERNEL_PANIC_BAD_STATE           = 8, 
    KERNEL_PANIC_BAD_MODE            = 9  
};

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

typedef uintptr_t Word;

typedef Word TId;

typedef int32_t Timeout;

typedef int64_t Ticks;

typedef uint64_t Cycles;

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 inline bool IsIsrTid(TId tid)
{
    return ((tid & TID_ISR_N) == TID_ISR_N);
}

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

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

struct Stack
{
    Word        SP;   
    EAccessMode mode; 
#if STK_NEED_TASK_ID
    TId         tid;  
#endif
};

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

    virtual size_t GetStackSize() const = 0;

    virtual size_t GetStackSizeBytes() const = 0;

    virtual size_t GetStackSpace()
    {
        const Word *stack = GetStack();
        const size_t stack_size = GetStackSize();
 
        // count leading Words equal to STK_STACK_MEMORY_FILLER (watermark)
        size_t space = 0U;
        for ( ; (space < stack_size) && (stack[space] == STK_STACK_MEMORY_FILLER); ++space)
        {}
 
        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;
};

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:
#if STK_SYNC_DEBUG_NAMES
    const char *m_trace_name; 
#endif
};

class ISyncObject : public util::DListEntry<ISyncObject, false>
{
public:
    ~ISyncObject()
    {}

    typedef DLHeadType ListHeadType;

    typedef DLEntryType ListEntryType;

    virtual void AddWaitObject(IWaitObject *wobj)
    {
        STK_ASSERT(wobj->GetHead() == nullptr);
        m_wait_list.LinkBack(wobj);
    }

    virtual void RemoveWaitObject(IWaitObject *wobj)
    {
        STK_ASSERT(wobj->GetHead() == &m_wait_list);
        m_wait_list.Unlink(wobj);
    }

    virtual bool Tick(Timeout elapsed_ticks);
 
protected:
    explicit ISyncObject() : m_wait_list()
    {}

    void WakeOne()
    {
        if (!m_wait_list.IsEmpty())
            static_cast<IWaitObject *>(m_wait_list.GetFirst())->Wake(false);
    }

    void WakeAll()
    {
        while (!m_wait_list.IsEmpty())
            static_cast<IWaitObject *>(m_wait_list.GetFirst())->Wake(false);
    }
 
    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;
};

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

    virtual EAccessMode GetAccessMode() const = 0;

    virtual void OnDeadlineMissed(uint32_t duration) = 0;

    virtual void OnExit() = 0;

    virtual int32_t GetWeight() const = 0;

    virtual TId GetId() const = 0;

    virtual const char *GetTraceName() const = 0;
};

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

    typedef DLEntryType ListEntryType;

    virtual ITask *GetUserTask() = 0;

    virtual Stack *GetUserStack() = 0;

    virtual int32_t GetWeight() const = 0;

    virtual void SetCurrentWeight(int32_t weight) = 0;

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

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 void OnTaskSleepUntil(Word caller_SP, Ticks timestamp) = 0;

        virtual void OnTaskExit(Stack *stack) = 0;

        virtual IWaitObject *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() = 0;

        virtual bool OnHardFault() = 0;
    };

    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 bool 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 void SleepUntil(Ticks timestamp) = 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;
};

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

    virtual void RemoveTask(IKernelTask *task) = 0;

    virtual IKernelTask *GetFirst() const = 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) = 0;
};

class IKernel
{
public:
    enum EState : uint8_t
    {
        STATE_INACTIVE = 0, 
        STATE_READY,        
        STATE_RUNNING,      
        STATE_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 EnumerateTasks(ITask **user_tasks, size_t max_size) = 0;

    template <size_t TMaxCount, typename TCallback>
    size_t EnumerateTasksT(TCallback &&callback)
    {
        STK_STATIC_ASSERT(TMaxCount > 0);
 
        ITask *tasks[TMaxCount] = {};
        size_t i = 0, count = EnumerateTasks(tasks, TMaxCount);
 
        while (i < count)
        {
            if (!callback(tasks[i++]))
                break;
        }
 
        return i;
    }

    virtual void Start() = 0;

    virtual EState GetState() const = 0;

    virtual IPlatform *GetPlatform() = 0;

    virtual ITaskSwitchStrategy *GetSwitchStrategy() = 0;
};

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 void SleepUntil(Ticks timestamp) = 0;

    virtual void SwitchToNext() = 0;

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

    virtual Timeout Suspend() = 0;

    virtual void Resume(Timeout elapsed_ticks) = 0;
};
 
} // namespace stk
 
#endif /* STK_COMMON_H_ */