STK C API

Pure C interface for C++ API of SuperTinyKernel RTOS. More...

Collaboration diagram for STK C API:

Namespaces
namespace	stk
	Namespace of STK package.

Classes
struct	stk_event_overrider_t
	C-level callback table that mirrors stk::IPlatform::IEventOverrider. More...
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 control-block. More...
struct	stk_msgq_mem_t
	Opaque memory container for a MessageQueue instance. More...
struct	stk_rwmutex_mem_t
	Opaque memory container for an RWMutex instance. More...
struct	stk_barrier_mem_t
	Opaque memory container for a Barrier instance. More...

Macros
#define	STK_C_VERSION   (0x20261004)
	Interface version.
#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_STATIC_CAST(type, val)
	Convenience wrapper for static_cast and C-style cast.
#define	STK_PERIODICITY_DEFAULT   (1000U)
	Default tick period (1 ms).
#define	STK_WAIT_INFINITE   (STK_STATIC_CAST(stk_timeout_t, INT32_MAX))
	Infinite timeout constant.
#define	STK_NO_WAIT   (STK_STATIC_CAST(stk_timeout_t, 0))
	No timeout constant.
#define	STK_ALIGN_SIZE   sizeof(stk_word_t)
	Memory buffer alignment.
#define	STK_ALIGN_MASK   (STK_ALIGN_SIZE - 1U)
	Alignment mask.
#define	STK_STACK_MEMORY_ALIGN   (4U)
	Stack memory alignment.
#define	STK_DEFINE_STACK_POOL(name, max_tasks, stack_size)
	Allocates a statically bound, multi-dimensional stack pool for tasks.
#define	STK_GET_STACK_FROM_POOL(name, task_id)
	Retrieves the base stack pointer for a specific task ID from a stack pool.
#define	__stk_c_stack
	Stack attribute (applies required alignment for a stack memory).
#define	__stk_c_aligned
	Memory buffer alignment attribute.
#define	STK_TLS_GET_T(type)
	Typed helper for getting TLS value.
#define	STK_TLS_SET_T(ptr)
	Typed helper for setting TLS value.
#define	STK_DEFAULT_CS_SESSION   (0U)
	Default session value for stk_critical_section_enter_ex()/stk_critical_section_exit_ex(), letting the call auto-detect the calling context's privilege level.
#define	STK_MUTEX_IMPL_SIZE   (10U + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))
	A memory size (multiples of stk_word_t) required for Mutex instance.
#define	STK_SPINLOCK_IMPL_SIZE   (6)
	A memory size (multiples of stk_word_t) required for SpinLock instance.
#define	STK_CV_IMPL_SIZE   (7U + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))
	A memory size (multiples of stk_word_t) required for ConditionVariable instance.
#define	STK_EVENT_IMPL_SIZE   (8U + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))
	A memory size (multiples of stk_word_t) required for Event instance.
#define	STK_SEM_IMPL_SIZE   (8U + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))
	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_CANCELED   (0x80000008U)
#define	STK_EF_ERROR_MASK   (0x80000000U)
#define	STK_EF_IMPL_SIZE   (STK_CV_IMPL_SIZE + 1U + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))
	A memory size (multiples of stk_word_t) required for EventFlags instance.
#define	STK_PIPE_IMPL_SIZE   (6U + (2U * STK_CV_IMPL_SIZE) + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))
	A memory size (multiples of stk_word_t) required for a Pipe control-block.
#define	STK_PIPE_BUF_SIZE(capacity, element_size)
	Compute the required data-buffer size (in bytes) for a Pipe.
#define	STK_MSGQ_IMPL_SIZE   (6U + (2U * STK_CV_IMPL_SIZE) + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))
	A memory size (multiples of stk_word_t) required for a MessageQueue instance.
#define	STK_MSGQ_BUF_SIZE(capacity, msg_size)
	Compute the required data-buffer size (in bytes) for a MessageQueue.
#define	STK_RWMUTEX_IMPL_SIZE   (17U + (STK_SYNC_DEBUG_NAMES ? 3U : 0U))
	A memory size (multiples of stk_word_t) required for RWMutex instance.
#define	STK_BARRIER_IMPL_SIZE   (STK_MUTEX_IMPL_SIZE + STK_CV_IMPL_SIZE + 4U + (STK_SYNC_DEBUG_NAMES ? 1U : 0U))
	A memory size (multiples of stk_word_t) required for Barrier instance.

Typedefs
typedef uintptr_t	stk_word_t
	CPU register type.
typedef stk_word_t	stk_tid_t
	Task id.
typedef int64_t	stk_tick_t
	Ticks value.
typedef int64_t	stk_time_t
	Time value.
typedef int32_t	stk_timeout_t
	Timeout value.
typedef uint64_t	stk_cycle_t
	CPU cycles value.
typedef int32_t	stk_weight_t
	Task weight value.
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 stk_kernel_state_t	stk_kernel_state_t
	Kernel state.
typedef struct stk_event_overrider_t	stk_event_overrider_t
typedef uint8_t	stk_cs_session_t
	Session of Critical Section.
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 enum stk_wait_result_t	stk_wait_result_t
	Outcome of a cancellable, timed kernel wait (see stk_cv_wait_ex()).
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 control-block.
typedef struct stk_pipe_t	stk_pipe_t
	Opaque handle to a Pipe instance.
typedef struct stk_msgq_mem_t	stk_msgq_mem_t
	Opaque memory container for a MessageQueue instance.
typedef struct stk_msgq_t	stk_msgq_t
	Opaque handle to a MessageQueue 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.
typedef struct stk_barrier_mem_t	stk_barrier_mem_t
	Opaque memory container for a Barrier instance.
typedef struct stk_barrier_t	stk_barrier_t
	Opaque handle to a Barrier instance.
typedef enum stk_barrier_result_t	stk_barrier_result_t
	Outcome of a stk_barrier_wait_ex() call.

Enumerations
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 }
	Kernel state. More...
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 }
	Outcome of a cancellable, timed kernel wait (see stk_cv_wait_ex()). More...
enum	stk_barrier_result_t {   STK_BARRIER_RELEASED = 0 ,   STK_BARRIER_LAST_ARRIVAL = 1 ,   STK_BARRIER_CANCELED = 2 }
	Outcome of a stk_barrier_wait_ex() call. More...

Functions
stk_kernel_t *	stk_kernel_create (uint8_t core_nr)
	Create kernel.
stk::IKernel *	stk_kernel_get_instance (uint8_t core_nr)
	Get the underlying C++ stk::IKernel object for a given core.
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 *tsk)
	Add task to non-HRT kernel (static or dynamic).
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)
	Add task with HRT timing parameters (HRT kernels only).
void	stk_kernel_remove_task (stk_kernel_t *k, stk_task_t *tsk)
	Remove finished task from dynamic kernel.
void	stk_kernel_start (stk_kernel_t *k)
	Start the scheduler - never returns.
stk_kernel_state_t	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.
bool	stk_kernel_is_started (const stk_kernel_t *k)
	Check whether the scheduler is currently running (first task switch has occurred).
void	stk_kernel_schedule_task_removal (stk_kernel_t *k, stk_task_t *task)
	Schedule removal of a running task from the kernel on the next tick.
void	stk_kernel_suspend_task (stk_kernel_t *k, stk_task_t *task, bool *suspended)
	Suspend a task (prevent it from being scheduled).
void	stk_kernel_resume_task (stk_kernel_t *k, stk_task_t *task)
	Resume a previously suspended task.
stk_timeout_t	stk_kernel_suspend (stk_kernel_t *k)
	Suspend scheduling (tickless idle entry point).
void	stk_kernel_resume (stk_kernel_t *k, stk_timeout_t elapsed_ticks)
	Resume scheduling after a prior stk_kernel_suspend() call.
size_t	stk_kernel_enumerate_tasks (stk_kernel_t *k, stk_task_t **tasks, size_t max_count)
	Enumerate all currently active tasks.
void	stk_kernel_process_tick (stk_kernel_t *k)
	Manually deliver one scheduler tick to the kernel.
void	stk_kernel_process_hard_fault (stk_kernel_t *k)
	Trigger a kernel hard fault (safe-state handler).
void	stk_kernel_set_event_overrider (stk_kernel_t *k, stk_event_overrider_t *overrider)
	Install a platform event overrider on the kernel.
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 *tsk, stk_weight_t weight)
	Set task weight (used only by Smooth Weighted Round Robin).
void	stk_task_set_priority (stk_task_t *tsk, uint8_t priority)
	Set task priority (used only by Fixed Priority scheduler).
void	stk_task_set_name (stk_task_t *tsk, const char *tname)
	Assign human-readable task name (for tracing/debugging).
const char *	stk_task_get_name (const stk_task_t *tsk)
	Get human-readable task name previously set with stk_task_set_name().
stk_tid_t	stk_task_get_id (const stk_task_t *tsk)
	Get the unique identifier of a task.
stk::ITask *	stk_task_get_instance (stk_task_t *tsk)
	Get the underlying C++ stk::ITask object wrapped by a stk_task_t handle.
stk_tid_t	stk_tid (void)
	Returns current task/thread ID (the value set by stk_task_set_id).
stk_tick_t	stk_ticks (void)
	Returns number of ticks elapsed since kernel start.
uint32_t	stk_tick_resolution (void)
	Returns how many microseconds correspond to one kernel tick.
stk_tick_t	stk_ticks_from_ms (stk_time_t msec)
	Get ticks from milliseconds using current kernel tick resolution.
stk_timeout_t	stk_ticks_from_ms_clamped_to_timeout (stk_timeout_t ms)
	Get ticks from milliseconds using current kernel tick resolution, clamped to the maximum value representable by stk_timeout_t (STK_WAIT_INFINITE).
static stk_tick_t	stk_ticks_from_ms_r (stk_time_t msec, uint32_t resolution)
	Get ticks from milliseconds using an explicit tick resolution.
stk_time_t	stk_time_now_ms (void)
	Returns current time in milliseconds since kernel start.
static stk_time_t	stk_ms_from_ticks_r (stk_tick_t ticks, uint32_t resolution)
	Convert ticks to milliseconds using an explicit tick resolution.
static stk_time_t	stk_ms_from_ticks (stk_tick_t ticks)
	Convert ticks to milliseconds using the current kernel tick resolution.
stk_cycle_t	stk_sys_timer_count (void)
	Get raw system timer counter value.
uint32_t	stk_sys_timer_frequency (void)
	Get system timer frequency in Hz.
stk_cycle_t	stk_hires_cycles (void)
	Get raw CPU cycle counter.
uint32_t	stk_hires_frequency (void)
	Get CPU clock frequency in Hz.
stk_tick_t	stk_hires_time_us (void)
	Get elapsed time in microseconds from the high-resolution clock.
void	stk_delay (stk_timeout_t ticks)
	Busy-wait delay (other tasks continue to run).
void	stk_delay_ms (stk_timeout_t ms)
	Busy-wait delay (other tasks continue to run).
void	stk_sleep (stk_timeout_t ticks)
	Put current task to sleep (non-HRT kernels only).
void	stk_sleep_ms (stk_timeout_t ms)
	Put current task to sleep (non-HRT kernels only).
bool	stk_sleep_until (stk_tick_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_sleep_cancel (stk_tid_t tid)
	Cancel the sleep of a task, waking it immediately.
void	stk_kernel_destroy (stk_kernel_t *k)
	Destroy dynamic kernel instance (only when not running).
void	stk_task_destroy (stk_task_t *tsk)
	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.
stk_cs_session_t	stk_critical_section_enter_ex (stk_cs_session_t ses)
	Enter global critical section - disable context switches on current core.
void	stk_critical_section_exit_ex (stk_cs_session_t ses)
	Leave global critical section - re-enable context switches.
void	stk_critical_section_enter ()
	Enter global critical section - disable context switches on current core.
void	stk_critical_section_exit ()
	Leave global critical section - re-enable context switches.
stk_mutex_t *	stk_mutex_create (stk_mutex_mem_t *const membuf)
	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, stk_timeout_t timeout)
	Try to lock the mutex with a timeout.
stk::sync::Mutex *	stk_mutex_get_instance (stk_mutex_t *mtx)
	Get the underlying C++ stk::sync::Mutex object wrapped by a stk_mutex_t handle.
stk_spinlock_t *	stk_spinlock_create (stk_spinlock_mem_t *const membuf)
	Create a recursive SpinLock.
void	stk_spinlock_destroy (stk_spinlock_t *slock)
	Destroy the SpinLock.
void	stk_spinlock_lock (stk_spinlock_t *slock)
	Acquire the SpinLock (recursive).
bool	stk_spinlock_trylock (stk_spinlock_t *slock)
	Attempt to acquire the SpinLock immediately.
void	stk_spinlock_unlock (stk_spinlock_t *slock)
	Release the SpinLock.
stk::sync::SpinLock *	stk_spinlock_get_instance (stk_spinlock_t *slock)
	Get the underlying C++ stk::sync::SpinLock object wrapped by a stk_spinlock_t handle.
stk_cv_t *	stk_cv_create (stk_cv_mem_t *const membuf)
	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, stk_timeout_t timeout)
	Wait for a signal on the condition variable.
stk_wait_result_t	stk_cv_wait_ex (stk_cv_t *cv, stk_mutex_t *mtx, stk_timeout_t timeout)
	Wait for a signal on the condition variable, preserving the full outcome.
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::sync::ConditionVariable *	stk_cv_get_instance (stk_cv_t *cv)
	Get the underlying C++ stk::sync::ConditionVariable object wrapped by a stk_cv_t handle.
stk_event_t *	stk_event_create (stk_event_mem_t *const membuf, 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, stk_timeout_t timeout)
	Wait for the event to become signaled.
bool	stk_event_trywait (stk_event_t *ev)
	Wait for the event to become signaled.
bool	stk_event_set (stk_event_t *ev)
	Set the event to signaled state.
bool	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::sync::Event *	stk_event_get_instance (stk_event_t *ev)
	Get the underlying C++ stk::sync::Event object wrapped by a stk_event_t handle.
stk_sem_t *	stk_sem_create (stk_sem_mem_t *const membuf, uint32_t initial_count, uint32_t max_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, stk_timeout_t timeout)
	Wait for a semaphore resource.
bool	stk_sem_trywait (stk_sem_t *sem)
	Poll the semaphore without blocking.
void	stk_sem_signal (stk_sem_t *sem)
	Signal/Release a semaphore resource.
bool	stk_sem_trysignal (stk_sem_t *sem)
	Try to signal/release a semaphore resource without exceeding max_count.
uint16_t	stk_sem_get_count (const stk_sem_t *sem)
	Get the current counter value.
stk::sync::Semaphore *	stk_sem_get_instance (stk_sem_t *sem)
	Get the underlying C++ stk::sync::Semaphore object wrapped by a stk_sem_t handle.
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 *const membuf, 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, stk_timeout_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::sync::EventFlags *	stk_ef_get_instance (stk_ef_t *ef)
	Get the underlying C++ stk::sync::EventFlags object wrapped by a stk_ef_t handle.
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)
	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, const void *data, stk_timeout_t timeout)
	Write a single element to the pipe.
bool	stk_pipe_trywrite (stk_pipe_t *pipe, const void *data)
	Attempt to write a single element to the pipe without blocking.
bool	stk_pipe_read (stk_pipe_t *pipe, void *data, stk_timeout_t timeout)
	Read a single element from the pipe.
bool	stk_pipe_tryread (stk_pipe_t *pipe, void *data)
	Attempt to read a single element from the pipe without blocking.
size_t	stk_pipe_write_bulk (stk_pipe_t *pipe, const void *src, size_t count, stk_timeout_t timeout)
	Write multiple elements to the pipe.
size_t	stk_pipe_trywrite_bulk (stk_pipe_t *pipe, const void *src, size_t count)
	Attempt to write multiple elements to the pipe without blocking.
size_t	stk_pipe_read_bulk (stk_pipe_t *pipe, void *dst, size_t count, stk_timeout_t timeout)
	Read multiple elements from the pipe.
size_t	stk_pipe_tryread_bulk (stk_pipe_t *pipe, void *dst, size_t count)
	Attempt to read multiple elements from the pipe without blocking.
size_t	stk_pipe_read_bulk_triggered (stk_pipe_t *pipe, void *dst, size_t trigger, size_t max_count, stk_timeout_t timeout)
	Read at least trigger elements, then drain up to max_count without blocking.
size_t	stk_pipe_tryread_bulk_triggered (stk_pipe_t *pipe, void *dst, size_t max_count)
	Non-blocking variant of stk_pipe_read_bulk_triggered.
void	stk_pipe_reset (stk_pipe_t *pipe)
	Discard all elements and reset the pipe to the empty state.
size_t	stk_pipe_get_capacity (const stk_pipe_t *pipe)
	Get the maximum number of elements the pipe can hold.
size_t	stk_pipe_get_element_size (const stk_pipe_t *pipe)
	Get the size of each element in bytes.
size_t	stk_pipe_get_count (const stk_pipe_t *pipe)
	Get the current number of elements in the pipe.
size_t	stk_pipe_get_space (const stk_pipe_t *pipe)
	Get the number of free slots currently available.
bool	stk_pipe_is_empty (const stk_pipe_t *pipe)
	Check whether the pipe is currently empty.
bool	stk_pipe_is_full (const stk_pipe_t *pipe)
	Check whether the pipe is currently full.
bool	stk_pipe_is_storage_valid (const stk_pipe_t *pipe)
	Verify that the backing storage is valid and the pipe is ready for use.
stk::sync::Pipe *	stk_pipe_get_instance (stk_pipe_t *pipe)
	Get the underlying C++ stk::sync::Pipe object wrapped by a stk_pipe_t handle.
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)
	Create a MessageQueue (using provided memory).
void	stk_msgq_destroy (stk_msgq_t *mq)
	Destroy a MessageQueue.
