kernel.h File Reference

Public kernel APIs. More...

#include <zephyr/kernel_includes.h>
#include <errno.h>
#include <limits.h>
#include <stdbool.h>
#include <zephyr/toolchain.h>
#include <zephyr/tracing/tracing_macros.h>
#include <zephyr/sys/mem_stats.h>
#include <zephyr/sys/iterable_sections.h>
#include <zephyr/sys/ring_buffer.h>
#include <zephyr/heap_constants.h>
#include <zephyr/tracing/tracing.h>
#include <zephyr/syscalls/kernel.h>

Go to the source code of this file.

Data Structures
struct	k_timer
	Kernel timer structure. More...
struct	k_queue
	Kernel queue structure. More...
struct	k_futex
	futex structure More...
struct	k_event
	Event Structure. More...
struct	k_fifo
	Kernel FIFO structure. More...
struct	k_lifo
	Kernel LIFO structure. More...
struct	k_mutex
	Kernel mutex structure. More...
struct	k_condvar
	Kernel condition variable structure. More...
struct	k_sem
	Semaphore structure. More...
struct	k_ipi_work
	IPI work item structure. More...
struct	k_work
	A structure used to submit work. More...
struct	k_work_delayable
	A structure used to submit work after a delay. More...
struct	k_work_sync
	A structure holding internal state for a pending synchronous operation on a work item or queue. More...
struct	k_work_queue_config
	A structure holding optional configuration items for a work queue. More...
struct	k_work_q
	Kernel workqueue structure. More...
struct	k_msgq
	Message Queue Structure. More...
struct	k_msgq_attrs
	Message Queue Attributes. More...
struct	k_mbox_msg
	Mailbox Message Structure. More...
struct	k_mbox
	Mailbox Structure. More...
struct	k_pipe
	Kernel pipe structure. More...
struct	k_heap
	Kernel synchronized heap structure. More...
struct	k_poll_signal
	Poll signal object. More...
struct	k_poll_event
	Poll Event. More...

Macros
#define	K_ANY   NULL
	Wildcard used to match any thread.
#define	K_PRIO_COOP(x)
	Compute a cooperative thread priority.
#define	K_PRIO_PREEMPT(x)
	Compute a preemptible thread priority.
#define	K_HIGHEST_THREAD_PRIO   (-CONFIG_NUM_COOP_PRIORITIES)
	Highest (most urgent) thread priority value.
#define	K_LOWEST_THREAD_PRIO   CONFIG_NUM_PREEMPT_PRIORITIES
	Lowest (least urgent) thread priority value, used by the idle thread.
#define	K_IDLE_PRIO   K_LOWEST_THREAD_PRIO
	Priority of the idle thread.
#define	K_HIGHEST_APPLICATION_THREAD_PRIO   (K_HIGHEST_THREAD_PRIO)
	Highest priority usable by application threads.
#define	K_LOWEST_APPLICATION_THREAD_PRIO   (K_LOWEST_THREAD_PRIO - 1)
	Lowest priority usable by application threads.
#define	K_ESSENTIAL   (BIT(0))
	system thread that must not abort
#define	K_FP_REGS   (BIT(K_FP_IDX))
	FPU registers are managed by context switch.
#define	K_USER   (BIT(2))
	user mode thread
#define	K_INHERIT_PERMS   (BIT(3))
	Inherit Permissions.
#define	K_CALLBACK_STATE   (BIT(4))
	Callback item state.
#define	K_DSP_REGS   (BIT(K_DSP_IDX))
	DSP registers are managed by context switch.
#define	K_AGU_REGS   (BIT(K_AGU_IDX))
	AGU registers are managed by context switch.
#define	K_SSE_REGS   (BIT(15))
	FP and SSE registers are managed by context switch on x86.
#define	k_thread_access_grant(thread, ...)
	Grant a thread access to a set of kernel objects.
#define	K_THREAD_DEFINE(name, stack_size, entry, p1, p2, p3, prio, options, delay)
	Statically define and initialize a thread.
#define	K_KERNEL_THREAD_DEFINE(name, stack_size, entry, p1, p2, p3, prio, options, delay)
	Statically define and initialize a thread intended to run only in kernel mode.
#define	K_NO_WAIT   Z_TIMEOUT_NO_WAIT
	Generate null timeout delay.
#define	K_NSEC(t)
	Generate timeout delay from nanoseconds.
#define	K_USEC(t)
	Generate timeout delay from microseconds.
#define	K_CYC(t)
	Generate timeout delay from cycles.
#define	K_TICKS(t)
	Generate timeout delay from system ticks.
#define	K_MSEC(ms)
	Generate timeout delay from milliseconds.
#define	K_SECONDS(s)
	Generate timeout delay from seconds.
#define	K_MINUTES(m)
	Generate timeout delay from minutes.
#define	K_HOURS(h)
	Generate timeout delay from hours.
#define	K_FOREVER   Z_FOREVER
	Generate infinite timeout delay.
#define	K_TIMEOUT_SUM(timeout1, timeout2)
	Add two k_timeout_t values together.
#define	K_TIMER_DEFINE(name, expiry_fn, stop_fn)
	Statically define and initialize a timer.
#define	K_QUEUE_DEFINE(name)
	Statically define and initialize a queue.
#define	K_EVENT_DEFINE(name)
	Statically define and initialize an event object.
#define	k_fifo_init(fifo)
	Initialize a FIFO queue.
#define	k_fifo_cancel_wait(fifo)
	Cancel waiting on a FIFO queue.
#define	k_fifo_put(fifo, data)
	Add an element to a FIFO queue.
