stk_c.h

Go to the documentation of this file.

/*
 * SuperTinyKernel™ (STK): 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_
 
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include <assert.h>

 
#ifdef __cplusplus
extern "C" {
#endif
 
// ─────────────────────────────────────────────────────────────────────────────
// 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)

#if defined(__GNUC__) || defined(__clang__) || defined(__ICCARM__)
    #define __stk_c_stack_attr __attribute__((aligned(16)))
#else
    #define __stk_c_stack_attr
#endif
 
// ─────────────────────────────────────────────────────────────────────────────
// Types
// ─────────────────────────────────────────────────────────────────────────────

typedef uintptr_t stk_word_t;

typedef stk_word_t stk_tid_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);

#define STK_WAIT_INFINITE (INT32_MAX)

#define STK_NO_WAIT (0)
 
// ─────────────────────────────────────────────────────────────────────────────
// 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);
 
// ─────────────────────────────────────────────────────────────────────────────
// 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 *task);

void stk_kernel_add_task_hrt(stk_kernel_t *k,
                             stk_task_t *task,
                             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 *task);

void stk_kernel_start(stk_kernel_t *k);

typedef enum _EKernelState {
    STK_KERNEL_STATE_INACTIVE = 0, 
    STK_KERNEL_STATE_READY    = 1, 
    STK_KERNEL_STATE_RUNNING  = 2  
} EKernelState;

EKernelState stk_kernel_get_state(const stk_kernel_t *k);

bool stk_kernel_is_schedulable(const stk_kernel_t *k);
 
// ─────────────────────────────────────────────────────────────────────────────
// Task creation
// ─────────────────────────────────────────────────────────────────────────────

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 *task, uint32_t weight);

void stk_task_set_priority(stk_task_t *task, uint8_t priority);

void stk_task_set_id(stk_task_t *task, uint32_t tid);

void stk_task_set_name(stk_task_t *task, const char *tname);
 
// ─────────────────────────────────────────────────────────────────────────────
// Services available from inside tasks
// ─────────────────────────────────────────────────────────────────────────────

stk_tid_t stk_tid(void);

int64_t stk_ticks(void);

int32_t stk_tick_resolution(void);

int64_t stk_ticks_from_ms(int64_t msec);

static inline int64_t stk_ticks_from_ms_r(int64_t msec, int32_t resolution)
{
    return msec * 1000 / resolution;
}

int64_t stk_time_now_ms(void);

void stk_delay(uint32_t ticks);

void stk_delay_ms(uint32_t ms);

void stk_sleep(uint32_t ticks);

void stk_sleep_ms(uint32_t ms);

void stk_sleep_until(int64_t ts);

void stk_yield(void);
 
// ─────────────────────────────────────────────────────────────────────────────
// Dynamic cleanup
// ─────────────────────────────────────────────────────────────────────────────

void stk_kernel_destroy(stk_kernel_t *k);

void stk_task_destroy(stk_task_t *task);
 
// ─────────────────────────────────────────────────────────────────────────────
// Thread-Local Storage (very simple / one pointer per task)
// ─────────────────────────────────────────────────────────────────────────────

void *stk_tls_get(void);

void stk_tls_set(void *ptr);

#define STK_TLS_GET(type) ((type *)stk_tls_get())

#define STK_TLS_SET(ptr) stk_tls_set((void *)(ptr))

 
// ─────────────────────────────────────────────────────────────────────────────
// Synchronization Primitives
// ─────────────────────────────────────────────────────────────────────────────
 
// ───── Critical Section ──────────────────────────────────────────────────────

void stk_critical_section_enter(void);

void stk_critical_section_exit(void);
 
// ───── Mutex ─────────────────────────────────────────────────────────────────

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

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

typedef struct stk_mutex_t stk_mutex_t;

stk_mutex_t *stk_mutex_create(stk_mutex_mem_t *memory, uint32_t memory_size);

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, int32_t timeout);
 
// ───── SpinLock ──────────────────────────────────────────────────────────────

#define STK_SPINLOCK_IMPL_SIZE (1)

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

typedef struct stk_spinlock_t stk_spinlock_t;

stk_spinlock_t *stk_spinlock_create(stk_spinlock_mem_t *memory, uint32_t memory_size);

void stk_spinlock_destroy(stk_spinlock_t *lock);

void stk_spinlock_lock(stk_spinlock_t *lock);

bool stk_spinlock_trylock(stk_spinlock_t *lock);

void stk_spinlock_unlock(stk_spinlock_t *lock);
 
// ───── Condition Variable ────────────────────────────────────────────────────

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

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

typedef struct stk_cv_t stk_cv_t;

stk_cv_t *stk_cv_create(stk_cv_mem_t *memory, uint32_t memory_size);

void stk_cv_destroy(stk_cv_t *cv);

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

void stk_cv_notify_one(stk_cv_t *cv);

void stk_cv_notify_all(stk_cv_t *cv);
 
// ───── Event ─────────────────────────────────────────────────────────────────

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

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

typedef struct stk_event_t stk_event_t;

stk_event_t *stk_event_create(stk_event_mem_t *memory, uint32_t memory_size, bool manual_reset);

void stk_event_destroy(stk_event_t *ev);

bool stk_event_wait(stk_event_t *ev, int32_t timeout);

bool stk_event_trywait(stk_event_t *ev);

void stk_event_set(stk_event_t *ev);

void stk_event_reset(stk_event_t *ev);

void stk_event_pulse(stk_event_t *ev);
 
// ───── Semaphore ─────────────────────────────────────────────────────────────

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

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

typedef struct stk_sem_t stk_sem_t;

stk_sem_t *stk_sem_create(stk_sem_mem_t *memory, uint32_t memory_size, uint32_t initial_count);

void stk_sem_destroy(stk_sem_t *sem);

bool stk_sem_wait(stk_sem_t *sem, int32_t timeout);

void stk_sem_signal(stk_sem_t *sem);
 
// ───── 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_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 + 1 + (STK_SYNC_DEBUG_NAMES ? 1 : 0))

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

typedef struct stk_ef_t stk_ef_t;

stk_ef_t *stk_ef_create(stk_ef_mem_t *memory, uint32_t memory_size, 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, int32_t timeout);

uint32_t stk_ef_trywait(stk_ef_t *ef, uint32_t flags, uint32_t options);
 
// ───── Pipe (FIFO) ───────────────────────────────────────────────────────────

#define STK_PIPE_SIZE 16

#define STK_PIPE_IMPL_SIZE ((27 + (STK_SYNC_DEBUG_NAMES ? 3 : 0)) + STK_PIPE_SIZE)

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

typedef struct stk_pipe_t stk_pipe_t;

stk_pipe_t *stk_pipe_create(stk_pipe_mem_t *memory, uint32_t memory_size);

void stk_pipe_destroy(stk_pipe_t *pipe);

bool stk_pipe_write(stk_pipe_t *pipe, stk_word_t data, int32_t timeout);

bool stk_pipe_read(stk_pipe_t *pipe, stk_word_t *data, int32_t timeout);

size_t stk_pipe_write_bulk(stk_pipe_t *pipe, const stk_word_t *src, size_t count, int32_t timeout);

size_t stk_pipe_read_bulk(stk_pipe_t *pipe, stk_word_t *dst, size_t count, int32_t timeout);

size_t stk_pipe_get_size(stk_pipe_t *pipe);
 
// ───── RWMutex (Reader-Writer Lock) ──────────────────────────────────────────

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

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

typedef struct stk_rwmutex_t stk_rwmutex_t;

stk_rwmutex_t *stk_rwmutex_create(stk_rwmutex_mem_t *memory, uint32_t memory_size);

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, int32_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, int32_t timeout);

void stk_rwmutex_unlock(stk_rwmutex_t *rw);
 
#ifdef __cplusplus
}
#endif

 
#endif /* STK_C_H_ */