stk_arch.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_ARCH_H_
#define STK_ARCH_H_

 
// Architecture back-end selection.
// Exactly one of the following macros must be defined by the build system (e.g. via -D compiler flag):
//   _STK_ARCH_ARM_CORTEX_M  — ARM Cortex-M (M0/M0+/M3/M4/M7/M33/M55).
//   _STK_ARCH_RISC_V        — RISC-V (RV32I/RV32E/RV64, with optional FPU).
//   _STK_ARCH_X86_WIN32     — x86/x64 on Windows (simulation/test use only).
//
// Defining more than one is not supported and will result in multiple conflicting definitions.
// _STK_ARCH_DEFINED is set by whichever back-end is included; it can be tested by downstream
// headers or build checks to verify that a valid architecture was selected.
#ifdef _STK_ARCH_ARM_CORTEX_M
    #include "arch/arm/cortex-m/stk_arch_arm-cortex-m.h"
    #define _STK_ARCH_DEFINED
#endif
#ifdef _STK_ARCH_RISC_V
    #include "arch/risc-v/stk_arch_risc-v.h"
    #define _STK_ARCH_DEFINED
#endif
#ifdef _STK_ARCH_X86_WIN32
    #include "arch/x86/win32/stk_arch_x86-win32.h"
    #define _STK_ARCH_DEFINED
#endif
 
#ifndef STK_PANIC_HANDLER
    extern void STK_PANIC_HANDLER_DEFAULT(stk::EKernelPanicId id);
    #define STK_PANIC_HANDLER(id) STK_PANIC_HANDLER_DEFAULT(id)
#endif
 
namespace stk {

static __stk_forceinline void STK_KERNEL_PANIC(stk::EKernelPanicId id)
{
    __stk_debug_break();   // debug aid
    STK_PANIC_HANDLER(id); // must not return
}

namespace hw {

template <typename T>
static constexpr Word PtrToWord(T *const ptr) noexcept
{
    STK_STATIC_ASSERT(sizeof(Word) == sizeof(T *));
    return reinterpret_cast<Word>(ptr);
}

template <typename T>
static constexpr T *WordToPtr(Word value) noexcept
{
    STK_STATIC_ASSERT(sizeof(Word) == sizeof(T *));
    return reinterpret_cast<T *>(value);
}

bool IsInsideISR();
 
// Some architectures (e.g. RISC-V with the 'tp' register) can implement TLS access as a
// single inline instruction. When the back-end header defines STK_INLINE_TLS,
// GetTls and SetTls are provided as inline functions there and the declarations below
// are suppressed to avoid duplicate definitions.
#if STK_TLS && !STK_INLINE_TLS

Word GetTls();

void SetTls(Word tp);
 
#endif // STK_INLINE_TLS
 
#if STK_TLS
template <class _TyTls>
__stk_forceinline _TyTls *GetTlsPtr()
{
    return hw::WordToPtr<_TyTls>(GetTls());
}

template <class _TyTls>
__stk_forceinline void SetTlsPtr(const _TyTls *tp)
{
    SetTls(hw::PtrToWord(tp));
}
#endif // STK_TLS

class CriticalSection
{
public:
    class ScopedLock
    {
    public:
        explicit ScopedLock() { CriticalSection::Enter(); }

        ~ScopedLock() { CriticalSection::Exit(); }
 
    private:
        STK_NONCOPYABLE_CLASS(ScopedLock);
    };

    static void Enter();

    static void Exit();
 
private:
    explicit CriticalSection() {}
    STK_NONCOPYABLE_CLASS(CriticalSection);
};

class SpinLock
{
public:
    enum EState
    {
        UNLOCKED = 0, 
        LOCKED        
    };

    explicit SpinLock() : m_lock(UNLOCKED)
    {}

    void Lock();

    void Unlock();

    bool TryLock();