#define	k_fifo_alloc_put(fifo, data)
	Add an element to a FIFO queue.
#define	k_fifo_put_list(fifo, head, tail)
	Atomically add a list of elements to a FIFO.
#define	k_fifo_put_slist(fifo, list)
	Atomically add a list of elements to a FIFO queue.
#define	k_fifo_get(fifo, timeout)
	Get an element from a FIFO queue.
#define	k_fifo_is_empty(fifo)
	Query a FIFO queue to see if it has data available.
#define	k_fifo_peek_head(fifo)
	Peek element at the head of a FIFO queue.
#define	k_fifo_peek_tail(fifo)
	Peek element at the tail of FIFO queue.
#define	K_FIFO_DEFINE(name)
	Statically define and initialize a FIFO queue.
#define	k_lifo_init(lifo)
	Initialize a LIFO queue.
#define	k_lifo_put(lifo, data)
	Add an element to a LIFO queue.
#define	k_lifo_alloc_put(lifo, data)
	Add an element to a LIFO queue.
#define	k_lifo_get(lifo, timeout)
	Get an element from a LIFO queue.
#define	K_LIFO_DEFINE(name)
	Statically define and initialize a LIFO queue.
#define	K_STACK_DEFINE(name, stack_num_entries)
	Statically define and initialize a stack.
#define	K_MUTEX_DEFINE(name)
	Statically define and initialize a mutex.
#define	K_CONDVAR_DEFINE(name)
	Statically define and initialize a condition variable.
#define	K_SEM_MAX_LIMIT   UINT_MAX
	Maximum limit value allowed for a semaphore.
#define	K_SEM_DEFINE(name, initial_count, count_limit)
	Statically define and initialize a semaphore.
#define	K_WORK_DELAYABLE_DEFINE(work, work_handler)
	Initialize a statically-defined delayable work item.
#define	K_WORK_USER_DEFINE(work, work_handler)
	Initialize a statically-defined user work item.
#define	K_WORK_DEFINE(work, work_handler)
	Initialize a statically-defined work item.
#define	K_MSGQ_DEFINE(q_name, q_msg_size, q_max_msgs, q_align)
	Statically define and initialize a message queue.
#define	K_MBOX_DEFINE(name)
	Statically define and initialize a mailbox.
#define	K_PIPE_DEFINE(name, pipe_buffer_size, pipe_align)
	Statically define and initialize a pipe.
#define	K_MEM_SLAB_DEFINE_IN_SECT(name, in_section, slab_block_size, slab_num_blocks, slab_align)
	Statically define and initialize a memory slab in a user-provided memory section with public (non-static) scope.
#define	K_MEM_SLAB_DEFINE(name, slab_block_size, slab_num_blocks, slab_align)
	Statically define and initialize a memory slab in a public (non-static) scope.
#define	K_MEM_SLAB_DEFINE_TYPE(name, type, slab_num_blocks)
	Statically define and initialize a memory slab for blocks of a given type in a public (non-static) scope.
#define	K_MEM_SLAB_DEFINE_IN_SECT_STATIC(name, in_section, slab_block_size, slab_num_blocks, slab_align)
	Statically define and initialize a memory slab in a user-provided memory section with private (static) scope.
#define	K_MEM_SLAB_DEFINE_STATIC(name, slab_block_size, slab_num_blocks, slab_align)
	Statically define and initialize a memory slab in a private (static) scope.
#define	K_MEM_SLAB_DEFINE_STATIC_TYPE(name, type, slab_num_blocks)
	Statically define and initialize a memory slab for blocks of a given type in a private (static) scope.
#define	K_HEAP_DEFINE(name, bytes)
	Define a static k_heap.
#define	K_HEAP_DEFINE_NOCACHE(name, bytes)
	Define a static k_heap in uncached memory.
#define	K_POLL_SIGNAL_INITIALIZER(obj)
	Statically initialize a poll signal.
#define	K_POLL_EVENT_INITIALIZER(_event_type, _event_mode, _event_obj)
	Statically initialize a poll event.
#define	K_POLL_EVENT_STATIC_INITIALIZER(_event_type, _event_mode, _event_obj, event_tag)
	Statically initialize a poll event, with a user tag.
#define	k_oops()
	Fatally terminate a thread.
#define	k_panic()
	Fatally terminate the system.
Poll event types
Values for the k_poll_event.type bitfield.
#define	K_POLL_TYPE_IGNORE   0
	Event is ignored by k_poll().
#define	K_POLL_TYPE_SIGNAL   Z_POLL_TYPE_BIT(_POLL_TYPE_SIGNAL)
	Poll for a raised poll signal.
#define	K_POLL_TYPE_SEM_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_SEM_AVAILABLE)
	Poll for a semaphore becoming available.
#define	K_POLL_TYPE_DATA_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_DATA_AVAILABLE)
	Poll for data becoming available in a queue.
#define	K_POLL_TYPE_FIFO_DATA_AVAILABLE   K_POLL_TYPE_DATA_AVAILABLE
	Poll for data becoming available in a FIFO.
#define	K_POLL_TYPE_MSGQ_DATA_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_MSGQ_DATA_AVAILABLE)
	Poll for data becoming available in a message queue.
#define	K_POLL_TYPE_PIPE_DATA_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_PIPE_DATA_AVAILABLE)
	Poll for data becoming available in a pipe.
Poll event states
Values for the k_poll_event.state bitfield.
#define	K_POLL_STATE_NOT_READY   0
	Condition being polled for has not occurred yet.
#define	K_POLL_STATE_SIGNALED   Z_POLL_STATE_BIT(_POLL_STATE_SIGNALED)
	Poll signal was raised.