bool	stk_msgq_put (stk_msgq_t *mq, const void *msg, stk_timeout_t timeout)
	Put a message into the queue.
bool	stk_msgq_tryput (stk_msgq_t *mq, const void *msg)
	Attempt to put a message into the queue without blocking.
bool	stk_msgq_putfront (stk_msgq_t *mq, const void *msg, stk_timeout_t timeout)
	Put a message into the front of the queue (priority insert).
bool	stk_msgq_tryputfront (stk_msgq_t *mq, const void *msg)
	Attempt to put a message into the front of the queue without blocking.
bool	stk_msgq_get (stk_msgq_t *mq, void *msg, stk_timeout_t timeout)
	Get a message from the queue.
bool	stk_msgq_tryget (stk_msgq_t *mq, void *msg)
	Attempt to get a message from the queue without blocking.
bool	stk_msgq_peek (stk_msgq_t *mq, void *msg, stk_timeout_t timeout)
	Peek at the next message to be delivered without removing it.
bool	stk_msgq_trypeek (stk_msgq_t *mq, void *msg)
	Attempt to peek at the next message without blocking.
bool	stk_msgq_peekfront (stk_msgq_t *mq, void *msg, stk_timeout_t timeout)
	Peek at the most recently front-inserted message without removing it.
bool	stk_msgq_trypeekfront (stk_msgq_t *mq, void *msg)
	Attempt to peek at the front message without blocking.
void	stk_msgq_reset (stk_msgq_t *mq)
	Discard all messages and reset the queue to the empty state.
size_t	stk_msgq_get_capacity (const stk_msgq_t *mq)
	Get the maximum number of messages the queue can hold.
size_t	stk_msgq_get_msg_size (const stk_msgq_t *mq)
	Get the size of each message in bytes.
size_t	stk_msgq_get_count (const stk_msgq_t *mq)
	Get the current number of messages waiting in the queue.
size_t	stk_msgq_get_space (const stk_msgq_t *mq)
	Get the number of free slots currently available.
bool	stk_msgq_is_empty (const stk_msgq_t *mq)
	Check whether the queue is currently empty.
uint8_t *	stk_msgq_get_buffer (stk_msgq_t *mq)
	Get a pointer to the raw message data buffer.
bool	stk_msgq_is_full (const stk_msgq_t *mq)
	Check whether the queue is currently full.
bool	stk_msgq_is_storage_valid (const stk_msgq_t *mq)
	Verify that the backing storage is valid and the queue is ready for use.
stk::sync::MessageQueue *	stk_msgq_get_instance (stk_msgq_t *mq)
	Get the underlying C++ stk::sync::MessageQueue object wrapped by a stk_msgq_t handle.
stk_rwmutex_t *	stk_rwmutex_create (stk_rwmutex_mem_t *const membuf)
	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, stk_timeout_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, stk_timeout_t timeout)
	Try to acquire the write lock with a timeout.
void	stk_rwmutex_unlock (stk_rwmutex_t *rw)
	Release the exclusive writer lock.
stk::sync::RWMutex *	stk_rwmutex_get_instance (stk_rwmutex_t *rw)
	Get the underlying C++ stk::sync::RWMutex object wrapped by a stk_rwmutex_t handle.
stk_barrier_t *	stk_barrier_create (stk_barrier_mem_t *const membuf, uint32_t count)
	Create a Barrier (using provided memory).
void	stk_barrier_destroy (stk_barrier_t *barrier)
	Destroy a Barrier.
bool	stk_barrier_wait (stk_barrier_t *barrier)
	Block the calling task until count tasks have called stk_barrier_wait().
stk_barrier_result_t	stk_barrier_wait_ex (stk_barrier_t *barrier)
	Block the calling task until count tasks have arrived, preserving the full outcome.
uint32_t	stk_barrier_get_threshold (const stk_barrier_t *barrier)
	Get the number of tasks required to trip the barrier.
stk::sync::Barrier *	stk_barrier_get_instance (stk_barrier_t *barrier)
	Get the underlying C++ stk::sync::Barrier object wrapped by a stk_barrier_t handle.

Detailed Description

Pure C interface for C++ API of SuperTinyKernel RTOS.

Macro Definition Documentation

__stk_c_aligned

#define __stk_c_aligned

Memory buffer alignment attribute.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 216 of file stk_c.h.

__stk_c_stack

#define __stk_c_stack

Stack attribute (applies required alignment for a stack memory).

Definition at line 207 of file stk_c.h.

STK_ALIGN_MASK

#define STK_ALIGN_MASK   (STK_ALIGN_SIZE - 1U)

Alignment mask.

Definition at line 164 of file stk_c.h.

Referenced by pthread_attr_setstack().

STK_ALIGN_SIZE

#define STK_ALIGN_SIZE   sizeof(stk_word_t)

Memory buffer alignment.

Definition at line 160 of file stk_c.h.

STK_BARRIER_IMPL_SIZE

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

A memory size (multiples of stk_word_t) required for Barrier instance.

Note

Composed of one Mutex (STK_MUTEX_IMPL_SIZE), one ConditionVariable (STK_CV_IMPL_SIZE), three uint32_t counters (threshold, count, generation), plus Barrier's own debug name if enabled.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 2109 of file stk_c.h.

STK_C_ASSERT

#define STK_C_ASSERT

(

e

)

Value:

assert(e)

Assertion macro used inside STK C bindings.

Definition at line 80 of file stk_c.h.

Referenced by stk::pthread::EnqueueReap(), stk::pthread::EnsureReaper(), pthread_create(), pthread_exit(), stk::pthread::ReaperEntry(), and stk_pthread_bind_kernel().

STK_C_CPU_COUNT

#define STK_C_CPU_COUNT   (1)

Number of kernel instances / CPU cores supported (default: 1).

Note

Each core usually gets its own independent kernel instance.

Definition at line 65 of file stk_c.h.

Referenced by SetEventOverrider(), stk_kernel_create(), stk_kernel_get_instance(), stk_timerhost_get(), and UnregisterKernel().

STK_C_KERNEL_MAX_TASKS

#define STK_C_KERNEL_MAX_TASKS   (4)

Maximum number of tasks per kernel instance (default: 4).

Note

Increase this value if you need more tasks. Has direct impact on RAM and FLASH usage.

Definition at line 57 of file stk_c.h.

STK_C_VERSION

#define STK_C_VERSION   (0x20261004)

Interface version.

Definition at line 45 of file stk_c.h.

STK_CV_IMPL_SIZE

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

A memory size (multiples of stk_word_t) required for ConditionVariable instance.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 1074 of file stk_c.h.

STK_DEFAULT_CS_SESSION

#define STK_DEFAULT_CS_SESSION   (0U)

Default session value for stk_critical_section_enter_ex()/stk_critical_section_exit_ex(), letting the call auto-detect the calling context's privilege level.

Definition at line 892 of file stk_c.h.

STK_DEFINE_STACK_POOL

#define STK_DEFINE_STACK_POOL	(		name,
			max_tasks,
			stack_size )

Value:

static stk_word_t name[max_tasks][stack_size] __stk_c_stack

Allocates a statically bound, multi-dimensional stack pool for tasks.

Parameters

[in]	name	Identifier name of the generated array.
[in]	max_tasks	Maximum number of tasks (rows in the array).
[in]	stack_size	Size of each individual stack in words (columns).

See also

STK_GET_STACK_FROM_POOL

Definition at line 186 of file stk_c.h.

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

STK_EF_ERROR_CANCELED

#define STK_EF_ERROR_CANCELED   (0x80000008U)

Wait was cancelled before the flag condition was met

Definition at line 1332 of file stk_c.h.

STK_EF_ERROR_ISR

#define STK_EF_ERROR_ISR   (0x80000004U)

Wait called from an ISR with a blocking timeout

Definition at line 1331 of file stk_c.h.

STK_EF_ERROR_MASK

#define STK_EF_ERROR_MASK   (0x80000000U)

Mask for testing any error; bit 31 set means error

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 1333 of file stk_c.h.

Referenced by stk_ef_is_error().

STK_EF_ERROR_PARAMETER

#define STK_EF_ERROR_PARAMETER   (0x80000001U)

Return-value error sentinels (bit 31 set indicates an error).

flags argument is 0 or has bit 31 set

Definition at line 1329 of file stk_c.h.

STK_EF_ERROR_TIMEOUT

#define STK_EF_ERROR_TIMEOUT   (0x80000002U)

Timeout expired before the flag condition was met

Definition at line 1330 of file stk_c.h.

STK_EF_IMPL_SIZE

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

A memory size (multiples of stk_word_t) required for EventFlags instance.

Note

EventFlags contains one ConditionVariable (STK_CV_IMPL_SIZE words) plus one 32-bit flags word and alignment padding.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 1347 of file stk_c.h.

STK_EF_OPT_NO_CLEAR

#define STK_EF_OPT_NO_CLEAR   (0x00000002U)

Do not clear matched bits on a successful return

Definition at line 1325 of file stk_c.h.

STK_EF_OPT_WAIT_ALL

#define STK_EF_OPT_WAIT_ALL   (0x00000001U)

Unblock when ALL requested bits are simultaneously set (AND semantics)

Definition at line 1324 of file stk_c.h.

STK_EF_OPT_WAIT_ANY

#define STK_EF_OPT_WAIT_ANY   (0x00000000U)

Options bitmask constants for stk_ef_wait() / stk_ef_trywait().

Unblock when ANY requested bit is set (OR semantics, default)

Definition at line 1323 of file stk_c.h.

STK_EVENT_IMPL_SIZE

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

A memory size (multiples of stk_word_t) required for Event instance.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 1154 of file stk_c.h.

STK_GET_STACK_FROM_POOL

#define STK_GET_STACK_FROM_POOL	(		name,
			task_id )

Value:

(name[task_id])

Retrieves the base stack pointer for a specific task ID from a stack pool.

Parameters

[in]	name	Identifier name of the allocated stack pool.
[in]	task_id	Index of the task whose stack pointer is requested.

See also

STK_DEFINE_STACK_POOL

Definition at line 195 of file stk_c.h.

STK_MSGQ_BUF_SIZE

#define STK_MSGQ_BUF_SIZE	(		capacity,
			msg_size )

Value:

((capacity) * (msg_size))

Compute the required data-buffer size (in bytes) for a MessageQueue.

Parameters

[in]	capacity	Maximum number of messages.
[in]	msg_size	Size of each message in bytes.

Note

Use this macro when declaring the uint8_t buffer passed to stk_msgq_create():

#define MY_QUEUE_CAP     8
#define MY_MSG_SIZE      sizeof(MyMsg_t)
 
static uint8_t        s_msgq_buf[STK_MSGQ_BUF_SIZE(MY_QUEUE_CAP, MY_MSG_SIZE)];
static stk_msgq_mem_t s_msgq_mem;
stk_msgq_t *g_queue = stk_msgq_create(&s_msgq_mem,
                                       s_msgq_buf,  sizeof(s_msgq_buf),
                                       MY_QUEUE_CAP, MY_MSG_SIZE);

Definition at line 1765 of file stk_c.h.

STK_MSGQ_IMPL_SIZE

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

A memory size (multiples of stk_word_t) required for a MessageQueue instance.

Covers the fixed-overhead fields of stk::sync::MessageQueue: six size_t members (buffer ptr, capacity, msg_size, count, head, tail) plus two ConditionVariable objects (cv_not_empty, cv_not_full) and optional debug-name word.

Note

The backing data buffer is allocated separately by the caller and passed to stk_msgq_create() via the buf / buf_size parameters.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 1736 of file stk_c.h.

STK_MUTEX_IMPL_SIZE

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

A memory size (multiples of stk_word_t) required for Mutex instance.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 947 of file stk_c.h.

STK_NO_WAIT

#define STK_NO_WAIT   (STK_STATIC_CAST(stk_timeout_t, 0))

No timeout constant.

Definition at line 156 of file stk_c.h.

STK_PERIODICITY_DEFAULT

#define STK_PERIODICITY_DEFAULT   (1000U)

Default tick period (1 ms).

in microseconds

Definition at line 139 of file stk_c.h.

STK_PIPE_BUF_SIZE

#define STK_PIPE_BUF_SIZE	(		capacity,
			element_size )

Value:

((((capacity) * (element_size)) + STK_ALIGN_MASK) & ~STK_ALIGN_MASK)

Compute the required data-buffer size (in bytes) for a Pipe.

Parameters

[in]	capacity	Maximum number of elements the pipe can hold.
[in]	element_size	Size of a single element in bytes.

Note

Use this macro when declaring the uint8_t buffer passed to stk_pipe_create():

#define MY_PIPE_CAP   16
#define MY_ELEM_SIZE  sizeof(MyMsg_t)
 
static uint8_t        s_pipe_buf[STK_PIPE_BUF_SIZE(MY_PIPE_CAP, MY_ELEM_SIZE)] __stk_c_aligned;
static stk_pipe_mem_t s_pipe_mem;
stk_pipe_t *g_pipe = stk_pipe_create(&s_pipe_mem,
                                      s_pipe_buf, sizeof(s_pipe_buf),
                                      MY_PIPE_CAP, MY_ELEM_SIZE);

Definition at line 1486 of file stk_c.h.

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

STK_PIPE_IMPL_SIZE

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

A memory size (multiples of stk_word_t) required for a Pipe control-block.

Covers the fixed-overhead fields of stk::sync::Pipe: one uint8_t pointer plus five size_t members (capacity, element_size, count, head, tail), two ConditionVariable objects (cv_not_empty, cv_not_full) and an optional debug-name word.

Note

The backing data buffer is allocated separately by the caller and passed to stk_pipe_create() via the buf / buf_size parameters.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 1457 of file stk_c.h.

STK_RWMUTEX_IMPL_SIZE

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

A memory size (multiples of stk_word_t) required for RWMutex instance.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 2007 of file stk_c.h.

STK_SEM_IMPL_SIZE

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

A memory size (multiples of stk_word_t) required for Semaphore instance.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 1229 of file stk_c.h.

STK_SPINLOCK_IMPL_SIZE

#define STK_SPINLOCK_IMPL_SIZE   (6)

A memory size (multiples of stk_word_t) required for SpinLock instance.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 1011 of file stk_c.h.

STK_STACK_MEMORY_ALIGN

#define STK_STACK_MEMORY_ALIGN   (4U)

Stack memory alignment.

Definition at line 175 of file stk_c.h.

STK_STATIC_CAST

#define STK_STATIC_CAST	(		type,
			val )

Value:

static_cast<type>(val)

Convenience wrapper for static_cast and C-style cast.

Parameters

[in]	type	Value type.
[in]	val	Value.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 88 of file stk_c.h.

Referenced by stk_ms_from_ticks_r(), and stk_ticks_from_ms_r().

STK_SYNC_DEBUG_NAMES

#define STK_SYNC_DEBUG_NAMES   (0)

Enable names for synchronization primitives for debugging/tracing purpose.

Definition at line 74 of file stk_c.h.

STK_TLS_GET_T

#define STK_TLS_GET_T

(

type

)

Value:

((type *)stk_tls_get())

Typed helper for getting TLS value.

Note

Expands to ((type *)stk_tls_get())

Definition at line 867 of file stk_c.h.

STK_TLS_SET_T

#define STK_TLS_SET_T

(

ptr

)

Value:

stk_tls_set((void *)(ptr))

Typed helper for setting TLS value.

Note

Expands to stk_tls_set((void *)(ptr))

Definition at line 872 of file stk_c.h.

STK_WAIT_INFINITE

#define STK_WAIT_INFINITE   (STK_STATIC_CAST(stk_timeout_t, INT32_MAX))

Infinite timeout constant.

Definition at line 152 of file stk_c.h.

Typedef Documentation

stk_barrier_mem_t

typedef struct stk_barrier_mem_t stk_barrier_mem_t

Opaque memory container for a Barrier instance.

stk_barrier_result_t

typedef enum stk_barrier_result_t stk_barrier_result_t

Outcome of a stk_barrier_wait_ex() call.

Note

It is a direct match for stk::sync::Barrier::EResult.

stk_barrier_t

typedef struct stk_barrier_t stk_barrier_t

Opaque handle to a Barrier instance.

Definition at line 2119 of file stk_c.h.

stk_cs_session_t

typedef uint8_t stk_cs_session_t

Session of Critical Section.

Opaque token returned by stk_critical_section_enter_ex() that carries the state which must be restored by the matching stk_critical_section_exit_ex() (e.g. the previous interrupt masking level, such as BASEPRI on ARM Cortex-M, and the privilege-level handling path that was selected on entry).

Note

Do not modify or interpret the value, pass it unchanged to stk_critical_section_exit_ex().

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 887 of file stk_c.h.

stk_cv_mem_t

typedef struct stk_cv_mem_t stk_cv_mem_t

Opaque memory container for a ConditionVariable instance.

stk_cv_t

typedef struct stk_cv_t stk_cv_t

Opaque handle to a Condition Variable instance.

Definition at line 1084 of file stk_c.h.

stk_cycle_t

typedef uint64_t stk_cycle_t

CPU cycles value.

See also

stk_sys_timer_count, stk_hires_cycles

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 123 of file stk_c.h.

stk_ef_mem_t

typedef struct stk_ef_mem_t stk_ef_mem_t

Opaque memory container for an EventFlags instance.

stk_ef_t

typedef struct stk_ef_t stk_ef_t

Opaque handle to an EventFlags instance.

Definition at line 1357 of file stk_c.h.

stk_event_mem_t

typedef struct stk_event_mem_t stk_event_mem_t

Opaque memory container for an Event instance.

stk_event_overrider_t

typedef struct stk_event_overrider_t stk_event_overrider_t

stk_event_t

typedef struct stk_event_t stk_event_t

Opaque handle to an Event instance.

Definition at line 1164 of file stk_c.h.

