stk_defs.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_DEFS_H_
#define STK_DEFS_H_
 
#include <cstddef>
#include <cstdint>
#include <algorithm>
#ifdef __ICCARM__
    #include <intrinsics.h>
    #if (__IAR_SYSTEMS_ICC__ < 8)
        #error "Only IAR EWARM 8.0 and higher is supported by STK."
    #endif
#endif

#include "stk_config.h"

#ifndef STK_TICKLESS_IDLE
    #define STK_TICKLESS_IDLE (0)
#endif
      
#ifndef STK_STRICT_COMPLIANCY
    #define STK_STRICT_COMPLIANCY (0)
#endif

#ifndef STK_TICKLESS_USE_ARM_DWT
    #define STK_TICKLESS_USE_ARM_DWT (1)
#endif

#ifndef STK_TICKLESS_TICKS_MAX
    #define STK_TICKLESS_TICKS_MAX (1000)
#endif
#if STK_TICKLESS_TICKS_MAX > 100000
    #error "STK_TICKLESS_TICKS_MAX is too large: cpu_ticks_requested may overflow uint32_t."
#endif

#ifndef STK_TLS
    #define STK_TLS (0)
#endif

#ifndef STK_TLS_PREFER_REGISTER
    #ifdef _STK_ARCH_RISC_V
        #define STK_TLS_PREFER_REGISTER (1)
    #else
        #define STK_TLS_PREFER_REGISTER (0)
    #endif
#endif

#ifndef STK_MPU
    #define STK_MPU (0)
#endif

#ifndef STK_MPU_STACK_GUARD
    #define STK_MPU_STACK_GUARD (0)
#endif

#ifndef STK_MPU_TASK_REGIONS
    #define STK_MPU_TASK_REGIONS (2)
#endif
 
#if STK_MPU_STACK_GUARD && (STK_MPU_TASK_REGIONS != 2) && (STK_MPU_TASK_REGIONS != 4)
    #error "STK_MPU_TASK_REGIONS must be defined as 2 or 4"
#endif

#if STK_SEGGER_SYSVIEW || STK_MPU_STACK_GUARD
    #ifndef STK_STACK_NEEDS_TASK_ID
        #define STK_STACK_NEEDS_TASK_ID (1)
    #endif
#endif

#if !defined(STK_SYNC_DEBUG_NAMES) && STK_SEGGER_SYSVIEW
    #define STK_SYNC_DEBUG_NAMES (1)
#elif !defined(STK_SYNC_DEBUG_NAMES)
    #define STK_SYNC_DEBUG_NAMES (0)
#endif

#if !STK_STRICT_COMPLIANCY
    #define STK_VIRT_DTOR
#else
    #define STK_VIRT_DTOR virtual
#endif

#if defined(__GNUC__) || defined(__ICCARM__)
    #define __stk_forceinline __attribute__((always_inline)) inline
#elif defined(_MSC_VER)
    #define __stk_forceinline __forceinline
#else
    #define __stk_forceinline inline
#endif

#if defined(__GNUC__) || defined(__ICCARM__)
    #define __stk_aligned(x) __attribute__((aligned(x)))
#else
    #define __stk_aligned(x)
#endif

#if defined(__GNUC__) || defined(__clang__) || defined(__ICCARM__) || defined(__CC_ARM) || defined(__ARMCC_VERSION)
    #define __stk_weak __attribute__((weak))
#else
    #define __stk_weak
#endif

#if defined(__GNUC__) || defined(__ICCARM__)
    #define __stk_attr_naked __attribute__((naked))
#else
    #define __stk_attr_naked
#endif

#if defined(__GNUC__) || defined(__ICCARM__)
    #define __stk_attr_noreturn __attribute__((__noreturn__))
#else
    #define __stk_attr_noreturn
#endif

#if defined(__GNUC__) || defined(__ICCARM__)
    #define __stk_attr_unused __attribute__((unused))
#else
    #define __stk_attr_unused