#define	K_POLL_STATE_SEM_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_SEM_AVAILABLE)
	Semaphore became available.
#define	K_POLL_STATE_DATA_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_DATA_AVAILABLE)
	Data became available in a queue.
#define	K_POLL_STATE_FIFO_DATA_AVAILABLE   K_POLL_STATE_DATA_AVAILABLE
	Data became available in a FIFO.
#define	K_POLL_STATE_MSGQ_DATA_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_MSGQ_DATA_AVAILABLE)
	Data became available in a message queue.
#define	K_POLL_STATE_PIPE_DATA_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_PIPE_DATA_AVAILABLE)
	Data became available in a pipe.
#define	K_POLL_STATE_CANCELLED   Z_POLL_STATE_BIT(_POLL_STATE_CANCELLED)
	Wait on the polled object was cancelled, e.g.

Typedefs
typedef void(*	k_thread_user_cb_t) (const struct k_thread *thread, void *user_data)
	Callback type used by thread iteration functions.
typedef void(*	k_timer_expiry_t) (struct k_timer *timer)
	Timer expiry function type.
typedef void(*	k_timer_stop_t) (struct k_timer *timer)
	Timer stop function type.
typedef void(*	k_ipi_func_t) (struct k_ipi_work *work)
	IPI work item handler function type.
typedef void(*	k_work_handler_t) (struct k_work *work)
	The signature for a work item handler function.
typedef void(*	k_work_user_handler_t) (struct k_work_user *work)
	Work item handler function type for user work queues.

Enumerations
enum	execution_context_types { K_ISR = 0 , K_COOP_THREAD , K_PREEMPT_THREAD }
	Types of execution contexts. More...
enum	{   K_WORK_RUNNING = BIT(K_WORK_RUNNING_BIT) , K_WORK_CANCELING = BIT(K_WORK_CANCELING_BIT) , K_WORK_QUEUED = BIT(K_WORK_QUEUED_BIT) , K_WORK_DELAYED = BIT(K_WORK_DELAYED_BIT) ,   K_WORK_FLUSHING = BIT(K_WORK_FLUSHING_BIT) }
	Work item and work queue state flag values. More...
enum	k_poll_modes { K_POLL_MODE_NOTIFY_ONLY = 0 , K_POLL_NUM_MODES }
	Modes of operation of a poll event. More...

Functions
static void	k_thread_runtime_stats_longest_frame_reset (__maybe_unused struct k_thread *thread)
	Resets thread longest frame usage data for specified thread.
void	k_thread_foreach (k_thread_user_cb_t user_cb, void *user_data)
	Iterate over all the threads in the system.
void	k_thread_foreach_filter_by_cpu (unsigned int cpu, k_thread_user_cb_t user_cb, void *user_data)
	Iterate over all the threads in running on specified cpu.
void	k_thread_foreach_unlocked (k_thread_user_cb_t user_cb, void *user_data)
	Iterate over all the threads in the system without locking.
void	k_thread_foreach_unlocked_filter_by_cpu (unsigned int cpu, k_thread_user_cb_t user_cb, void *user_data)
	Iterate over the threads in running on current cpu without locking.
k_thread_stack_t *	k_thread_stack_alloc (size_t size, int flags)
	Dynamically allocate a thread stack.
int	k_thread_stack_free (k_thread_stack_t *stack)
	Free a dynamically allocated thread stack.
k_tid_t	k_thread_create (struct k_thread *new_thread, k_thread_stack_t *stack, size_t stack_size, k_thread_entry_t entry, void *p1, void *p2, void *p3, int prio, uint32_t options, k_timeout_t delay)
	Create a thread.
FUNC_NORETURN void	k_thread_user_mode_enter (k_thread_entry_t entry, void *p1, void *p2, void *p3)
	Drop a thread's privileges permanently to user mode.
static void	k_thread_heap_assign (struct k_thread *thread, struct k_heap *heap)
	Assign a resource memory pool to a thread.
int	k_thread_join (struct k_thread *thread, k_timeout_t timeout)
	Sleep until a thread exits.
int32_t	k_sleep (k_timeout_t timeout)
	Put the current thread to sleep.
static int32_t	k_msleep (int32_t ms)
	Put the current thread to sleep.
int32_t	k_usleep (int32_t us)
	Put the current thread to sleep with microsecond resolution.
void	k_busy_wait (uint32_t usec_to_wait)
	Cause the current thread to busy wait.
bool	k_can_yield (void)
	Check whether it is possible to yield in the current context.
void	k_yield (void)
	Yield the current thread.
void	k_wakeup (k_tid_t thread)
	Wake up a sleeping thread.
__attribute_const__ k_tid_t	k_sched_current_thread_query (void)
	Query thread ID of the current thread.
static bool	k_is_pre_kernel (void)
	Test whether startup is in the before-main-task phase.
static __attribute_const__ k_tid_t	k_current_get (void)
	Get thread ID of the current thread.
void	k_thread_abort (k_tid_t thread)
	Abort a thread.
k_ticks_t	k_thread_timeout_expires_ticks (const struct k_thread *thread)
	Get time when a thread wakes up, in system ticks.
k_ticks_t	k_thread_timeout_remaining_ticks (const struct k_thread *thread)
	Get time remaining before a thread wakes up, in system ticks.
int	k_thread_priority_get (k_tid_t thread)
	Get a thread's priority.
void	k_thread_priority_set (k_tid_t thread, int prio)
	Set a thread's priority.
void	k_thread_deadline_set (k_tid_t thread, int deadline)
	Set relative deadline expiration time for scheduler.
