stk_c.h File Reference

C language binding/interface for SuperTinyKernel (STK). More...

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include <assert.h>

Include dependency graph for stk_c.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	stk_mutex_mem_t
	Opaque memory container for a Mutex instance. More...
struct	stk_spinlock_mem_t
	Opaque memory container for SpinLock object. More...
struct	stk_cv_mem_t
	Opaque memory container for a ConditionVariable instance. More...
struct	stk_event_mem_t
	Opaque memory container for an Event instance. More...
struct	stk_sem_mem_t
	Opaque memory container for a Semaphore instance. More...
struct	stk_ef_mem_t
	Opaque memory container for an EventFlags instance. More...
struct	stk_pipe_mem_t
	Opaque memory container for a Pipe instance. More...
struct	stk_rwmutex_mem_t
	Opaque memory container for an RWMutex instance. More...

Macros
#define	STK_C_KERNEL_MAX_TASKS   (4)
	Maximum number of tasks per kernel instance (default: 4).
#define	STK_C_CPU_COUNT   (1)
	Number of kernel instances / CPU cores supported (default: 1).
#define	STK_SYNC_DEBUG_NAMES   (0)
	Enable names for synchronization primitives for debugging/tracing purpose.
#define	STK_C_ASSERT(e)
	Assertion macro used inside STK C bindings.
#define	__stk_c_stack_attr
	Stack attribute (applies required alignment).
#define	STK_PERIODICITY_DEFAULT   (1000U)
	Default tick period (1 ms).
#define	STK_WAIT_INFINITE   (INT32_MAX)
	Infinite timeout constant.
#define	STK_NO_WAIT   (0)
	No timeout constant.
#define	STK_TLS_GET(type)
	Typed helper for getting TLS value.
#define	STK_TLS_SET(ptr)
	Typed helper for setting TLS value.
#define	STK_MUTEX_IMPL_SIZE   (10 + (STK_SYNC_DEBUG_NAMES ? 1 : 0))
	A memory size (multiples of stk_word_t) required for Mutex instance.
#define	STK_SPINLOCK_IMPL_SIZE   (1)
	A memory size (multiples of stk_word_t) required for SpinLock instance.
#define	STK_CV_IMPL_SIZE   (7 + (STK_SYNC_DEBUG_NAMES ? 1 : 0))
	A memory size (multiples of stk_word_t) required for ConditionVariable instance.
#define	STK_EVENT_IMPL_SIZE   (8 + (STK_SYNC_DEBUG_NAMES ? 1 : 0))
	A memory size (multiples of stk_word_t) required for Event instance.
#define	STK_SEM_IMPL_SIZE   (8 + (STK_SYNC_DEBUG_NAMES ? 1 : 0))
	A memory size (multiples of stk_word_t) required for Semaphore instance.
#define	STK_EF_OPT_WAIT_ANY   (0x00000000U)
	Options bitmask constants for stk_ef_wait() / stk_ef_trywait().
#define	STK_EF_OPT_WAIT_ALL   (0x00000001U)
#define	STK_EF_OPT_NO_CLEAR   (0x00000002U)
#define	STK_EF_ERROR_PARAMETER   (0x80000001U)
	Return-value error sentinels (bit 31 set indicates an error).
#define	STK_EF_ERROR_TIMEOUT   (0x80000002U)
#define	STK_EF_ERROR_ISR   (0x80000004U)
#define	STK_EF_ERROR_MASK   (0x80000000U)
#define	STK_EF_IMPL_SIZE   (STK_CV_IMPL_SIZE + 1 + (STK_SYNC_DEBUG_NAMES ? 1 : 0))
	A memory size (multiples of stk_word_t) required for EventFlags instance.
#define	STK_PIPE_SIZE   16
	Size of the Pipe: Pipe<stk_word_t, STK_PIPE_SIZE>.
#define	STK_PIPE_IMPL_SIZE   ((27 + (STK_SYNC_DEBUG_NAMES ? 3 : 0)) + STK_PIPE_SIZE)
	A memory size (multiples of stk_word_t) required for Pipe instance.
#define	STK_RWMUTEX_IMPL_SIZE   (17 + (STK_SYNC_DEBUG_NAMES ? 3 : 0))
	A memory size (multiples of stk_word_t) required for RWMutex instance.