stk_kernel_state_t

typedef enum stk_kernel_state_t stk_kernel_state_t

Kernel state.

Note

It is a direct match for IKernel::EState enum.

See also

stk_kernel_get_state()

stk_kernel_t

typedef struct stk_kernel_t stk_kernel_t

Opaque handle to a kernel instance.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 131 of file stk_c.h.

stk_msgq_mem_t

typedef struct stk_msgq_mem_t stk_msgq_mem_t

Opaque memory container for a MessageQueue instance.

stk_msgq_t

typedef struct stk_msgq_t stk_msgq_t

Opaque handle to a MessageQueue instance.

Definition at line 1746 of file stk_c.h.

stk_mutex_mem_t

typedef struct stk_mutex_mem_t stk_mutex_mem_t

Opaque memory container for a Mutex instance.

stk_mutex_t

typedef struct stk_mutex_t stk_mutex_t

Opaque handle to a Mutex instance.

Definition at line 957 of file stk_c.h.

stk_pipe_mem_t

typedef struct stk_pipe_mem_t stk_pipe_mem_t

Opaque memory container for a Pipe control-block.

stk_pipe_t

typedef struct stk_pipe_t stk_pipe_t

Opaque handle to a Pipe instance.

Definition at line 1467 of file stk_c.h.

stk_rwmutex_mem_t

typedef struct stk_rwmutex_mem_t stk_rwmutex_mem_t

Opaque memory container for an RWMutex instance.

stk_rwmutex_t

typedef struct stk_rwmutex_t stk_rwmutex_t

Opaque handle to an RWMutex instance.

Definition at line 2017 of file stk_c.h.

stk_sem_mem_t

typedef struct stk_sem_mem_t stk_sem_mem_t

Opaque memory container for a Semaphore instance.

stk_sem_t

typedef struct stk_sem_t stk_sem_t

Opaque handle to a Semaphore instance.

Definition at line 1239 of file stk_c.h.

stk_spinlock_t

typedef struct stk_spinlock_t stk_spinlock_t

Opaque handle to a SpinLock instance.

Definition at line 1022 of file stk_c.h.

stk_task_entry_t

typedef void(* stk_task_entry_t) (void *arg)

Task entry point function type.

Parameters

[in]

arg

User-supplied argument (may be NULL)

Note

If KERNEL_STATIC, the function must never return. If KERNEL_DYNAMIC, it may return and then task will be considered as finished.

KERNEL_TICKLESS is compatible with both KERNEL_STATIC and KERNEL_DYNAMIC, but is incompatible with KERNEL_HRT (see kernel type definitions below).

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 148 of file stk_c.h.

stk_task_t

typedef struct stk_task_t stk_task_t

Opaque handle to a task instance.

Definition at line 135 of file stk_c.h.

stk_tick_t

typedef int64_t stk_tick_t

Ticks value.

See also

stk_ticks

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 108 of file stk_c.h.

stk_tid_t

typedef stk_word_t stk_tid_t

Task id.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 103 of file stk_c.h.

stk_time_t

typedef int64_t stk_time_t

Time value.

See also

stk_time_now_ms

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 113 of file stk_c.h.

stk_timeout_t

typedef int32_t stk_timeout_t

Timeout value.

See also

stk_sleep, stk_delay

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 118 of file stk_c.h.

stk_wait_result_t

typedef enum stk_wait_result_t stk_wait_result_t

Outcome of a cancellable, timed kernel wait (see stk_cv_wait_ex()).

Note

It is a direct match for stk::EWaitResult.

stk_weight_t

typedef int32_t stk_weight_t

Task weight value.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 127 of file stk_c.h.

stk_word_t

typedef uintptr_t stk_word_t

CPU register type.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 99 of file stk_c.h.

Enumeration Type Documentation

stk_barrier_result_t

enum stk_barrier_result_t

Outcome of a stk_barrier_wait_ex() call.

Note

It is a direct match for stk::sync::Barrier::EResult.

Enumerator
STK_BARRIER_RELEASED	Released because the barrier tripped; this task was not the last arrival.
STK_BARRIER_LAST_ARRIVAL	This task was the last arrival and tripped the barrier.
STK_BARRIER_CANCELED	Wait was cancelled before the barrier tripped; this task's arrival was rolled back and does not count toward the generation it was waiting on.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 2137 of file stk_c.h.

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

stk_kernel_state_t

enum stk_kernel_state_t

Kernel state.

Note

It is a direct match for IKernel::EState enum.

See also

stk_kernel_get_state()

Enumerator
STK_KERNEL_STATE_INACTIVE	not ready, stk_kernel_init() must be called
STK_KERNEL_STATE_READY	ready to start, stk_kernel_start() must be called
STK_KERNEL_STATE_RUNNING	initialized and running, stk_kernel_start() was called successfully
STK_KERNEL_STATE_SUSPENDED	scheduling suspended via stk_kernel_service_suspend() (tickless idle)

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 384 of file stk_c.h.

                                {
    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_wait_result_t

enum stk_wait_result_t

Outcome of a cancellable, timed kernel wait (see stk_cv_wait_ex()).

Note

It is a direct match for stk::EWaitResult.

Enumerator
STK_WAIT_RESULT_FAIL	The kernel returned an error without actually waiting.
STK_WAIT_RESULT_SIGNAL	The wake was caused by a signal.
STK_WAIT_RESULT_TIMEOUT	The wake was caused by a timeout expiry.
STK_WAIT_RESULT_CANCELED	The wait was cancelled by another task, independent of signal/timeout.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 1063 of file stk_c.h.

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

Function Documentation

stk_barrier_create()

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

Create a Barrier (using provided memory).

Parameters

[in]	membuf	Pointer to static memory container.
[in]	count	Number of tasks that must call stk_barrier_wait() before any of them is released. Must not be 0.

Returns

Barrier handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 926 of file stk_c_sync.cpp.

{
    STK_ASSERT(membuf != nullptr);
    STK_ASSERT(count != 0U);
 
    stk_barrier_t *result = nullptr;
    if ((membuf != nullptr) && (count != 0U))
    {
        result = ConstructIn<stk_barrier_t>(*membuf, count);
    }
 
    return result;
}

References stk::ConstructIn(), and STK_ASSERT.

Here is the call graph for this function:

stk_barrier_destroy()

void stk_barrier_destroy

(

stk_barrier_t *

barrier

)

Destroy a Barrier.

Parameters

[in]

barrier

Barrier handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 941 of file stk_c_sync.cpp.

{
    if (barrier != nullptr)
    {
        barrier->~stk_barrier_t();
    }
}

stk_barrier_get_instance()

stk::sync::Barrier * stk_barrier_get_instance

(

stk_barrier_t *

barrier

)

Get the underlying C++ stk::sync::Barrier object wrapped by a stk_barrier_t handle.

Parameters

[in]

barrier

Barrier handle obtained via stk_barrier_create().

Returns

Pointer to the wrapped stk::sync::Barrier instance. Never NULL for a valid handle.

Note

C++ callers only (guarded by __cplusplus); not part of the C ABI.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 979 of file stk_c_sync.cpp.

{
    STK_ASSERT(barrier != nullptr);
 
    return &barrier->handle;
}

References stk_barrier_t::handle, and STK_ASSERT.

stk_barrier_get_threshold()

uint32_t stk_barrier_get_threshold

(

const stk_barrier_t *

barrier

)

Get the number of tasks required to trip the barrier.

Parameters

[in]

barrier

Barrier handle.

Returns

Construction-time threshold.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 972 of file stk_c_sync.cpp.

{
    STK_ASSERT(barrier != nullptr);
 
    return barrier->handle.GetThreshold();
}

References stk::sync::Barrier::GetThreshold(), stk_barrier_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_barrier_wait()

bool stk_barrier_wait

(

stk_barrier_t *

barrier

)

Block the calling task until count tasks have called stk_barrier_wait().

Once the last task arrives, all currently waiting tasks are woken up and the barrier resets itself so it can be reused for the next round.

Parameters

[in]

barrier

Barrier handle.

Note

Cannot report a cancellation - returns False the same as a normal (non-last) release. Use stk_barrier_wait_ex() to tell the two apart.

Warning

ISR-unsafe.

Returns

True if the calling task was the last one to arrive (and thus released the others), False if the calling task was one of the released waiters.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 949 of file stk_c_sync.cpp.

{
    STK_ASSERT(barrier != nullptr);
 
    return barrier->handle.Wait();
}

References stk_barrier_t::handle, STK_ASSERT, and stk::sync::Barrier::Wait().

Here is the call graph for this function:

stk_barrier_wait_ex()

stk_barrier_result_t stk_barrier_wait_ex

(

stk_barrier_t *

barrier

)

Block the calling task until count tasks have arrived, preserving the full outcome.

Identical to stk_barrier_wait(), except the caller can distinguish a normal release, being the last arrival, and a cancellation.

Parameters

[in]

barrier

Barrier handle.

Returns

STK_BARRIER_LAST_ARRIVAL, STK_BARRIER_RELEASED, or STK_BARRIER_CANCELED.

Warning

ISR-unsafe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 956 of file stk_c_sync.cpp.

{
    STK_ASSERT(barrier != nullptr);
 
    stk_barrier_result_t result;
 
    switch (barrier->handle.WaitEx())
    {
    case Barrier::BARRIER_LAST_ARRIVAL: result = STK_BARRIER_LAST_ARRIVAL; break;
    case Barrier::BARRIER_CANCELED:     result = STK_BARRIER_CANCELED;     break;
    default:                            result = STK_BARRIER_RELEASED;     break;
    }
 
    return result;
}

References stk::sync::Barrier::BARRIER_CANCELED, stk::sync::Barrier::BARRIER_LAST_ARRIVAL, stk_barrier_t::handle, STK_ASSERT, STK_BARRIER_CANCELED, STK_BARRIER_LAST_ARRIVAL, STK_BARRIER_RELEASED, and stk::sync::Barrier::WaitEx().

Here is the call graph for this function:

stk_critical_section_enter()

void stk_critical_section_enter

(

)

Enter global critical section - disable context switches on current core.

Warning

Can be used from a Privileged thread ONLY. When called from a User thread the section cannot be left properly: the matching stk_critical_section_exit() has no session to restore, and in User privilege it is not permitted to clear the interrupt masking (e.g. BASEPRI on ARM Cortex-M) that was set on entry. Use stk_critical_section_enter_ex() / stk_critical_section_exit_ex() in code that may run in a User thread (e.g. shared library or middleware code).

Note

Misuse is caught by STK_ASSERT(IsPrivilegedContext()) when assertions are enabled; with assertions disabled the call is not checked and the behavior is undefined.

Supports nesting (number of enter calls must match number of exit calls).

See also

stk_critical_section_enter_ex

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 681 of file stk_c.cpp.

{
    STK_ASSERT(stk::hw::IsPrivilegedContext());
 
    STK_UNUSED(hw::CriticalSection::Enter(hw::CriticalSection::DEFAULT_SESSION));
}

References stk::hw::CriticalSection::DEFAULT_SESSION, stk::hw::CriticalSection::Enter(), stk::hw::IsPrivilegedContext(), STK_ASSERT, and STK_UNUSED.

Here is the call graph for this function:

stk_critical_section_enter_ex()

stk_cs_session_t stk_critical_section_enter_ex

(

stk_cs_session_t

ses

)

Enter global critical section - disable context switches on current core.

Preferred API for entering a critical section. It works from both Privileged and User thread contexts: the returned session preserves the state of the entry, so that the matching stk_critical_section_exit_ex() can restore it correctly regardless of the privilege level the caller is running at.

Note

Supports nesting (number of enter calls must match number of exit calls). Every call must be paired with stk_critical_section_exit_ex() using the session returned by that very call, and nested sections must be left in reverse (LIFO) order.

Keep the section as short as possible: context switches on the current core are disabled until the matching exit.

Parameters

[in]

ses

STK_DEFAULT_CS_SESSION to auto-detect the calling context's privilege level, or an explicit session value to force a specific handling path.

Returns

Session value that must be supplied to the matching stk_critical_section_exit_ex().

See also

stk_critical_section_exit_ex

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 671 of file stk_c.cpp.

{
    return hw::CriticalSection::Enter(ses);
}

References stk::hw::CriticalSection::Enter().

Here is the call graph for this function:

stk_critical_section_exit()

void stk_critical_section_exit

(

)

Leave global critical section - re-enable context switches.

Warning

Can be used from a Privileged thread ONLY, see the warning of stk_critical_section_enter(). Use stk_critical_section_exit_ex() in code that may run in a User thread.

Note

Must be called once for each previous stk_critical_section_enter().

See also

stk_critical_section_exit_ex

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 688 of file stk_c.cpp.

{
    hw::CriticalSection::Exit(hw::CriticalSection::DEFAULT_SESSION);
}

References stk::hw::CriticalSection::DEFAULT_SESSION, and stk::hw::CriticalSection::Exit().

Here is the call graph for this function:

stk_critical_section_exit_ex()

void stk_critical_section_exit_ex

(

stk_cs_session_t

ses

)

Leave global critical section - re-enable context switches.

Restores the state captured by the matching stk_critical_section_enter_ex().

Note

Must be called exactly once for each previous stk_critical_section_enter_ex(), with the session value returned by that call.

Parameters

[in]

ses

Session value returned by the matching stk_critical_section_enter_ex() call.

See also

stk_critical_section_enter_ex

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 676 of file stk_c.cpp.

{
    hw::CriticalSection::Exit(ses);
}

References stk::hw::CriticalSection::Exit().

Here is the call graph for this function:

stk_cv_create()

stk_cv_t * stk_cv_create

(

stk_cv_mem_t *const

membuf

)

Create a Condition Variable (using provided memory).

Parameters

[in]

membuf

Pointer to static memory container.

Returns

CV handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 152 of file stk_c_sync.cpp.

{
    STK_ASSERT(membuf != nullptr);
 
    stk_cv_t *result = nullptr;
    if (membuf != nullptr)
    {
        result = ConstructIn<stk_cv_t>(*membuf);
    }
 
    return result;
}

References stk::ConstructIn(), and STK_ASSERT.

Here is the call graph for this function:

stk_cv_destroy()

void stk_cv_destroy

(

stk_cv_t *

cv

)

Destroy a Condition Variable.

Parameters

[in]

cv

CV handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 165 of file stk_c_sync.cpp.

{
    if (cv != nullptr)
    {
        cv->~stk_cv_t();
    }
}

stk_cv_get_instance()

stk::sync::ConditionVariable * stk_cv_get_instance

(

stk_cv_t *

cv

)

Get the underlying C++ stk::sync::ConditionVariable object wrapped by a stk_cv_t handle.

Parameters

[in]

cv

CV handle obtained via stk_cv_create().

Returns

Pointer to the wrapped stk::sync::ConditionVariable instance. Never NULL for a valid handle.

Note

C++ callers only (guarded by __cplusplus); not part of the C ABI.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 213 of file stk_c_sync.cpp.

{
    STK_ASSERT(cv != nullptr);
 
    return &cv->handle;
}

References stk_cv_t::handle, and STK_ASSERT.

stk_cv_notify_all()

void stk_cv_notify_all

(

stk_cv_t *

cv

)

Wake all tasks waiting on the condition variable.

Parameters

[in]

cv

CV handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 206 of file stk_c_sync.cpp.

{
    STK_ASSERT(cv != nullptr);
 
    cv->handle.NotifyAll();
}

References stk_cv_t::handle, stk::sync::ConditionVariable::NotifyAll(), and STK_ASSERT.

Here is the call graph for this function:

stk_cv_notify_one()

void stk_cv_notify_one

(

stk_cv_t *

cv

)

Wake one task waiting on the condition variable.

Parameters

[in]

cv

CV handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 199 of file stk_c_sync.cpp.

{
    STK_ASSERT(cv != nullptr);
 
    cv->handle.NotifyOne();
}

References stk_cv_t::handle, stk::sync::ConditionVariable::NotifyOne(), and STK_ASSERT.

Here is the call graph for this function:

stk_cv_wait()

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

Wait for a signal on the condition variable.

Atomically releases the mutex and suspends the task. The mutex is re-acquired before returning.

Parameters

[in]	cv	CV handle.
[in]	mtx	Locked mutex handle protecting the state.
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE.

Returns

True if signaled, False if the wait did not end in a signal (timeout or an externally cancelled wait).

Note

Collapses the distinction between timeout and cancellation. Use stk_cv_wait_ex() if the caller needs to tell them apart.

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 173 of file stk_c_sync.cpp.

{
    STK_ASSERT(cv != nullptr);
    STK_ASSERT(mtx != nullptr);
 
    return cv->handle.Wait(mtx->handle, timeout);
}

References stk_cv_t::handle, stk_mutex_t::handle, STK_ASSERT, and stk::sync::ConditionVariable::Wait().

Here is the call graph for this function:

stk_cv_wait_ex()

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

Wait for a signal on the condition variable, preserving the full outcome.

Identical to stk_cv_wait(), except the caller gets the raw stk_wait_result_t instead of a collapsed bool, so a cancellation can be distinguished from a timeout.

Parameters

[in]	cv	CV handle.
[in]	mtx	Locked mutex handle protecting the state.
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE.

Returns

STK_WAIT_RESULT_SIGNAL, STK_WAIT_RESULT_TIMEOUT, or STK_WAIT_RESULT_CANCELED.

Note

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Warning

ISR-safe only with timeout = STK_NO_WAIT, ISR-unsafe otherwise.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 181 of file stk_c_sync.cpp.

{
    STK_ASSERT(cv != nullptr);
    STK_ASSERT(mtx != nullptr);
 
    stk_wait_result_t result;
 
    switch (cv->handle.WaitEx(mtx->handle, timeout))
    {
    case WAIT_RESULT_SIGNAL:   result = STK_WAIT_RESULT_SIGNAL;   break;
    case WAIT_RESULT_TIMEOUT:  result = STK_WAIT_RESULT_TIMEOUT;  break;
    case WAIT_RESULT_CANCELED: result = STK_WAIT_RESULT_CANCELED; break;
    default:                   result = STK_WAIT_RESULT_FAIL;     break;
    }
 
    return result;
}

References stk_cv_t::handle, stk_mutex_t::handle, STK_ASSERT, STK_WAIT_RESULT_CANCELED, STK_WAIT_RESULT_FAIL, STK_WAIT_RESULT_SIGNAL, STK_WAIT_RESULT_TIMEOUT, stk::WAIT_RESULT_CANCELED, stk::WAIT_RESULT_SIGNAL, stk::WAIT_RESULT_TIMEOUT, and stk::sync::ConditionVariable::WaitEx().

Here is the call graph for this function:

stk_delay()

void stk_delay

(

stk_timeout_t

ticks

)

Busy-wait delay (other tasks continue to run).

Parameters

[in]

ticks

Ticks to delay.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 644 of file stk_c.cpp.

{ stk::Delay(ticks); }

References stk::Delay().

Here is the call graph for this function:

stk_delay_ms()

void stk_delay_ms

(

stk_timeout_t

ms

)

Busy-wait delay (other tasks continue to run).

Parameters

[in]

ms

Milliseconds to delay.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 646 of file stk_c.cpp.

{ stk::DelayMs(ms); }

References stk::DelayMs().

Here is the call graph for this function:

stk_ef_clear()

uint32_t stk_ef_clear	(	stk_ef_t *	ef,
		uint32_t	flags )

Clear one or more flags.

Atomically clears the specified bits.

Parameters

[in]	ef	EventFlags handle.
[in]	flags	Bitmask of bits to clear. Must not be 0 and must not have bit 31 set.

Returns

Flags word value before clearing, or STK_EF_ERROR_PARAMETER on invalid input.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 415 of file stk_c_sync.cpp.

{
    STK_ASSERT(ef != nullptr);
 
    return ef->handle.Clear(flags);
}

References stk::sync::EventFlags::Clear(), stk_ef_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_ef_create()

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

Create an EventFlags object (using provided memory).

Parameters

[in]	membuf	Pointer to static memory container.
[in]	initial_flags	Initial value of the 32-bit flags word (bits 0..30 only; bit 31 is reserved and must not be set).

Returns

EventFlags handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 386 of file stk_c_sync.cpp.

{
    STK_ASSERT(membuf != nullptr);
 
    stk_ef_t *result = nullptr;
    if (membuf != nullptr)
    {
        result = ConstructIn<stk_ef_t>(*membuf, initial_flags);
    }
 
    return result;
}

References stk::ConstructIn(), and STK_ASSERT.

Here is the call graph for this function:

stk_ef_destroy()

void stk_ef_destroy

(

stk_ef_t *

ef

)

Destroy an EventFlags object.

Parameters

[in]

ef

EventFlags handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 400 of file stk_c_sync.cpp.

{
    if (ef != nullptr)
    {
        ef->~stk_ef_t();
    }
}

stk_ef_get()

uint32_t stk_ef_get

(

stk_ef_t *

ef

)

Read the current flags word without modifying it.

Parameters

[in]

ef

EventFlags handle.

Returns

Point-in-time snapshot of the 32-bit flags word.

Note

ISR-safe. Never blocks or modifies state.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 422 of file stk_c_sync.cpp.

{
    STK_ASSERT(ef != nullptr);
 
    return ef->handle.Get();
}

References stk::sync::EventFlags::Get(), stk_ef_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_ef_get_instance()

stk::sync::EventFlags * stk_ef_get_instance

(

stk_ef_t *

ef

)

Get the underlying C++ stk::sync::EventFlags object wrapped by a stk_ef_t handle.

Parameters

[in]

ef

EventFlags handle obtained via stk_ef_create().

Returns

Pointer to the wrapped stk::sync::EventFlags instance. Never NULL for a valid handle.

Note

C++ callers only (guarded by __cplusplus); not part of the C ABI.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 443 of file stk_c_sync.cpp.

{
    STK_ASSERT(ef != nullptr);
 
    return &ef->handle;
}

References stk_ef_t::handle, and STK_ASSERT.

stk_ef_is_error()

bool stk_ef_is_error ( uint32_t result )

inlinestatic

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).