void	k_thread_absolute_deadline_set (k_tid_t thread, int deadline)
	Set absolute deadline expiration time for scheduler.
void	k_reschedule (void)
	Invoke the scheduler.
int	k_thread_cpu_mask_clear (k_tid_t thread)
	Sets all CPU enable masks to zero.
int	k_thread_cpu_mask_enable_all (k_tid_t thread)
	Sets all CPU enable masks to one.
int	k_thread_cpu_mask_enable (k_tid_t thread, int cpu)
	Enable thread to run on specified CPU.
int	k_thread_cpu_mask_disable (k_tid_t thread, int cpu)
	Prevent thread to run on specified CPU.
int	k_thread_cpu_pin (k_tid_t thread, int cpu)
	Pin a thread to a CPU.
void	k_thread_suspend (k_tid_t thread)
	Suspend a thread.
void	k_thread_resume (k_tid_t thread)
	Resume a suspended thread.
static void	k_thread_start (k_tid_t thread)
	Start an inactive thread.
void	k_sched_time_slice_set (int32_t slice, int prio)
	Set time-slicing period and scope.
void	k_thread_time_slice_set (struct k_thread *th, int32_t slice_ticks, k_thread_timeslice_fn_t expired, void *data)
	Set thread time slice.
bool	k_is_in_isr (void)
	Determine if code is running at interrupt level.
int	k_is_preempt_thread (void)
	Determine if code is running in a preemptible thread.
void	k_sched_lock (void)
	Lock the scheduler.
void	k_sched_unlock (void)
	Unlock the scheduler.
void	k_thread_custom_data_set (void *value)
	Set current thread's custom data.
void *	k_thread_custom_data_get (void)
	Get current thread's custom data.
int	k_thread_name_set (k_tid_t thread, const char *str)
	Set current thread name.
const char *	k_thread_name_get (k_tid_t thread)
	Get thread name.
int	k_thread_name_copy (k_tid_t thread, char *buf, size_t size)
	Copy the thread name into a supplied buffer.
const char *	k_thread_state_str (k_tid_t thread_id, char *buf, size_t buf_size)
	Get thread state string.
void	k_timer_init (struct k_timer *timer, k_timer_expiry_t expiry_fn, k_timer_stop_t stop_fn)
	Initialize a timer.
void	k_timer_start (struct k_timer *timer, k_timeout_t duration, k_timeout_t period)
	Start a timer.
void	k_timer_stop (struct k_timer *timer)
	Stop a timer.
uint32_t	k_timer_status_get (struct k_timer *timer)
	Read timer status.
uint32_t	k_timer_status_sync (struct k_timer *timer)
	Synchronize thread to timer expiration.
k_ticks_t	k_timer_expires_ticks (const struct k_timer *timer)
	Get next expiration time of a timer, in system ticks.
k_ticks_t	k_timer_remaining_ticks (const struct k_timer *timer)
	Get time remaining before a timer next expires, in system ticks.
static uint32_t	k_timer_remaining_get (struct k_timer *timer)
	Get time remaining before a timer next expires.
void	k_timer_user_data_set (struct k_timer *timer, void *user_data)
	Associate user-specific data with a timer.
void *	k_timer_user_data_get (const struct k_timer *timer)
	Retrieve the user-specific data from a timer.
int	k_timer_cleanup (struct k_timer *timer)
	Clean up a dynamically allocated timer before freeing it.
int64_t	k_uptime_ticks (void)
	Get system uptime, in system ticks.
static int64_t	k_uptime_get (void)
	Get system uptime.
static uint32_t	k_uptime_get_32 (void)
	Get system uptime (32-bit version).
static uint32_t	k_uptime_seconds (void)
	Get system uptime in seconds.
static int64_t	k_uptime_delta (int64_t *reftime)
	Get elapsed time, and update the referenced time.
static uint32_t	k_cycle_get_32 (void)
	Read the hardware clock.
static uint64_t	k_cycle_get_64 (void)
	Read the 64-bit hardware clock.
void	k_queue_init (struct k_queue *queue)
	Initialize a queue.
void	k_queue_cancel_wait (struct k_queue *queue)
	Cancel waiting on a queue.
void	k_queue_append (struct k_queue *queue, void *data)
	Append an element to the end of a queue.
int32_t	k_queue_alloc_append (struct k_queue *queue, void *data)
	Append an element to a queue.
void	k_queue_prepend (struct k_queue *queue, void *data)
	Prepend an element to a queue.
int32_t	k_queue_alloc_prepend (struct k_queue *queue, void *data)
	Prepend an element to a queue.
void	k_queue_insert (struct k_queue *queue, void *prev, void *data)
	Inserts an element to a queue.
int	k_queue_append_list (struct k_queue *queue, void *head, void *tail)
	Atomically append a list of elements to a queue.
int	k_queue_merge_slist (struct k_queue *queue, sys_slist_t *list)
	Atomically add a list of elements to a queue.
void *	k_queue_get (struct k_queue *queue, k_timeout_t timeout)
	Get an element from a queue.
bool	k_queue_remove (struct k_queue *queue, void *data)
	Remove an element from a queue.
bool	k_queue_unique_append (struct k_queue *queue, void *data)
	Append an element to a queue only if it's not present already.
int	k_queue_is_empty (struct k_queue *queue)
	Query a queue to see if it has data available.
void *	k_queue_peek_head (struct k_queue *queue)
	Peek element at the head of queue.
void *	k_queue_peek_tail (struct k_queue *queue)
	Peek element at the tail of queue.