    bool IsLocked() const { return (m_lock == LOCKED); }
 
protected:
    STK_NONCOPYABLE_CLASS(SpinLock);
 
#ifdef _STK_ARCH_X86_WIN32
    volatile long m_lock; 
#else
    volatile bool m_lock __stk_aligned(8); 
#endif
};

template <typename T>
static __stk_forceinline T ReadVolatile64(volatile const T *addr)
{
    STK_STATIC_ASSERT_N(sz, sizeof(T) == 8U);  // only 64-bit types permitted
    STK_STATIC_ASSERT_N(al, alignof(T) >= 4U); // type must be at least 4-byte aligned
    STK_STATIC_ASSERT_N(ilo, ((STK_ENDIAN_IDX_LO >= 0U) && (STK_ENDIAN_IDX_LO <= 1U)));
    STK_STATIC_ASSERT_N(ihi, ((STK_ENDIAN_IDX_HI >= 0U) && (STK_ENDIAN_IDX_HI <= 1U)));
 
    if __stk_constexpr_cpp17 (sizeof(void *) == 8U) // 64-bit arch: aligned 64-bit load is inherently atomic
    {
        return (*addr);
    }
    else
    {
        // 32-bit arch: split the 64-bit address into two 32-bit halves;
        // writer always updates hi before lo (see WriteVolatile64), so if hi is
        // the same before and after reading lo, no write straddled the two reads.
    #if STK_STRICT_COMPLIANCY
        const Word p_base = hw::PtrToWord(addr);
        volatile const uint32_t *const plo = hw::WordToPtr<uint32_t>(p_base + (STK_ENDIAN_IDX_LO * sizeof(uint32_t)));
        volatile const uint32_t *const phi = hw::WordToPtr<uint32_t>(p_base + (STK_ENDIAN_IDX_HI * sizeof(uint32_t)));
    #else
        volatile const uint32_t *const p_base = reinterpret_cast<volatile const uint32_t *>(addr);
        volatile const uint32_t *const plo = &p_base[STK_ENDIAN_IDX_LO];
        volatile const uint32_t *const phi = &p_base[STK_ENDIAN_IDX_HI];  
    #endif
 
        uint32_t hi, lo;
        do
        {
            hi = (*phi);
            __stk_full_memfence();
 
            lo = (*plo);
            __stk_full_memfence();
        }
        while (hi != (*phi)); // hi changed: a write occurred during the read; retry
 
        const uint64_t result = (static_cast<uint64_t>(hi) << 32U) | static_cast<uint64_t>(lo);
        
        return static_cast<T>(result);
    }
}

template <typename T>
static __stk_forceinline void WriteVolatile64(volatile T *addr, T value)
{
    STK_STATIC_ASSERT_N(sz, sizeof(T) == 8U);  // only 64-bit types permitted
    STK_STATIC_ASSERT_N(al, alignof(T) >= 4U); // type must be at least 4-byte aligned
    STK_STATIC_ASSERT_N(ilo, ((STK_ENDIAN_IDX_LO >= 0U) && (STK_ENDIAN_IDX_LO <= 1U)));
    STK_STATIC_ASSERT_N(ihi, ((STK_ENDIAN_IDX_HI >= 0U) && (STK_ENDIAN_IDX_HI <= 1U)));
 
    if __stk_constexpr_cpp17 (sizeof(void *) == 8U) // 64-bit arch: aligned 64-bit store is inherently atomic
    {
        (*addr) = value;
    }
    else
    {
    #if STK_STRICT_COMPLIANCY
        const Word p_base = hw::PtrToWord(addr);
        volatile uint32_t *const plo = hw::WordToPtr<uint32_t>(p_base + (STK_ENDIAN_IDX_LO * sizeof(uint32_t)));
        volatile uint32_t *const phi = hw::WordToPtr<uint32_t>(p_base + (STK_ENDIAN_IDX_HI * sizeof(uint32_t)));
    #else
        volatile uint32_t *const p_base = reinterpret_cast<volatile uint32_t *>(addr);
        volatile uint32_t *const plo = &p_base[STK_ENDIAN_IDX_LO];
        volatile uint32_t *const phi = &p_base[STK_ENDIAN_IDX_HI];
    #endif
 
        // write hi first: ReadVolatile64 reads hi twice and retries if it changed,
        // so writing hi before lo ensures readers can detect a torn write.
        (*phi) = static_cast<uint32_t>(static_cast<uint64_t>(value) >> 32U);
        __stk_full_memfence();
 
        (*plo) = static_cast<uint32_t>(value);
    }
}

struct HiResClock
{
    static Cycles GetCycles();

    static uint32_t GetFrequency();

    static __stk_forceinline Ticks GetTimeUs()
    {
        Ticks ticks = 0LL;
        const uint32_t freq = GetFrequency();
 
        if (freq != 0U)
        {
            const Cycles cycles = GetCycles();
            const Cycles ticksu = (cycles * 1000000ULL) / static_cast<Cycles>(freq);
            
            ticks = static_cast<Ticks>(ticksu);
        }
 
        return ticks;
    }
};
 
} // namespace hw

static constexpr TId GetTidFromUserTask(const ITask *task) noexcept { return hw::PtrToWord(task); }

static constexpr ITask *GetUserTaskFromTid(TId task_id) noexcept { return hw::WordToPtr<ITask>(task_id); }
 
} // namespace stk

#ifndef _STK_CUSTOM_MEMCPY
static __stk_forceinline void STK_MEMCPY(void *const dest, const void *const src, const size_t size)
{
    using namespace stk;
 
    if ((dest != nullptr) && (src != nullptr) && (size != 0U))
    {
        const Word dest_addr = hw::PtrToWord(dest);
        const Word src_addr  = hw::PtrToWord(src);
 
        // fast path: check if destination, source, and size are all 4-byte aligned
        // then copy data in 4-byte chunks
        if (((dest_addr & 0x03U) == 0U) && 
            ((src_addr  & 0x03U) == 0U) && 
            ((size      & 0x03U) == 0U))
        {
            uint32_t *const       p_d32 = static_cast<uint32_t *>(dest);
            const uint32_t *const p_s32 = static_cast<const uint32_t *>(src);
            const size_t          words = (size >> 2U);
 
            STK_UNUSED(std::copy_n(p_s32, words, p_d32));
        }
        // slow path
        else
        {
            uint8_t *const       p_d = static_cast<uint8_t *>(dest);
            const uint8_t *const p_s = static_cast<const uint8_t *>(src);
 
            STK_UNUSED(std::copy_n(p_s, size, p_d));
        }
    }
}
#endif
 
#endif /* STK_ARCH_H_ */