< Mask for testing any error; bit 31 set means error

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 1338 of file stk_c.h.

{ 
    return ((result & STK_EF_ERROR_MASK) != 0U); 
}

References STK_EF_ERROR_MASK.

stk_ef_set()

uint32_t stk_ef_set	(	stk_ef_t *	ef,
		uint32_t	flags )

Set one or more flags.

Atomically OR-sets the specified bits and wakes all current waiters so each can re-evaluate its own predicate.

Parameters

[in]	ef	EventFlags handle.
[in]	flags	Bitmask of bits to set. Must not be 0 and must not have bit 31 set.

Returns

Flags word value after setting, or STK_EF_ERROR_PARAMETER on invalid input.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 408 of file stk_c_sync.cpp.

{
    STK_ASSERT(ef != nullptr);
 
    return ef->handle.Set(flags);
}

References stk_ef_t::handle, stk::sync::EventFlags::Set(), and STK_ASSERT.

Here is the call graph for this function:

stk_ef_trywait()

uint32_t stk_ef_trywait	(	stk_ef_t *	ef,
		uint32_t	flags,
		uint32_t	options )

Non-blocking flag poll.

Checks immediately whether the flag condition is satisfied. Clears matched bits on success unless STK_EF_OPT_NO_CLEAR is set.

Parameters

[in]	ef	EventFlags handle.
[in]	flags	Bitmask of flag bits to watch.
[in]	options	STK_EF_OPT_WAIT_ANY (default) or STK_EF_OPT_WAIT_ALL, optionally OR-ed with STK_EF_OPT_NO_CLEAR.

Returns

Matched flags bitmask on success, or STK_EF_ERROR_TIMEOUT immediately if the condition is not met.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 436 of file stk_c_sync.cpp.

{
    STK_ASSERT(ef != nullptr);
 
    return ef->handle.TryWait(flags, options);
}

References stk_ef_t::handle, STK_ASSERT, and stk::sync::EventFlags::TryWait().

Here is the call graph for this function:

stk_ef_wait()

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

Wait for one or more flags to be set.

Suspends the calling task until the requested flag condition is satisfied or the timeout expires. On success, matched bits are atomically cleared unless STK_EF_OPT_NO_CLEAR is set in options.

Parameters

[in]	ef	EventFlags handle.
[in]	flags	Bitmask of flag bits to watch. Must not be 0 and must not have bit 31 set.
[in]	options	Combination of STK_EF_OPT_WAIT_ANY / STK_EF_OPT_WAIT_ALL and optionally STK_EF_OPT_NO_CLEAR.
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE. Use STK_NO_WAIT for a non-blocking poll.

Returns

Bitmask of the matched flags on success, or a STK_EF_ERROR_* sentinel on failure. Always check stk_ef_is_error() before using the return value as a flags mask.

Note

If the predicate becomes satisfied in the same tick that the deadline expires, the wait succeeds and returns the matched flags.

Returns STK_EF_ERROR_CANCELED, not STK_EF_ERROR_TIMEOUT, if the wait was cancelled before either the flag condition was met or the deadline expired.

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Warning

ISR-safe only with timeout = STK_NO_WAIT, ISR-unsafe otherwise.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 429 of file stk_c_sync.cpp.

{
    STK_ASSERT(ef != nullptr);
 
    return ef->handle.Wait(flags, options, timeout);
}

References stk_ef_t::handle, STK_ASSERT, and stk::sync::EventFlags::Wait().

Here is the call graph for this function:

stk_event_create()

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

Create an Event (using provided memory).

Parameters

[in]	membuf	Pointer to static memory container.
[in]	manual_reset	True for manual-reset, False for auto-reset.

Returns

Event handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 231 of file stk_c_sync.cpp.

{
    STK_ASSERT(membuf != nullptr);
 
    stk_event_t *result = nullptr;
    if (membuf != nullptr)
    {
        result = ConstructIn<stk_event_t>(*membuf, manual_reset);
    }
 
    return result;
}

References stk::ConstructIn(), and STK_ASSERT.

Here is the call graph for this function:

stk_event_destroy()

void stk_event_destroy

(

stk_event_t *

ev

)

Destroy an Event.

Parameters

[in]

ev

Event handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 245 of file stk_c_sync.cpp.

{
    if (ev != nullptr)
    {
        ev->~stk_event_t();
    }
}

stk_event_get_instance()

stk::sync::Event * stk_event_get_instance

(

stk_event_t *

ev

)

Get the underlying C++ stk::sync::Event object wrapped by a stk_event_t handle.

Parameters

[in]

ev

Event handle obtained via stk_event_create().

Returns

Pointer to the wrapped stk::sync::Event instance. Never NULL for a valid handle.

Note

C++ callers only (guarded by __cplusplus); not part of the C ABI.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 288 of file stk_c_sync.cpp.

{
    STK_ASSERT(ev != nullptr);
 
    return &ev->handle;
}

References stk_event_t::handle, and STK_ASSERT.

stk_event_pulse()

void stk_event_pulse

(

stk_event_t *

ev

)

Pulse the event (signal then immediately reset).

Parameters

[in]

ev

Event handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 281 of file stk_c_sync.cpp.

{
    STK_ASSERT(ev != nullptr);
 
    ev->handle.Pulse();
}

References stk_event_t::handle, stk::sync::Event::Pulse(), and STK_ASSERT.

Here is the call graph for this function:

stk_event_reset()

bool stk_event_reset

(

stk_event_t *

ev

)

Reset the event to non-signaled state.

Parameters

[in]

ev

Event handle.

Returns

true if state was changed from signaled to non-signaled, false if event was already non-signaled.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 274 of file stk_c_sync.cpp.

{
    STK_ASSERT(ev != nullptr);
 
    return ev->handle.Reset();
}

References stk_event_t::handle, stk::sync::Event::Reset(), and STK_ASSERT.

Here is the call graph for this function:

stk_event_set()

bool stk_event_set

(

stk_event_t *

ev

)

Set the event to signaled state.

Parameters

[in]

ev

Event handle.

Returns

true if state was changed from non-signaled to signaled, false if event was already signaled.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 267 of file stk_c_sync.cpp.

{
    STK_ASSERT(ev != nullptr);
 
    return ev->handle.Set();
}

References stk_event_t::handle, stk::sync::Event::Set(), and STK_ASSERT.

Here is the call graph for this function:

stk_event_trywait()

bool stk_event_trywait

(

stk_event_t *

ev

)

Wait for the event to become signaled.

Parameters

[in]

ev

Event handle.

Returns

True if signaled, False on timeout.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 260 of file stk_c_sync.cpp.

{
    STK_ASSERT(ev != nullptr);
 
    return ev->handle.TryWait();
}

References stk_event_t::handle, STK_ASSERT, and stk::sync::Event::TryWait().

Here is the call graph for this function:

stk_event_wait()

bool stk_event_wait	(	stk_event_t *	ev,
		stk_timeout_t	timeout )

Wait for the event to become signaled.

Parameters

[in]	ev	Event handle.
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE.

Returns

True if signaled, False on timeout.

Note

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 253 of file stk_c_sync.cpp.

{
    STK_ASSERT(ev != nullptr);
 
    return ev->handle.Wait(timeout);
}

References stk_event_t::handle, STK_ASSERT, and stk::sync::Event::Wait().

Here is the call graph for this function:

stk_hires_cycles()

stk_cycle_t stk_hires_cycles

(

void

)

Get raw CPU cycle counter.

Returns

64-bit cycle count. Resolution is one clock cycle.

Note

ISR-safe. Use stk_hires_frequency() to convert to real time.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 641 of file stk_c.cpp.

{ return stk::hw::HiResClock::GetCycles(); }

References stk::hw::HiResClock::GetCycles().

Here is the call graph for this function:

stk_hires_frequency()

uint32_t stk_hires_frequency

(

void

)

Get CPU clock frequency in Hz.

Returns

Clock frequency in Hz.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 642 of file stk_c.cpp.

{ return stk::hw::HiResClock::GetFrequency(); }

References stk::hw::HiResClock::GetFrequency().

Here is the call graph for this function:

stk_hires_time_us()

stk_tick_t stk_hires_time_us

(

void

)

Get elapsed time in microseconds from the high-resolution clock.

Returns

Microseconds since an arbitrary but fixed epoch (typically reset).

Note

ISR-safe. Equivalent to stk_hires_cycles() * 1000000 / stk_hires_frequency().

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 643 of file stk_c.cpp.

{ return stk::hw::HiResClock::GetTimeUs(); }

References stk::hw::HiResClock::GetTimeUs().

Here is the call graph for this function:

stk_kernel_add_task()

void stk_kernel_add_task	(	stk_kernel_t *	k,
		stk_task_t *	tsk )

Add task to non-HRT kernel (static or dynamic).

Parameters

[in]	k	Kernel handle.
[in]	tsk	Task handle created with one of stk_task_create_* functions.

Note

For static kernels this must be done before stk_kernel_start().

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 428 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
    STK_ASSERT(tsk != nullptr);
 
    CastCToKernelInterface(k)->AddTask(&tsk->handle);
}

References stk::IKernel::AddTask(), CastCToKernelInterface(), stk_task_t::handle, and STK_ASSERT.

Referenced by stk::pthread::EnsureReaper().

Here is the call graph for this function:

Here is the caller graph for this function:

stk_kernel_add_task_hrt()

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 )

Add task with HRT timing parameters (HRT kernels only).

Parameters

[in]	k	Kernel handle.
[in]	tsk	Task handle.
[in]	periodicity_ticks	Period in ticks.
[in]	deadline_ticks	Relative deadline in ticks.
[in]	start_delay_ticks	Initial offset / phase in ticks (>= 0).

Note

Must be called after stk_kernel_init() and before stk_kernel_start().

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 536 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
    STK_ASSERT(tsk != nullptr);
 
    CastCToKernelInterface(k)->AddTask(
        &tsk->handle,
        periodicity_ticks,
        deadline_ticks,
        start_delay_ticks);
}

References stk::IKernel::AddTask(), CastCToKernelInterface(), stk_task_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_kernel_create()

stk_kernel_t * stk_kernel_create

(

uint8_t

core_nr

)

Create kernel.

Note

At least STK_C_KERNEL_TYPE_CPU_0 must be defined with the type of the kernel. Place STK_C_KERNEL_TYPE_CPU_X defines inside the stk_config.h file which is per project. STK_C_KERNEL_TYPE_CPU_X type will be assigned to X core.

Parameters

[in]

core_nr

CPU core number (starts with 0). Max: 7 (for 8 cores).

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 331 of file stk_c.cpp.

{
    STK_STATIC_ASSERT((STK_C_CPU_COUNT <= 8U)); // switch (core_nr) below handles cases 0..7; STK_C_KERNEL_TYPE_CPU_N is only defined up to N=7
    STK_ASSERT(core_nr < STK_C_CPU_COUNT);
 
    IKernel *k;
 
    switch (core_nr)
    {
#ifdef STK_C_KERNEL_TYPE_CPU_0
    STK_KERNEL_CASE(0)
#endif
#ifdef STK_C_KERNEL_TYPE_CPU_1
    STK_KERNEL_CASE(1)
#endif
#ifdef STK_C_KERNEL_TYPE_CPU_2
    STK_KERNEL_CASE(2)
#endif
#ifdef STK_C_KERNEL_TYPE_CPU_3
    STK_KERNEL_CASE(3)
#endif
#ifdef STK_C_KERNEL_TYPE_CPU_4
    STK_KERNEL_CASE(4)
#endif
#ifdef STK_C_KERNEL_TYPE_CPU_5
    STK_KERNEL_CASE(5)
#endif
#ifdef STK_C_KERNEL_TYPE_CPU_6
    STK_KERNEL_CASE(6)
#endif
#ifdef STK_C_KERNEL_TYPE_CPU_7
    STK_KERNEL_CASE(7)
#endif
    default: {
        k = nullptr;
        break; }
    }
 
    return CastCppKernelInterfaceToC(k);
}

References CastCppKernelInterfaceToC(), STK_ASSERT, STK_C_CPU_COUNT, STK_KERNEL_CASE, and STK_STATIC_ASSERT.

Here is the call graph for this function:

stk_kernel_destroy()

void stk_kernel_destroy

(

stk_kernel_t *

k

)

Destroy dynamic kernel instance (only when not running).

Parameters

[in]

k

Kernel handle.

Note

Kernel must not be running (all tasks must have exited or been removed). Only valid for kernels created with dynamic factory functions.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 385 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
 
    // Detach the event overrider and clear the registry entry BEFORE calling
    // the destructor: the platform teardown inside ~IKernel() may still invoke
    // GetPlatform() paths, and we must not leave a dangling overrider pointer
    // registered at that point.
    UnregisterKernel(CastCToKernelInterface(k));
}

References CastCToKernelInterface(), STK_ASSERT, and UnregisterKernel().

Here is the call graph for this function:

stk_kernel_enumerate_tasks()

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

Enumerate all currently active tasks.

Parameters

[in]	k	Kernel handle.
[out]	tasks	Caller-allocated array of opaque task pointers. Each element is a stk_task_t* that can be passed to other stk_task_* / stk_kernel_* functions.
[in]	max_count	Capacity of the tasks array (number of elements).

Returns