int	k_futex_wait (struct k_futex *futex, int expected, k_timeout_t timeout)
	Pend the current thread on a futex.
int	k_futex_wake (struct k_futex *futex, bool wake_all)
	Wake one/all threads pending on a futex.
void	k_event_init (struct k_event *event)
	Initialize an event object.
uint32_t	k_event_post (struct k_event *event, uint32_t events)
	Post one or more events to an event object.
uint32_t	k_event_set (struct k_event *event, uint32_t events)
	Set the events in an event object.
uint32_t	k_event_set_masked (struct k_event *event, uint32_t events, uint32_t events_mask)
	Set or clear the events in an event object.
uint32_t	k_event_clear (struct k_event *event, uint32_t events)
	Clear the events in an event object.
uint32_t	k_event_wait (struct k_event *event, uint32_t events, bool reset, k_timeout_t timeout)
	Wait for any of the specified events.
uint32_t	k_event_wait_all (struct k_event *event, uint32_t events, bool reset, k_timeout_t timeout)
	Wait for all of the specified events.
uint32_t	k_event_wait_safe (struct k_event *event, uint32_t events, bool reset, k_timeout_t timeout)
	Wait for any of the specified events (safe version).
uint32_t	k_event_wait_all_safe (struct k_event *event, uint32_t events, bool reset, k_timeout_t timeout)
	Wait for all of the specified events (safe version).
static uint32_t	k_event_test (struct k_event *event, uint32_t events_mask)
	Test the events currently tracked in the event object.
void	k_stack_init (struct k_stack *stack, stack_data_t *buffer, uint32_t num_entries)
	Initialize a stack.
int32_t	k_stack_alloc_init (struct k_stack *stack, uint32_t num_entries)
	Initialize a stack.
int	k_stack_cleanup (struct k_stack *stack)
	Release a stack's allocated buffer.
int	k_stack_push (struct k_stack *stack, stack_data_t data)
	Push an element onto a stack.
int	k_stack_pop (struct k_stack *stack, stack_data_t *data, k_timeout_t timeout)
	Pop an element from a stack.
int	k_mutex_init (struct k_mutex *mutex)
	Initialize a mutex.
int	k_mutex_lock (struct k_mutex *mutex, k_timeout_t timeout)
	Lock a mutex.
int	k_mutex_unlock (struct k_mutex *mutex)
	Unlock a mutex.
int	k_condvar_init (struct k_condvar *condvar)
	Initialize a condition variable.
int	k_condvar_signal (struct k_condvar *condvar)
	Signals one thread that is pending on the condition variable.
int	k_condvar_broadcast (struct k_condvar *condvar)
	Unblock all threads that are pending on the condition variable.
int	k_condvar_wait (struct k_condvar *condvar, struct k_mutex *mutex, k_timeout_t timeout)
	Waits on the condition variable releasing the mutex lock.
int	k_sem_init (struct k_sem *sem, unsigned int initial_count, unsigned int limit)
	Initialize a semaphore.
int	k_sem_take (struct k_sem *sem, k_timeout_t timeout)
	Take a semaphore.
void	k_sem_give (struct k_sem *sem)
	Give a semaphore.
void	k_sem_reset (struct k_sem *sem)
	Resets a semaphore's count to zero.
unsigned int	k_sem_count_get (struct k_sem *sem)
	Get a semaphore's count.
static void	k_ipi_work_init (struct k_ipi_work *work)
	Initialize the specified IPI work item.
int	k_ipi_work_add (struct k_ipi_work *work, uint32_t cpu_bitmask, k_ipi_func_t func)
	Add an IPI work item to the IPI work queue.
int	k_ipi_work_wait (struct k_ipi_work *work, k_timeout_t timeout)
	Wait until the IPI work item has been processed by all targeted CPUs.
void	k_ipi_work_signal (void)
	Signal that there is one or more IPI work items to process.
void	k_work_init (struct k_work *work, k_work_handler_t handler)
	Initialize a (non-delayable) work structure.
int	k_work_busy_get (const struct k_work *work)
	Busy state flags from the work item.
static bool	k_work_is_pending (const struct k_work *work)
	Test whether a work item is currently pending.
int	k_work_submit_to_queue (struct k_work_q *queue, struct k_work *work)
	Submit a work item to a queue.
int	k_work_submit (struct k_work *work)
	Submit a work item to the system queue.
bool	k_work_flush (struct k_work *work, struct k_work_sync *sync)
	Wait for last-submitted instance to complete.
int	k_work_cancel (struct k_work *work)
	Cancel a work item.
bool	k_work_cancel_sync (struct k_work *work, struct k_work_sync *sync)
	Cancel a work item and wait for it to complete.
void	k_work_queue_init (struct k_work_q *queue)
	Initialize a work queue structure.
void	k_work_queue_start (struct k_work_q *queue, k_thread_stack_t *stack, size_t stack_size, int prio, const struct k_work_queue_config *cfg)
	Initialize a work queue.
void	k_work_queue_run (struct k_work_q *queue, const struct k_work_queue_config *cfg)
	Run work queue using calling thread.
static k_tid_t	k_work_queue_thread_get (struct k_work_q *queue)
	Access the thread that animates a work queue.
int	k_work_queue_drain (struct k_work_q *queue, bool plug)
	Wait until the work queue has drained, optionally plugging it.
int	k_work_queue_unplug (struct k_work_q *queue)
	Release a work queue to accept new submissions.
int	k_work_queue_stop (struct k_work_q *queue, k_timeout_t timeout)
	Stop a work queue.
void	k_work_init_delayable (struct k_work_delayable *dwork, k_work_handler_t handler)
	Initialize a delayable work structure.
