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_
 
#include "stk_defs.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
 
// =============================================================================
#if STK_MPU
// =============================================================================

#define STK_MPU_SHARED_DATA_SECTION __attribute__((section(".stk_mpu_shared_data")))

#define STK_MPU_SHARED_CODE_SECTION __attribute__((section(".stk_mpu_shared_code")))

#define STK_MPU_SHARED_BSS_SECTION __attribute__((section(".stk_mpu_shared_bss")))

#define STK_MPU_KERNEL_DATA_SECTION __attribute__((section(".stk_mpu_kernel_data")))

#define STK_MPU_KERNEL_CODE_SECTION __attribute__((section(".stk_mpu_kernel_code")))

#define STK_MPU_KERNEL_BSS_SECTION __attribute__((section(".stk_mpu_kernel_bss")))
 
#else
 
#define STK_MPU_SHARED_DATA_SECTION
#define STK_MPU_SHARED_CODE_SECTION
#define STK_MPU_SHARED_BSS_SECTION
#define STK_MPU_KERNEL_DATA_SECTION
#define STK_MPU_KERNEL_CODE_SECTION
#define STK_MPU_KERNEL_BSS_SECTION
 
// =============================================================================
#endif // STK_MPU
// =============================================================================
 
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();

bool IsPrivilegedContext();
 
// 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

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

class CriticalSection
{
public:
    enum ESessionFlags : uint8_t
    {
        SESSION_FLAG_NONE  = 0U,        
        SESSION_FLAG_NPRIV = (1U << 0), 
    };

    typedef uint8_t Session;

    static constexpr Session DEFAULT_SESSION = SESSION_FLAG_NONE;

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

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

    static Session Enter(const Session ses = DEFAULT_SESSION);

    static void Exit(const Session ses = DEFAULT_SESSION);
 
private:
    STK_NONCOPYABLE_CLASS(CriticalSection);

    explicit CriticalSection()
    {}
};

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

    class ScopedLock
    {
    public:
        explicit ScopedLock(SpinLock &sl) : m_sl(sl)
        {
            sl.Lock();
        }

        ~ScopedLock()
        {
            m_sl.Unlock();
        }
 
    private:
        STK_NONCOPYABLE_CLASS(ScopedLock);
        SpinLock &m_sl;
    };

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

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

#ifndef _STK_CORTEX_M_TRUSTZONE_NON_SECURE
static constexpr TId GetTidFromUserTask(const ITask *task) noexcept { return hw::PtrToWord(task); }
#else
TId GetTidFromUserTask(const ITask *task);
#endif

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

#ifndef _STK_CUSTOM_MEMCPY
static inline 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

#ifndef _STK_CUSTOM_MEMSET
static inline void STK_MEMSET(void *const dest, const uint8_t value, const size_t size)
{
    using namespace stk;
 
    if ((dest != nullptr) && (size != 0U))
    {
        const Word dest_addr = hw::PtrToWord(dest);
 
        // fast path: destination and size are 4-byte aligned, fill in 4-byte chunks
        if (((dest_addr & 0x03U) == 0U) &&
            ((size      & 0x03U) == 0U))
        {
            uint32_t *const p_d32  = static_cast<uint32_t *>(dest);
            const uint32_t  word   = static_cast<uint32_t>(value) * 0x01010101U;
            const size_t    words  = (size >> 2U);
 
            STK_UNUSED(std::fill_n(p_d32, words, word));
        }
        // slow path
        else
        {
            uint8_t *const p_d = static_cast<uint8_t *>(dest);
 
            STK_UNUSED(std::fill_n(p_d, size, value));
        }
    }
}
#endif
 
#endif /* STK_ARCH_H_ */