Number of active tasks written into tasks (0 .. max_count).

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 477 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
    STK_ASSERT(tasks != nullptr);
 
    stk::ITask *itasks[STK_C_TASKS_MAX] = {};
    
    // Determine the safe upper bound for the temporary buffer
    const size_t requested_size = (max_count < static_cast<size_t>(STK_C_TASKS_MAX)) ? max_count : 
        static_cast<size_t>(STK_C_TASKS_MAX);
 
    // Pass via ArrayView temporary object
    const size_t ret_count = CastCToKernelInterface(k)->EnumerateTasks(
        ArrayView<stk::ITask *>(itasks, requested_size));
 
    ArrayView<stk_task_t *> output_view(tasks, max_count);
    for (size_t i = 0U; i < ret_count; ++i)
    {
        output_view[i] = CastCppTaskInterfaceToC(itasks[i]);
    }
 
    return ret_count;
}

References CastCppTaskInterfaceToC(), CastCToKernelInterface(), stk::IKernel::EnumerateTasks(), STK_ASSERT, and STK_C_TASKS_MAX.

Here is the call graph for this function:

stk_kernel_get_instance()

stk::IKernel * stk_kernel_get_instance

(

uint8_t

core_nr

)

Get the underlying C++ stk::IKernel object for a given core.

Parameters

[in]

core_nr

Core id (0U = first core, ...). Must be < STK_C_CPU_COUNT.

Returns

Pointer to the stk::IKernel instance registered for core_nr. Never NULL.

Note

C++ callers only (guarded by __cplusplus); not part of the C ABI.

Warning

core_nr must refer to a kernel already created via stk_kernel_create() and not yet destroyed via stk_kernel_destroy(), otherwise this triggers an assertion failure.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 372 of file stk_c.cpp.

{
    STK_ASSERT(core_nr < STK_C_CPU_COUNT);
 
    IKernel *const k = s_KernelMap[core_nr].kernel;
 
    // Kernel not found: stk_kernel_get_instance() called before
    // stk_kernel_create() or after stk_kernel_destroy().
    STK_ASSERT(k != nullptr);
 
    return k;
}

References s_KernelMap, STK_ASSERT, and STK_C_CPU_COUNT.

stk_kernel_get_state()

stk_kernel_state_t stk_kernel_get_state

(

const stk_kernel_t *

k

)

Get state of the scheduler.

Parameters

[in]

k

Kernel handle.

Returns

State value, see stk_kernel_state_t.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 413 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
 
    return static_cast<stk_kernel_state_t>(CastCToKernelInterfaceConst(k)->GetState());
}

References CastCToKernelInterfaceConst(), stk::IKernel::GetState(), and STK_ASSERT.

Here is the call graph for this function:

stk_kernel_init()

void stk_kernel_init	(	stk_kernel_t *	k,
		uint32_t	tick_period_us )

Initialize kernel with given tick period.

Parameters

[in]	k	Kernel handle.
[in]	tick_period_us	System tick period in microseconds (usually 100–10000).

Note

Must be called exactly once before adding tasks or starting scheduler.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 399 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
 
    CastCToKernelInterface(k)->Initialize(tick_period_us);
}

References CastCToKernelInterface(), stk::IKernel::Initialize(), and STK_ASSERT.

Here is the call graph for this function:

stk_kernel_is_schedulable()

bool stk_kernel_is_schedulable

(

const stk_kernel_t *

k

)

Test whether currently configured task set is schedulable.

Parameters

[in]

k

Kernel handle.

Returns

True if task set passes schedulability test, False otherwise.

Note

Only meaningful for HRT RM/DM kernels.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 420 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
 
    return SchedulabilityCheck::IsSchedulableWCRT<STK_C_KERNEL_MAX_TASKS>(
        const_cast<IKernel *>(CastCToKernelInterfaceConst(k))->GetSwitchStrategy());
}

References CastCToKernelInterfaceConst(), stk::SchedulabilityCheck::IsSchedulableWCRT(), and STK_ASSERT.

Here is the call graph for this function:

stk_kernel_is_started()

bool stk_kernel_is_started

(

const stk_kernel_t *

k

)

Check whether the scheduler is currently running (first task switch has occurred).

Parameters

[in]

k

Kernel handle.

Returns

True if stk_kernel_start() has been called and the first context switch has occurred, False before stk_kernel_start() or after all tasks have exited.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 444 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
 
    const stk::IKernel::EKernelState st = CastCToKernelInterfaceConst(k)->GetState();
    return ((st == stk::IKernel::KSTATE_RUNNING) || (st == stk::IKernel::KSTATE_SUSPENDED));
}

References CastCToKernelInterfaceConst(), stk::IKernel::GetState(), stk::IKernel::KSTATE_RUNNING, stk::IKernel::KSTATE_SUSPENDED, and STK_ASSERT.

Here is the call graph for this function:

stk_kernel_process_hard_fault()

void stk_kernel_process_hard_fault

(

stk_kernel_t *

k

)

Trigger a kernel hard fault (safe-state handler).

Parameters

[in]

k

Kernel handle.

Note

Normally invoked automatically by the kernel when an HRT task misses its deadline. Exposed here for custom fault handlers or test harnesses that need to force a controlled system halt via the platform driver's fault path.

This call does not return.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 522 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
 
    CastCToKernelInterface(k)->GetPlatform()->ProcessHardFault();
}

References CastCToKernelInterface(), stk::IKernel::GetPlatform(), stk::IPlatform::ProcessHardFault(), and STK_ASSERT.

Here is the call graph for this function:

stk_kernel_process_tick()

void stk_kernel_process_tick

(

stk_kernel_t *

k

)

Manually deliver one scheduler tick to the kernel.

Parameters

[in]

k

Kernel handle.

Note

Use this when the platform driver's built-in SysTick handler is disabled (STK_SYSTICK_HANDLER = _STK_SYSTICK_HANDLER_DISABLE in stk_config.h) and the application provides its own tick source. Call from your custom tick ISR at the rate matching the tick period configured in stk_kernel_init().

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 515 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
 
    CastCToKernelInterface(k)->GetPlatform()->ProcessTick();
}

References CastCToKernelInterface(), stk::IKernel::GetPlatform(), stk::IPlatform::ProcessTick(), and STK_ASSERT.

Here is the call graph for this function:

stk_kernel_remove_task()

void stk_kernel_remove_task	(	stk_kernel_t *	k,
		stk_task_t *	tsk )

Remove finished task from dynamic kernel.

Parameters

[in]	k	Kernel handle.
[in]	tsk	Task that has already returned from its entry function.

Note

Only valid in dynamic kernels. Task must have exited (returned from entry function).

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 436 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
    STK_ASSERT(tsk != nullptr);
 
    CastCToKernelInterface(k)->RemoveTask(&tsk->handle);
}

References CastCToKernelInterface(), stk_task_t::handle, stk::IKernel::RemoveTask(), and STK_ASSERT.

Here is the call graph for this function:

stk_kernel_resume()

void stk_kernel_resume	(	stk_kernel_t *	k,
		stk_timeout_t	elapsed_ticks )

Resume scheduling after a prior stk_kernel_suspend() call.

Parameters

[in]	k	Kernel handle.
[in]	elapsed_ticks	Number of ticks that elapsed during the suspended period. The kernel uses this value to advance internal time counters and wake tasks whose sleep deadlines have expired.

Note

ISR-safe.

See also

stk_kernel_suspend

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 508 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
 
    CastCToKernelInterface(k)->GetPlatform()->Resume(static_cast<stk::Timeout>(elapsed_ticks));
}

References CastCToKernelInterface(), stk::IKernel::GetPlatform(), stk::IPlatform::Resume(), and STK_ASSERT.

Here is the call graph for this function:

stk_kernel_resume_task()

void stk_kernel_resume_task	(	stk_kernel_t *	k,
		stk_task_t *	task )

Resume a previously suspended task.

Parameters

[in]	k	Kernel handle.
[in]	task	Task to resume. Must have been suspended with stk_kernel_suspend_task().

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 469 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
    STK_ASSERT(tsk != nullptr);
 
    CastCToKernelInterface(k)->ResumeTask(&tsk->handle);
}

References CastCToKernelInterface(), stk_task_t::handle, stk::IKernel::ResumeTask(), and STK_ASSERT.

Here is the call graph for this function:

stk_kernel_schedule_task_removal()

void stk_kernel_schedule_task_removal	(	stk_kernel_t *	k,
		stk_task_t *	task )

Schedule removal of a running task from the kernel on the next tick.

Parameters

[in]	k	Kernel handle.
[in]	task	Task to remove. Must be currently scheduled.

Note

KERNEL_DYNAMIC only. The task is removed on the next scheduling tick and its OnExit() callback is invoked automatically.

To remove a task before stk_kernel_start(), use stk_kernel_remove_task() instead.

See also

stk_kernel_remove_task

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 452 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
    STK_ASSERT(tsk != nullptr);
 
    CastCToKernelInterface(k)->ScheduleTaskRemoval(&tsk->handle);
}

References CastCToKernelInterface(), stk_task_t::handle, stk::IKernel::ScheduleTaskRemoval(), and STK_ASSERT.

Here is the call graph for this function:

stk_kernel_set_event_overrider()

void stk_kernel_set_event_overrider	(	stk_kernel_t *	k,
		stk_event_overrider_t *	overrider )

Install a platform event overrider on the kernel.

Forwards to IPlatform::SetEventOverrider() via an internal C++ bridge object. Any previously installed overrider is replaced.

Parameters

[in]	k	Kernel handle obtained from stk_kernel_create().
[in]	overrider	Pointer to a caller-owned stk_event_overrider_t. Pass NULL to remove a previously installed overrider. When non-NULL, the struct must remain valid for the entire lifetime of the kernel (static or global storage is recommended).

Note

Must be called after stk_kernel_init() and before stk_kernel_start().

Not ISR-safe.

See also

stk_event_overrider_t

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 529 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
 
    SetEventOverrider(CastCToKernelInterface(k), overrider);
}

References CastCToKernelInterface(), SetEventOverrider(), and STK_ASSERT.

Here is the call graph for this function:

stk_kernel_start()

void stk_kernel_start

(

stk_kernel_t *

k

)

Start the scheduler - never returns.

Parameters

[in]

k

Kernel handle.

Note

Transfers control to the scheduler and a first ready task. May return if all tasks are finished and kernel is dynamic.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 406 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
 
    CastCToKernelInterface(k)->Start();
}

References CastCToKernelInterface(), stk::IKernel::Start(), and STK_ASSERT.

Here is the call graph for this function:

stk_kernel_suspend()

stk_timeout_t stk_kernel_suspend

(

stk_kernel_t *

k

)

Suspend scheduling (tickless idle entry point).

Parameters

[in]

k

Kernel handle.

Returns

Number of ticks available for the suspension period, determined by the nearest pending wake-up deadline across all sleeping tasks. The caller may program a hardware timer with this value to suppress SysTick wakeups.

Note

ISR-safe. Pair every call with stk_kernel_resume().

Only meaningful when the kernel was created with KERNEL_TICKLESS mode.

See also

stk_kernel_resume, STK_KERNEL_STATE_SUSPENDED

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 501 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
 
    return static_cast<stk_timeout_t>(CastCToKernelInterface(k)->GetPlatform()->Suspend());
}

References CastCToKernelInterface(), stk::IKernel::GetPlatform(), STK_ASSERT, and stk::IPlatform::Suspend().

Here is the call graph for this function:

stk_kernel_suspend_task()

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

Suspend a task (prevent it from being scheduled).

Parameters

[in]	k	Kernel handle.
[in]	task	Task to suspend.
[out]	suspended	Set to true if the task was successfully suspended (was awake), false if the task was already sleeping (e.g. blocked on a mutex or timed Sleep).

Note

Do not hold a critical section when suspending the calling task - this will deadlock.

If the task suspends itself, the call blocks until the kernel switches it out.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 460 of file stk_c.cpp.

{
    STK_ASSERT(k != nullptr);
    STK_ASSERT(tsk != nullptr);
    STK_ASSERT(suspended != nullptr);
 
    CastCToKernelInterface(k)->SuspendTask(&tsk->handle, *suspended);
}

References CastCToKernelInterface(), stk_task_t::handle, STK_ASSERT, and stk::IKernel::SuspendTask().

Here is the call graph for this function:

stk_ms_from_ticks()

stk_time_t stk_ms_from_ticks ( stk_tick_t ticks )

inlinestatic

Convert ticks to milliseconds using the current kernel tick resolution.

Parameters

[in]

ticks

Tick count to convert.

Returns

Equivalent time in milliseconds.

Note

Requires the kernel to be initialized before calling.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 715 of file stk_c.h.

{
    return stk_ms_from_ticks_r(ticks, stk_tick_resolution());
}

References stk_ms_from_ticks_r(), and stk_tick_resolution().

Here is the call graph for this function:

stk_ms_from_ticks_r()

stk_time_t stk_ms_from_ticks_r ( stk_tick_t ticks, uint32_t resolution )

inlinestatic

Convert ticks to milliseconds using an explicit tick resolution.

Parameters

[in]	ticks	Tick count to convert.
[in]	resolution	Microseconds per tick (see stk_tick_resolution()).

Returns

Equivalent time in milliseconds.

Note

ISR-safe (arithmetic only).

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 704 of file stk_c.h.

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

References STK_STATIC_CAST.

Referenced by stk_ms_from_ticks().

Here is the caller graph for this function:

stk_msgq_create()

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 )

Create a MessageQueue (using provided memory).

Constructs a stk::sync::MessageQueue in-place inside membuf. The queue will hold up to capacity messages, each msg_size bytes wide. The backing storage for messages must be supplied by the caller via buf / buf_size.

Parameters

[in]	membuf	Pointer to static memory container for the queue object.
[in]	buf	Pointer to the message data buffer. Must be at least capacity * msg_size bytes.
[in]	buf_size	Size of buf in bytes (used only for the safety assertion; must equal capacity * msg_size).
[in]	capacity	Maximum number of messages [1, 65534].
[in]	msg_size	Size of each individual message in bytes (>= 1).

Returns

MessageQueue handle, or NULL if any size assertion fails.

Note

Convenience macro STK_MSGQ_BUF_SIZE(capacity, msg_size) computes the required buf_size.

Only available when kernel is compiled with KERNEL_SYNC mode enabled.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 644 of file stk_c_sync.cpp.

{
    STK_ASSERT(membuf != nullptr);
    STK_ASSERT(buf != nullptr);
    STK_ASSERT(capacity >= 1U);
    STK_ASSERT(msg_size >= 1U);
    STK_ASSERT(buf_size >= capacity * msg_size);
 
    stk_msgq_t *result = nullptr;
    if ((membuf != nullptr) && (buf_size >= (capacity * msg_size)))
    {
        result = ConstructIn<stk_msgq_t>(*membuf, buf, capacity, msg_size);
    }
 
    return result;
}

References stk::ConstructIn(), and STK_ASSERT.

Here is the call graph for this function:

stk_msgq_destroy()

void stk_msgq_destroy

(

stk_msgq_t *

mq

)

Destroy a MessageQueue.

Parameters

[in]

mq

MessageQueue handle.

Note

Any tasks still blocked on Put/Get at destruction time are considered a logic error; an assertion is triggered in debug builds.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 665 of file stk_c_sync.cpp.

{
    if (mq != nullptr)
    {
        mq->~stk_msgq_t();
    }
}

stk_msgq_get()

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

Get a message from the queue.

Copies the oldest message into msg. Blocks if the queue is empty until a message arrives or the timeout expires.

Parameters

[in]	mq	MessageQueue handle.
[out]	msg	Destination buffer (must be >= msg_size bytes).
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE. Use STK_NO_WAIT for a non-blocking attempt.

Returns

True if a message was retrieved, False on timeout.

Note

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Warning

ISR-safe only with timeout = STK_NO_WAIT.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 705 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
    STK_ASSERT(msg != nullptr);
 
    return mq->handle.Get(msg, timeout);
}

References stk::sync::MessageQueue::Get(), stk_msgq_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_msgq_get_buffer()

uint8_t * stk_msgq_get_buffer

(

stk_msgq_t *

mq

)

Get a pointer to the raw message data buffer.

Parameters

[in]

mq

MessageQueue handle.

Returns

Pointer to the beginning of the backing byte buffer supplied at construction time.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 802 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
 
    return mq->handle.GetBuffer();
}

References stk::sync::MessageQueue::GetBuffer(), stk_msgq_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_msgq_get_capacity()

size_t stk_msgq_get_capacity

(

const stk_msgq_t *

mq

)

Get the maximum number of messages the queue can hold.

Parameters

[in]

mq

MessageQueue handle.

Returns

Construction-time capacity.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 760 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
 
    return mq->handle.GetCapacity();
}

References stk::sync::MessageQueue::GetCapacity(), stk_msgq_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_msgq_get_count()

size_t stk_msgq_get_count

(

const stk_msgq_t *

mq

)

Get the current number of messages waiting in the queue.

Parameters

[in]

mq

MessageQueue handle.

Returns

Point-in-time snapshot of the message count.

Note

ISR-safe on targets where a size_t-aligned read is atomic.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 774 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
 
    return mq->handle.GetCount();
}

References stk::sync::MessageQueue::GetCount(), stk_msgq_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_msgq_get_instance()

stk::sync::MessageQueue * stk_msgq_get_instance

(

stk_msgq_t *

mq

)

Get the underlying C++ stk::sync::MessageQueue object wrapped by a stk_msgq_t handle.

Parameters

[in]

mq

MessageQueue handle obtained via stk_msgq_create().

Returns

Pointer to the wrapped stk::sync::MessageQueue instance. Never NULL for a valid handle.

Note

C++ callers only (guarded by __cplusplus); not part of the C ABI.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 816 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
 
    return &mq->handle;
}

References stk_msgq_t::handle, and STK_ASSERT.

stk_msgq_get_msg_size()

size_t stk_msgq_get_msg_size

(

const stk_msgq_t *

mq

)

Get the size of each message in bytes.

Parameters

[in]

mq

MessageQueue handle.

Returns

Construction-time message size.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 767 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
 
    return mq->handle.GetMsgSize();
}