Typedefs
typedef uintptr_t	stk_word_t
	CPU register type.
typedef stk_word_t	stk_tid_t
	Task id.
typedef struct stk_kernel_t	stk_kernel_t
	Opaque handle to a kernel instance.
typedef struct stk_task_t	stk_task_t
	Opaque handle to a task instance.
typedef void(*	stk_task_entry_t) (void *arg)
	Task entry point function type.
typedef enum _EKernelState	EKernelState
	Kernel state.
typedef struct stk_mutex_mem_t	stk_mutex_mem_t
	Opaque memory container for a Mutex instance.
typedef struct stk_mutex_t	stk_mutex_t
	Opaque handle to a Mutex instance.
typedef struct stk_spinlock_t	stk_spinlock_t
	Opaque handle to a SpinLock instance.
typedef struct stk_cv_mem_t	stk_cv_mem_t
	Opaque memory container for a ConditionVariable instance.
typedef struct stk_cv_t	stk_cv_t
	Opaque handle to a Condition Variable instance.
typedef struct stk_event_mem_t	stk_event_mem_t
	Opaque memory container for an Event instance.
typedef struct stk_event_t	stk_event_t
	Opaque handle to an Event instance.
typedef struct stk_sem_mem_t	stk_sem_mem_t
	Opaque memory container for a Semaphore instance.
typedef struct stk_sem_t	stk_sem_t
	Opaque handle to a Semaphore instance.
typedef struct stk_ef_mem_t	stk_ef_mem_t
	Opaque memory container for an EventFlags instance.
typedef struct stk_ef_t	stk_ef_t
	Opaque handle to an EventFlags instance.
typedef struct stk_pipe_mem_t	stk_pipe_mem_t
	Opaque memory container for a Pipe instance.
typedef struct stk_pipe_t	stk_pipe_t
	Opaque handle to a Pipe instance.
typedef struct stk_rwmutex_mem_t	stk_rwmutex_mem_t
	Opaque memory container for an RWMutex instance.
typedef struct stk_rwmutex_t	stk_rwmutex_t
	Opaque handle to an RWMutex instance.

Enumerations
enum	_EKernelState {   STK_KERNEL_STATE_INACTIVE = 0 ,   STK_KERNEL_STATE_READY = 1 ,   STK_KERNEL_STATE_RUNNING = 2 }
	Kernel state. More...

Functions
stk_kernel_t *	stk_kernel_create (uint8_t core_nr)
	Create kernel.
void	stk_kernel_init (stk_kernel_t *k, uint32_t tick_period_us)
	Initialize kernel with given tick period.
void	stk_kernel_add_task (stk_kernel_t *k, stk_task_t *task)
	Add task to non-HRT kernel (static or dynamic).
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)
	Add task with HRT timing parameters (HRT kernels only).
void	stk_kernel_remove_task (stk_kernel_t *k, stk_task_t *task)
	Remove finished task from dynamic kernel.
void	stk_kernel_start (stk_kernel_t *k)
	Start the scheduler - never returns.
EKernelState	stk_kernel_get_state (const stk_kernel_t *k)
	Get state of the scheduler.
bool	stk_kernel_is_schedulable (const stk_kernel_t *k)
	Test whether currently configured task set is schedulable.
stk_task_t *	stk_task_create_privileged (stk_task_entry_t entry, void *arg, stk_word_t *stack, uint32_t stack_size)
	Create privileged-mode (kernel-mode) task.
stk_task_t *	stk_task_create_user (stk_task_entry_t entry, void *arg, stk_word_t *stack, uint32_t stack_size)
	Create user-mode task.
void	stk_task_set_weight (stk_task_t *task, uint32_t weight)
	Set task weight (used only by Smooth Weighted Round Robin).
void	stk_task_set_priority (stk_task_t *task, uint8_t priority)
	Set task priority (used only by Fixed Priority scheduler).
void	stk_task_set_id (stk_task_t *task, uint32_t tid)
	Assign application-defined task ID (for tracing/debugging).
void	stk_task_set_name (stk_task_t *task, const char *tname)
	Assign human-readable task name (for tracing/debugging).
