stk_c.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_C_H_
#define STK_C_H_
 
#ifdef __cplusplus
    #include <cstdint>
    #include <cstddef>
    #include <cstdbool>
    #include <cassert>
#else
    #include <stdint.h>
    #include <stddef.h>
    #include <stdbool.h>
    #include <assert.h>
#endif
 
#include <stk_config.h>

 
#ifdef __cplusplus
extern "C" {
#endif

#define STK_C_VERSION (0x20261004)
 
// =============================================================================
// Configuration macros (can be overridden before including this file)
// =============================================================================

#ifndef STK_C_KERNEL_MAX_TASKS
    #define STK_C_KERNEL_MAX_TASKS (4)
#endif

#ifndef STK_C_CPU_COUNT
    #define STK_C_CPU_COUNT (1)
#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

#define STK_C_ASSERT(e) assert(e)
  
#ifdef __cplusplus
    #define STK_STATIC_CAST(type, val) static_cast<type>(val)
#else
    #define STK_STATIC_CAST(type, val) ((type)(val))
#endif
 
// =============================================================================
// Types
// =============================================================================

typedef uintptr_t stk_word_t;

typedef stk_word_t stk_tid_t;

typedef int64_t stk_tick_t;

typedef int64_t stk_time_t;

typedef int32_t stk_timeout_t;

typedef uint64_t stk_cycle_t;

typedef int32_t stk_weight_t;

typedef struct stk_kernel_t stk_kernel_t;

typedef struct stk_task_t stk_task_t;

#define STK_PERIODICITY_DEFAULT (1000U) 

typedef void (*stk_task_entry_t)(void *arg);

typedef enum stk_wait_result_t {
    STK_WAIT_RESULT_FAIL     = -1, 
    STK_WAIT_RESULT_SIGNAL   = 0,  
    STK_WAIT_RESULT_TIMEOUT  = 1,  
    STK_WAIT_RESULT_CANCELED = 2   
} stk_wait_result_t;

#define STK_WAIT_INFINITE (STK_STATIC_CAST(stk_timeout_t, INT32_MAX))

#define STK_NO_WAIT (STK_STATIC_CAST(stk_timeout_t, 0))

#define STK_ALIGN_SIZE sizeof(stk_word_t)

#define STK_ALIGN_MASK (STK_ALIGN_SIZE - 1U)

#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

#define STK_DEFINE_STACK_POOL(name, max_tasks, stack_size) \
    static stk_word_t name[max_tasks][stack_size] __stk_c_stack

#define STK_GET_STACK_FROM_POOL(name, task_id) (name[task_id])
   
// =============================================================================
// Attributes
// =============================================================================

#if defined(__GNUC__) || defined(__clang__) || defined(__ICCARM__)
    #define __stk_c_stack __attribute__((aligned(STK_STACK_MEMORY_ALIGN)))
#else
    #define __stk_c_stack
#endif

#if defined(__GNUC__) || defined(__clang__) || defined(__ICCARM__)
    #define __stk_c_aligned __attribute__((aligned(STK_ALIGN_SIZE)))
#else
    #define __stk_c_aligned
#endif
 
// =============================================================================
// Kernel factory functions
// =============================================================================
 
/* Available kernel type definitions:
 
   Kernel mode flags (may be OR-combined, subject to the constraints listed below):
     KERNEL_STATIC   - fixed task list; tasks must never return from their entry function.
     KERNEL_DYNAMIC  - tasks may be added/removed at runtime and may return when done.
     KERNEL_HRT      - Hard Real-Time mode; must be combined with KERNEL_STATIC or KERNEL_DYNAMIC.
     KERNEL_SYNC     - enables synchronization primitives (Mutex, Event, Semaphore, etc.).
     KERNEL_TICKLESS - tickless low-power idle; suppresses the SysTick when all tasks sleep.
                       Requires STK_TICKLESS_IDLE=1 in stk_config.h.
                       INCOMPATIBLE with KERNEL_HRT (HRT requires a continuous tick).
 
// Standard variants
Kernel<KERNEL_STATIC,  STK_C_KERNEL_MAX_TASKS, SwitchStrategyRR, PlatformDefault>
Kernel<KERNEL_DYNAMIC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyRR, PlatformDefault>
Kernel<KERNEL_STATIC,  STK_C_KERNEL_MAX_TASKS, SwitchStrategySWRR, PlatformDefault>
Kernel<KERNEL_DYNAMIC, STK_C_KERNEL_MAX_TASKS, SwitchStrategySWRR, PlatformDefault>
Kernel<KERNEL_STATIC,  STK_C_KERNEL_MAX_TASKS, SwitchStrategyFP32, PlatformDefault>
Kernel<KERNEL_DYNAMIC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyFP32, PlatformDefault>
 
// HRT variants (KERNEL_TICKLESS must NOT be combined with any of these)
Kernel<KERNEL_STATIC  | KERNEL_HRT, STK_C_KERNEL_MAX_TASKS, SwitchStrategyRR, PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_HRT, STK_C_KERNEL_MAX_TASKS, SwitchStrategyRR, PlatformDefault>
Kernel<KERNEL_STATIC  | KERNEL_HRT, STK_C_KERNEL_MAX_TASKS, SwitchStrategyRM, PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_HRT, STK_C_KERNEL_MAX_TASKS, SwitchStrategyRM, PlatformDefault>
Kernel<KERNEL_STATIC  | KERNEL_HRT, STK_C_KERNEL_MAX_TASKS, SwitchStrategyDM, PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_HRT, STK_C_KERNEL_MAX_TASKS, SwitchStrategyDM, PlatformDefault>
Kernel<KERNEL_STATIC  | KERNEL_HRT, STK_C_KERNEL_MAX_TASKS, SwitchStrategyEDF, PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_HRT, STK_C_KERNEL_MAX_TASKS, SwitchStrategyEDF, PlatformDefault>
 
// Standard variants with KERNEL_SYNC
Kernel<KERNEL_STATIC  | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyRR,   PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyRR,   PlatformDefault>
Kernel<KERNEL_STATIC  | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategySWRR, PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategySWRR, PlatformDefault>
Kernel<KERNEL_STATIC  | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyFP32, PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyFP32, PlatformDefault>
 
// HRT variants with KERNEL_SYNC
Kernel<KERNEL_STATIC  | KERNEL_HRT | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyRR,  PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_HRT | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyRR,  PlatformDefault>
Kernel<KERNEL_STATIC  | KERNEL_HRT | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyRM,  PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_HRT | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyRM,  PlatformDefault>
Kernel<KERNEL_STATIC  | KERNEL_HRT | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyDM,  PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_HRT | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyDM,  PlatformDefault>
Kernel<KERNEL_STATIC  | KERNEL_HRT | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyEDF, PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_HRT | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyEDF, PlatformDefault>
 
// Tickless variants (low-power; KERNEL_TICKLESS requires STK_TICKLESS_IDLE=1 in stk_config.h)
Kernel<KERNEL_STATIC  | KERNEL_TICKLESS, STK_C_KERNEL_MAX_TASKS, SwitchStrategyRR,   PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_TICKLESS, STK_C_KERNEL_MAX_TASKS, SwitchStrategyRR,   PlatformDefault>
Kernel<KERNEL_STATIC  | KERNEL_TICKLESS, STK_C_KERNEL_MAX_TASKS, SwitchStrategySWRR, PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_TICKLESS, STK_C_KERNEL_MAX_TASKS, SwitchStrategySWRR, PlatformDefault>
Kernel<KERNEL_STATIC  | KERNEL_TICKLESS, STK_C_KERNEL_MAX_TASKS, SwitchStrategyFP32, PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_TICKLESS, STK_C_KERNEL_MAX_TASKS, SwitchStrategyFP32, PlatformDefault>
 
// Tickless variants with KERNEL_SYNC
Kernel<KERNEL_STATIC  | KERNEL_TICKLESS | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyRR,   PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_TICKLESS | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyRR,   PlatformDefault>
Kernel<KERNEL_STATIC  | KERNEL_TICKLESS | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategySWRR, PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_TICKLESS | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategySWRR, PlatformDefault>
Kernel<KERNEL_STATIC  | KERNEL_TICKLESS | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyFP32, PlatformDefault>
Kernel<KERNEL_DYNAMIC | KERNEL_TICKLESS | KERNEL_SYNC, STK_C_KERNEL_MAX_TASKS, SwitchStrategyFP32, PlatformDefault>
*/


stk_kernel_t *stk_kernel_create(uint8_t core_nr);
 
#ifdef __cplusplus
namespace stk { class IKernel; }

extern "C" stk::IKernel *stk_kernel_get_instance(uint8_t core_nr);
#endif // __cplusplus
 
// =============================================================================
// Kernel control
// =============================================================================

void stk_kernel_init(stk_kernel_t *k, uint32_t tick_period_us);

void stk_kernel_add_task(stk_kernel_t *k, stk_task_t *tsk);

void stk_kernel_add_task_hrt(stk_kernel_t *k,
                             stk_task_t   *tsk,
                             int32_t       periodicity_ticks,
                             int32_t       deadline_ticks,
                             int32_t       start_delay_ticks);

void stk_kernel_remove_task(stk_kernel_t *k, stk_task_t *tsk);

void stk_kernel_start(stk_kernel_t *k);

typedef enum stk_kernel_state_t {
    STK_KERNEL_STATE_INACTIVE  = 0, 
    STK_KERNEL_STATE_READY     = 1, 
    STK_KERNEL_STATE_RUNNING   = 2, 
    STK_KERNEL_STATE_SUSPENDED = 3  
} stk_kernel_state_t;

stk_kernel_state_t stk_kernel_get_state(const stk_kernel_t *k);

bool stk_kernel_is_schedulable(const stk_kernel_t *k);

bool stk_kernel_is_started(const stk_kernel_t *k);

void stk_kernel_schedule_task_removal(stk_kernel_t *k, stk_task_t *task);

void stk_kernel_suspend_task(stk_kernel_t *k, stk_task_t *task, bool *suspended);

void stk_kernel_resume_task(stk_kernel_t *k, stk_task_t *task);

stk_timeout_t stk_kernel_suspend(stk_kernel_t *k);

void stk_kernel_resume(stk_kernel_t *k, stk_timeout_t elapsed_ticks);

size_t stk_kernel_enumerate_tasks(stk_kernel_t *k, stk_task_t **tasks, size_t max_count);

void stk_kernel_process_tick(stk_kernel_t *k);

void stk_kernel_process_hard_fault(stk_kernel_t *k);
 
// =============================================================================
// Platform event overrider
// =============================================================================

typedef struct stk_event_overrider_t
{
    bool (*on_sleep)(stk_timeout_t sleep_ticks, void *user_data);

    bool (*on_hard_fault)(void *user_data);

    void *user_data;
} stk_event_overrider_t;

void stk_kernel_set_event_overrider(stk_kernel_t *k, stk_event_overrider_t *overrider);
 
// =============================================================================
// Tasks
// =============================================================================

stk_task_t *stk_task_create_privileged(stk_task_entry_t  entry,
                                       void             *arg,
                                       stk_word_t       *stack,
                                       uint32_t          stack_size);

stk_task_t *stk_task_create_user(stk_task_entry_t  entry,
                                 void             *arg,
                                 stk_word_t       *stack,
                                 uint32_t          stack_size);

void stk_task_set_weight(stk_task_t *tsk, stk_weight_t weight);

void stk_task_set_priority(stk_task_t *tsk, uint8_t priority);

void stk_task_set_name(stk_task_t *tsk, const char *tname);

const char *stk_task_get_name(const stk_task_t *tsk);

stk_tid_t stk_task_get_id(const stk_task_t *tsk);
 
#ifdef __cplusplus
namespace stk { class ITask; }

extern "C" stk::ITask *stk_task_get_instance(stk_task_t *tsk);
#endif // __cplusplus
 
// =============================================================================
// Services available from inside tasks
// =============================================================================

stk_tid_t stk_tid(void);

stk_tick_t stk_ticks(void);

uint32_t stk_tick_resolution(void);

stk_tick_t stk_ticks_from_ms(stk_time_t msec);

stk_timeout_t stk_ticks_from_ms_clamped_to_timeout(stk_timeout_t ms);

static inline stk_tick_t stk_ticks_from_ms_r(stk_time_t msec, uint32_t resolution)
{
    stk_time_t result = 0LL;
    
    if (resolution != 0U)
    {
        const stk_time_t total_scaled = msec * 1000LL;
        result = total_scaled / STK_STATIC_CAST(stk_time_t, resolution);
    }
 
    return STK_STATIC_CAST(stk_tick_t, result);
}

stk_time_t stk_time_now_ms(void);

static inline stk_time_t stk_ms_from_ticks_r(stk_tick_t ticks, uint32_t resolution)
{
    const stk_tick_t total_ticks = ticks * STK_STATIC_CAST(stk_tick_t, resolution);
    return STK_STATIC_CAST(stk_time_t, total_ticks / 1000LL);
}

static inline stk_time_t stk_ms_from_ticks(stk_tick_t ticks)
{
    return stk_ms_from_ticks_r(ticks, stk_tick_resolution());
}

stk_cycle_t stk_sys_timer_count(void);

uint32_t stk_sys_timer_frequency(void);
 
// =============================================================================
// High-Resolution Clock  (see hw::HiResClock)
// =============================================================================

stk_cycle_t stk_hires_cycles(void);

uint32_t stk_hires_frequency(void);

stk_tick_t stk_hires_time_us(void);

void stk_delay(stk_timeout_t ticks);

void stk_delay_ms(stk_timeout_t ms);

void stk_sleep(stk_timeout_t ticks);

void stk_sleep_ms(stk_timeout_t ms);

bool stk_sleep_until(stk_tick_t ts);

void stk_yield(void);

void stk_sleep_cancel(stk_tid_t tid);
 
// =============================================================================
// Dynamic cleanup
// =============================================================================

void stk_kernel_destroy(stk_kernel_t *k);

void stk_task_destroy(stk_task_t *tsk);
 
// =============================================================================
// Thread-Local Storage (TLS)
// =============================================================================


void *stk_tls_get(void);

void stk_tls_set(void *ptr);

#define STK_TLS_GET_T(type) ((type *)stk_tls_get())

#define STK_TLS_SET_T(ptr) stk_tls_set((void *)(ptr))
 
// =============================================================================
// Synchronization Primitives
// =============================================================================
 
// ----- Critical Section ------------------------------------------------------

typedef uint8_t stk_cs_session_t;

#define STK_DEFAULT_CS_SESSION (0U)

stk_cs_session_t stk_critical_section_enter_ex(stk_cs_session_t ses /*= STK_DEFAULT_CS_SESSION*/);

void stk_critical_section_exit_ex(stk_cs_session_t ses /*= STK_DEFAULT_CS_SESSION*/);

void stk_critical_section_enter();

void stk_critical_section_exit();
 
// ----- Mutex -----------------------------------------------------------------

#define STK_MUTEX_IMPL_SIZE (10U + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))

typedef struct stk_mutex_mem_t {
    stk_word_t data[STK_MUTEX_IMPL_SIZE] __stk_c_aligned;
} stk_mutex_mem_t;

typedef struct stk_mutex_t stk_mutex_t;

stk_mutex_t *stk_mutex_create(stk_mutex_mem_t *const membuf);

void stk_mutex_destroy(stk_mutex_t *mtx);

void stk_mutex_lock(stk_mutex_t *mtx);

bool stk_mutex_trylock(stk_mutex_t *mtx);

void stk_mutex_unlock(stk_mutex_t *mtx);

bool stk_mutex_timed_lock(stk_mutex_t *mtx, stk_timeout_t timeout);

stk_wait_result_t stk_mutex_timed_lock_ex(stk_mutex_t *mtx, stk_timeout_t timeout);
 
#ifdef __cplusplus
namespace stk { namespace sync { class Mutex; } }

extern "C" stk::sync::Mutex *stk_mutex_get_instance(stk_mutex_t *mtx);
#endif // __cplusplus
 
// ----- FastMutex -------------------------------------------------------------

#define STK_FASTMUTEX_IMPL_SIZE (9U + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))

typedef struct stk_fastmutex_mem_t {
    stk_word_t data[STK_FASTMUTEX_IMPL_SIZE] __stk_c_aligned;
} stk_fastmutex_mem_t;

typedef struct stk_fastmutex_t stk_fastmutex_t;

stk_fastmutex_t *stk_fastmutex_create(stk_fastmutex_mem_t *const membuf);

void stk_fastmutex_destroy(stk_fastmutex_t *mtx);

void stk_fastmutex_lock(stk_fastmutex_t *mtx);

bool stk_fastmutex_trylock(stk_fastmutex_t *mtx);

void stk_fastmutex_unlock(stk_fastmutex_t *mtx);

bool stk_fastmutex_timed_lock(stk_fastmutex_t *mtx, stk_timeout_t timeout);

stk_wait_result_t stk_fastmutex_timed_lock_ex(stk_fastmutex_t *mtx, stk_timeout_t timeout);
 
#ifdef __cplusplus
namespace stk { namespace sync { class FastMutex; } }

extern "C" stk::sync::FastMutex *stk_fastmutex_get_instance(stk_fastmutex_t *mtx);
#endif // __cplusplus
 
// ----- SpinLock --------------------------------------------------------------

#define STK_SPINLOCK_IMPL_SIZE (6)

typedef struct {
    stk_word_t data[STK_SPINLOCK_IMPL_SIZE] __stk_c_aligned;
} stk_spinlock_mem_t;

typedef struct stk_spinlock_t stk_spinlock_t;

stk_spinlock_t *stk_spinlock_create(stk_spinlock_mem_t *const membuf);

void stk_spinlock_destroy(stk_spinlock_t *slock);

void stk_spinlock_lock(stk_spinlock_t *slock);

bool stk_spinlock_trylock(stk_spinlock_t *slock);

void stk_spinlock_unlock(stk_spinlock_t *slock);
 
#ifdef __cplusplus
namespace stk { namespace sync { class SpinLock; } }

extern "C" stk::sync::SpinLock *stk_spinlock_get_instance(stk_spinlock_t *slock);
#endif // __cplusplus
 
// ----- Condition Variable ----------------------------------------------------

#define STK_CV_IMPL_SIZE (7U + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))

typedef struct stk_cv_mem_t {
    stk_word_t data[STK_CV_IMPL_SIZE] __stk_c_aligned;
} stk_cv_mem_t;

typedef struct stk_cv_t stk_cv_t;

stk_cv_t *stk_cv_create(stk_cv_mem_t *const membuf);

void stk_cv_destroy(stk_cv_t *cv);

bool stk_cv_wait(stk_cv_t *cv, stk_mutex_t *mtx, stk_timeout_t timeout);

stk_wait_result_t stk_cv_wait_ex(stk_cv_t *cv, stk_mutex_t *mtx, stk_timeout_t timeout);

bool stk_cv_wait_fastmutex(stk_cv_t *cv, stk_fastmutex_t *mtx, stk_timeout_t timeout);

stk_wait_result_t stk_cv_wait_ex_fastmutex(stk_cv_t *cv, stk_fastmutex_t *mtx, stk_timeout_t timeout);

void stk_cv_notify_one(stk_cv_t *cv);

void stk_cv_notify_all(stk_cv_t *cv);
 
#ifdef __cplusplus
namespace stk { namespace sync { class ConditionVariable; } }

extern "C" stk::sync::ConditionVariable *stk_cv_get_instance(stk_cv_t *cv);
#endif // __cplusplus
 
// ----- Event -----------------------------------------------------------------

#define STK_EVENT_IMPL_SIZE (8U + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))

typedef struct stk_event_mem_t {
    stk_word_t data[STK_EVENT_IMPL_SIZE] __stk_c_aligned;
} stk_event_mem_t;

typedef struct stk_event_t stk_event_t;

stk_event_t *stk_event_create(stk_event_mem_t *const membuf, 
                              bool             manual_reset);

void stk_event_destroy(stk_event_t *ev);

bool stk_event_wait(stk_event_t *ev, stk_timeout_t timeout);

stk_wait_result_t stk_event_wait_ex(stk_event_t *ev, stk_timeout_t timeout);

bool stk_event_trywait(stk_event_t *ev);

bool stk_event_set(stk_event_t *ev);

bool stk_event_reset(stk_event_t *ev);

void stk_event_pulse(stk_event_t *ev);
 
#ifdef __cplusplus
namespace stk { namespace sync { class Event; } }

extern "C" stk::sync::Event *stk_event_get_instance(stk_event_t *ev);
#endif // __cplusplus
 
// ----- Semaphore -------------------------------------------------------------

#define STK_SEM_IMPL_SIZE (8U + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))

typedef struct stk_sem_mem_t {
    stk_word_t data[STK_SEM_IMPL_SIZE] __stk_c_aligned;
} stk_sem_mem_t;

typedef struct stk_sem_t stk_sem_t;

stk_sem_t *stk_sem_create(stk_sem_mem_t *const membuf,
                          uint32_t       initial_count, 
                          uint32_t       max_count);

void stk_sem_destroy(stk_sem_t *sem);

bool stk_sem_wait(stk_sem_t *sem, stk_timeout_t timeout);

stk_wait_result_t stk_sem_wait_ex(stk_sem_t *sem, stk_timeout_t timeout);

bool stk_sem_trywait(stk_sem_t *sem);

void stk_sem_signal(stk_sem_t *sem);

bool stk_sem_trysignal(stk_sem_t *sem);

uint16_t stk_sem_get_count(const stk_sem_t *sem);
 
#ifdef __cplusplus
namespace stk { namespace sync { class Semaphore; } }

extern "C" stk::sync::Semaphore *stk_sem_get_instance(stk_sem_t *sem);
#endif // __cplusplus
 
// ----- EventFlags ------------------------------------------------------------

#define STK_EF_OPT_WAIT_ANY (0x00000000U) 
#define STK_EF_OPT_WAIT_ALL (0x00000001U) 
#define STK_EF_OPT_NO_CLEAR (0x00000002U) 

#define STK_EF_ERROR_PARAMETER (0x80000001U) 
#define STK_EF_ERROR_TIMEOUT   (0x80000002U) 
#define STK_EF_ERROR_ISR       (0x80000004U) 
#define STK_EF_ERROR_CANCELED  (0x80000008U) 
#define STK_EF_ERROR_MASK      (0x80000000U) 

static inline bool stk_ef_is_error(uint32_t result) 
{ 
    return ((result & STK_EF_ERROR_MASK) != 0U); 
}

#define STK_EF_IMPL_SIZE (STK_CV_IMPL_SIZE + 1U + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))

typedef struct stk_ef_mem_t {
    stk_word_t data[STK_EF_IMPL_SIZE] __stk_c_aligned;
} stk_ef_mem_t;

typedef struct stk_ef_t stk_ef_t;

stk_ef_t *stk_ef_create(stk_ef_mem_t *const membuf,
                        uint32_t      initial_flags);

void stk_ef_destroy(stk_ef_t *ef);

uint32_t stk_ef_set(stk_ef_t *ef, uint32_t flags);

uint32_t stk_ef_clear(stk_ef_t *ef, uint32_t flags);

uint32_t stk_ef_get(stk_ef_t *ef);

uint32_t stk_ef_wait(stk_ef_t *ef, uint32_t flags, uint32_t options, stk_timeout_t timeout);

uint32_t stk_ef_trywait(stk_ef_t *ef, uint32_t flags, uint32_t options);
 
#ifdef __cplusplus
namespace stk { namespace sync { class EventFlags; } }

extern "C" stk::sync::EventFlags *stk_ef_get_instance(stk_ef_t *ef);
#endif // __cplusplus
 
// ----- Pipe (FIFO) -----------------------------------------------------------

#define STK_PIPE_IMPL_SIZE (6U + (2U * STK_CV_IMPL_SIZE) + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))

typedef struct stk_pipe_mem_t {
    stk_word_t data[STK_PIPE_IMPL_SIZE] __stk_c_aligned;
} stk_pipe_mem_t;

typedef struct stk_pipe_t stk_pipe_t;

#define STK_PIPE_BUF_SIZE(capacity, element_size) \
    ((((capacity) * (element_size)) + STK_ALIGN_MASK) & ~STK_ALIGN_MASK)

stk_pipe_t *stk_pipe_create(stk_pipe_mem_t *const membuf,
                            uint8_t        *buf,
                            uint32_t        buf_size,
                            size_t          capacity,
                            size_t          element_size);

void stk_pipe_destroy(stk_pipe_t *pipe);

bool stk_pipe_write(stk_pipe_t *pipe, const void *data, stk_timeout_t timeout);

stk_wait_result_t stk_pipe_write_ex(stk_pipe_t *pipe, const void *data, stk_timeout_t timeout);

bool stk_pipe_trywrite(stk_pipe_t *pipe, const void *data);

bool stk_pipe_read(stk_pipe_t *pipe, void *data, stk_timeout_t timeout);

stk_wait_result_t stk_pipe_read_ex(stk_pipe_t *pipe, void *data, stk_timeout_t timeout);

bool stk_pipe_tryread(stk_pipe_t *pipe, void *data);

size_t stk_pipe_write_bulk(stk_pipe_t *pipe, const void *src, size_t count, stk_timeout_t timeout);

stk_wait_result_t stk_pipe_write_bulk_ex(stk_pipe_t *pipe, const void *src, size_t count,
                                         size_t *written, stk_timeout_t timeout);

size_t stk_pipe_trywrite_bulk(stk_pipe_t *pipe, const void *src, size_t count);

size_t stk_pipe_read_bulk(stk_pipe_t *pipe, void *dst, size_t count, stk_timeout_t timeout);

stk_wait_result_t stk_pipe_read_bulk_ex(stk_pipe_t *pipe, void *dst, size_t count,
                                        size_t *read_count, stk_timeout_t timeout);

size_t stk_pipe_tryread_bulk(stk_pipe_t *pipe, void *dst, size_t count);

size_t stk_pipe_read_bulk_triggered(stk_pipe_t   *pipe,
                                    void         *dst,
                                    size_t        trigger,
                                    size_t        max_count,
                                    stk_timeout_t timeout);

stk_wait_result_t stk_pipe_read_bulk_triggered_ex(stk_pipe_t   *pipe,
                                                  void         *dst,
                                                  size_t        trigger,
                                                  size_t        max_count,
                                                  size_t       *read_count,
                                                  stk_timeout_t timeout);

size_t stk_pipe_tryread_bulk_triggered(stk_pipe_t *pipe, void *dst, size_t max_count);

void stk_pipe_reset(stk_pipe_t *pipe);

size_t stk_pipe_get_capacity(const stk_pipe_t *pipe);

size_t stk_pipe_get_element_size(const stk_pipe_t *pipe);

size_t stk_pipe_get_count(const stk_pipe_t *pipe);

size_t stk_pipe_get_space(const stk_pipe_t *pipe);

bool stk_pipe_is_empty(const stk_pipe_t *pipe);

bool stk_pipe_is_full(const stk_pipe_t *pipe);

bool stk_pipe_is_storage_valid(const stk_pipe_t *pipe);
 
#ifdef __cplusplus
namespace stk { namespace sync { class Pipe; } }

extern "C" stk::sync::Pipe *stk_pipe_get_instance(stk_pipe_t *pipe);
#endif // __cplusplus
 
// ----- MessageQueue ----------------------------------------------------------

#define STK_MSGQ_IMPL_SIZE (6U + (2U * STK_CV_IMPL_SIZE) + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))

typedef struct stk_msgq_mem_t {
    stk_word_t data[STK_MSGQ_IMPL_SIZE] __stk_c_aligned;
} stk_msgq_mem_t;

typedef struct stk_msgq_t stk_msgq_t;

#define STK_MSGQ_BUF_SIZE(capacity, msg_size) ((capacity) * (msg_size))

stk_msgq_t *stk_msgq_create(stk_msgq_mem_t *const membuf,
                            uint8_t        *buf,
                            uint32_t        buf_size,
                            size_t          capacity,
                            size_t          msg_size);

void stk_msgq_destroy(stk_msgq_t *mq);

bool stk_msgq_put(stk_msgq_t *mq, const void *msg, stk_timeout_t timeout);

stk_wait_result_t stk_msgq_put_ex(stk_msgq_t *mq, const void *msg, stk_timeout_t timeout);

bool stk_msgq_tryput(stk_msgq_t *mq, const void *msg);

bool stk_msgq_putfront(stk_msgq_t *mq, const void *msg, stk_timeout_t timeout);

stk_wait_result_t stk_msgq_putfront_ex(stk_msgq_t *mq, const void *msg, stk_timeout_t timeout);

bool stk_msgq_tryputfront(stk_msgq_t *mq, const void *msg);

bool stk_msgq_get(stk_msgq_t *mq, void *msg, stk_timeout_t timeout);

stk_wait_result_t stk_msgq_get_ex(stk_msgq_t *mq, void *msg, stk_timeout_t timeout);

bool stk_msgq_tryget(stk_msgq_t *mq, void *msg);

bool stk_msgq_peek(stk_msgq_t *mq, void *msg, stk_timeout_t timeout);

stk_wait_result_t stk_msgq_peek_ex(stk_msgq_t *mq, void *msg, stk_timeout_t timeout);

bool stk_msgq_trypeek(stk_msgq_t *mq, void *msg);

bool stk_msgq_peekfront(stk_msgq_t *mq, void *msg, stk_timeout_t timeout);

stk_wait_result_t stk_msgq_peekfront_ex(stk_msgq_t *mq, void *msg, stk_timeout_t timeout);

bool stk_msgq_trypeekfront(stk_msgq_t *mq, void *msg);

void stk_msgq_reset(stk_msgq_t *mq);

size_t stk_msgq_get_capacity(const stk_msgq_t *mq);

size_t stk_msgq_get_msg_size(const stk_msgq_t *mq);

size_t stk_msgq_get_count(const stk_msgq_t *mq);

size_t stk_msgq_get_space(const stk_msgq_t *mq);

bool stk_msgq_is_empty(const stk_msgq_t *mq);

uint8_t *stk_msgq_get_buffer(stk_msgq_t *mq);

bool stk_msgq_is_full(const stk_msgq_t *mq);

bool stk_msgq_is_storage_valid(const stk_msgq_t *mq);
 
#ifdef __cplusplus
namespace stk { namespace sync { class MessageQueue; } }

extern "C" stk::sync::MessageQueue *stk_msgq_get_instance(stk_msgq_t *mq);
#endif // __cplusplus
 
// ----- RWMutex (Reader-Writer Lock) ------------------------------------------

#define STK_RWMUTEX_IMPL_SIZE (17U + (STK_SYNC_DEBUG_NAMES ? 3U : 0U))

typedef struct stk_rwmutex_mem_t {
    stk_word_t data[STK_RWMUTEX_IMPL_SIZE] __stk_c_aligned;
} stk_rwmutex_mem_t;

typedef struct stk_rwmutex_t stk_rwmutex_t;

stk_rwmutex_t *stk_rwmutex_create(stk_rwmutex_mem_t *const membuf);

void stk_rwmutex_destroy(stk_rwmutex_t *rw);

void stk_rwmutex_read_lock(stk_rwmutex_t *rw);

bool stk_rwmutex_try_read_lock(stk_rwmutex_t *rw);

bool stk_rwmutex_timed_read_lock(stk_rwmutex_t *rw, stk_timeout_t timeout);

stk_wait_result_t stk_rwmutex_timed_read_lock_ex(stk_rwmutex_t *rw, stk_timeout_t timeout);

void stk_rwmutex_read_unlock(stk_rwmutex_t *rw);

void stk_rwmutex_lock(stk_rwmutex_t *rw);

bool stk_rwmutex_trylock(stk_rwmutex_t *rw);

bool stk_rwmutex_timed_lock(stk_rwmutex_t *rw, stk_timeout_t timeout);

stk_wait_result_t stk_rwmutex_timed_lock_ex(stk_rwmutex_t *rw, stk_timeout_t timeout);

void stk_rwmutex_unlock(stk_rwmutex_t *rw);
 
#ifdef __cplusplus
namespace stk { namespace sync { class RWMutex; } }

extern "C" stk::sync::RWMutex *stk_rwmutex_get_instance(stk_rwmutex_t *rw);
#endif // __cplusplus
 
// ----- Barrier -----------------------------------------------------------------

#define STK_BARRIER_IMPL_SIZE (STK_MUTEX_IMPL_SIZE + STK_CV_IMPL_SIZE + 4U + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))

typedef struct stk_barrier_mem_t {
    stk_word_t data[STK_BARRIER_IMPL_SIZE] __stk_c_aligned;
} stk_barrier_mem_t;

typedef struct stk_barrier_t stk_barrier_t;

stk_barrier_t *stk_barrier_create(stk_barrier_mem_t *const membuf, uint32_t count);

void stk_barrier_destroy(stk_barrier_t *barrier);

typedef enum stk_barrier_result_t {
    STK_BARRIER_RELEASED     = 0, 
    STK_BARRIER_LAST_ARRIVAL = 1, 
    STK_BARRIER_CANCELED     = 2  
} stk_barrier_result_t;

bool stk_barrier_wait(stk_barrier_t *barrier);

stk_barrier_result_t stk_barrier_wait_ex(stk_barrier_t *barrier);

uint32_t stk_barrier_get_threshold(const stk_barrier_t *barrier);
 
#ifdef __cplusplus
namespace stk { namespace sync { class Barrier; } }

extern "C" stk::sync::Barrier *stk_barrier_get_instance(stk_barrier_t *barrier);
#endif // __cplusplus
 
#ifdef __cplusplus
}
#endif
 
#ifdef __cplusplus
namespace stk {
template <typename T, typename Mem, typename... Args>
static inline T *ConstructIn(Mem &mem, Args &&... args)
{
    STK_STATIC_ASSERT_DESC((sizeof(T) <= sizeof(Mem)),
        "stk_*_mem_t is too small for the C++ object");
    STK_STATIC_ASSERT_DESC((alignof(T) <= alignof(Mem)),
        "stk_*_mem_t is not sufficiently aligned for the C++ object");
 
    STK_ASSERT((reinterpret_cast<uintptr_t>(mem.data) % alignof(T)) == 0U);
 
    return new (static_cast<void *>(mem.data)) T(static_cast<Args &&>(args)...);
}
} // namespace stk
#endif // __cplusplus

 
#endif /* STK_C_H_ */