References stk::sync::MessageQueue::GetMsgSize(), stk_msgq_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_msgq_get_space()

size_t stk_msgq_get_space

(

const stk_msgq_t *

mq

)

Get the number of free slots currently available.

Parameters

[in]

mq

MessageQueue handle.

Returns

Point-in-time snapshot of the free-slot count.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 781 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
 
    return mq->handle.GetSpace();
}

References stk::sync::MessageQueue::GetSpace(), stk_msgq_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_msgq_is_empty()

bool stk_msgq_is_empty

(

const stk_msgq_t *

mq

)

Check whether the queue is currently empty.

Parameters

[in]

mq

MessageQueue handle.

Returns

True if the queue contains no messages.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 788 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
 
    return mq->handle.IsEmpty();
}

References stk_msgq_t::handle, stk::sync::MessageQueue::IsEmpty(), and STK_ASSERT.

Here is the call graph for this function:

stk_msgq_is_full()

bool stk_msgq_is_full

(

const stk_msgq_t *

mq

)

Check whether the queue is currently full.

Parameters

[in]

mq

MessageQueue handle.

Returns

True if the queue contains capacity messages.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 795 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
 
    return mq->handle.IsFull();
}

References stk_msgq_t::handle, stk::sync::MessageQueue::IsFull(), and STK_ASSERT.

Here is the call graph for this function:

stk_msgq_is_storage_valid()

bool stk_msgq_is_storage_valid

(

const stk_msgq_t *

mq

)

Verify that the backing storage is valid and the queue is ready for use.

Always true for queues constructed with a non-NULL buffer. Useful as a post-construction sanity check in no-exceptions environments; stk_msgq_create() returning NULL already covers the primary failure path.

Parameters

[in]

mq

MessageQueue handle.

Returns

True if the queue is ready for use.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 809 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
 
    return mq->handle.IsStorageValid();
}

References stk_msgq_t::handle, stk::sync::MessageQueue::IsStorageValid(), and STK_ASSERT.

Here is the call graph for this function:

stk_msgq_peek()

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

Peek at the next message to be delivered without removing it.

Copies msg_size bytes from the oldest slot into msg, leaving the message in place so that a subsequent stk_msgq_get() returns the same message. Blocks if the queue is empty until a message is available or the timeout expires.

Parameters

[in]	mq	MessageQueue handle.
[out]	msg	Destination buffer (must be >= msg_size bytes).
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE. Use STK_NO_WAIT for a non-blocking attempt.

Returns

True if a message was peeked, False on timeout.

Note

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Warning

ISR-safe only with timeout = STK_NO_WAIT.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 721 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
    STK_ASSERT(msg != nullptr);
 
    return mq->handle.Peek(msg, timeout);
}

References stk_msgq_t::handle, stk::sync::MessageQueue::Peek(), and STK_ASSERT.

Here is the call graph for this function:

stk_msgq_peekfront()

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

Peek at the most recently front-inserted message without removing it.

Copies msg_size bytes from the front slot (i.e. the message that stk_msgq_putfront() most recently placed) into msg, leaving the message in the queue. Blocks if the queue is empty until a message is available or the timeout expires.

Parameters

[in]	mq	MessageQueue handle.
[out]	msg	Destination buffer (must be >= msg_size bytes).
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE. Use STK_NO_WAIT for a non-blocking attempt.

Returns

True if a message was peeked, False on timeout.

Note

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Warning

ISR-safe only with timeout = STK_NO_WAIT.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 737 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
    STK_ASSERT(msg != nullptr);
 
    return mq->handle.PeekFront(msg, timeout);
}

References stk_msgq_t::handle, stk::sync::MessageQueue::PeekFront(), and STK_ASSERT.

Here is the call graph for this function:

stk_msgq_put()

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

Put a message into the queue.

Copies msg_size bytes from msg into the next available slot. Blocks if the queue is full until space becomes available or the timeout expires.

Parameters

[in]	mq	MessageQueue handle.
[in]	msg	Pointer to the message payload (must be >= msg_size bytes).
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE. Use STK_NO_WAIT for a non-blocking attempt.

Returns

True if the message was enqueued, False on timeout.

Note

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Warning

ISR-safe only with timeout = STK_NO_WAIT.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 673 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
    STK_ASSERT(msg != nullptr);
 
    return mq->handle.Put(msg, timeout);
}

References stk_msgq_t::handle, stk::sync::MessageQueue::Put(), and STK_ASSERT.

Here is the call graph for this function:

stk_msgq_putfront()

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

Put a message into the front of the queue (priority insert).

Copies msg_size bytes from msg into the slot immediately before the current read pointer, making it the next message that stk_msgq_get() will return. Blocks if the queue is full until space becomes available or the timeout expires.

Parameters

[in]	mq	MessageQueue handle.
[in]	msg	Pointer to the message payload (must be >= msg_size bytes).
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE. Use STK_NO_WAIT for a non-blocking attempt.

Returns

True if the message was enqueued at the front, False on timeout.

Note

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Warning

ISR-safe only with timeout = STK_NO_WAIT.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 689 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
    STK_ASSERT(msg != nullptr);
 
    return mq->handle.PutFront(msg, timeout);
}

References stk_msgq_t::handle, stk::sync::MessageQueue::PutFront(), and STK_ASSERT.

Here is the call graph for this function:

stk_msgq_reset()

void stk_msgq_reset

(

stk_msgq_t *

mq

)

Discard all messages and reset the queue to the empty state.

Tasks blocked in Put() are woken so they can re-enqueue into the now-empty queue.

Parameters

[in]

mq

MessageQueue handle.

Warning

Messages that were in the queue are silently discarded.

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 753 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
 
    mq->handle.Reset();
}

References stk_msgq_t::handle, stk::sync::MessageQueue::Reset(), and STK_ASSERT.

Here is the call graph for this function:

stk_msgq_tryget()

bool stk_msgq_tryget	(	stk_msgq_t *	mq,
		void *	msg )

Attempt to get a message from the queue without blocking.

Parameters

[in]	mq	MessageQueue handle.
[out]	msg	Destination buffer.

Returns

True if a message was retrieved, False if the queue was empty.

Warning

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 713 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
    STK_ASSERT(msg != nullptr);
 
    return mq->handle.TryGet(msg);
}

References stk_msgq_t::handle, STK_ASSERT, and stk::sync::MessageQueue::TryGet().

Here is the call graph for this function:

stk_msgq_trypeek()

bool stk_msgq_trypeek	(	stk_msgq_t *	mq,
		void *	msg )

Attempt to peek at the next message without blocking.

Parameters

[in]	mq	MessageQueue handle.
[out]	msg	Destination buffer (must be >= msg_size bytes).

Returns

True if a message was peeked, False if the queue was empty.

Warning

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 729 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
    STK_ASSERT(msg != nullptr);
 
    return mq->handle.TryPeek(msg);
}

References stk_msgq_t::handle, STK_ASSERT, and stk::sync::MessageQueue::TryPeek().

Here is the call graph for this function:

stk_msgq_trypeekfront()

bool stk_msgq_trypeekfront	(	stk_msgq_t *	mq,
		void *	msg )

Attempt to peek at the front message without blocking.

Parameters

[in]	mq	MessageQueue handle.
[out]	msg	Destination buffer (must be >= msg_size bytes).

Returns

True if a message was peeked, False if the queue was empty.

Warning

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 745 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
    STK_ASSERT(msg != nullptr);
 
    return mq->handle.TryPeekFront(msg);
}

References stk_msgq_t::handle, STK_ASSERT, and stk::sync::MessageQueue::TryPeekFront().

Here is the call graph for this function:

stk_msgq_tryput()

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

Attempt to put a message into the queue without blocking.

Parameters

[in]	mq	MessageQueue handle.
[in]	msg	Pointer to the message payload.

Returns

True if enqueued, False if the queue was full.

Warning

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 681 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
    STK_ASSERT(msg != nullptr);
 
    return mq->handle.TryPut(msg);
}

References stk_msgq_t::handle, STK_ASSERT, and stk::sync::MessageQueue::TryPut().

Here is the call graph for this function:

stk_msgq_tryputfront()

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

Attempt to put a message into the front of the queue without blocking.

Parameters

[in]	mq	MessageQueue handle.
[in]	msg	Pointer to the message payload.

Returns

True if enqueued at the front, False if the queue was full.

Warning

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 697 of file stk_c_sync.cpp.

{
    STK_ASSERT(mq != nullptr);
    STK_ASSERT(msg != nullptr);
 
    return mq->handle.TryPutFront(msg);
}

References stk_msgq_t::handle, STK_ASSERT, and stk::sync::MessageQueue::TryPutFront().

Here is the call graph for this function:

stk_mutex_create()

stk_mutex_t * stk_mutex_create

(

stk_mutex_mem_t *const

membuf

)

Create a Mutex (using provided memory).

Parameters

[in]

membuf

Pointer to static memory container.

Returns

Mutex handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 34 of file stk_c_sync.cpp.

{
    STK_ASSERT(membuf != nullptr);
 
    stk_mutex_t *result = nullptr;
    if (membuf != nullptr)
    {
        result = ConstructIn<stk_mutex_t>(*membuf);
    }
 
    return result;
}

References stk::ConstructIn(), and STK_ASSERT.

Here is the call graph for this function:

stk_mutex_destroy()

void stk_mutex_destroy

(

stk_mutex_t *

mtx

)

Destroy a Mutex.

Parameters

[in]

mtx

Mutex handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 47 of file stk_c_sync.cpp.

{
    if (mtx != nullptr)
    {
        mtx->~stk_mutex_t();
    }
}

stk_mutex_get_instance()

stk::sync::Mutex * stk_mutex_get_instance

(

stk_mutex_t *

mtx

)

Get the underlying C++ stk::sync::Mutex object wrapped by a stk_mutex_t handle.

Parameters

[in]

mtx

Mutex handle obtained via stk_mutex_create().

Returns

Pointer to the wrapped stk::sync::Mutex instance. Never NULL for a valid handle.

Note

C++ callers only (guarded by __cplusplus); not part of the C ABI.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 83 of file stk_c_sync.cpp.

{
    STK_ASSERT(mtx != nullptr);
 
    return &mtx->handle;
}

References stk_mutex_t::handle, and STK_ASSERT.

stk_mutex_lock()

void stk_mutex_lock

(

stk_mutex_t *

mtx

)

Lock the mutex. Blocks until available.

Parameters

[in]

mtx

Mutex handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 55 of file stk_c_sync.cpp.

{
    STK_ASSERT(mtx != nullptr);
 
    mtx->handle.Lock();
}

References stk_mutex_t::handle, stk::sync::Mutex::Lock(), and STK_ASSERT.

Here is the call graph for this function:

stk_mutex_timed_lock()

bool stk_mutex_timed_lock	(	stk_mutex_t *	mtx,
		stk_timeout_t	timeout )

Try to lock the mutex with a timeout.

Parameters

[in]	mtx	Mutex handle.
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE.

Returns

True if locked successfully, False on timeout.

Note

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 76 of file stk_c_sync.cpp.

{
    STK_ASSERT(mtx != nullptr);
 
    return mtx->handle.TimedLock(timeout);
}

References stk_mutex_t::handle, STK_ASSERT, and stk::sync::Mutex::TimedLock().

Here is the call graph for this function:

stk_mutex_trylock()

bool stk_mutex_trylock

(

stk_mutex_t *

mtx

)

Try locking the mutex. Does not block if already locked.

Parameters

[in]

mtx

Mutex handle.

Returns

True if locked successfully, False on timeout.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 62 of file stk_c_sync.cpp.

{
    STK_ASSERT(mtx != nullptr);
 
    return mtx->handle.TryLock();
}

References stk_mutex_t::handle, STK_ASSERT, and stk::sync::Mutex::TryLock().

Here is the call graph for this function:

stk_mutex_unlock()

void stk_mutex_unlock

(

stk_mutex_t *

mtx

)

Unlock the mutex.

Parameters

[in]

mtx

Mutex handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 69 of file stk_c_sync.cpp.

{
    STK_ASSERT(mtx != nullptr);
 
    mtx->handle.Unlock();
}

References stk_mutex_t::handle, STK_ASSERT, and stk::sync::Mutex::Unlock().

Here is the call graph for this function:

stk_pipe_create()

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 )

Create a Pipe (using provided memory).

Constructs a stk::sync::Pipe in-place inside membuf. The pipe will hold up to capacity elements, each element_size bytes wide. The backing ring-buffer storage must be supplied by the caller via buf / buf_size.

Parameters

[in]	membuf	Pointer to static memory container for the Pipe control-block.
[in]	buf	Pointer to the element data buffer. Must be at least capacity * element_size bytes.
[in]	buf_size	Size of buf in bytes (used for the safety assertion; must equal capacity * element_size).
[in]	capacity	Maximum number of elements [1, 65534].
[in]	element_size	Size of each individual element in bytes (>= 1).

Returns

Pipe handle, or NULL if any size assertion fails.

Note

Convenience macro STK_PIPE_BUF_SIZE(capacity, element_size) computes the required buf_size.

Only available when kernel is compiled with KERNEL_SYNC mode enabled.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 462 of file stk_c_sync.cpp.

{
    STK_ASSERT(membuf       != nullptr);
    STK_ASSERT(buf          != nullptr);
    STK_ASSERT(capacity     >= 1U);
    STK_ASSERT(element_size >= 1U);
    STK_ASSERT(buf_size     >= capacity * element_size);
 
    stk_pipe_t *result = nullptr;
    if ((membuf != nullptr) && (buf_size >= (capacity * element_size)))
    {
        result = ConstructIn<stk_pipe_t>(*membuf, buf, capacity, element_size);
    }
 
    return result;
}

References stk::ConstructIn(), and STK_ASSERT.

Here is the call graph for this function:

stk_pipe_destroy()

void stk_pipe_destroy

(

stk_pipe_t *

pipe

)

Destroy a Pipe.

Parameters

[in]

pipe

Pipe handle.

Note

Any tasks still blocked on Write/Read at destruction time are considered a logic error; an assertion is triggered in debug builds.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 483 of file stk_c_sync.cpp.

{
    if (pipe != nullptr)
    {
        pipe->~stk_pipe_t();
    }
}

stk_pipe_get_capacity()

size_t stk_pipe_get_capacity

(

const stk_pipe_t *

pipe

)

Get the maximum number of elements the pipe can hold.

Parameters

[in]

pipe

Pipe handle.

Returns

Construction-time capacity.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 576 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
 
    return pipe->handle.GetCapacity();
}

References stk::sync::Pipe::GetCapacity(), stk_pipe_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_pipe_get_count()

size_t stk_pipe_get_count

(

const stk_pipe_t *

pipe

)

Get the current number of elements in the pipe.

Parameters

[in]

pipe

Pipe handle.

Returns

Point-in-time snapshot of the element count.

Note

ISR-safe on targets where a size_t-aligned read is atomic.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 590 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
 
    return pipe->handle.GetCount();
}

References stk::sync::Pipe::GetCount(), stk_pipe_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_pipe_get_element_size()

size_t stk_pipe_get_element_size

(

const stk_pipe_t *

pipe

)

Get the size of each element in bytes.

Parameters

[in]

pipe

Pipe handle.

Returns

Construction-time element size.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 583 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
 
    return pipe->handle.GetElementSize();
}

References stk::sync::Pipe::GetElementSize(), stk_pipe_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_pipe_get_instance()

stk::sync::Pipe * stk_pipe_get_instance

(

stk_pipe_t *

pipe

)

Get the underlying C++ stk::sync::Pipe object wrapped by a stk_pipe_t handle.

Parameters

[in]

pipe

Pipe handle obtained via stk_pipe_create().

Returns

Pointer to the wrapped stk::sync::Pipe instance. Never NULL for a valid handle.

Note

C++ callers only (guarded by __cplusplus); not part of the C ABI.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 625 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
 
    return &pipe->handle;
}

References stk_pipe_t::handle, and STK_ASSERT.

stk_pipe_get_space()

size_t stk_pipe_get_space

(

const stk_pipe_t *

pipe

)

Get the number of free slots currently available.

Parameters

[in]

pipe

Pipe handle.

Returns

Point-in-time snapshot of the free-slot count.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 597 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
 
    return pipe->handle.GetSpace();
}

References stk::sync::Pipe::GetSpace(), stk_pipe_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_pipe_is_empty()

bool stk_pipe_is_empty

(

const stk_pipe_t *

pipe

)

Check whether the pipe is currently empty.

Parameters

[in]

pipe

Pipe handle.

Returns

True if the pipe contains no elements.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 604 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
 
    return pipe->handle.IsEmpty();
}

References stk_pipe_t::handle, stk::sync::Pipe::IsEmpty(), and STK_ASSERT.

Here is the call graph for this function:

stk_pipe_is_full()

bool stk_pipe_is_full

(

const stk_pipe_t *

pipe

)

Check whether the pipe is currently full.

Parameters

[in]

pipe

Pipe handle.

Returns

True if the pipe contains capacity elements.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 611 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
 
    return pipe->handle.IsFull();
}

References stk_pipe_t::handle, stk::sync::Pipe::IsFull(), and STK_ASSERT.

Here is the call graph for this function:

stk_pipe_is_storage_valid()

bool stk_pipe_is_storage_valid

(

const stk_pipe_t *

pipe

)

Verify that the backing storage is valid and the pipe is ready for use.

Parameters

[in]

pipe

Pipe handle.

Returns

True if the pipe is ready for use.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 618 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
 
    return pipe->handle.IsStorageValid();
}

References stk_pipe_t::handle, stk::sync::Pipe::IsStorageValid(), and STK_ASSERT.

Here is the call graph for this function:

stk_pipe_read()

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

Read a single element from the pipe.