stk_tid_t	stk_tid (void)
	Returns current task/thread ID (the value set by stk_task_set_id).
int64_t	stk_ticks (void)
	Returns number of ticks elapsed since kernel start.
int32_t	stk_tick_resolution (void)
	Returns how many microseconds correspond to one kernel tick.
int64_t	stk_ticks_from_ms (int64_t msec)
	Get ticks from milliseconds using current kernel tick resolution.
static int64_t	stk_ticks_from_ms_r (int64_t msec, int32_t resolution)
	Get ticks from milliseconds using an explicit tick resolution.
int64_t	stk_time_now_ms (void)
	Returns current time in milliseconds since kernel start.
void	stk_delay (uint32_t ticks)
	Busy-wait delay (other tasks continue to run).
void	stk_delay_ms (uint32_t ms)
	Busy-wait delay (other tasks continue to run).
void	stk_sleep (uint32_t ticks)
	Put current task to sleep (non-HRT kernels only).
void	stk_sleep_ms (uint32_t ms)
	Put current task to sleep (non-HRT kernels only).
void	stk_sleep_until (int64_t ts)
	Put current task to sleep (non-HRT kernels only).
void	stk_yield (void)
	Voluntarily give up CPU to another ready task (cooperative yield).
void	stk_kernel_destroy (stk_kernel_t *k)
	Destroy dynamic kernel instance (only when not running).
void	stk_task_destroy (stk_task_t *task)
	Destroy dynamically created task object.
void *	stk_tls_get (void)
	Get thread-local pointer (platform-specific slot).
void	stk_tls_set (void *ptr)
	Set thread-local pointer.
void	stk_critical_section_enter (void)
	Enter critical section — disable context switches on current core.
void	stk_critical_section_exit (void)
	Leave critical section — re-enable context switches.
stk_mutex_t *	stk_mutex_create (stk_mutex_mem_t *memory, uint32_t memory_size)
	Create a Mutex (using provided memory).
void	stk_mutex_destroy (stk_mutex_t *mtx)
	Destroy a Mutex.
void	stk_mutex_lock (stk_mutex_t *mtx)
	Lock the mutex. Blocks until available.
bool	stk_mutex_trylock (stk_mutex_t *mtx)
	Try locking the mutex. Does not block if already locked.
void	stk_mutex_unlock (stk_mutex_t *mtx)
	Unlock the mutex.
bool	stk_mutex_timed_lock (stk_mutex_t *mtx, int32_t timeout)
	Try to lock the mutex with a timeout.
stk_spinlock_t *	stk_spinlock_create (stk_spinlock_mem_t *memory, uint32_t memory_size)
	Create a recursive SpinLock.
void	stk_spinlock_destroy (stk_spinlock_t *lock)
	Destroy the SpinLock.
void	stk_spinlock_lock (stk_spinlock_t *lock)
	Acquire the SpinLock (recursive).
bool	stk_spinlock_trylock (stk_spinlock_t *lock)
	Attempt to acquire the SpinLock immediately.
void	stk_spinlock_unlock (stk_spinlock_t *lock)
	Release the SpinLock.
stk_cv_t *	stk_cv_create (stk_cv_mem_t *memory, uint32_t memory_size)
	Create a Condition Variable (using provided memory).
void	stk_cv_destroy (stk_cv_t *cv)
	Destroy a Condition Variable.
bool	stk_cv_wait (stk_cv_t *cv, stk_mutex_t *mtx, int32_t timeout)
	Wait for a signal on the condition variable.
void	stk_cv_notify_one (stk_cv_t *cv)
	Wake one task waiting on the condition variable.
void	stk_cv_notify_all (stk_cv_t *cv)
	Wake all tasks waiting on the condition variable.
stk_event_t *	stk_event_create (stk_event_mem_t *memory, uint32_t memory_size, bool manual_reset)
	Create an Event (using provided memory).
void	stk_event_destroy (stk_event_t *ev)
	Destroy an Event.
bool	stk_event_wait (stk_event_t *ev, int32_t timeout)
	Wait for the event to become signaled.
bool	stk_event_trywait (stk_event_t *ev)
	Wait for the event to become signaled.
void	stk_event_set (stk_event_t *ev)
	Set the event to signaled state.
void	stk_event_reset (stk_event_t *ev)
	Reset the event to non-signaled state.