static struct k_work_delayable *	k_work_delayable_from_work (struct k_work *work)
	Get the parent delayable work structure from a work pointer.
int	k_work_delayable_busy_get (const struct k_work_delayable *dwork)
	Busy state flags from the delayable work item.
static bool	k_work_delayable_is_pending (const struct k_work_delayable *dwork)
	Test whether a delayed work item is currently pending.
static k_ticks_t	k_work_delayable_expires_get (const struct k_work_delayable *dwork)
	Get the absolute tick count at which a scheduled delayable work will be submitted.
static k_ticks_t	k_work_delayable_remaining_get (const struct k_work_delayable *dwork)
	Get the number of ticks until a scheduled delayable work will be submitted.
int	k_work_schedule_for_queue (struct k_work_q *queue, struct k_work_delayable *dwork, k_timeout_t delay)
	Submit an idle work item to a queue after a delay.
int	k_work_schedule (struct k_work_delayable *dwork, k_timeout_t delay)
	Submit an idle work item to the system work queue after a delay.
int	k_work_reschedule_for_queue (struct k_work_q *queue, struct k_work_delayable *dwork, k_timeout_t delay)
	Reschedule a work item to a queue after a delay.
int	k_work_reschedule (struct k_work_delayable *dwork, k_timeout_t delay)
	Reschedule a work item to the system work queue after a delay.
bool	k_work_flush_delayable (struct k_work_delayable *dwork, struct k_work_sync *sync)
	Flush delayable work.
int	k_work_cancel_delayable (struct k_work_delayable *dwork)
	Cancel delayable work.
bool	k_work_cancel_delayable_sync (struct k_work_delayable *dwork, struct k_work_sync *sync)
	Cancel delayable work and wait.
static void	k_work_user_init (struct k_work_user *work, k_work_user_handler_t handler)
	Initialize a userspace work item.
static bool	k_work_user_is_pending (struct k_work_user *work)
	Check if a userspace work item is pending.
static int	k_work_user_submit_to_queue (struct k_work_user_q *work_q, struct k_work_user *work)
	Submit a work item to a user mode workqueue.
void	k_work_user_queue_start (struct k_work_user_q *work_q, k_thread_stack_t *stack, size_t stack_size, int prio, const char *name)
	Start a workqueue in user mode.
static k_tid_t	k_work_user_queue_thread_get (struct k_work_user_q *work_q)
	Access the user mode thread that animates a work queue.
void	k_work_poll_init (struct k_work_poll *work, k_work_handler_t handler)
	Initialize a triggered work item.
int	k_work_poll_submit_to_queue (struct k_work_q *work_q, struct k_work_poll *work, struct k_poll_event *events, int num_events, k_timeout_t timeout)
	Submit a triggered work item.
int	k_work_poll_submit (struct k_work_poll *work, struct k_poll_event *events, int num_events, k_timeout_t timeout)
	Submit a triggered work item to the system workqueue.
int	k_work_poll_cancel (struct k_work_poll *work)
	Cancel a triggered work item.
void	k_msgq_init (struct k_msgq *msgq, char *buffer, size_t msg_size, uint32_t max_msgs)
	Initialize a message queue.
int	k_msgq_alloc_init (struct k_msgq *msgq, size_t msg_size, uint32_t max_msgs)
	Initialize a message queue.
int	k_msgq_cleanup (struct k_msgq *msgq)
	Release allocated buffer for a queue.
int	k_msgq_put (struct k_msgq *msgq, const void *data, k_timeout_t timeout)
	Send a message to the end of a message queue.
int	k_msgq_put_front (struct k_msgq *msgq, const void *data)
	Send a message to the front of a message queue.
int	k_msgq_get (struct k_msgq *msgq, void *data, k_timeout_t timeout)
	Receive a message from a message queue.
int	k_msgq_peek (struct k_msgq *msgq, void *data)
	Peek/read a message from a message queue.
int	k_msgq_peek_at (struct k_msgq *msgq, void *data, uint32_t idx)
	Peek/read a message from a message queue at the specified index.
void	k_msgq_purge (struct k_msgq *msgq)
	Purge a message queue.
uint32_t	k_msgq_num_free_get (struct k_msgq *msgq)
	Get the amount of free space in a message queue.
void	k_msgq_get_attrs (struct k_msgq *msgq, struct k_msgq_attrs *attrs)
	Get basic attributes of a message queue.
uint32_t	k_msgq_num_used_get (struct k_msgq *msgq)
	Get the number of messages in a message queue.
void	k_mbox_init (struct k_mbox *mbox)
	Initialize a mailbox.
int	k_mbox_put (struct k_mbox *mbox, struct k_mbox_msg *tx_msg, k_timeout_t timeout)
	Send a mailbox message in a synchronous manner.
void	k_mbox_async_put (struct k_mbox *mbox, struct k_mbox_msg *tx_msg, struct k_sem *sem)
	Send a mailbox message in an asynchronous manner.
int	k_mbox_get (struct k_mbox *mbox, struct k_mbox_msg *rx_msg, void *buffer, k_timeout_t timeout)
	Receive a mailbox message.
void	k_mbox_data_get (struct k_mbox_msg *rx_msg, void *buffer)
	Retrieve mailbox message data into a buffer.
void	k_pipe_init (struct k_pipe *pipe, uint8_t *buffer, size_t buffer_size)
	initialize a pipe
int	k_pipe_write (struct k_pipe *pipe, const uint8_t *data, size_t len, k_timeout_t timeout)
	Write data to a pipe.