Copies element_size bytes from the oldest slot into the buffer pointed to by data. Blocks if the pipe is empty until data is produced or the timeout expires.

Parameters

[in]	pipe	Pipe handle.
[out]	data	Destination buffer (must be >= element_size bytes).
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE. Use STK_NO_WAIT for a non-blocking attempt.

Returns

True if an element was read, False on timeout.

Note

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Warning

ISR-safe only with timeout = STK_NO_WAIT.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 507 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
    STK_ASSERT(data != nullptr);
 
    return pipe->handle.Read(data, timeout);
}

References stk_pipe_t::handle, stk::sync::Pipe::Read(), and STK_ASSERT.

Here is the call graph for this function:

stk_pipe_read_bulk()

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

Read multiple elements from the pipe.

Attempts to retrieve count elements from the FIFO. Blocks until the full amount is read or the timeout expires.

Parameters

[in]	pipe	Pipe handle.
[out]	dst	Pointer to the destination array (must hold at least count elements of element_size bytes each).
[in]	count	Number of elements to read.
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE. Use STK_NO_WAIT for a non-blocking attempt.

Returns

Number of elements actually read. Equal to count unless a timeout occurred.

Note

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Warning

ISR-safe only with timeout = STK_NO_WAIT.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 537 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
 
    return pipe->handle.ReadBulk(dst, count, timeout);
}

References stk_pipe_t::handle, stk::sync::Pipe::ReadBulk(), and STK_ASSERT.

Here is the call graph for this function:

stk_pipe_read_bulk_triggered()

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

Read at least trigger elements, then drain up to max_count without blocking.

Blocks until at least trigger elements are simultaneously available in the pipe, or the timeout expires. Once the threshold is reached the call dequeues min(max_count, available) elements in a single atomic pass.

Parameters

[in]	pipe	Pipe handle.
[out]	dst	Destination buffer; must hold at least max_count elements of element_size bytes.
[in]	trigger	Minimum number of elements that must be available before any data is dequeued. Clamped to [1, max_count] internally.
[in]	max_count	Maximum number of elements to return in total.
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE. Use STK_NO_WAIT for a non-blocking attempt.

Returns

Number of elements actually read (0 if timeout fired before trigger was reached).

Note

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Warning

ISR-safe only with timeout = STK_NO_WAIT.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 551 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
 
    return pipe->handle.ReadBulkTriggered(dst, trigger, max_count, timeout);
}

References stk_pipe_t::handle, stk::sync::Pipe::ReadBulkTriggered(), and STK_ASSERT.

Here is the call graph for this function:

stk_pipe_reset()

void stk_pipe_reset

(

stk_pipe_t *

pipe

)

Discard all elements and reset the pipe to the empty state.

Any tasks blocked in Write() are woken so they can re-evaluate.

Parameters

[in]

pipe

Pipe handle.

Warning

Elements that were in the pipe are silently discarded.

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 569 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
 
    pipe->handle.Reset();
}

References stk_pipe_t::handle, stk::sync::Pipe::Reset(), and STK_ASSERT.

Here is the call graph for this function:

stk_pipe_tryread()

bool stk_pipe_tryread	(	stk_pipe_t *	pipe,
		void *	data )

Attempt to read a single element from the pipe without blocking.

Parameters

[in]	pipe	Pipe handle.
[out]	data	Destination buffer (must be >= element_size bytes).

Returns

True if an element was read, False if the pipe was empty.

Warning

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 515 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
    STK_ASSERT(data != nullptr);
 
    return pipe->handle.TryRead(data);
}

References stk_pipe_t::handle, STK_ASSERT, and stk::sync::Pipe::TryRead().

Here is the call graph for this function:

stk_pipe_tryread_bulk()

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

Attempt to read multiple elements from the pipe without blocking.

Reads as many elements as are currently available without blocking.

Parameters

[in]	pipe	Pipe handle.
[out]	dst	Pointer to the destination array.
[in]	count	Number of elements to read.

Returns

Number of elements actually read.

Warning

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 544 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
 
    return pipe->handle.TryReadBulk(dst, count);
}

References stk_pipe_t::handle, STK_ASSERT, and stk::sync::Pipe::TryReadBulk().

Here is the call graph for this function:

stk_pipe_tryread_bulk_triggered()

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

Non-blocking variant of stk_pipe_read_bulk_triggered.

Returns immediately with however many elements are available, up to max_count. The trigger threshold is not enforced.

Parameters

[in]	pipe	Pipe handle.
[out]	dst	Destination buffer.
[in]	max_count	Maximum number of elements to read.

Returns

Number of elements actually read.

Warning

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 562 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
 
    return pipe->handle.TryReadBulkTriggered(dst, max_count);
}

References stk_pipe_t::handle, STK_ASSERT, and stk::sync::Pipe::TryReadBulkTriggered().

Here is the call graph for this function:

stk_pipe_trywrite()

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

Attempt to write a single element to the pipe without blocking.

Parameters

[in]	pipe	Pipe handle.
[in]	data	Pointer to the element payload.

Returns

True if written, False if the pipe was full.

Warning

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 499 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
    STK_ASSERT(data != nullptr);
 
    return pipe->handle.TryWrite(data);
}

References stk_pipe_t::handle, STK_ASSERT, and stk::sync::Pipe::TryWrite().

Here is the call graph for this function:

stk_pipe_trywrite_bulk()

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

Attempt to write multiple elements to the pipe without blocking.

Copies as many elements as possible. Elements that do not fit are discarded.

Parameters

[in]	pipe	Pipe handle.
[in]	src	Pointer to the source array.
[in]	count	Number of elements to write.

Returns

Number of elements actually written.

Warning

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 530 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
 
    return pipe->handle.TryWriteBulk(src, count);
}

References stk_pipe_t::handle, STK_ASSERT, and stk::sync::Pipe::TryWriteBulk().

Here is the call graph for this function:

stk_pipe_write()

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

Write a single element to the pipe.

Copies element_size bytes from data into the next available slot. Blocks if the pipe is full until space becomes available or the timeout expires.

Parameters

[in]	pipe	Pipe handle.
[in]	data	Pointer to the element payload (must be >= element_size bytes).
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE. Use STK_NO_WAIT for a non-blocking attempt.

Returns

True if the element was written, False on timeout.

Note

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Warning

ISR-safe only with timeout = STK_NO_WAIT.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 491 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
    STK_ASSERT(data != nullptr);
 
    return pipe->handle.Write(data, timeout);
}

References stk_pipe_t::handle, STK_ASSERT, and stk::sync::Pipe::Write().

Here is the call graph for this function:

stk_pipe_write_bulk()

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

Write multiple elements to the pipe.

Copies a block of count elements. Blocks until the full amount is written or the timeout expires.

Parameters

[in]	pipe	Pipe handle.
[in]	src	Pointer to the source array (must hold at least count elements of element_size bytes each).
[in]	count	Number of elements to write.
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE. Use STK_NO_WAIT for a non-blocking attempt.

Returns

Number of elements actually written. Equal to count unless a timeout occurred.

Note

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Warning

ISR-safe only with timeout = STK_NO_WAIT.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 523 of file stk_c_sync.cpp.

{
    STK_ASSERT(pipe != nullptr);
 
    return pipe->handle.WriteBulk(src, count, timeout);
}

References stk_pipe_t::handle, STK_ASSERT, and stk::sync::Pipe::WriteBulk().

Here is the call graph for this function:

stk_rwmutex_create()

stk_rwmutex_t * stk_rwmutex_create

(

stk_rwmutex_mem_t *const

membuf

)

Create an RWMutex (using provided memory).

Parameters

[in]

membuf

Pointer to static memory container.

Returns

RWMutex handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 831 of file stk_c_sync.cpp.

{
    STK_ASSERT(membuf != nullptr);
 
    stk_rwmutex_t *result = nullptr;
    if (membuf != nullptr)
    {
        result = ConstructIn<stk_rwmutex_t>(*membuf);
    }
 
    return result;
}

References stk::ConstructIn(), and STK_ASSERT.

Here is the call graph for this function:

stk_rwmutex_destroy()

void stk_rwmutex_destroy

(

stk_rwmutex_t *

rw

)

Destroy an RWMutex.

Parameters

[in]

rw

RWMutex handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 844 of file stk_c_sync.cpp.

{
    if (rw != nullptr)
    {
        rw->~stk_rwmutex_t();
    }
}

stk_rwmutex_get_instance()

stk::sync::RWMutex * stk_rwmutex_get_instance

(

stk_rwmutex_t *

rw

)

Get the underlying C++ stk::sync::RWMutex object wrapped by a stk_rwmutex_t handle.

Parameters

[in]

rw

RWMutex handle obtained via stk_rwmutex_create().

Returns

Pointer to the wrapped stk::sync::RWMutex instance. Never NULL for a valid handle.

Note

C++ callers only (guarded by __cplusplus); not part of the C ABI.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 908 of file stk_c_sync.cpp.

{
    STK_ASSERT(rw != nullptr);
 
    return &rw->handle;
}

References stk_rwmutex_t::handle, and STK_ASSERT.

stk_rwmutex_lock()

void stk_rwmutex_lock

(

stk_rwmutex_t *

rw

)

Acquire the lock for exclusive writing. Blocks until available.

Blocks until all active readers have released their locks and no other writer is active.

Parameters

[in]

rw

RWMutex handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 880 of file stk_c_sync.cpp.

{
    STK_ASSERT(rw != nullptr);
 
    rw->handle.Lock();
}

References stk_rwmutex_t::handle, stk::sync::RWMutex::Lock(), and STK_ASSERT.

Here is the call graph for this function:

stk_rwmutex_read_lock()

void stk_rwmutex_read_lock

(

stk_rwmutex_t *

rw

)

Acquire the lock for shared reading. Blocks until available.

Blocks if a writer is currently active or writers are waiting (Writer Preference Policy).

Parameters

[in]

rw

RWMutex handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 852 of file stk_c_sync.cpp.

{
    STK_ASSERT(rw != nullptr);
 
    rw->handle.ReadLock();
}

References stk_rwmutex_t::handle, stk::sync::RWMutex::ReadLock(), and STK_ASSERT.

Here is the call graph for this function:

stk_rwmutex_read_unlock()

void stk_rwmutex_read_unlock

(

stk_rwmutex_t *

rw

)

Release the shared reader lock.

If this is the last active reader, waiting writers are notified.

Parameters

[in]

rw

RWMutex handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 873 of file stk_c_sync.cpp.

{
    STK_ASSERT(rw != nullptr);
 
    rw->handle.ReadUnlock();
}

References stk_rwmutex_t::handle, stk::sync::RWMutex::ReadUnlock(), and STK_ASSERT.

Here is the call graph for this function:

stk_rwmutex_timed_lock()

bool stk_rwmutex_timed_lock	(	stk_rwmutex_t *	rw,
		stk_timeout_t	timeout )

Try to acquire the write lock with a timeout.

Parameters

[in]	rw	RWMutex handle.
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE. Use STK_NO_WAIT for non-blocking.

Returns

True if acquired, False on timeout.

Note

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 894 of file stk_c_sync.cpp.

{
    STK_ASSERT(rw != nullptr);
 
    return rw->handle.TimedLock(timeout);
}

References stk_rwmutex_t::handle, STK_ASSERT, and stk::sync::RWMutex::TimedLock().

Here is the call graph for this function:

stk_rwmutex_timed_read_lock()

bool stk_rwmutex_timed_read_lock	(	stk_rwmutex_t *	rw,
		stk_timeout_t	timeout )

Try to acquire the read lock with a timeout.

Parameters

[in]	rw	RWMutex handle.
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE. Use STK_NO_WAIT for non-blocking.

Returns

True if acquired, False on timeout.

Note

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 866 of file stk_c_sync.cpp.

{
    STK_ASSERT(rw != nullptr);
 
    return rw->handle.TimedReadLock(timeout);
}

References stk_rwmutex_t::handle, STK_ASSERT, and stk::sync::RWMutex::TimedReadLock().

Here is the call graph for this function:

stk_rwmutex_try_read_lock()

bool stk_rwmutex_try_read_lock

(

stk_rwmutex_t *

rw

)

Try to acquire the read lock without blocking.

Parameters

[in]

rw

RWMutex handle.

Returns

True if the read lock was acquired, False if a writer is active or waiting.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 859 of file stk_c_sync.cpp.

{
    STK_ASSERT(rw != nullptr);
 
    return rw->handle.TryReadLock();
}

References stk_rwmutex_t::handle, STK_ASSERT, and stk::sync::RWMutex::TryReadLock().

Here is the call graph for this function:

stk_rwmutex_trylock()

bool stk_rwmutex_trylock

(

stk_rwmutex_t *

rw

)

Try to acquire the write lock without blocking.

Parameters

[in]

rw

RWMutex handle.

Returns

True if the exclusive lock was acquired, False otherwise.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 887 of file stk_c_sync.cpp.

{
    STK_ASSERT(rw != nullptr);
 
    return rw->handle.TryLock();
}

References stk_rwmutex_t::handle, STK_ASSERT, and stk::sync::RWMutex::TryLock().

Here is the call graph for this function:

stk_rwmutex_unlock()

void stk_rwmutex_unlock

(

stk_rwmutex_t *

rw

)

Release the exclusive writer lock.

Prioritizes waking waiting writers. If none are waiting, all waiting readers are woken (Writer Preference Policy).

Parameters

[in]

rw

RWMutex handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 901 of file stk_c_sync.cpp.

{
    STK_ASSERT(rw != nullptr);
 
    rw->handle.Unlock();
}

References stk_rwmutex_t::handle, STK_ASSERT, and stk::sync::RWMutex::Unlock().

Here is the call graph for this function:

stk_sem_create()

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

Create a Semaphore (using provided memory).

Parameters

[in]	membuf	Pointer to static memory container.
[in]	initial_count	Starting value of the resource counter.
[in]	max_count	Maximum value the counter is allowed to reach. Pass 0 to use the default maximum (65534). Must be >= initial_count.

Returns

Semaphore handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 308 of file stk_c_sync.cpp.

{
    STK_ASSERT(membuf != nullptr);
 
    const uint32_t effective_max = ((max_count == 0U) ? Semaphore::COUNT_MAX : max_count);
 
    stk_sem_t *result = nullptr;
    if (membuf != nullptr)
    {
        result = ConstructIn<stk_sem_t>(*membuf, initial_count, effective_max);
    }
 
    return result;
}

References stk::ConstructIn(), stk::sync::Semaphore::COUNT_MAX, and STK_ASSERT.

Here is the call graph for this function:

stk_sem_destroy()

void stk_sem_destroy

(

stk_sem_t *

sem

)

Destroy a Semaphore.

Parameters

[in]

sem

Semaphore handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 325 of file stk_c_sync.cpp.

{
    if (sem != nullptr)
    {
        sem->~stk_sem_t();
    }
}

stk_sem_get_count()

uint16_t stk_sem_get_count

(

const stk_sem_t *

sem

)

Get the current counter value.

Parameters

[in]

sem

Semaphore handle.

Returns

Advisory snapshot of the counter. May be stale by the time the caller acts on it.

Note

ISR-safe on targets where a 16-bit aligned read is atomic.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 361 of file stk_c_sync.cpp.

{
    STK_ASSERT(sem != nullptr);
 
    return sem->handle.GetCount();
}

References stk::sync::Semaphore::GetCount(), stk_sem_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_sem_get_instance()

stk::sync::Semaphore * stk_sem_get_instance

(

stk_sem_t *

sem

)

Get the underlying C++ stk::sync::Semaphore object wrapped by a stk_sem_t handle.

Parameters

[in]

sem

Semaphore handle obtained via stk_sem_create().

Returns

Pointer to the wrapped stk::sync::Semaphore instance. Never NULL for a valid handle.

Note

C++ callers only (guarded by __cplusplus); not part of the C ABI.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 368 of file stk_c_sync.cpp.

{
    STK_ASSERT(sem != nullptr);
 
    return &sem->handle;
}

References stk_sem_t::handle, and STK_ASSERT.

stk_sem_signal()

void stk_sem_signal

(

stk_sem_t *

sem

)

Signal/Release a semaphore resource.

Parameters

[in]

sem

Semaphore handle.

Warning

API contract: the counter must not already be at max_count with no task waiting. Violating this triggers an assertion in a debug build. Use stk_sem_trysignal() instead if a signal that would exceed max_count should be tolerated (e.g. a redundant signal) rather than treated as a caller error.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 347 of file stk_c_sync.cpp.

{
    STK_ASSERT(sem != nullptr);
 
    sem->handle.Signal();
}

References stk_sem_t::handle, stk::sync::Semaphore::Signal(), and STK_ASSERT.

Here is the call graph for this function:

stk_sem_trysignal()

bool stk_sem_trysignal

(

stk_sem_t *

sem

)

Try to signal/release a semaphore resource without exceeding max_count.

Identical to stk_sem_signal(), except that if the counter is already at max_count and no task is waiting, this returns false instead of asserting. The check and the increment (or hand-off to a waiter) happen atomically, so this is safe to call from multiple concurrent signalers without racing each other the way a separate stk_sem_get_count() check followed by stk_sem_signal() would.

Parameters

[in]

sem

Semaphore handle.

Returns

True if signaled (incremented, or handed directly to a waiter), False if the counter was already at max_count and nobody was waiting.

Warning

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 354 of file stk_c_sync.cpp.

{
    STK_ASSERT(sem != nullptr);
 
    return sem->handle.TrySignal();
}

References stk_sem_t::handle, STK_ASSERT, and stk::sync::Semaphore::TrySignal().

Here is the call graph for this function:

stk_sem_trywait()

bool stk_sem_trywait

(

stk_sem_t *

sem

)

Poll the semaphore without blocking.

Acquires a resource token if one is immediately available; returns false instantly if the counter is zero.

Parameters

[in]

sem

Semaphore handle.