void	stk_event_pulse (stk_event_t *ev)
	Pulse the event (signal then immediately reset).
stk_sem_t *	stk_sem_create (stk_sem_mem_t *memory, uint32_t memory_size, uint32_t initial_count)
	Create a Semaphore (using provided memory).
void	stk_sem_destroy (stk_sem_t *sem)
	Destroy a Semaphore.
bool	stk_sem_wait (stk_sem_t *sem, int32_t timeout)
	Wait for a semaphore resource.
void	stk_sem_signal (stk_sem_t *sem)
	Signal/Release a semaphore resource.
static bool	stk_ef_is_error (uint32_t result)
	Returns true if a value returned by stk_ef_set(), stk_ef_clear(), stk_ef_wait(), or stk_ef_trywait() is an error sentinel (bit 31 set).
stk_ef_t *	stk_ef_create (stk_ef_mem_t *memory, uint32_t memory_size, uint32_t initial_flags)
	Create an EventFlags object (using provided memory).
void	stk_ef_destroy (stk_ef_t *ef)
	Destroy an EventFlags object.
uint32_t	stk_ef_set (stk_ef_t *ef, uint32_t flags)
	Set one or more flags.
uint32_t	stk_ef_clear (stk_ef_t *ef, uint32_t flags)
	Clear one or more flags.
uint32_t	stk_ef_get (stk_ef_t *ef)
	Read the current flags word without modifying it.
uint32_t	stk_ef_wait (stk_ef_t *ef, uint32_t flags, uint32_t options, int32_t timeout)
	Wait for one or more flags to be set.
uint32_t	stk_ef_trywait (stk_ef_t *ef, uint32_t flags, uint32_t options)
	Non-blocking flag poll.
stk_pipe_t *	stk_pipe_create (stk_pipe_mem_t *memory, uint32_t memory_size)
	Create a Pipe (using provided memory).
void	stk_pipe_destroy (stk_pipe_t *pipe)
	Destroy a Pipe.
bool	stk_pipe_write (stk_pipe_t *pipe, stk_word_t data, int32_t timeout)
	Write data to the pipe.
bool	stk_pipe_read (stk_pipe_t *pipe, stk_word_t *data, int32_t timeout)
	Read data from the pipe.
size_t	stk_pipe_write_bulk (stk_pipe_t *pipe, const stk_word_t *src, size_t count, int32_t timeout)
	Write multiple elements to the pipe.
size_t	stk_pipe_read_bulk (stk_pipe_t *pipe, stk_word_t *dst, size_t count, int32_t timeout)
	Read multiple elements from the pipe.
size_t	stk_pipe_get_size (stk_pipe_t *pipe)
	Get current number of elements in the pipe.
stk_rwmutex_t *	stk_rwmutex_create (stk_rwmutex_mem_t *memory, uint32_t memory_size)
	Create an RWMutex (using provided memory).
void	stk_rwmutex_destroy (stk_rwmutex_t *rw)
	Destroy an RWMutex.
void	stk_rwmutex_read_lock (stk_rwmutex_t *rw)
	Acquire the lock for shared reading. Blocks until available.
bool	stk_rwmutex_try_read_lock (stk_rwmutex_t *rw)
	Try to acquire the read lock without blocking.
bool	stk_rwmutex_timed_read_lock (stk_rwmutex_t *rw, int32_t timeout)
	Try to acquire the read lock with a timeout.
void	stk_rwmutex_read_unlock (stk_rwmutex_t *rw)
	Release the shared reader lock.
void	stk_rwmutex_lock (stk_rwmutex_t *rw)
	Acquire the lock for exclusive writing. Blocks until available.
bool	stk_rwmutex_trylock (stk_rwmutex_t *rw)
	Try to acquire the write lock without blocking.
bool	stk_rwmutex_timed_lock (stk_rwmutex_t *rw, int32_t timeout)
	Try to acquire the write lock with a timeout.
void	stk_rwmutex_unlock (stk_rwmutex_t *rw)
	Release the exclusive writer lock.

Detailed Description

C language binding/interface for SuperTinyKernel (STK).

This header provides a pure C API to create, configure and run STK kernel from C code.

Definition in file stk_c.h.