#endif

#if defined(__GNUC__) || defined(__ICCARM__)
    #define __stk_attr_used __attribute__((used))
#else
    #define __stk_attr_used
#endif

#if defined(__GNUC__) || defined(__ICCARM__)
    #define __stk_attr_noinline __attribute__((noinline))
#else
    #define __stk_attr_noinline
#endif

#if defined(__GNUC__) || defined(__ICCARM__)
    #define __stk_attr_deprecated __attribute__((deprecated))
#elif defined(_MSC_VER)
    #define __stk_attr_deprecated __declspec(deprecated)
#else
    #define __stk_attr_deprecated
#endif

#if defined(__GNUC__) || defined(__clang__)
    static __stk_forceinline void __stk_full_memfence() { __sync_synchronize(); }
#elif defined(__ICCARM__)
    static __stk_forceinline void __stk_full_memfence() { __DMB(); }
#elif defined(_MSC_VER)
    static __stk_forceinline void __stk_full_memfence() { __stk_dmb(); }
#else
    #error "__stk_full_memfence() is not implemented for this compiler. Add a definition to stk_defs.h."
#endif

#if defined(__GNUC__) || defined(__clang__) || defined(__ICCARM__)
    static __stk_forceinline void __stk_compiler_barrier() { __asm volatile("" ::: "memory"); }
#elif defined(_MSC_VER)
    static __stk_forceinline void __stk_compiler_barrier() { _ReadWriteBarrier(); }
#else
    #error "__stk_compiler_barrier() is not implemented for this compiler. Add a definition to stk_defs.h."
#endif

#ifndef __stk_relax_cpu
#if defined(__GNUC__) || defined(__clang__)
    #if defined(__i386__) || defined(__x86_64__)
    static __stk_forceinline void __stk_relax_cpu() { __builtin_ia32_pause(); }
    #elif defined(__riscv)
        #ifdef __riscv_zihintpause
            static __stk_forceinline void __stk_relax_cpu() { __builtin_riscv_pause(); }
        #else
            static __stk_forceinline void __stk_relax_cpu() { __asm volatile("nop" ::: "memory"); }
        #endif
    #elif defined(__ARM_ARCH) || defined(_STK_ARCH_ARM_CORTEX_M)
            static __stk_forceinline void __stk_relax_cpu() { __asm volatile("yield" ::: "memory"); }
    #else
            static __stk_forceinline void __stk_relax_cpu() { __asm volatile("" ::: "memory"); }
    #endif
#elif defined(__ICCARM__)
    static __stk_forceinline void __stk_relax_cpu() { __asm volatile("YIELD"); }
#elif defined(_MSC_VER)
    #include <intrin.h>
    #if defined(_M_IX86) || defined(_M_X64)
        static __stk_forceinline void __stk_relax_cpu() { _mm_pause(); }
    #elif defined(_M_ARM) || defined(_M_ARM64)
        static __stk_forceinline void __stk_relax_cpu() { __yield(); }
    #else
        static __stk_forceinline void __stk_relax_cpu() { __stk_full_memfence(); }
    #endif
#else
    #error "__stk_relax_cpu() is not implemented for this compiler. Add a definition to stk_defs.h."
#endif
#endif

#if defined(DEBUG) || defined(_DEBUG)
    #if defined(_STK_ARCH_ARM_CORTEX_M)
        static __stk_forceinline void __stk_debug_break() { __asm volatile("bkpt 0"); }
    #elif defined(_STK_ARCH_RISC_V)
        static __stk_forceinline void __stk_debug_break() { __asm volatile("ebreak"); }
    #elif defined(_STK_ARCH_X86_WIN32)
        #ifdef _MSC_VER
            static __stk_forceinline void __stk_debug_break() { __debugbreak(); }
        #else
            static __stk_forceinline void __stk_debug_break() { __asm volatile("int $3"); }
        #endif
    #endif
#else
    static __stk_forceinline void __stk_debug_break() {}