int	k_pipe_read (struct k_pipe *pipe, uint8_t *data, size_t len, k_timeout_t timeout)
	Read data from a pipe This routine reads up to len bytes of data from pipe.
void	k_pipe_reset (struct k_pipe *pipe)
	Reset a pipe This routine resets the pipe, discarding any unread data and unblocking any threads waiting to write or read, causing the waiting threads to return with -ECANCELED.
void	k_pipe_close (struct k_pipe *pipe)
	Close a pipe.
int	k_mem_slab_init (struct k_mem_slab *slab, void *buffer, size_t block_size, uint32_t num_blocks)
	Initialize a memory slab.
int	k_mem_slab_alloc (struct k_mem_slab *slab, void **mem, k_timeout_t timeout)
	Allocate memory from a memory slab.
void	k_mem_slab_free (struct k_mem_slab *slab, void *mem)
	Free memory allocated from a memory slab.
static uint32_t	k_mem_slab_num_used_get (struct k_mem_slab *slab)
	Get the number of used blocks in a memory slab.
static uint32_t	k_mem_slab_max_used_get (struct k_mem_slab *slab)
	Get the number of maximum used blocks so far in a memory slab.
static uint32_t	k_mem_slab_num_free_get (struct k_mem_slab *slab)
	Get the number of unused blocks in a memory slab.
int	k_mem_slab_runtime_stats_get (struct k_mem_slab *slab, struct sys_memory_stats *stats)
	Get the memory stats for a memory slab.
int	k_mem_slab_runtime_stats_reset_max (struct k_mem_slab *slab)
	Reset the maximum memory usage for a slab.
void	k_heap_init (struct k_heap *h, void *mem, size_t bytes)
	Initialize a k_heap.
void *	k_heap_aligned_alloc (struct k_heap *h, size_t align, size_t bytes, k_timeout_t timeout)
	Allocate aligned memory from a k_heap.
void *	k_heap_alloc (struct k_heap *h, size_t bytes, k_timeout_t timeout)
	Allocate memory from a k_heap.
void *	k_heap_calloc (struct k_heap *h, size_t num, size_t size, k_timeout_t timeout)
	Allocate and initialize memory for an array of objects from a k_heap.
void *	k_heap_realloc (struct k_heap *h, void *ptr, size_t bytes, k_timeout_t timeout)
	Reallocate memory from a k_heap.
void	k_heap_free (struct k_heap *h, void *mem)
	Free memory allocated by k_heap_alloc().
int	k_heap_array_get (struct k_heap **heap)
	Get the array of statically defined heaps.
void *	k_aligned_alloc (size_t align, size_t size)
	Allocate memory from the heap with a specified alignment.
void *	k_malloc (size_t size)
	Allocate memory from the heap.
void	k_free (void *ptr)
	Free memory allocated from heap.
void *	k_calloc (size_t nmemb, size_t size)
	Allocate memory from heap, array style.
void *	k_realloc (void *ptr, size_t size)
	Expand the size of an existing allocation.
void	k_poll_event_init (struct k_poll_event *event, uint32_t type, int mode, void *obj)
	Initialize one struct k_poll_event instance.
int	k_poll (struct k_poll_event *events, int num_events, k_timeout_t timeout)
	Wait for one or many of multiple poll events to occur.
void	k_poll_signal_init (struct k_poll_signal *sig)
	Initialize a poll signal object.
void	k_poll_signal_reset (struct k_poll_signal *sig)
	Reset a poll signal object's state to unsignaled.
void	k_poll_signal_check (struct k_poll_signal *sig, unsigned int *signaled, int *result)
	Fetch the signaled state and result value of a poll signal.
int	k_poll_signal_raise (struct k_poll_signal *sig, int result)
	Signal a poll signal object.
static void	k_cpu_idle (void)
	Make the CPU idle.
static void	k_cpu_atomic_idle (unsigned int key)
	Make the CPU idle in an atomic fashion.
int	k_float_disable (struct k_thread *thread)
	Disable preservation of floating point context information.
int	k_float_enable (struct k_thread *thread, unsigned int options)
	Enable preservation of floating point context information.
int	k_thread_runtime_stats_get (k_tid_t thread, k_thread_runtime_stats_t *stats)
	Get the runtime statistics of a thread.
int	k_thread_runtime_stats_all_get (k_thread_runtime_stats_t *stats)
	Get the runtime statistics of all threads.
int	k_thread_runtime_stats_cpu_get (int cpu, k_thread_runtime_stats_t *stats)
	Get the runtime statistics of all threads on specified cpu.
int	k_thread_runtime_stats_enable (k_tid_t thread)
	Enable gathering of runtime statistics for specified thread.
int	k_thread_runtime_stats_disable (k_tid_t thread)
	Disable gathering of runtime statistics for specified thread.
bool	k_thread_runtime_stats_is_enabled (k_tid_t thread)
	Check if runtime statistics gathering is enabled for a thread.
void	k_sys_runtime_stats_enable (void)
	Enable gathering of system runtime statistics.
void	k_sys_runtime_stats_disable (void)
	Disable gathering of system runtime statistics.

Detailed Description

Public kernel APIs.

Macro Definition Documentation

k_oops

#define k_oops

(

)

Value:

z_except_reason(K_ERR_KERNEL_OOPS)

Fatally terminate a thread.

This should be called when a thread has encountered an unrecoverable runtime condition and needs to terminate. What this ultimately means is determined by the _fatal_error_handler() implementation, which will be called with reason code K_ERR_KERNEL_OOPS.

If this is called from ISR context, the default system fatal error handler will treat it as an unrecoverable system error, just like k_panic().

k_panic

#define k_panic

