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
 
namespace stk {

#define STK_KERNEL_PANIC(id)                         \
    do {                                             \
        __stk_debug_break();   /* debug aid */       \
        STK_PANIC_HANDLER(id); /* must not return */ \
    } while (0)

namespace hw {

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

template <typename T>
__stk_forceinline 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_DEFINED,
// GetTls and SetTls are provided as inline functions there and the declarations below
// are suppressed to avoid duplicate definitions.
#if !_STK_INLINE_TLS_DEFINED

Word GetTls();

void SetTls(Word tp);
 
#endif // _STK_INLINE_TLS_DEFINED

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

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>
__stk_forceinline T ReadVolatile64(volatile const T *addr)
{
    STK_STATIC_ASSERT_N(sz, sizeof(T) == 8);  // only 64-bit types permitted
    STK_STATIC_ASSERT_N(al, alignof(T) >= 4); // type must be at least 4-byte aligned
 
    if (sizeof(void *) == 8) // 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.
        volatile const uint32_t *plo = &((volatile const uint32_t *)addr)[STK_ENDIAN_IDX_LO];
        volatile const uint32_t *phi = &((volatile const uint32_t *)addr)[STK_ENDIAN_IDX_HI];
 
        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
 
        return ((uint64_t)hi << 32) | lo;
    }
}

template <typename T>
__stk_forceinline void WriteVolatile64(volatile T *addr, T value)
{
    STK_STATIC_ASSERT_N(sz, sizeof(T) == 8);  // only 64-bit types permitted
    STK_STATIC_ASSERT_N(al, alignof(T) >= 4); // type must be at least 4-byte aligned
 
    if (sizeof(void *) == 8) // 64-bit arch: aligned 64-bit store is inherently atomic
    {
        (*addr) = value;
    }
    else
    {
        volatile uint32_t *plo = &((volatile uint32_t *)addr)[STK_ENDIAN_IDX_LO];
        volatile uint32_t *phi = &((volatile uint32_t *)addr)[STK_ENDIAN_IDX_HI];
 
        // 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) = (uint32_t)(value >> 32);
        __stk_full_memfence();
 
        (*plo) = (uint32_t)value;
    }
}

struct HiResClock
{
    static Cycles GetCycles();

    static uint32_t GetFrequency();

    static inline Ticks GetTimeUs()
    {
        uint32_t freq = GetFrequency();
        STK_ASSERT(freq != 0); // guaranteed non-zero
 
        return static_cast<Ticks>((GetCycles() * 1000000ULL) / freq);
    }
};
 
} // namespace hw

inline bool ISyncObject::Tick(Timeout elapsed_ticks)
{
    // note: ScopedCriticalSection usage
    //
    // Single-core: no critical section needed - Tick() runs inside the
    // SysTick ISR which already executes with interrupts disabled, making
    // re-entrancy impossible on the local core.
    //
    // Multi-core: critical section is required because the tick handler on
    // each core may call Tick() concurrently for the same Semaphore instance,
    // and ISyncObject::Tick() is not re-entrant.
#if (STK_ARCH_CPU_COUNT > 1)
    hw::CriticalSection::ScopedLock cs_;
#endif
 
    IWaitObject *itr = static_cast<IWaitObject *>(m_wait_list.GetFirst());
 
    while (itr != nullptr)
    {
        IWaitObject *next = static_cast<IWaitObject *>(itr->GetNext());
 
        if (!itr->Tick(elapsed_ticks))
            itr->Wake(true);
 
        itr = next;
    }
 
    return !m_wait_list.IsEmpty();
}
 
} // namespace stk
 
#ifndef STK_PANIC_HANDLER
    extern void STK_PANIC_HANDLER_DEFAULT(stk::EKernelPanicId id);
    #define STK_PANIC_HANDLER(id) STK_PANIC_HANDLER_DEFAULT(id)
#endif
 
#endif /* STK_ARCH_H_ */