#endif

#if (__cplusplus >= 201703L) || (defined(_MSVC_LANG) && (_MSVC_LANG >= 201703L))
    #define __stk_constexpr_cpp17 constexpr
#else
    #define __stk_constexpr_cpp17
#endif

#ifdef _STK_ASSERT_REDIRECT
    extern void STK_ASSERT_HANDLER(const char *, const char *, int32_t);
    #define STK_ASSERT(e) ((e) ? (void)0 : STK_ASSERT_HANDLER(#e, __FILE__, __LINE__))
#else
    #if defined(DEBUG) || defined(_DEBUG)
        #include <cassert>
        #define STK_ASSERT(e) assert(e)
    #else
        #define STK_ASSERT(e)
    #endif
#endif

#define STK_STATIC_ASSERT_DESC_N(NAME, X, DESC) static_assert((X), DESC)

#define STK_STATIC_ASSERT_DESC(X, DESC) STK_STATIC_ASSERT_DESC_N(_, X, DESC)

#define STK_STATIC_ASSERT_N(NAME, X) STK_STATIC_ASSERT_DESC_N(N, (X), #X)

#define STK_STATIC_ASSERT(X) STK_STATIC_ASSERT_DESC_N(_, (X), #X)

#ifndef STK_STACK_MEMORY_FILLER
    #define STK_STACK_MEMORY_FILLER (static_cast<stk::Word>((sizeof(stk::Word) <= 4U) ? 0xDEADBEEFU : 0xDEADBEEFDEADBEEFULL))
#endif

#ifndef STK_STACK_MEMORY_ALIGN
    #if defined(__riscv)
        #define STK_STACK_MEMORY_ALIGN (16U)
    #elif defined(__i386__) || defined(__x86_64__) || defined(_M_IX86) || defined(_M_X64)
        #define STK_STACK_MEMORY_ALIGN (8U)
    #else // ARM, others
        #define STK_STACK_MEMORY_ALIGN (4U)
    #endif
#endif

#ifndef STK_CS_NESTINGS_MAX
    #define STK_CS_NESTINGS_MAX (16U)
#endif

#ifndef STK_ARCH_CPU_COUNT
    #define STK_ARCH_CPU_COUNT (1U)
#endif

#ifndef STK_STACK_SIZE_MIN
    #ifdef __riscv
        #if defined(__riscv_32e) && (__riscv_32e == 1)
            // RISC-V RV32E (Embedded): Small 16-register file.
            #if !defined(__riscv_flen) || (__riscv_flen == 0)
                #define STK_STACK_SIZE_MIN (32U)
            #else
                // FPU present: Requires additional space for 32 FP registers.
                #define STK_STACK_SIZE_MIN (32U + (__riscv_flen * 2))
            #endif
        #else
            // Standard RISC-V (RV32I/RV64I): Large 32-register file.
            // Higher minimum to prevent memory corruption on platforms like RP2350.
            #if !defined(__riscv_flen) || (__riscv_flen == 0)
                #define STK_STACK_SIZE_MIN (256U)
            #else
                // Standard RISC-V with FPU: Maximum frame allocation.
                #define STK_STACK_SIZE_MIN (512U + (__riscv_flen * 2))
            #endif
        #endif
    #else
        // ARM Cortex-M and other architectures
        #define STK_STACK_SIZE_MIN (32U)
    #endif
#endif

#ifndef STK_SLEEP_TRAP_STACK_SIZE
    #define STK_SLEEP_TRAP_STACK_SIZE (STK_STACK_SIZE_MIN)
#endif

template <size_t MODE, size_t FLAG, size_t ONTRUE, size_t ONFALSE>
struct STK_ALLOCATE_COUNT
{
#if defined(_MSC_VER) || defined(__ICCARM__)
    // MSVC and IAR builds may over-allocate when the flag is not set to avoid compile errors.
    static constexpr size_t Value = ((ONTRUE > ONFALSE) ? ONTRUE : ONFALSE);
#else
    // GCC and Clang support zero-sized array extensions natively.
    static constexpr size_t Value = (((MODE & FLAG) != 0U) ? ONTRUE : ONFALSE);
#endif
};