(

)

Value:

z_except_reason(K_ERR_KERNEL_PANIC)

Fatally terminate the system.

This should be called when the Zephyr kernel has encountered an unrecoverable runtime condition and needs to terminate. What this ultimately means is determined by the _fatal_error_handler() implementation, which will be called with reason code K_ERR_KERNEL_PANIC.

Typedef Documentation

k_ipi_func_t

typedef void(* k_ipi_func_t) (struct k_ipi_work *work)

IPI work item handler function type.

Invoked at ISR level on each CPU targeted by k_ipi_work_add().

Parameters

work	IPI work item being processed.

Function Documentation

k_ipi_work_add()

int k_ipi_work_add	(	struct k_ipi_work *	work,
		uint32_t	cpu_bitmask,
		k_ipi_func_t	func )

Add an IPI work item to the IPI work queue.

Adds the specified IPI work item to the IPI work queues of each CPU identified by cpu_bitmask. The specified IPI work item will subsequently execute at ISR level as those CPUs process their received IPIs. Do not re-use the specified IPI work item until it has been processed by all of the identified CPUs.

Attention

Available only when the following Kconfig option is enabled:

CONFIG_SCHED_IPI_SUPPORTED 

.

Parameters

work	Pointer to the IPI work item
cpu_bitmask	Set of CPUs to which the IPI work item will be sent
func	Function to execute on the targeted CPU(s)

Return values

0	on success
-EBUSY	if the specified IPI work item is still being processed

k_ipi_work_init()

void k_ipi_work_init ( struct k_ipi_work * work )

inlinestatic

Initialize the specified IPI work item.

Attention

Available only when the following Kconfig option is enabled:

CONFIG_SCHED_IPI_SUPPORTED 

.

Parameters

work	Pointer to the IPI work item to be initialized

k_ipi_work_signal()

void k_ipi_work_signal

(

void

)

Signal that there is one or more IPI work items to process.

This routine sends an IPI to the set of CPUs identified by calls to k_ipi_work_add() since this CPU sent its last set of IPIs.

Attention

Available only when the following Kconfig option is enabled:

CONFIG_SCHED_IPI_SUPPORTED 

.

k_ipi_work_wait()

int k_ipi_work_wait	(	struct k_ipi_work *	work,
		k_timeout_t	timeout )

Wait until the IPI work item has been processed by all targeted CPUs.

This routine waits until the IPI work item has been processed by all CPUs to which it was sent. If called from an ISR, then timeout must be set to K_NO_WAIT. To prevent deadlocks the caller must not have IRQs locked when calling this function.

Note

It is not in general possible to poll safely for completion of this function in ISR or locked contexts where the calling CPU cannot service IPIs (because the targeted CPUs may themselves be waiting on the calling CPU). Application code must be prepared for failure or to poll from a thread context.

Attention

Available only when the following Kconfig option is enabled:

CONFIG_SCHED_IPI_SUPPORTED 

.

Parameters

work	Pointer to the IPI work item
timeout	Maximum time to wait for IPI work to be processed

Return values

-EAGAIN	Waiting period timed out.
0	if processed by all targeted CPUs

k_sys_runtime_stats_disable()

void k_sys_runtime_stats_disable

(

void

)

Disable gathering of system runtime statistics.

This routine disables the gathering of system runtime statistics. Note that it does not affect the gathering of similar statistics for individual threads.

k_sys_runtime_stats_enable()

void k_sys_runtime_stats_enable

(

void

)

Enable gathering of system runtime statistics.

This routine enables the gathering of system runtime statistics. Note that it does not affect the gathering of similar statistics for individual threads.

k_thread_runtime_stats_all_get()

int k_thread_runtime_stats_all_get

(

k_thread_runtime_stats_t *

stats

)

Get the runtime statistics of all threads.

Parameters

stats

Pointer to struct to copy statistics into.

Returns

-EINVAL if null pointers, otherwise 0

k_thread_runtime_stats_cpu_get()

int k_thread_runtime_stats_cpu_get	(	int	cpu,
		k_thread_runtime_stats_t *	stats )

Get the runtime statistics of all threads on specified cpu.

Parameters

cpu	The cpu number
stats	Pointer to struct to copy statistics into.

Returns

-EINVAL if null pointers, otherwise 0

k_thread_runtime_stats_disable()

int k_thread_runtime_stats_disable

(

k_tid_t

thread

)

Disable gathering of runtime statistics for specified thread.

This routine disables the gathering of runtime statistics for the specified thread.

Parameters

thread

ID of thread

Returns

-EINVAL if invalid thread ID, otherwise 0

k_thread_runtime_stats_enable()

int k_thread_runtime_stats_enable

(

k_tid_t

thread

)

Enable gathering of runtime statistics for specified thread.

This routine enables the gathering of runtime statistics for the specified thread.

Parameters

thread

ID of thread

Returns

-EINVAL if invalid thread ID, otherwise 0

k_thread_runtime_stats_get()

int k_thread_runtime_stats_get	(	k_tid_t	thread,
		k_thread_runtime_stats_t *	stats )

Get the runtime statistics of a thread.

Parameters

thread	ID of thread.
stats	Pointer to struct to copy statistics into.

Returns

-EINVAL if null pointers, otherwise 0

k_thread_runtime_stats_is_enabled()

bool k_thread_runtime_stats_is_enabled

(

k_tid_t

thread

)

Check if runtime statistics gathering is enabled for a thread.

This routine checks whether the specified thread has enabled runtime statistics.

Parameters

thread

ID of thread

Returns

true if usage statistics are enabled for the given thread, otherwise false