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;

const TId TID_ISR = static_cast<TId>(~0);

const TId TID_NONE = static_cast<TId>(0);

typedef int32_t Timeout;

const Timeout WAIT_INFINITE = INT32_MAX;

const Timeout NO_WAIT = 0;

typedef int64_t Ticks;

typedef uint64_t Cycles;

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

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
        (void)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 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;
    };

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

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

    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 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 int32_t GetTickResolution() 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;
};
 
} // namespace stk
 
#endif /* STK_COMMON_H_ */