#if defined(__BYTE_ORDER__) && (__BYTE_ORDER__ == __ORDER_BIG_ENDIAN__)
    #define STK_ENDIAN_IDX_HI (0U) // big-endian: high word at index 0
    #define STK_ENDIAN_IDX_LO (1U) // big-endian: low word at index 1
#else
    #define STK_ENDIAN_IDX_HI (1U) // little-endian (default): high word at index 1
    #define STK_ENDIAN_IDX_LO (0U) // little-endian (default): low word at index 0
#endif

#define STK_NONCOPYABLE_CLASS(TYPE)\
    TYPE(const TYPE &) = delete;\
    TYPE &operator=(const TYPE &) = delete;

#define STK_UNUSED(X) static_cast<void>((X))

#if __cplusplus >= 202002L
    #define STK_LIKELY(x)   ([&]() { if (!!(x)) [[likely]] { return true; } else { return false; } }())
    #define STK_UNLIKELY(x) ([&]() { if (!!(x)) { return true; } else [[unlikely]] { return false; } }())
#elif defined(__GNUC__) || defined(__clang__)
    #define STK_LIKELY(x)   __builtin_expect(!!(x), 1)
    #define STK_UNLIKELY(x) __builtin_expect(!!(x), 0)
#else
    #define STK_LIKELY(x)   (x)
    #define STK_UNLIKELY(x) (x)
#endif

#define STK_STATIC_ARRAY_SIZE(ARRAY) static_cast<size_t>(sizeof(ARRAY) / sizeof(ARRAY[0]))

namespace stk {

template <typename T>
static constexpr T Min(T a, T b) noexcept { return ((a < b) ? a : b); }

template <typename T>
static constexpr T Max(T a, T b) noexcept { return ((a > b) ? a : b); }

template <typename T>
static constexpr T Align(T v, T align) noexcept
{
    return ((v + align - static_cast<T>(1U)) / align) * align;
}

template <typename T>
static constexpr T AlignPow2(T v, T align) noexcept
{
    return (v + align - static_cast<T>(1U)) & ~(align - static_cast<T>(1U));
}

static __stk_forceinline uint32_t CountLeadingZeros(const uint32_t value) noexcept
{
    uint32_t ret_val;
    uint32_t temp_val = value;
 
#if defined(__GNUC__) || defined(__clang__)
    ret_val = static_cast<uint32_t>(__builtin_clz(temp_val));
#elif defined(__ICCARM__)
    ret_val = static_cast<uint32_t>(__CLZ(temp_val));
#else
    uint32_t count = 0U;
 
    // note: binary search requires temp_val > 0 to resolve to a max of 31 leading zeros safely
    if (temp_val <= 0x0000FFFFU) { count += 16U; temp_val = temp_val << 16U; } else { }
    if (temp_val <= 0x00FFFFFFU) { count += 8U;  temp_val = temp_val << 8U;  } else { }
    if (temp_val <= 0x0FFFFFFFU) { count += 4U;  temp_val = temp_val << 4U;  } else { }
    if (temp_val <= 0x3FFFFFFFU) { count += 2U;  temp_val = temp_val << 2U;  } else { }
    if (temp_val <= 0x7FFFFFFFU) { count += 1U; } else { }
 
    ret_val = count;
#endif
 
    return ret_val;
}

namespace util {}
 
} // namespace stk

#ifndef _STK_CUSTOM_MEMCPY
static void STK_MEMCPY(void *const dest, const void *const src, const size_t size);
#endif

#ifndef _STK_CUSTOM_MEMSET
static void STK_MEMSET(void *const dest, const uint8_t value, const size_t size);
#endif
 
#endif /* STK_DEFS_H_ */