Returns

True if a token was acquired, False if count was zero.

Warning

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 340 of file stk_c_sync.cpp.

{
    STK_ASSERT(sem != nullptr);
 
    return sem->handle.TryWait();
}

References stk_sem_t::handle, STK_ASSERT, and stk::sync::Semaphore::TryWait().

Here is the call graph for this function:

stk_sem_wait()

bool stk_sem_wait	(	stk_sem_t *	sem,
		stk_timeout_t	timeout )

Wait for a semaphore resource.

Parameters

[in]	sem	Semaphore handle.
[in]	timeout	Maximum time to wait in OS ticks or STK_WAIT_INFINITE.

Returns

True if resource acquired, False on timeout.

Note

If OS tick rate is 1 kHz then 1 tick = 1 ms. Use stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 333 of file stk_c_sync.cpp.

{
    STK_ASSERT(sem != nullptr);
 
    return sem->handle.Wait(timeout);
}

References stk_sem_t::handle, STK_ASSERT, and stk::sync::Semaphore::Wait().

Here is the call graph for this function:

stk_sleep()

void stk_sleep

(

stk_timeout_t

ticks

)

Put current task to sleep (non-HRT kernels only).

Parameters

[in]

ticks

Ticks to sleep.

Note

Unlike stk_delay_ms(), this function does not spin and allows the kernel to idle the CPU. When KERNEL_TICKLESS is active and all tasks are sleeping, the SysTick is suppressed and the CPU enters a low-power WFI state until the nearest wake-up deadline.

Unsupported in KERNEL_HRT mode; in HRT mode tasks sleep automatically according to their periodicity and workload, use stk_yield instead.

See also

stk_sleep_ms, stk_sleep_until, stk_ticks

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 645 of file stk_c.cpp.

{ stk::Sleep(ticks); }

References stk::Sleep().

Here is the call graph for this function:

stk_sleep_cancel()

void stk_sleep_cancel

(

stk_tid_t

tid

)

Cancel the sleep of a task, waking it immediately.

Parameters

[in]

tid

Identifier of the task to wake (obtained from stk_tid() or stk_task_get_id()).

Note

No-op if the target task is not currently sleeping.

ISR-safe.

See also

stk_sleep, stk_sleep_ms, stk_sleep_until

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 649 of file stk_c.cpp.

{ stk::SleepCancel(tid); }

References stk::SleepCancel().

Here is the call graph for this function:

stk_sleep_ms()

void stk_sleep_ms

(

stk_timeout_t

ms

)

Put current task to sleep (non-HRT kernels only).

Parameters

[in]

ms

Milliseconds to sleep.

Note

Unlike stk_delay_ms(), this function does not spin and allows the kernel to idle the CPU. When KERNEL_TICKLESS is active and all tasks are sleeping, the SysTick is suppressed and the CPU enters a low-power WFI state until the nearest wake-up deadline.

Unsupported in KERNEL_HRT mode; in HRT mode tasks sleep automatically according to their periodicity and workload, use stk_yield instead.

See also

stk_sleep, stk_sleep_until, stk_ticks

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 647 of file stk_c.cpp.

{ stk::SleepMs(ms); }

References stk::SleepMs().

Here is the call graph for this function:

stk_sleep_until()

bool stk_sleep_until

(

stk_tick_t

ts

)

Put current task to sleep (non-HRT kernels only).

Parameters

[in]

ts

Absolute time (timestamp), a deadline for a sleep period.

Returns

True if sleep succeeded, false otherwise.

Note

Unlike stk_delay_ms(), this function does not spin and allows the kernel to idle the CPU. When KERNEL_TICKLESS is active and all tasks are sleeping, the SysTick is suppressed and the CPU enters a low-power WFI state until the nearest wake-up deadline.

Unsupported in KERNEL_HRT mode; in HRT mode tasks sleep automatically according to their periodicity and workload, use stk_yield instead.

See also

stk_sleep, stk_sleep_ms, stk_ticks

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 648 of file stk_c.cpp.

{ return stk::SleepUntil(ts); }

References stk::SleepUntil().

Here is the call graph for this function:

stk_spinlock_create()

stk_spinlock_t * stk_spinlock_create

(

stk_spinlock_mem_t *const

membuf

)

Create a recursive SpinLock.

Parameters

[in]

membuf

Pointer to static memory container.

Returns

SpinLock handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 98 of file stk_c_sync.cpp.

{
    STK_ASSERT(membuf != nullptr);
 
    stk_spinlock_t *result = nullptr;
    if (membuf != nullptr)
    {
        result = ConstructIn<stk_spinlock_t>(*membuf);
    }
 
    return result;
}

References stk::ConstructIn(), and STK_ASSERT.

Here is the call graph for this function:

stk_spinlock_destroy()

void stk_spinlock_destroy

(

stk_spinlock_t *

slock

)

Destroy the SpinLock.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 111 of file stk_c_sync.cpp.

{
    if (slock != nullptr)
    {
        slock->~stk_spinlock_t();
    }
}

stk_spinlock_get_instance()

stk::sync::SpinLock * stk_spinlock_get_instance

(

stk_spinlock_t *

slock

)

Get the underlying C++ stk::sync::SpinLock object wrapped by a stk_spinlock_t handle.

Parameters

[in]

slock

SpinLock handle obtained via stk_spinlock_create().

Returns

Pointer to the wrapped stk::sync::SpinLock instance. Never NULL for a valid handle.

Note

C++ callers only (guarded by __cplusplus); not part of the C ABI.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 137 of file stk_c_sync.cpp.

{
    STK_ASSERT(slock != nullptr);
 
    return &slock->handle;
}

References stk_spinlock_t::handle, and STK_ASSERT.

stk_spinlock_lock()

void stk_spinlock_lock

(

stk_spinlock_t *

slock

)

Acquire the SpinLock (recursive).

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 119 of file stk_c_sync.cpp.

{
    STK_ASSERT(slock != nullptr);
    slock->handle.Lock();
}

References stk_spinlock_t::handle, stk::sync::SpinLock::Lock(), and STK_ASSERT.

Here is the call graph for this function:

stk_spinlock_trylock()

bool stk_spinlock_trylock

(

stk_spinlock_t *

slock

)

Attempt to acquire the SpinLock immediately.

Returns

True if locked successfully, False otherwise.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 125 of file stk_c_sync.cpp.

{
    STK_ASSERT(slock != nullptr);
    return slock->handle.TryLock();
}

References stk_spinlock_t::handle, STK_ASSERT, and stk::sync::SpinLock::TryLock().

Here is the call graph for this function:

stk_spinlock_unlock()

void stk_spinlock_unlock

(

stk_spinlock_t *

slock

)

Release the SpinLock.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 131 of file stk_c_sync.cpp.

{
    STK_ASSERT(slock != nullptr);
    slock->handle.Unlock();
}

References stk_spinlock_t::handle, STK_ASSERT, and stk::sync::SpinLock::Unlock().

Here is the call graph for this function:

stk_sys_timer_count()

stk_cycle_t stk_sys_timer_count

(

void

)

Get raw system timer counter value.

Returns

64-bit hardware counter value. Useful for sub-tick timing measurements.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 639 of file stk_c.cpp.

{ return stk::GetSysTimerCount(); }

References stk::GetSysTimerCount().

Here is the call graph for this function:

stk_sys_timer_frequency()

uint32_t stk_sys_timer_frequency

(

void

)

Get system timer frequency in Hz.

Returns

Timer frequency (Hz). Divide stk_sys_timer_count() differences by this value to obtain elapsed time in seconds.

Note

ISR-safe.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 640 of file stk_c.cpp.

{ return stk::GetSysTimerFrequency(); }

References stk::GetSysTimerFrequency().

Here is the call graph for this function:

stk_task_create_privileged()

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.

Parameters

[in]	entry	Task entry function.
[in]	arg	Argument passed to entry function.
[in]	stack	Pointer to stack buffer (array of stk_word_t).
[in]	stack_size	Number of elements (words) in the stack buffer.

Returns

Task handle (static storage in static kernels, heap in dynamic).

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 555 of file stk_c.cpp.

{
    STK_ASSERT(entry != nullptr);
    STK_ASSERT(stack != nullptr);
    STK_ASSERT(stack_size != 0);
 
    return AllocateTask(entry, arg, stack, stack_size, ACCESS_PRIVILEGED);
}

References stk::ACCESS_PRIVILEGED, AllocateTask(), and STK_ASSERT.

Here is the call graph for this function:

stk_task_create_user()

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.

Parameters

[in]	entry	Task entry function.
[in]	arg	Argument passed to entry function.
[in]	stack	Pointer to stack buffer (array of stk_word_t).
[in]	stack_size	Number of elements (words) in the stack buffer.

Returns

Task handle.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 567 of file stk_c.cpp.

{
    STK_ASSERT(entry != nullptr);
    STK_ASSERT(stack != nullptr);
    STK_ASSERT(stack_size != 0);
 
    return AllocateTask(entry, arg, stack, stack_size, ACCESS_USER);
}

References stk::ACCESS_USER, AllocateTask(), and STK_ASSERT.

Referenced by stk::pthread::EnsureReaper().

Here is the call graph for this function:

Here is the caller graph for this function:

stk_task_destroy()

void stk_task_destroy

(

stk_task_t *

tsk

)

Destroy dynamically created task object.

Parameters

[in]

tsk

Task handle.

Note

Only valid for tasks created with dynamic creation functions. Task must no longer be scheduled (must have exited or been removed).

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 623 of file stk_c.cpp.

{
    STK_ASSERT(tsk != nullptr);
 
    FreeTask(tsk);
}

References FreeTask(), and STK_ASSERT.

Here is the call graph for this function:

stk_task_get_id()

stk_tid_t stk_task_get_id

(

const stk_task_t *

tsk

)

Get the unique identifier of a task.

Parameters

[in]

tsk

Task handle.

Returns

Task identifier (stk_tid_t). Equivalent to the value stk_tid() returns when called from within that task.

Note

ISR-safe.

See also

stk_tid

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 609 of file stk_c.cpp.

{
    STK_ASSERT(tsk != nullptr);
 
    return stk::GetTidFromUserTask(&tsk->handle);
}

References stk::GetTidFromUserTask(), stk_task_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_task_get_instance()

stk::ITask * stk_task_get_instance

(

stk_task_t *

tsk

)

Get the underlying C++ stk::ITask object wrapped by a stk_task_t handle.

Gateway for mixed C/C++ code: lets C++ callers linked against the C API reach the real polymorphic task object (e.g. to pass it to a C++-only API) without duplicating task bookkeeping.

Parameters

[in]

tsk

Task handle obtained via stk_task_create_privileged() or stk_task_create_user().

Returns

Pointer to the wrapped stk::ITask instance. Never NULL for a valid handle.

Note

C++ callers only (guarded by __cplusplus); not part of the C ABI.

Warning

The returned pointer is only valid for the lifetime of tsk.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 616 of file stk_c.cpp.

{
    STK_ASSERT(tsk != nullptr);
 
    return &tsk->handle;
}

References stk_task_t::handle, and STK_ASSERT.

stk_task_get_name()

const char * stk_task_get_name

(

const stk_task_t *

tsk

)

Get human-readable task name previously set with stk_task_set_name().

Parameters

[in]

tsk

Task handle.

Returns

Null-terminated name string, or NULL if not set.

Note

ISR-safe (reads a stored pointer, no kernel call).

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 602 of file stk_c.cpp.

{
    STK_ASSERT(tsk != nullptr);
 
    return tsk->handle.GetTraceName();
}

References TaskWrapper::GetTraceName(), stk_task_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_task_set_name()

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

Assign human-readable task name (for tracing/debugging).

Parameters

[in]	tsk	Task handle.
[in]	tname	Null-terminated string (may be NULL).

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 595 of file stk_c.cpp.

{
    STK_ASSERT(tsk != nullptr);
 
    tsk->handle.SetName(tname);
}

References stk_task_t::handle, TaskWrapper::SetName(), and STK_ASSERT.

Referenced by stk::pthread::EnsureReaper().

Here is the call graph for this function:

Here is the caller graph for this function:

stk_task_set_priority()

void stk_task_set_priority	(	stk_task_t *	tsk,
		uint8_t	priority )

Set task priority (used only by Fixed Priority scheduler).

Parameters

[in]	tsk	Task handle.
[in]	priority	Priority level [0 = lowest … 31 = highest].

Note

Must be called before adding task to kernel.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 586 of file stk_c.cpp.

{
    STK_ASSERT(priority <= 31U);
    
    const stk_weight_t weight = static_cast<stk_weight_t>(priority);
 
    stk_task_set_weight(tsk, weight);
}

References STK_ASSERT, and stk_task_set_weight().

Here is the call graph for this function:

stk_task_set_weight()

void stk_task_set_weight	(	stk_task_t *	tsk,
		stk_weight_t	weight )

Set task weight (used only by Smooth Weighted Round Robin).

Parameters

[in]	tsk	Task handle.
[in]	weight	Positive weight value (recommended 1–16777215).

Note

Must be called before adding task to kernel.

See also

SwitchStrategySmoothWeightedRoundRobin.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 579 of file stk_c.cpp.

{
    STK_ASSERT(tsk != nullptr);
 
    tsk->handle.SetWeight(weight);
}

References stk_task_t::handle, TaskWrapper::SetWeight(), and STK_ASSERT.

Referenced by stk_task_set_priority().

Here is the call graph for this function:

Here is the caller graph for this function:

stk_tick_resolution()

uint32_t stk_tick_resolution

(

void

)

Returns how many microseconds correspond to one kernel tick.

Returns

Tick resolution in microseconds.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 635 of file stk_c.cpp.

{ return stk::GetTickResolution(); }

References stk::GetTickResolution().

Referenced by stk_ms_from_ticks().

Here is the call graph for this function:

Here is the caller graph for this function:

stk_ticks()

stk_tick_t stk_ticks

(

void

)

Returns number of ticks elapsed since kernel start.

Returns

Tick count (monotonically increasing).

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 634 of file stk_c.cpp.

{ return stk::GetTicks(); }

References stk::GetTicks().

Here is the call graph for this function:

stk_ticks_from_ms()

stk_tick_t stk_ticks_from_ms

(

stk_time_t

msec

)

Get ticks from milliseconds using current kernel tick resolution.

Parameters

[in]

msec

Milliseconds to convert.

Returns

Ticks.

Note

Equivalent to stk::GetTicksFromMsec(msec). Requires the kernel to be initialized before calling (stk_tick_resolution() must return a valid non-zero value).

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 637 of file stk_c.cpp.

{ return stk_ticks_from_ms_r(msec, stk::GetTickResolution()); }

References stk::GetTickResolution(), and stk_ticks_from_ms_r().

Here is the call graph for this function:

stk_ticks_from_ms_clamped_to_timeout()

stk_timeout_t stk_ticks_from_ms_clamped_to_timeout

(

stk_timeout_t

ms

)

Get ticks from milliseconds using current kernel tick resolution, clamped to the maximum value representable by stk_timeout_t (STK_WAIT_INFINITE).

Parameters

[in]

ms

Milliseconds to convert.

Returns

Equivalent tick count, clamped to STK_WAIT_INFINITE if it would otherwise overflow.

Note

Equivalent to stk::GetTicksFromMsClampedToTimeout(ms). Prefer this over stk_ticks_from_ms() when the result is passed directly as a timeout argument (e.g. to stk_mutex_timed_lock()), so a large millisecond value can never wrap into an unintended (or negative) timeout.

If tick rate is 1 kHz then 1 tick = 1 ms.

ISR-unsafe (internally calls stk_tick_resolution() which accesses the kernel service).

See also

stk_ticks_from_ms, STK_WAIT_INFINITE

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 638 of file stk_c.cpp.

{ return static_cast<stk_timeout_t>(stk::GetTicksFromMsClampedToTimeout(static_cast<stk::Timeout>(ms))); }

References stk::GetTicksFromMsClampedToTimeout().

Here is the call graph for this function:

stk_ticks_from_ms_r()

stk_tick_t stk_ticks_from_ms_r ( stk_time_t msec, uint32_t resolution )

inlinestatic

Get ticks from milliseconds using an explicit tick resolution.

Parameters

[in]	msec	Milliseconds to convert.
[in]	resolution	Microseconds per tick (see stk_tick_resolution()).

Returns

Ticks.

Note

Equivalent to stk::GetTicksFromMsec(msec, resolution). Use this overload when the resolution is already cached to avoid a repeated call to stk_tick_resolution().

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 680 of file stk_c.h.

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

References STK_STATIC_CAST.

Referenced by stk_ticks_from_ms().

Here is the caller graph for this function:

stk_tid()

stk_tid_t stk_tid

(

void

)

Returns current task/thread ID (the value set by stk_task_set_id).

Returns

Task identifier (0 if not set).

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 633 of file stk_c.cpp.

{ return stk::GetTid(); }

References stk::GetTid().

Here is the call graph for this function:

stk_time_now_ms()

stk_time_t stk_time_now_ms

(

void

)

Returns current time in milliseconds since kernel start.

Returns

Time in milliseconds.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 636 of file stk_c.cpp.

{ return stk::GetTimeNowMs(); }

References stk::GetTimeNowMs().

Here is the call graph for this function:

stk_tls_get()

void * stk_tls_get

(

void

)

Get thread-local pointer (platform-specific slot).

Returns

Pointer previously stored with stk_tls_set() (NULL if never set).

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

stk_tls_set()

void stk_tls_set

(

void *

ptr

)

Set thread-local pointer.

Parameters

[in]

ptr

Pointer value to store for the current task/thread.

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

stk_yield()

void stk_yield

(

void

)

Voluntarily give up CPU to another ready task (cooperative yield).

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 650 of file stk_c.cpp.

{ stk::Yield(); }

References stk::Yield().

Here is the call graph for this function: