Kernel APIs

This section contains APIs for the kernel’s core services, as described in the Zephyr Kernel Primer (version 2).

Important

Unless otherwise noted these APIs can be used by threads, but not by ISRs.

Threads

A thread is an independently scheduled series of instructions that implements a portion of an application’s processing. Threads are used to perform processing that is too lengthy or too complex to be performed by an ISR. (See Threads.)

typedef k_thread_entry_t

Thread entry point function type.

A thread’s entry point function is invoked when the thread starts executing. Up to 3 argument values can be passed to the function.

The thread terminates execution permanently if the entry point function returns. The thread is responsible for releasing any shared resources it may own (such as mutexes and dynamically allocated memory), prior to returning.

Return
N/A
Parameters
  • p1: First argument.
  • p2: Second argument.
  • p3: Third argument.

k_tid_t k_thread_spawn(char *stack, size_t stack_size, k_thread_entry_t entry, void *p1, void *p2, void *p3, int prio, uint32_t options, int32_t delay)

Spawn a thread.

This routine initializes a thread, then schedules it for execution.

The new thread may be scheduled for immediate execution or a delayed start. If the newly spawned thread does not have a delayed start the kernel scheduler may preempt the current thread to allow the new thread to execute.

Thread options are architecture-specific, and can include K_ESSENTIAL, K_FP_REGS, and K_SSE_REGS. Multiple options may be specified by separating them using “|” (the logical OR operator).

Return
ID of new thread.
Parameters
  • stack: Pointer to the stack space.
  • stack_size: Stack size in bytes.
  • entry: Thread entry function.
  • p1: 1st entry point parameter.
  • p2: 2nd entry point parameter.
  • p3: 3rd entry point parameter.
  • prio: Thread priority.
  • options: Thread options.
  • delay: Scheduling delay (in milliseconds), or K_NO_WAIT (for no delay).

void k_sleep(int32_t duration)

Put the current thread to sleep.

This routine puts the current thread to sleep for duration milliseconds.

Return
N/A
Parameters
  • duration: Number of milliseconds to sleep.

void k_busy_wait(uint32_t usec_to_wait)

Cause the current thread to busy wait.

This routine causes the current thread to execute a “do nothing” loop for usec_to_wait microseconds.

Return
N/A

void k_yield(void)

Yield the current thread.

This routine causes the current thread to yield execution to another thread of the same or higher priority. If there are no other ready threads of the same or higher priority, the routine returns immediately.

Return
N/A

void k_wakeup(k_tid_t thread)

Wake up a sleeping thread.

This routine prematurely wakes up thread from sleeping.

If thread is not currently sleeping, the routine has no effect.

Return
N/A
Parameters
  • thread: ID of thread to wake.

k_tid_t k_current_get(void)

Get thread ID of the current thread.

Return
ID of current thread.

int k_thread_cancel(k_tid_t thread)

Cancel thread performing a delayed start.

This routine prevents thread from executing if it has not yet started execution. The thread must be re-spawned before it will execute.

Parameters
  • thread: ID of thread to cancel.
Return Value
  • 0: Thread spawning cancelled.
  • -EINVAL: Thread has already started executing.

void k_thread_abort(k_tid_t thread)

Abort a thread.

This routine permanently stops execution of thread. The thread is taken off all kernel queues it is part of (i.e. the ready queue, the timeout queue, or a kernel object wait queue). However, any kernel resources the thread might currently own (such as mutexes or memory blocks) are not released. It is the responsibility of the caller of this routine to ensure all necessary cleanup is performed.

Return
N/A
Parameters
  • thread: ID of thread to abort.

int k_thread_priority_get(k_tid_t thread)

Get a thread’s priority.

This routine gets the priority of thread.

Return
Priority of thread.
Parameters
  • thread: ID of thread whose priority is needed.

void k_thread_priority_set(k_tid_t thread, int prio)

Set a thread’s priority.

This routine immediately changes the priority of thread.

Rescheduling can occur immediately depending on the priority thread is set to:

  • If its priority is raised above the priority of the caller of this function, and the caller is preemptible, thread will be scheduled in.
  • If the caller operates on itself, it lowers its priority below that of other threads in the system, and the caller is preemptible, the thread of highest priority will be scheduled in.

Priority can be assigned in the range of -CONFIG_NUM_COOP_PRIORITIES to CONFIG_NUM_PREEMPT_PRIORITIES-1, where -CONFIG_NUM_COOP_PRIORITIES is the highest priority.

Warning
Changing the priority of a thread currently involved in mutex priority inheritance may result in undefined behavior.
Return
N/A
Parameters
  • thread: ID of thread whose priority is to be set.
  • prio: New priority.

void k_thread_suspend(k_tid_t thread)

Suspend a thread.

This routine prevents the kernel scheduler from making thread the current thread. All other internal operations on thread are still performed; for example, any timeout it is waiting on keeps ticking, kernel objects it is waiting on are still handed to it, etc.

If thread is already suspended, the routine has no effect.

Return
N/A
Parameters
  • thread: ID of thread to suspend.

void k_thread_resume(k_tid_t thread)

Resume a suspended thread.

This routine allows the kernel scheduler to make thread the current thread, when it is next eligible for that role.

If thread is not currently suspended, the routine has no effect.

Return
N/A
Parameters
  • thread: ID of thread to resume.

void k_sched_time_slice_set(int32_t slice, int prio)

Set time-slicing period and scope.

This routine specifies how the scheduler will perform time slicing of preemptible threads.

To enable time slicing, slice must be non-zero. The scheduler ensures that no thread runs for more than the specified time limit before other threads of that priority are given a chance to execute. Any thread whose priority is higher than prio is exempted, and may execute as long as desired without being pre-empted due to time slicing.

Time slicing only limits the maximum amount of time a thread may continuously execute. Once the scheduler selects a thread for execution, there is no minimum guaranteed time the thread will execute before threads of greater or equal priority are scheduled.

When the current thread is the only one of that priority eligible for execution, this routine has no effect; the thread is immediately rescheduled after the slice period expires.

To disable timeslicing, set both slice and prio to zero.

Return
N/A
Parameters
  • slice: Maximum time slice length (in milliseconds).
  • prio: Highest thread priority level eligible for time slicing.

void k_sched_lock(void)

Lock the scheduler.

This routine prevents the current thread from being preempted by another thread by instructing the scheduler to treat it as a cooperative thread. If the thread subsequently performs an operation that makes it unready, it will be context switched out in the normal manner. When the thread again becomes the current thread, its non-preemptible status is maintained.

This routine can be called recursively.

Note
k_sched_lock() and k_sched_unlock() should normally be used when the operation being performed can be safely interrupted by ISRs. However, if the amount of processing involved is very small, better performance may be obtained by using irq_lock() and irq_unlock().
Return
N/A

void k_sched_unlock(void)

Unlock the scheduler.

This routine reverses the effect of a previous call to k_sched_lock(). A thread must call the routine once for each time it called k_sched_lock() before the thread becomes preemptible.

Return
N/A

void k_thread_custom_data_set(void *value)

Set current thread’s custom data.

This routine sets the custom data for the current thread to @ value.

Custom data is not used by the kernel itself, and is freely available for a thread to use as it sees fit. It can be used as a framework upon which to build thread-local storage.

Return
N/A
Parameters
  • value: New custom data value.

void *k_thread_custom_data_get(void)

Get current thread’s custom data.

This routine returns the custom data for the current thread.

Return
Current custom data value.

K_ESSENTIAL (1 << 0)
K_THREAD_DEFINE(name, stack_size, entry, p1, p2, p3, prio, options, delay) char __noinit __stack _k_thread_obj_##name[stack_size]; \ struct _static_thread_data _k_thread_data_##name __aligned(4) \ __in_section(_static_thread_data, static, name) = \ _THREAD_INITIALIZER(_k_thread_obj_##name, stack_size, \ entry, p1, p2, p3, prio, options, delay, \ NULL, 0); \ const k_tid_t name = (k_tid_t)_k_thread_obj_##name

Statically define and initialize a thread.

The thread may be scheduled for immediate execution or a delayed start.

Thread options are architecture-specific, and can include K_ESSENTIAL, K_FP_REGS, and K_SSE_REGS. Multiple options may be specified by separating them using “|” (the logical OR operator).

The ID of the thread can be accessed using:

extern const k_tid_t <name>;

Parameters
  • name: Name of the thread.
  • stack_size: Stack size in bytes.
  • entry: Thread entry function.
  • p1: 1st entry point parameter.
  • p2: 2nd entry point parameter.
  • p3: 3rd entry point parameter.
  • prio: Thread priority.
  • options: Thread options.
  • delay: Scheduling delay (in milliseconds), or K_NO_WAIT (for no delay).

Workqueues

A workqueue processes a series of work items by executing the associated functions in a dedicated thread. Workqueues are typically used by an ISR or high-priority thread to offload non-urgent processing. (See Workqueue Threads.)

typedef k_work_handler_t

Work item handler function type.

A work item’s handler function is executed by a workqueue’s thread when the work item is processed by the workqueue.

Return
N/A
Parameters
  • work: Address of the work item.

static void k_work_init(struct k_work *work, k_work_handler_t handler)

Initialize a work item.

This routine initializes a workqueue work item, prior to its first use.

Return
N/A
Parameters
  • work: Address of work item.
  • handler: Function to invoke each time work item is processed.

static void k_work_submit_to_queue(struct k_work_q *work_q, struct k_work *work)

Submit a work item.

This routine submits work item work to be processed by workqueue work_q. If the work item is already pending in the workqueue’s queue as a result of an earlier submission, this routine has no effect on the work item. If the work item has already been processed, or is currently being processed, its work is considered complete and the work item can be resubmitted.

Warning
A submitted work item must not be modified until it has been processed by the workqueue.
Note
Can be called by ISRs.
Return
N/A
Parameters
  • work_q: Address of workqueue.
  • work: Address of work item.

static int k_work_pending(struct k_work *work)

Check if a work item is pending.

This routine indicates if work item work is pending in a workqueue’s queue.

Note
Can be called by ISRs.
Return
1 if work item is pending, or 0 if it is not pending.
Parameters
  • work: Address of work item.

void k_work_q_start(struct k_work_q *work_q, char *stack, size_t stack_size, int prio)

Start a workqueue.

This routine starts workqueue work_q. The workqueue spawns its work processing thread, which runs forever.

Return
N/A
Parameters
  • work_q: Address of workqueue.
  • stack: Pointer to work queue thread’s stack space.
  • stack_size: Size of the work queue thread’s stack (in bytes).
  • prio: Priority of the work queue’s thread.

void k_delayed_work_init(struct k_delayed_work *work, k_work_handler_t handler)

Initialize a delayed work item.

This routine initializes a workqueue delayed work item, prior to its first use.

Return
N/A
Parameters
  • work: Address of delayed work item.
  • handler: Function to invoke each time work item is processed.

int k_delayed_work_submit_to_queue(struct k_work_q *work_q, struct k_delayed_work *work, int32_t delay)

Submit a delayed work item.

This routine schedules work item work to be processed by workqueue work_q after a delay of delay milliseconds. The routine initiates an asychronous countdown for the work item and then returns to the caller. Only when the countdown completes is the work item actually submitted to the workqueue and becomes pending.

Submitting a previously submitted delayed work item that is still counting down cancels the existing submission and restarts the countdown using the new delay. If the work item is currently pending on the workqueue’s queue because the countdown has completed it is too late to resubmit the item, and resubmission fails without impacting the work item. If the work item has already been processed, or is currently being processed, its work is considered complete and the work item can be resubmitted.

Warning
A delayed work item must not be modified until it has been processed by the workqueue.
Note
Can be called by ISRs.
Parameters
  • work_q: Address of workqueue.
  • work: Address of delayed work item.
  • delay: Delay before submitting the work item (in milliseconds).
Return Value
  • 0: Work item countdown started.
  • -EINPROGRESS: Work item is already pending.
  • -EINVAL: Work item is being processed or has completed its work.
  • -EADDRINUSE: Work item is pending on a different workqueue.

int k_delayed_work_cancel(struct k_delayed_work *work)

Cancel a delayed work item.

This routine cancels the submission of delayed work item work. A delayed work item can only be cancelled while its countdown is still underway.

Note
Can be called by ISRs.
Parameters
  • work: Address of delayed work item.
Return Value
  • 0: Work item countdown cancelled.
  • -EINPROGRESS: Work item is already pending.
  • -EINVAL: Work item is being processed or has completed its work.

static void k_work_submit(struct k_work *work)

Submit a work item to the system workqueue.

This routine submits work item work to be processed by the system workqueue. If the work item is already pending in the workqueue’s queue as a result of an earlier submission, this routine has no effect on the work item. If the work item has already been processed, or is currently being processed, its work is considered complete and the work item can be resubmitted.

Warning
Work items submitted to the system workqueue should avoid using handlers that block or yield since this may prevent the system workqueue from processing other work items in a timely manner.
Note
Can be called by ISRs.
Return
N/A
Parameters
  • work: Address of work item.

static int k_delayed_work_submit(struct k_delayed_work *work, int32_t delay)

Submit a delayed work item to the system workqueue.

This routine schedules work item work to be processed by the system workqueue after a delay of delay milliseconds. The routine initiates an asychronous countdown for the work item and then returns to the caller. Only when the countdown completes is the work item actually submitted to the workqueue and becomes pending.

Submitting a previously submitted delayed work item that is still counting down cancels the existing submission and restarts the countdown using the new delay. If the work item is currently pending on the workqueue’s queue because the countdown has completed it is too late to resubmit the item, and resubmission fails without impacting the work item. If the work item has already been processed, or is currently being processed, its work is considered complete and the work item can be resubmitted.

Warning
Work items submitted to the system workqueue should avoid using handlers that block or yield since this may prevent the system workqueue from processing other work items in a timely manner.
Note
Can be called by ISRs.
Parameters
  • work: Address of delayed work item.
  • delay: Delay before submitting the work item (in milliseconds).
Return Value
  • 0: Work item countdown started.
  • -EINPROGRESS: Work item is already pending.
  • -EINVAL: Work item is being processed or has completed its work.
  • -EADDRINUSE: Work item is pending on a different workqueue.

static int32_t k_delayed_work_remaining_get(struct k_delayed_work *work)

Get time remaining before a delayed work gets scheduled.

This routine computes the (approximate) time remaining before a delayed work gets executed. If the delayed work is not waiting to be schedules, it returns zero.

Return
Remaining time (in milliseconds).
Parameters
  • work: Delayed work item.

K_WORK_INITIALIZER(work_handler) { \ ._reserved = NULL, \ .handler = work_handler, \ .flags = { 0 } \ }

Initialize a statically-defined work item.

This macro can be used to initialize a statically-defined workqueue work item, prior to its first use. For example,

struct k_work <work> = K_WORK_INITIALIZER(<work_handler>);

Parameters
  • work_handler: Function to invoke each time work item is processed.

Clocks

Kernel clocks enable threads and ISRs to measure the passage of time with either normal and high precision. (See Kernel Clocks.)

int64_t k_uptime_get(void)

Get system uptime.

This routine returns the elapsed time since the system booted, in milliseconds.

Return
Current uptime.

uint32_t k_uptime_get_32(void)

Get system uptime (32-bit version).

This routine returns the lower 32-bits of the elapsed time since the system booted, in milliseconds.

This routine can be more efficient than k_uptime_get(), as it reduces the need for interrupt locking and 64-bit math. However, the 32-bit result cannot hold a system uptime time larger than approximately 50 days, so the caller must handle possible rollovers.

Return
Current uptime.

int64_t k_uptime_delta(int64_t *reftime)

Get elapsed time.

This routine computes the elapsed time between the current system uptime and an earlier reference time, in milliseconds.

Return
Elapsed time.
Parameters
  • reftime: Pointer to a reference time, which is updated to the current uptime upon return.

uint32_t k_uptime_delta_32(int64_t *reftime)

Get elapsed time (32-bit version).

This routine computes the elapsed time between the current system uptime and an earlier reference time, in milliseconds.

This routine can be more efficient than k_uptime_delta(), as it reduces the need for interrupt locking and 64-bit math. However, the 32-bit result cannot hold an elapsed time larger than approximately 50 days, so the caller must handle possible rollovers.

Return
Elapsed time.
Parameters
  • reftime: Pointer to a reference time, which is updated to the current uptime upon return.

K_NO_WAIT 0

Generate null timeout delay.

This macro generates a timeout delay that that instructs a kernel API not to wait if the requested operation cannot be performed immediately.

Return
Timeout delay value.

K_MSEC(ms) (ms)

Generate timeout delay from milliseconds.

This macro generates a timeout delay that that instructs a kernel API to wait up to ms milliseconds to perform the requested operation.

Return
Timeout delay value.
Parameters
  • ms: Duration in milliseconds.

K_SECONDS(s) K_MSEC((s) * MSEC_PER_SEC)

Generate timeout delay from seconds.

This macro generates a timeout delay that that instructs a kernel API to wait up to s seconds to perform the requested operation.

Return
Timeout delay value.
Parameters
  • s: Duration in seconds.

K_MINUTES(m) K_SECONDS((m) * 60)

Generate timeout delay from minutes.

This macro generates a timeout delay that that instructs a kernel API to wait up to m minutes to perform the requested operation.

Return
Timeout delay value.
Parameters
  • m: Duration in minutes.

K_HOURS(h) K_MINUTES((h) * 60)

Generate timeout delay from hours.

This macro generates a timeout delay that that instructs a kernel API to wait up to h hours to perform the requested operation.

Return
Timeout delay value.
Parameters
  • h: Duration in hours.

K_FOREVER (-1)

Generate infinite timeout delay.

This macro generates a timeout delay that that instructs a kernel API to wait as long as necessary to perform the requested operation.

Return
Timeout delay value.

k_cycle_get_32 _arch_k_cycle_get_32()

Read the hardware clock.

This routine returns the current time, as measured by the system’s hardware clock.

Return
Current hardware clock up-counter (in cycles).

SYS_CLOCK_HW_CYCLES_TO_NS(X) (uint32_t)(SYS_CLOCK_HW_CYCLES_TO_NS64(X))

Compute nanoseconds from hardware clock cycles.

This macro converts a time duration expressed in hardware clock cycles to the equivalent duration expressed in nanoseconds.

Return
Duration in nanoseconds.
Parameters
  • X: Duration in hardware clock cycles.

Timers

Timers enable threads to measure the passage of time, and to optionally execute an action when the timer expires. (See Timers.)

typedef k_timer_expiry_t

Timer expiry function type.

A timer’s expiry function is executed by the system clock interrupt handler each time the timer expires. The expiry function is optional, and is only invoked if the timer has been initialized with one.

Return
N/A
Parameters
  • timer: Address of timer.

typedef k_timer_stop_t

Timer stop function type.

A timer’s stop function is executed if the timer is stopped prematurely. The function runs in the context of the thread that stops the timer. The stop function is optional, and is only invoked if the timer has been initialized with one.

Return
N/A
Parameters
  • timer: Address of timer.

void k_timer_init(struct k_timer *timer, k_timer_expiry_t expiry_fn, k_timer_stop_t stop_fn)

Initialize a timer.

This routine initializes a timer, prior to its first use.

Return
N/A
Parameters
  • timer: Address of timer.
  • expiry_fn: Function to invoke each time the timer expires.
  • stop_fn: Function to invoke if the timer is stopped while running.

void k_timer_start(struct k_timer *timer, int32_t duration, int32_t period)

Start a timer.

This routine starts a timer, and resets its status to zero. The timer begins counting down using the specified duration and period values.

Attempting to start a timer that is already running is permitted. The timer’s status is reset to zero and the timer begins counting down using the new duration and period values.

Return
N/A
Parameters
  • timer: Address of timer.
  • duration: Initial timer duration (in milliseconds).
  • period: Timer period (in milliseconds).

void k_timer_stop(struct k_timer *timer)

Stop a timer.

This routine stops a running timer prematurely. The timer’s stop function, if one exists, is invoked by the caller.

Attempting to stop a timer that is not running is permitted, but has no effect on the timer.

Note
Can be called by ISRs. The stop handler has to be callable from ISRs if k_timer_stop is to be called from ISRs.
Return
N/A
Parameters
  • timer: Address of timer.

uint32_t k_timer_status_get(struct k_timer *timer)

Read timer status.

This routine reads the timer’s status, which indicates the number of times it has expired since its status was last read.

Calling this routine resets the timer’s status to zero.

Return
Timer status.
Parameters
  • timer: Address of timer.

uint32_t k_timer_status_sync(struct k_timer *timer)

Synchronize thread to timer expiration.

This routine blocks the calling thread until the timer’s status is non-zero (indicating that it has expired at least once since it was last examined) or the timer is stopped. If the timer status is already non-zero, or the timer is already stopped, the caller continues without waiting.

Calling this routine resets the timer’s status to zero.

This routine must not be used by interrupt handlers, since they are not allowed to block.

Return
Timer status.
Parameters
  • timer: Address of timer.

static int32_t k_timer_remaining_get(struct k_timer *timer)

Get time remaining before a timer next expires.

This routine computes the (approximate) time remaining before a running timer next expires. If the timer is not running, it returns zero.

Return
Remaining time (in milliseconds).
Parameters
  • timer: Address of timer.

static void k_timer_user_data_set(struct k_timer *timer, void *user_data)

Associate user-specific data with a timer.

This routine records the user_data with the timer, to be retrieved later.

It can be used e.g. in a timer handler shared across multiple subsystems to retrieve data specific to the subsystem this timer is associated with.

Return
N/A
Parameters
  • timer: Address of timer.
  • user_data: User data to associate with the timer.

static void *k_timer_user_data_get(struct k_timer *timer)

Retrieve the user-specific data from a timer.

Return
The user data.
Parameters
  • timer: Address of timer.

K_TIMER_DEFINE(name, expiry_fn, stop_fn) struct k_timer name \ __in_section(_k_timer, static, name) = \ K_TIMER_INITIALIZER(name, expiry_fn, stop_fn)

Statically define and initialize a timer.

The timer can be accessed outside the module where it is defined using:

extern struct k_timer <name>;

Parameters
  • name: Name of the timer variable.
  • expiry_fn: Function to invoke each time the timer expires.
  • stop_fn: Function to invoke if the timer is stopped while running.

Memory Slabs

Memory slabs enable the dynamic allocation and release of fixed-size memory blocks. (See Memory Slabs.)

void k_mem_slab_init(struct k_mem_slab *slab, void *buffer, size_t block_size, uint32_t num_blocks)

Initialize a memory slab.

Initializes a memory slab, prior to its first use.

The memory slab’s buffer contains slab_num_blocks memory blocks that are slab_block_size bytes long. The buffer must be aligned to an N-byte boundary, where N is a power of 2 larger than 2 (i.e. 4, 8, 16, ...). To ensure that each memory block is similarly aligned to this boundary, slab_block_size must also be a multiple of N.

Return
N/A
Parameters
  • slab: Address of the memory slab.
  • buffer: Pointer to buffer used for the memory blocks.
  • block_size: Size of each memory block (in bytes).
  • num_blocks: Number of memory blocks.

int k_mem_slab_alloc(struct k_mem_slab *slab, void **mem, int32_t timeout)

Allocate memory from a memory slab.

This routine allocates a memory block from a memory slab.

Parameters
  • slab: Address of the memory slab.
  • mem: Pointer to block address area.
  • timeout: Maximum time to wait for operation to complete (in milliseconds). Use K_NO_WAIT to return without waiting, or K_FOREVER to wait as long as necessary.
Return Value
  • 0: Memory allocated. The block address area pointed at by mem is set to the starting address of the memory block.
  • -ENOMEM: Returned without waiting.
  • -EAGAIN: Waiting period timed out.

void k_mem_slab_free(struct k_mem_slab *slab, void **mem)

Free memory allocated from a memory slab.

This routine releases a previously allocated memory block back to its associated memory slab.

Return
N/A
Parameters
  • slab: Address of the memory slab.
  • mem: Pointer to block address area (as set by k_mem_slab_alloc()).

static uint32_t k_mem_slab_num_used_get(struct k_mem_slab *slab)

Get the number of used blocks in a memory slab.

This routine gets the number of memory blocks that are currently allocated in slab.

Return
Number of allocated memory blocks.
Parameters
  • slab: Address of the 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.

This routine gets the number of memory blocks that are currently unallocated in slab.

Return
Number of unallocated memory blocks.
Parameters
  • slab: Address of the memory slab.

K_MEM_SLAB_DEFINE(name, slab_block_size, slab_num_blocks, slab_align) char __noinit __aligned(slab_align) \ _k_mem_slab_buf_##name[(slab_num_blocks) * (slab_block_size)]; \ struct k_mem_slab name \ __in_section(_k_mem_slab, static, name) = \ K_MEM_SLAB_INITIALIZER(name, _k_mem_slab_buf_##name, \ slab_block_size, slab_num_blocks)

Statically define and initialize a memory slab.

The memory slab’s buffer contains slab_num_blocks memory blocks that are slab_block_size bytes long. The buffer is aligned to a slab_align -byte boundary. To ensure that each memory block is similarly aligned to this boundary, slab_block_size must also be a multiple of slab_align.

The memory slab can be accessed outside the module where it is defined using:

extern struct k_mem_slab <name>;

Parameters
  • name: Name of the memory slab.
  • slab_block_size: Size of each memory block (in bytes).
  • slab_num_blocks: Number memory blocks.
  • slab_align: Alignment of the memory slab’s buffer (power of 2).

Memory Pools

Memory pools enable the dynamic allocation and release of variable-size memory blocks. (See Memory Pools.)

int k_mem_pool_alloc(struct k_mem_pool *pool, struct k_mem_block *block, size_t size, int32_t timeout)

Allocate memory from a memory pool.

This routine allocates a memory block from a memory pool.

Parameters
  • pool: Address of the memory pool.
  • block: Pointer to block descriptor for the allocated memory.
  • size: Amount of memory to allocate (in bytes).
  • timeout: Maximum time to wait for operation to complete (in milliseconds). Use K_NO_WAIT to return without waiting, or K_FOREVER to wait as long as necessary.
Return Value
  • 0: Memory allocated. The data field of the block descriptor is set to the starting address of the memory block.
  • -ENOMEM: Returned without waiting.
  • -EAGAIN: Waiting period timed out.

void k_mem_pool_free(struct k_mem_block *block)

Free memory allocated from a memory pool.

This routine releases a previously allocated memory block back to its memory pool.

Return
N/A
Parameters
  • block: Pointer to block descriptor for the allocated memory.

void k_mem_pool_defrag(struct k_mem_pool *pool)

Defragment a memory pool.

This routine instructs a memory pool to concatenate unused memory blocks into larger blocks wherever possible. Manually defragmenting the memory pool may speed up future allocations of memory blocks by eliminating the need for the memory pool to perform an automatic partial defragmentation.

Return
N/A
Parameters
  • pool: Address of the memory pool.

K_MEM_POOL_DEFINE(name, min_size, max_size, n_max, align) _MEMORY_POOL_QUAD_BLOCK_DEFINE(name, min_size, max_size, n_max); \ _MEMORY_POOL_BLOCK_SETS_DEFINE(name, min_size, max_size, n_max); \ _MEMORY_POOL_BUFFER_DEFINE(name, max_size, n_max, align); \ __asm__("_build_mem_pool " STRINGIFY(name) " " STRINGIFY(min_size) " " \ STRINGIFY(max_size) " " STRINGIFY(n_max) "\n\t"); \ extern struct k_mem_pool name

Statically define and initialize a memory pool.

The memory pool’s buffer contains n_max blocks that are max_size bytes long. The memory pool allows blocks to be repeatedly partitioned into quarters, down to blocks of min_size bytes long. The buffer is aligned to a align -byte boundary. To ensure that the minimum sized blocks are similarly aligned to this boundary, min_size must also be a multiple of align.

If the pool is to be accessed outside the module where it is defined, it can be declared via

extern struct k_mem_pool <name>;

Parameters
  • name: Name of the memory pool.
  • min_size: Size of the smallest blocks in the pool (in bytes).
  • max_size: Size of the largest blocks in the pool (in bytes).
  • n_max: Number of maximum sized blocks in the pool.
  • align: Alignment of the pool’s buffer (power of 2).

Heap Memory Pool

The heap memory pools enable the dynamic allocation and release of memory in a malloc()-like manner. (See Heap Memory Pool.)

void *k_malloc(size_t size)

Allocate memory from heap.

This routine provides traditional malloc() semantics. Memory is allocated from the heap memory pool.

Return
Address of the allocated memory if successful; otherwise NULL.
Parameters
  • size: Amount of memory requested (in bytes).

void k_free(void *ptr)

Free memory allocated from heap.

This routine provides traditional free() semantics. The memory being returned must have been allocated from the heap memory pool.

If ptr is NULL, no operation is performed.

Return
N/A
Parameters
  • ptr: Pointer to previously allocated memory.

Semaphores

Semaphores provide traditional counting semaphore capabilities. (See Semaphores.)

void k_sem_init(struct k_sem *sem, unsigned int initial_count, unsigned int limit)

Initialize a semaphore.

This routine initializes a semaphore object, prior to its first use.

Return
N/A
Parameters
  • sem: Address of the semaphore.
  • initial_count: Initial semaphore count.
  • limit: Maximum permitted semaphore count.

int k_sem_take(struct k_sem *sem, int32_t timeout)

Take a semaphore.

This routine takes sem.

Note
Can be called by ISRs, but timeout must be set to K_NO_WAIT.
Note
When porting code from the nanokernel legacy API to the new API, be careful with the return value of this function. The return value is the reverse of the one of nano_sem_take family of APIs: 0 means success, and non-zero means failure, while the nano_sem_take family returns 1 for success and 0 for failure.
Parameters
  • sem: Address of the semaphore.
  • timeout: Waiting period to take the semaphore (in milliseconds), or one of the special values K_NO_WAIT and K_FOREVER.
Return Value
  • 0: Semaphore taken.
  • -EBUSY: Returned without waiting.
  • -EAGAIN: Waiting period timed out.

void k_sem_give(struct k_sem *sem)

Give a semaphore.

This routine gives sem, unless the semaphore is already at its maximum permitted count.

Note
Can be called by ISRs.
Return
N/A
Parameters
  • sem: Address of the semaphore.

static void k_sem_reset(struct k_sem *sem)

Reset a semaphore’s count to zero.

This routine sets the count of sem to zero.

Return
N/A
Parameters
  • sem: Address of the semaphore.

static unsigned int k_sem_count_get(struct k_sem *sem)

Get a semaphore’s count.

This routine returns the current count of sem.

Return
Current semaphore count.
Parameters
  • sem: Address of the semaphore.

K_SEM_DEFINE(name, initial_count, count_limit) struct k_sem name \ __in_section(_k_sem, static, name) = \ K_SEM_INITIALIZER(name, initial_count, count_limit)

Statically define and initialize a semaphore.

The semaphore can be accessed outside the module where it is defined using:

extern struct k_sem <name>;

Parameters
  • name: Name of the semaphore.
  • initial_count: Initial semaphore count.
  • count_limit: Maximum permitted semaphore count.

Mutexes

Mutexes provide traditional reentrant mutex capabilities with basic priority inheritance. (See Mutexes.)

void k_mutex_init(struct k_mutex *mutex)

Initialize a mutex.

This routine initializes a mutex object, prior to its first use.

Upon completion, the mutex is available and does not have an owner.

Return
N/A
Parameters
  • mutex: Address of the mutex.

int k_mutex_lock(struct k_mutex *mutex, int32_t timeout)

Lock a mutex.

This routine locks mutex. If the mutex is locked by another thread, the calling thread waits until the mutex becomes available or until a timeout occurs.

A thread is permitted to lock a mutex it has already locked. The operation completes immediately and the lock count is increased by 1.

Parameters
  • mutex: Address of the mutex.
  • timeout: Waiting period to lock the mutex (in milliseconds), or one of the special values K_NO_WAIT and K_FOREVER.
Return Value
  • 0: Mutex locked.
  • -EBUSY: Returned without waiting.
  • -EAGAIN: Waiting period timed out.

void k_mutex_unlock(struct k_mutex *mutex)

Unlock a mutex.

This routine unlocks mutex. The mutex must already be locked by the calling thread.

The mutex cannot be claimed by another thread until it has been unlocked by the calling thread as many times as it was previously locked by that thread.

Return
N/A
Parameters
  • mutex: Address of the mutex.

K_MUTEX_DEFINE(name) struct k_mutex name \ __in_section(_k_mutex, static, name) = \ K_MUTEX_INITIALIZER(name)

Statically define and initialize a mutex.

The mutex can be accessed outside the module where it is defined using:

extern struct k_mutex <name>;

Parameters
  • name: Name of the mutex.

Alerts

Alerts enable an application to perform asynchronous signalling, somewhat akin to Unix-style signals. (See Alerts.)

typedef k_alert_handler_t

Alert handler function type.

An alert’s alert handler function is invoked by the system workqueue when the alert is signalled. The alert handler function is optional, and is only invoked if the alert has been initialized with one.

Return
0 if alert has been consumed; non-zero if alert should pend.
Parameters
  • alert: Address of the alert.

void k_alert_init(struct k_alert *alert, k_alert_handler_t handler, unsigned int max_num_pending_alerts)

Initialize an alert.

This routine initializes an alert object, prior to its first use.

Return
N/A
Parameters
  • alert: Address of the alert.
  • handler: Action to take when alert is sent. Specify either the address of a function to be invoked by the system workqueue thread, K_ALERT_IGNORE (which causes the alert to be ignored), or K_ALERT_DEFAULT (which causes the alert to pend).
  • max_num_pending_alerts: Maximum number of pending alerts.

int k_alert_recv(struct k_alert *alert, int32_t timeout)

Receive an alert.

This routine receives a pending alert for alert.

Note
Can be called by ISRs, but timeout must be set to K_NO_WAIT.
Parameters
  • alert: Address of the alert.
  • timeout: Waiting period to receive the alert (in milliseconds), or one of the special values K_NO_WAIT and K_FOREVER.
Return Value
  • 0: Alert received.
  • -EBUSY: Returned without waiting.
  • -EAGAIN: Waiting period timed out.

void k_alert_send(struct k_alert *alert)

Signal an alert.

This routine signals alert. The action specified for alert will be taken, which may trigger the execution of an alert handler function and/or cause the alert to pend (assuming the alert has not reached its maximum number of pending alerts).

Note
Can be called by ISRs.
Return
N/A
Parameters
  • alert: Address of the alert.

K_ALERT_DEFINE(name, alert_handler, max_num_pending_alerts) struct k_alert name \ __in_section(_k_alert, static, name) = \ K_ALERT_INITIALIZER(name, alert_handler, \ max_num_pending_alerts)

Statically define and initialize an alert.

The alert can be accessed outside the module where it is defined using:

extern struct k_alert <name>;

Parameters
  • name: Name of the alert.
  • alert_handler: Action to take when alert is sent. Specify either the address of a function to be invoked by the system workqueue thread, K_ALERT_IGNORE (which causes the alert to be ignored), or K_ALERT_DEFAULT (which causes the alert to pend).
  • max_num_pending_alerts: Maximum number of pending alerts.

Fifos

Fifos provide traditional first in, first out (FIFO) queuing of data items of any size. (See Fifos.)

void k_fifo_init(struct k_fifo *fifo)

Initialize a fifo.

This routine initializes a fifo object, prior to its first use.

Return
N/A
Parameters
  • fifo: Address of the fifo.

void k_fifo_put(struct k_fifo *fifo, void *data)

Add an element to a fifo.

This routine adds a data item to fifo. A fifo data item must be aligned on a 4-byte boundary, and the first 32 bits of the item are reserved for the kernel’s use.

Note
Can be called by ISRs.
Return
N/A
Parameters
  • fifo: Address of the fifo.
  • data: Address of the data item.

void k_fifo_put_list(struct k_fifo *fifo, void *head, void *tail)

Atomically add a list of elements to a fifo.

This routine adds a list of data items to fifo in one operation. The data items must be in a singly-linked list, with the first 32 bits each data item pointing to the next data item; the list must be NULL-terminated.

Note
Can be called by ISRs.
Return
N/A
Parameters
  • fifo: Address of the fifo.
  • head: Pointer to first node in singly-linked list.
  • tail: Pointer to last node in singly-linked list.

void k_fifo_put_slist(struct k_fifo *fifo, sys_slist_t *list)

Atomically add a list of elements to a fifo.

This routine adds a list of data items to fifo in one operation. The data items must be in a singly-linked list implemented using a sys_slist_t object. Upon completion, the sys_slist_t object is invalid and must be re-initialized via sys_slist_init().

Note
Can be called by ISRs.
Return
N/A
Parameters
  • fifo: Address of the fifo.
  • list: Pointer to sys_slist_t object.

void *k_fifo_get(struct k_fifo *fifo, int32_t timeout)

Get an element from a fifo.

This routine removes a data item from fifo in a “first in, first out” manner. The first 32 bits of the data item are reserved for the kernel’s use.

Note
Can be called by ISRs, but timeout must be set to K_NO_WAIT.
Return
Address of the data item if successful; NULL if returned without waiting, or waiting period timed out.
Parameters
  • fifo: Address of the fifo.
  • timeout: Waiting period to obtain a data item (in milliseconds), or one of the special values K_NO_WAIT and K_FOREVER.

static int k_fifo_is_empty(struct k_fifo *fifo)

Query a fifo to see if it has data available.

Note that the data might be already gone by the time this function returns if other threads is also trying to read from the fifo.

Note
Can be called by ISRs.
Return
Non-zero if the fifo is empty.
Return
0 if data is available.
Parameters
  • fifo: Address of the fifo.

K_FIFO_DEFINE(name) struct k_fifo name \ __in_section(_k_fifo, static, name) = \ K_FIFO_INITIALIZER(name)

Statically define and initialize a fifo.

The fifo can be accessed outside the module where it is defined using:

extern struct k_fifo <name>;

Parameters
  • name: Name of the fifo.

Lifos

Lifos provide traditional last in, first out (LIFO) queuing of data items of any size. (See Lifos.)

void k_lifo_init(struct k_lifo *lifo)

Initialize a lifo.

This routine initializes a lifo object, prior to its first use.

Return
N/A
Parameters
  • lifo: Address of the lifo.

void k_lifo_put(struct k_lifo *lifo, void *data)

Add an element to a lifo.

This routine adds a data item to lifo. A lifo data item must be aligned on a 4-byte boundary, and the first 32 bits of the item are reserved for the kernel’s use.

Note
Can be called by ISRs.
Return
N/A
Parameters
  • lifo: Address of the lifo.
  • data: Address of the data item.

void *k_lifo_get(struct k_lifo *lifo, int32_t timeout)

Get an element from a lifo.

This routine removes a data item from lifo in a “last in, first out” manner. The first 32 bits of the data item are reserved for the kernel’s use.

Note
Can be called by ISRs, but timeout must be set to K_NO_WAIT.
Return
Address of the data item if successful; NULL if returned without waiting, or waiting period timed out.
Parameters
  • lifo: Address of the lifo.
  • timeout: Waiting period to obtain a data item (in milliseconds), or one of the special values K_NO_WAIT and K_FOREVER.

K_LIFO_DEFINE(name) struct k_lifo name \ __in_section(_k_lifo, static, name) = \ K_LIFO_INITIALIZER(name)

Statically define and initialize a lifo.

The lifo can be accessed outside the module where it is defined using:

extern struct k_lifo <name>;

Parameters
  • name: Name of the fifo.

Stacks

Stacks provide traditional last in, first out (LIFO) queuing of 32-bit data items. (See Stacks.)

void k_stack_init(struct k_stack *stack, uint32_t *buffer, int num_entries)

Initialize a stack.

This routine initializes a stack object, prior to its first use.

Return
N/A
Parameters
  • stack: Address of the stack.
  • buffer: Address of array used to hold stacked values.
  • num_entries: Maximum number of values that can be stacked.

void k_stack_push(struct k_stack *stack, uint32_t data)

Push an element onto a stack.

This routine adds a 32-bit value data to stack.

Note
Can be called by ISRs.
Return
N/A
Parameters
  • stack: Address of the stack.
  • data: Value to push onto the stack.

int k_stack_pop(struct k_stack *stack, uint32_t *data, int32_t timeout)

Pop an element from a stack.

This routine removes a 32-bit value from stack in a “last in, first out” manner and stores the value in data.

Note
Can be called by ISRs, but timeout must be set to K_NO_WAIT.
Parameters
  • stack: Address of the stack.
  • data: Address of area to hold the value popped from the stack.
  • timeout: Waiting period to obtain a value (in milliseconds), or one of the special values K_NO_WAIT and K_FOREVER.
Return Value
  • 0: Element popped from stack.
  • -EBUSY: Returned without waiting.
  • -EAGAIN: Waiting period timed out.

K_STACK_DEFINE(name, stack_num_entries) uint32_t __noinit \ _k_stack_buf_##name[stack_num_entries]; \ struct k_stack name \ __in_section(_k_stack, static, name) = \ K_STACK_INITIALIZER(name, _k_stack_buf_##name, \ stack_num_entries)

Statically define and initialize a stack.

The stack can be accessed outside the module where it is defined using:

extern struct k_stack <name>;

Parameters
  • name: Name of the stack.
  • stack_num_entries: Maximum number of values that can be stacked.

Message Queues

Message queues provide a simple message queuing mechanism for fixed-size data items. (See Message Queues.)

void k_msgq_init(struct k_msgq *q, char *buffer, size_t msg_size, uint32_t max_msgs)

Initialize a message queue.

This routine initializes a message queue object, prior to its first use.

The message queue’s ring buffer must contain space for max_msgs messages, each of which is msg_size bytes long. The buffer must be aligned to an N-byte boundary, where N is a power of 2 (i.e. 1, 2, 4, ...). To ensure that each message is similarly aligned to this boundary, q_msg_size must also be a multiple of N.

Return
N/A
Parameters
  • q: Address of the message queue.
  • buffer: Pointer to ring buffer that holds queued messages.
  • msg_size: Message size (in bytes).
  • max_msgs: Maximum number of messages that can be queued.

int k_msgq_put(struct k_msgq *q, void *data, int32_t timeout)

Send a message to a message queue.

This routine sends a message to message queue q.

Note
Can be called by ISRs.
Parameters
  • q: Address of the message queue.
  • data: Pointer to the message.
  • timeout: Waiting period to add the message (in milliseconds), or one of the special values K_NO_WAIT and K_FOREVER.
Return Value
  • 0: Message sent.
  • -ENOMSG: Returned without waiting or queue purged.
  • -EAGAIN: Waiting period timed out.

int k_msgq_get(struct k_msgq *q, void *data, int32_t timeout)

Receive a message from a message queue.

This routine receives a message from message queue q in a “first in, first out” manner.

Note
Can be called by ISRs, but timeout must be set to K_NO_WAIT.
Parameters
  • q: Address of the message queue.
  • data: Address of area to hold the received message.
  • timeout: Waiting period to receive the message (in milliseconds), or one of the special values K_NO_WAIT and K_FOREVER.
Return Value
  • 0: Message received.
  • -ENOMSG: Returned without waiting.
  • -EAGAIN: Waiting period timed out.

void k_msgq_purge(struct k_msgq *q)

Purge a message queue.

This routine discards all unreceived messages in a message queue’s ring buffer. Any threads that are blocked waiting to send a message to the message queue are unblocked and see an -ENOMSG error code.

Return
N/A
Parameters
  • q: Address of the message queue.

static uint32_t k_msgq_num_free_get(struct k_msgq *q)

Get the amount of free space in a message queue.

This routine returns the number of unused entries in a message queue’s ring buffer.

Return
Number of unused ring buffer entries.
Parameters
  • q: Address of the message queue.

static uint32_t k_msgq_num_used_get(struct k_msgq *q)

Get the number of messages in a message queue.

This routine returns the number of messages in a message queue’s ring buffer.

Return
Number of messages.
Parameters
  • q: Address of the message queue.

K_MSGQ_DEFINE(q_name, q_msg_size, q_max_msgs, q_align) static char __noinit __aligned(q_align) \ _k_fifo_buf_##q_name[(q_max_msgs) * (q_msg_size)]; \ struct k_msgq q_name \ __in_section(_k_msgq, static, q_name) = \ K_MSGQ_INITIALIZER(q_name, _k_fifo_buf_##q_name, \ q_msg_size, q_max_msgs)

Statically define and initialize a message queue.

The message queue’s ring buffer contains space for q_max_msgs messages, each of which is q_msg_size bytes long. The buffer is aligned to a q_align -byte boundary, which must be a power of 2. To ensure that each message is similarly aligned to this boundary, q_msg_size must also be a multiple of q_align.

The message queue can be accessed outside the module where it is defined using:

extern struct k_msgq <name>;

Parameters
  • q_name: Name of the message queue.
  • q_msg_size: Message size (in bytes).
  • q_max_msgs: Maximum number of messages that can be queued.
  • q_align: Alignment of the message queue’s ring buffer.

Mailboxes

Mailboxes provide an enhanced message queuing mechanism for variable-size messages. (See Mailboxes.)

void k_mbox_init(struct k_mbox *mbox)

Initialize a mailbox.

This routine initializes a mailbox object, prior to its first use.

Return
N/A
Parameters
  • mbox: Address of the mailbox.

int k_mbox_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg, int32_t timeout)

Send a mailbox message in a synchronous manner.

This routine sends a message to mbox and waits for a receiver to both receive and process it. The message data may be in a buffer, in a memory pool block, or non-existent (i.e. an empty message).

Parameters
  • mbox: Address of the mailbox.
  • tx_msg: Address of the transmit message descriptor.
  • timeout: Waiting period for the message to be received (in milliseconds), or one of the special values K_NO_WAIT and K_FOREVER. Once the message has been received, this routine waits as long as necessary for the message to be completely processed.
Return Value
  • 0: Message sent.
  • -ENOMSG: Returned without waiting.
  • -EAGAIN: Waiting period timed out.

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.

This routine sends a message to mbox without waiting for a receiver to process it. The message data may be in a buffer, in a memory pool block, or non-existent (i.e. an empty message). Optionally, the semaphore sem will be given when the message has been both received and completely processed by the receiver.

Return
N/A
Parameters
  • mbox: Address of the mailbox.
  • tx_msg: Address of the transmit message descriptor.
  • sem: Address of a semaphore, or NULL if none is needed.

int k_mbox_get(struct k_mbox *mbox, struct k_mbox_msg *rx_msg, void *buffer, int32_t timeout)

Receive a mailbox message.

This routine receives a message from mbox, then optionally retrieves its data and disposes of the message.

Parameters
  • mbox: Address of the mailbox.
  • rx_msg: Address of the receive message descriptor.
  • buffer: Address of the buffer to receive data, or NULL to defer data retrieval and message disposal until later.
  • timeout: Waiting period for a message to be received (in milliseconds), or one of the special values K_NO_WAIT and K_FOREVER.
Return Value
  • 0: Message received.
  • -ENOMSG: Returned without waiting.
  • -EAGAIN: Waiting period timed out.

void k_mbox_data_get(struct k_mbox_msg *rx_msg, void *buffer)

Retrieve mailbox message data into a buffer.

This routine completes the processing of a received message by retrieving its data into a buffer, then disposing of the message.

Alternatively, this routine can be used to dispose of a received message without retrieving its data.

Return
N/A
Parameters
  • rx_msg: Address of the receive message descriptor.
  • buffer: Address of the buffer to receive data, or NULL to discard the data.

int k_mbox_data_block_get(struct k_mbox_msg *rx_msg, struct k_mem_pool *pool, struct k_mem_block *block, int32_t timeout)

Retrieve mailbox message data into a memory pool block.

This routine completes the processing of a received message by retrieving its data into a memory pool block, then disposing of the message. The memory pool block that results from successful retrieval must be returned to the pool once the data has been processed, even in cases where zero bytes of data are retrieved.

Alternatively, this routine can be used to dispose of a received message without retrieving its data. In this case there is no need to return a memory pool block to the pool.

This routine allocates a new memory pool block for the data only if the data is not already in one. If a new block cannot be allocated, the routine returns a failure code and the received message is left unchanged. This permits the caller to reattempt data retrieval at a later time or to dispose of the received message without retrieving its data.

Parameters
  • rx_msg: Address of a receive message descriptor.
  • pool: Address of memory pool, or NULL to discard data.
  • block: Address of the area to hold memory pool block info.
  • timeout: Waiting period to wait for a memory pool block (in milliseconds), or one of the special values K_NO_WAIT and K_FOREVER.
Return Value
  • 0: Data retrieved.
  • -ENOMEM: Returned without waiting.
  • -EAGAIN: Waiting period timed out.

K_MBOX_DEFINE(name) struct k_mbox name \ __in_section(_k_mbox, static, name) = \ K_MBOX_INITIALIZER(name) \

Statically define and initialize a mailbox.

The mailbox is to be accessed outside the module where it is defined using:

extern struct k_mbox <name>;

Parameters
  • name: Name of the mailbox.

Pipes

Pipes provide a traditional anonymous pipe mechanism for sending variable-size chunks of data, in whole or in part. (See Pipes.)

void k_pipe_init(struct k_pipe *pipe, unsigned char *buffer, size_t size)

Initialize a pipe.

This routine initializes a pipe object, prior to its first use.

Return
N/A
Parameters
  • pipe: Address of the pipe.
  • buffer: Address of the pipe’s ring buffer, or NULL if no ring buffer is used.
  • size: Size of the pipe’s ring buffer (in bytes), or zero if no ring buffer is used.

int k_pipe_put(struct k_pipe *pipe, void *data, size_t bytes_to_write, size_t *bytes_written, size_t min_xfer, int32_t timeout)

Write data to a pipe.

This routine writes up to bytes_to_write bytes of data to pipe.

Parameters
  • pipe: Address of the pipe.
  • data: Address of data to write.
  • bytes_to_write: Size of data (in bytes).
  • bytes_written: Address of area to hold the number of bytes written.
  • min_xfer: Minimum number of bytes to write.
  • timeout: Waiting period to wait for the data to be written (in milliseconds), or one of the special values K_NO_WAIT and K_FOREVER.
Return Value
  • 0: At least min_xfer bytes of data were written.
  • -EIO: Returned without waiting; zero data bytes were written.
  • -EAGAIN: Waiting period timed out; between zero and min_xfer minus one data bytes were written.

int k_pipe_get(struct k_pipe *pipe, void *data, size_t bytes_to_read, size_t *bytes_read, size_t min_xfer, int32_t timeout)

Read data from a pipe.

This routine reads up to bytes_to_read bytes of data from pipe.

Parameters
  • pipe: Address of the pipe.
  • data: Address to place the data read from pipe.
  • bytes_to_read: Maximum number of data bytes to read.
  • bytes_read: Address of area to hold the number of bytes read.
  • min_xfer: Minimum number of data bytes to read.
  • timeout: Waiting period to wait for the data to be read (in milliseconds), or one of the special values K_NO_WAIT and K_FOREVER.
Return Value
  • 0: At least min_xfer bytes of data were read.
  • -EIO: Returned without waiting; zero data bytes were read.
  • -EAGAIN: Waiting period timed out; between zero and min_xfer minus one data bytes were read.

void k_pipe_block_put(struct k_pipe *pipe, struct k_mem_block *block, size_t size, struct k_sem *sem)

Write memory block to a pipe.

This routine writes the data contained in a memory block to pipe. Once all of the data in the block has been written to the pipe, it will free the memory block block and give the semaphore sem (if specified).

Return
N/A
Parameters
  • pipe: Address of the pipe.
  • block: Memory block containing data to send
  • size: Number of data bytes in memory block to send
  • sem: Semaphore to signal upon completion (else NULL)

K_PIPE_DEFINE(name, pipe_buffer_size, pipe_align) static unsigned char __noinit __aligned(pipe_align) \ _k_pipe_buf_##name[pipe_buffer_size]; \ struct k_pipe name \ __in_section(_k_pipe, static, name) = \ K_PIPE_INITIALIZER(name, _k_pipe_buf_##name, pipe_buffer_size)

Statically define and initialize a pipe.

The pipe can be accessed outside the module where it is defined using:

extern struct k_pipe <name>;

Parameters
  • name: Name of the pipe.
  • pipe_buffer_size: Size of the pipe’s ring buffer (in bytes), or zero if no ring buffer is used.
  • pipe_align: Alignment of the pipe’s ring buffer (power of 2).

Interrupt Service Routines (ISRs)

An interrupt service routine is a series of instructions that is executed asynchronously in response to a hardware or software interrupt. (See Interrupts.)

int k_is_in_isr(void)

Determine if code is running at interrupt level.

This routine allows the caller to customize its actions, depending on whether it is a thread or an ISR.

Note
Can be called by ISRs.
Return
0 if invoked by a thread.
Return
Non-zero if invoked by an ISR.

int k_is_preempt_thread(void)

Determine if code is running in a preemptible thread.

This routine allows the caller to customize its actions, depending on whether it can be preempted by another thread. The routine returns a ‘true’ value if all of the following conditions are met:

  • The code is running in a thread, not at ISR.
  • The thread’s priority is in the preemptible range.
  • The thread has not locked the scheduler.

Note
Can be called by ISRs.
Return
0 if invoked by an ISR or by a cooperative thread.
Return
Non-zero if invoked by a preemptible thread.

IRQ_CONNECT(irq_p, priority_p, isr_p, isr_param_p, flags_p) _ARCH_IRQ_CONNECT(irq_p, priority_p, isr_p, isr_param_p, flags_p)

Initialize an interrupt handler.

This routine initializes an interrupt handler for an IRQ. The IRQ must be subsequently enabled before the interrupt handler begins servicing interrupts.

Warning
Although this routine is invoked at run-time, all of its arguments must be computable by the compiler at build time.
Return
Interrupt vector assigned to this interrupt.
Parameters
  • irq_p: IRQ line number.
  • priority_p: Interrupt priority.
  • isr_p: Address of interrupt service routine.
  • isr_param_p: Parameter passed to interrupt service routine.
  • flags_p: Architecture-specific IRQ configuration flags..

IRQ_DIRECT_CONNECT(irq_p, priority_p, isr_p, flags_p) _ARCH_IRQ_DIRECT_CONNECT(irq_p, priority_p, isr_p, flags_p)

Initialize a ‘direct’ interrupt handler.

This routine initializes an interrupt handler for an IRQ. The IRQ must be subsequently enabled via irq_enable() before the interrupt handler begins servicing interrupts.

These ISRs are designed for performance-critical interrupt handling and do not go through common interrupt handling code. They must be implemented in such a way that it is safe to put them directly in the vector table. For ISRs written in C, The ISR_DIRECT_DECLARE() macro will do this automatically. For ISRs wriiten in assembly it is entirely up to the developer to ensure that the right steps are taken.

This type of interrupt currently has a few limitations compared to normal Zephyr interrupts:

  • No parameters are passed to the ISR.
  • No stack switch is done, the ISR will run on the interrupted context’s stack, unless the architecture automatically does the stack switch in HW.
  • Interrupt locking state is unchanged from how the HW sets it when the ISR runs. On arches that enter ISRs with interrupts locked, they will remain locked.
  • Scheduling decisions are now optional, controlled by the return value of ISRs implemented with the ISR_DIRECT_DECLARE() macro
  • The call into the OS to exit power management idle state is now optional. Normal interrupts always do this before the ISR is run, but when it runs is now controlled by the placement of a ISR_DIRECT_PM() macro, or omitted entirely.

Warning
Although this routine is invoked at run-time, all of its arguments must be computable by the compiler at build time.
Return
Interrupt vector assigned to this interrupt.
Parameters
  • irq_p: IRQ line number.
  • priority_p: Interrupt priority.
  • isr_p: Address of interrupt service routine.
  • flags_p: Architecture-specific IRQ configuration flags.

ISR_DIRECT_HEADER _ARCH_ISR_DIRECT_HEADER()

Common tasks before executing the body of an ISR.

This macro must be at the beginning of all direct interrupts and performs minimal architecture-specific tasks before the ISR itself can run. It takes no arguments and has no return value.

Common tasks before exiting the body of an ISR.

This macro must be at the end of all direct interrupts and performs minimal architecture-specific tasks like EOI. It has no return value.

In a normal interrupt, a check is done at end of interrupt to invoke _Swap() logic if the current thread is preemptible and there is another thread ready to run in the kernel’s ready queue cache. This is now optional and controlled by the check_reschedule argument. If unsure, set to nonzero. On systems that do stack switching and nested interrupt tracking in software, _Swap() should only be called if this was a non-nested interrupt.

Parameters
  • check_reschedule: If nonzero, additionally invoke scheduling logic

ISR_DIRECT_PM _ARCH_ISR_DIRECT_PM()

Perform power management idle exit logic.

This macro may optionally be invoked somewhere in between IRQ_DIRECT_HEADER() and IRQ_DIRECT_FOOTER() invocations. It performs tasks necessary to exit power management idle state. It takes no parameters and returns no arguments. It may be omitted, but be careful!

ISR_DIRECT_DECLARE(name) _ARCH_ISR_DIRECT_DECLARE(name)

Helper macro to declare a direct interrupt service routine.

This will declare the function in a proper way and automatically include the ISR_DIRECT_FOOTER() and ISR_DIRECT_HEADER() macros. The function should return nonzero status if a scheduling decision should potentially be made. See ISR_DIRECT_FOOTER() for more details on the scheduling decision.

For architectures that support ‘regular’ and ‘fast’ interrupt types, where these interrupt types require different assembly language handling of registers by the ISR, this will always generate code for the ‘fast’ interrupt type.

Example usage:

ISR_DIRECT_DECLARE(my_isr) { bool done = do_stuff(); ISR_DIRECT_PM(); < done after do_stuff() due to latency concerns if (!done) { return 0; < Don’t bother checking if we have to _Swap() } k_sem_give(some_sem); return 1; }

Parameters
  • name: symbol name of the ISR

irq_lock _arch_irq_lock()

Lock interrupts.

This routine disables all interrupts on the CPU. It returns an unsigned integer “lock-out key”, which is an architecture-dependent indicator of whether interrupts were locked prior to the call. The lock-out key must be passed to irq_unlock() to re-enable interrupts.

This routine can be called recursively, as long as the caller keeps track of each lock-out key that is generated. Interrupts are re-enabled by passing each of the keys to irq_unlock() in the reverse order they were acquired. (That is, each call to irq_lock() must be balanced by a corresponding call to irq_unlock().)

Note
This routine can be called by ISRs or by threads. If it is called by a thread, the interrupt lock is thread-specific; this means that interrupts remain disabled only while the thread is running. If the thread performs an operation that allows another thread to run (for example, giving a semaphore or sleeping for N milliseconds), the interrupt lock no longer applies and interrupts may be re-enabled while other processing occurs. When the thread once again becomes the current thread, the kernel re-establishes its interrupt lock; this ensures the thread won’t be interrupted until it has explicitly released the interrupt lock it established.
Warning
The lock-out key should never be used to manually re-enable interrupts or to inspect or manipulate the contents of the CPU’s interrupt bits.
Return
Lock-out key.

irq_unlock(key) _arch_irq_unlock(key)

Unlock interrupts.

This routine reverses the effect of a previous call to irq_lock() using the associated lock-out key. The caller must call the routine once for each time it called irq_lock(), supplying the keys in the reverse order they were acquired, before interrupts are enabled.

Note
Can be called by ISRs.
Return
N/A
Parameters
  • key: Lock-out key generated by irq_lock().

irq_enable(irq) _arch_irq_enable(irq)

Enable an IRQ.

This routine enables interrupts from source irq.

Return
N/A
Parameters
  • irq: IRQ line.

irq_disable(irq) _arch_irq_disable(irq)

Disable an IRQ.

This routine disables interrupts from source irq.

Return
N/A
Parameters
  • irq: IRQ line.

irq_is_enabled(irq) _arch_irq_is_enabled(irq)

Get IRQ enable state.

This routine indicates if interrupts from source irq are enabled.

Return
interrupt enable state, true or false
Parameters
  • irq: IRQ line.

Atomic Services

The atomic services enable multiple threads and ISRs to read and modify 32-bit variables in an uninterruptible manner. (See Atomic Services.)

Important

All atomic services APIs can be used by both threads and ISRs.

int atomic_cas(atomic_t *target, atomic_val_t old_value, atomic_val_t new_value)

Atomic compare-and-set.

This routine performs an atomic compare-and-set on target. If the current value of target equals old_value, target is set to new_value. If the current value of target does not equal old_value, target is left unchanged.

Return
1 if new_value is written, 0 otherwise.
Parameters
  • target: Address of atomic variable.
  • old_value: Original value to compare against.
  • new_value: New value to store.

atomic_val_t atomic_add(atomic_t *target, atomic_val_t value)

Atomic addition.

This routine performs an atomic addition on target.

Return
Previous value of target.
Parameters
  • target: Address of atomic variable.
  • value: Value to add.

atomic_val_t atomic_sub(atomic_t *target, atomic_val_t value)

Atomic subtraction.

This routine performs an atomic subtraction on target.

Return
Previous value of target.
Parameters
  • target: Address of atomic variable.
  • value: Value to subtract.

atomic_val_t atomic_inc(atomic_t *target)

Atomic increment.

This routine performs an atomic increment by 1 on target.

Return
Previous value of target.
Parameters
  • target: Address of atomic variable.

atomic_val_t atomic_dec(atomic_t *target)

Atomic decrement.

This routine performs an atomic decrement by 1 on target.

Return
Previous value of target.
Parameters
  • target: Address of atomic variable.

atomic_val_t atomic_get(const atomic_t *target)

Atomic get.

This routine performs an atomic read on target.

Return
Value of target.
Parameters
  • target: Address of atomic variable.

atomic_val_t atomic_set(atomic_t *target, atomic_val_t value)

Atomic get-and-set.

This routine atomically sets target to value and returns the previous value of target.

Return
Previous value of target.
Parameters
  • target: Address of atomic variable.
  • value: Value to write to target.

atomic_val_t atomic_clear(atomic_t *target)

Atomic clear.

This routine atomically sets target to zero and returns its previous value. (Hence, it is equivalent to atomic_set(target, 0).)

Return
Previous value of target.
Parameters
  • target: Address of atomic variable.

atomic_val_t atomic_or(atomic_t *target, atomic_val_t value)

Atomic bitwise inclusive OR.

This routine atomically sets target to the bitwise inclusive OR of target and value.

Return
Previous value of target.
Parameters
  • target: Address of atomic variable.
  • value: Value to OR.

atomic_val_t atomic_xor(atomic_t *target, atomic_val_t value)

Atomic bitwise exclusive OR (XOR).

This routine atomically sets target to the bitwise exclusive OR (XOR) of target and value.

Return
Previous value of target.
Parameters
  • target: Address of atomic variable.
  • value: Value to XOR

atomic_val_t atomic_and(atomic_t *target, atomic_val_t value)

Atomic bitwise AND.

This routine atomically sets target to the bitwise AND of target and value.

Return
Previous value of target.
Parameters
  • target: Address of atomic variable.
  • value: Value to AND.

atomic_val_t atomic_nand(atomic_t *target, atomic_val_t value)

Atomic bitwise NAND.

This routine atomically sets target to the bitwise NAND of target and value. (This operation is equivalent to target = ~(target & value).)

Return
Previous value of target.
Parameters
  • target: Address of atomic variable.
  • value: Value to NAND.

static int atomic_test_bit(const atomic_t *target, int bit)

Atomically test a bit.

This routine tests whether bit number bit of target is set or not. The target may be a single atomic variable or an array of them.

Return
1 if the bit was set, 0 if it wasn’t.
Parameters
  • target: Address of atomic variable or array.
  • bit: Bit number (starting from 0).

static int atomic_test_and_clear_bit(atomic_t *target, int bit)

Atomically test and clear a bit.

Atomically clear bit number bit of target and return its old value. The target may be a single atomic variable or an array of them.

Return
1 if the bit was set, 0 if it wasn’t.
Parameters
  • target: Address of atomic variable or array.
  • bit: Bit number (starting from 0).

static int atomic_test_and_set_bit(atomic_t *target, int bit)

Atomically set a bit.

Atomically set bit number bit of target and return its old value. The target may be a single atomic variable or an array of them.

Return
1 if the bit was set, 0 if it wasn’t.
Parameters
  • target: Address of atomic variable or array.
  • bit: Bit number (starting from 0).

static void atomic_clear_bit(atomic_t *target, int bit)

Atomically clear a bit.

Atomically clear bit number bit of target. The target may be a single atomic variable or an array of them.

Return
N/A
Parameters
  • target: Address of atomic variable or array.
  • bit: Bit number (starting from 0).

static void atomic_set_bit(atomic_t *target, int bit)

Atomically set a bit.

Atomically set bit number bit of target. The target may be a single atomic variable or an array of them.

Return
N/A
Parameters
  • target: Address of atomic variable or array.
  • bit: Bit number (starting from 0).

ATOMIC_INIT(i) (i)

Initialize an atomic variable.

This macro can be used to initialize an atomic variable. For example, 

atomic_t my_var = ATOMIC_INIT(75);

Parameters
  • i: Value to assign to atomic variable.

ATOMIC_DEFINE(name, num_bits) atomic_t name[1 + ((num_bits) - 1) / ATOMIC_BITS]

Define an array of atomic variables.

This macro defines an array of atomic variables containing at least num_bits bits.

Note
If used from file scope, the bits of the array are initialized to zero; if used from within a function, the bits are left uninitialized.
Parameters
  • name: Name of array of atomic variables.
  • num_bits: Number of bits needed.

Floating Point Services

The floating point services enable threads to use a board’s floating point registers. (See Floating Point Services.)

void k_float_enable(k_tid_t thread, unsigned int options)

Enable preservation of floating point context information.

This routine informs the kernel that the specified thread (which may be the current thread) will be using the floating point registers. The options parameter indicates which floating point register sets will be used by the specified thread:

a) K_FP_REGS indicates x87 FPU and MMX registers only b) K_SSE_REGS indicates SSE registers (and also x87 FPU and MMX registers)

Invoking this routine initializes the thread’s floating point context info to that of an FPU that has been reset. The next time the thread is scheduled by _Swap() it will either inherit an FPU that is guaranteed to be in a “sane” state (if the most recent user of the FPU was cooperatively swapped out) or the thread’s own floating point context will be loaded (if the most recent user of the FPU was pre-empted, or if this thread is the first user of the FPU). Thereafter, the kernel will protect the thread’s FP context so that it is not altered during a preemptive context switch.

Warning
This routine should only be used to enable floating point support for a thread that does not currently have such support enabled already.
Return
N/A
Parameters
  • thread: ID of thread.
  • options: Registers to be preserved (K_FP_REGS or K_SSE_REGS).

void k_float_disable(k_tid_t thread)

Disable preservation of floating point context information.

This routine informs the kernel that the specified thread (which may be the current thread) will no longer be using the floating point registers.

Warning
This routine should only be used to disable floating point support for a thread that currently has such support enabled.
Return
N/A
Parameters
  • thread: ID of thread.

Ring Buffers

Ring buffers enable simple first in, first out (FIFO) queuing of variable-size data items. (See Ring Buffers.)

static void sys_ring_buf_init(struct ring_buf *buf, uint32_t size, uint32_t *data)

Initialize a ring buffer.

This routine initializes a ring buffer, prior to its first use. It is only used for ring buffers not defined using SYS_RING_BUF_DECLARE_POW2 or SYS_RING_BUF_DECLARE_SIZE.

Setting size to a power of 2 establishes a high performance ring buffer that doesn’t require the use of modulo arithmetic operations to maintain itself.

Parameters
  • buf: Address of ring buffer.
  • size: Ring buffer size (in 32-bit words).
  • data: Ring buffer data area (typically uint32_t data[size]).

static int sys_ring_buf_is_empty(struct ring_buf *buf)

Determine if a ring buffer is empty.

Return
1 if the ring buffer is empty, or 0 if not.
Parameters
  • buf: Address of ring buffer.

static int sys_ring_buf_space_get(struct ring_buf *buf)

Determine free space in a ring buffer.

Return
Ring buffer free space (in 32-bit words).
Parameters
  • buf: Address of ring buffer.

int sys_ring_buf_put(struct ring_buf *buf, uint16_t type, uint8_t value, uint32_t *data, uint8_t size32)

Write a data item to a ring buffer.

This routine writes a data item to ring buffer buf. The data item is an array of 32-bit words (from zero to 1020 bytes in length), coupled with a 16-bit type identifier and an 8-bit integer value.

Warning
Use cases involving multiple writers to the ring buffer must prevent concurrent write operations, either by preventing all writers from being preempted or by using a mutex to govern writes to the ring buffer.
Parameters
  • buf: Address of ring buffer.
  • type: Data item’s type identifier (application specific).
  • value: Data item’s integer value (application specific).
  • data: Address of data item.
  • size32: Data item size (number of 32-bit words).
Return Value
  • 0: Data item was written.
  • -EMSGSIZE: Ring buffer has insufficient free space.

int sys_ring_buf_get(struct ring_buf *buf, uint16_t *type, uint8_t *value, uint32_t *data, uint8_t *size32)

Read a data item from a ring buffer.

This routine reads a data item from ring buffer buf. The data item is an array of 32-bit words (up to 1020 bytes in length), coupled with a 16-bit type identifier and an 8-bit integer value.

Warning
Use cases involving multiple reads of the ring buffer must prevent concurrent read operations, either by preventing all readers from being preempted or by using a mutex to govern reads to the ring buffer.
Parameters
  • buf: Address of ring buffer.
  • type: Area to store the data item’s type identifier.
  • value: Area to store the data item’s integer value.
  • data: Area to store the data item.
  • size32: Size of the data item storage area (number of 32-bit chunks).
Return Value
  • 0: Data item was fetched; size32 now contains the number of 32-bit words read into data area data.
  • -EAGAIN: Ring buffer is empty.
  • -EMSGSIZE: Data area data is too small; size32 now contains the number of 32-bit words needed.

SYS_RING_BUF_DECLARE_POW2(name, pow) static uint32_t _ring_buffer_data_##name[1 << (pow)]; \ struct ring_buf name = { \ .size = (1 << (pow)), \ .mask = (1 << (pow)) - 1, \ .buf = _ring_buffer_data_##name \ };

Statically define and initialize a high performance ring buffer.

This macro establishes a ring buffer whose size must be a power of 2; that is, the ring buffer contains 2^pow 32-bit words, where pow is the specified ring buffer size exponent. A high performance ring buffer doesn’t require the use of modulo arithmetic operations to maintain itself.

The ring buffer can be accessed outside the module where it is defined using:

extern struct ring_buf <name>;

Parameters
  • name: Name of the ring buffer.
  • pow: Ring buffer size exponent.

SYS_RING_BUF_DECLARE_SIZE(name, size32) static uint32_t _ring_buffer_data_##name[size32]; \ struct ring_buf name = { \ .size = size32, \ .buf = _ring_buffer_data_##name \ };

Statically define and initialize a standard ring buffer.

This macro establishes a ring buffer of an arbitrary size. A standard ring buffer uses modulo arithmetic operations to maintain itself.

The ring buffer can be accessed outside the module where it is defined using:

extern struct ring_buf <name>;

Parameters
  • name: Name of the ring buffer.
  • size32: Size of ring buffer (in 32-bit words).

Legacy APIs

These APIs will be deprecated in an upcoming release so we recommend you avoid using them in your applications.

static k_tid_t sys_thread_self_get(void)

Return the ID of the currently executing thread.

Legacy API: Will be deprecated in Zephyr 1.9

This routine returns a pointer to the thread control block of the currently executing thread. It is cast to a nano_thread_id_t for public use.

Return
The ID of the currently executing thread.

static void sys_thread_busy_wait(uint32_t usec_to_wait)

Cause the currently executing thread to busy wait.

Legacy API: Will be deprecated in Zephyr 1.9

This routine causes the current task or fiber to execute a “do nothing” loop for a specified period of time.

Warning
This routine utilizes the system clock, so it must not be invoked until the system clock is fully operational or while interrupts are locked.
Return
N/A
Parameters
  • usec_to_wait: Number of microseconds to busy wait.

int sys_execution_context_type_get(void)

Return the type of the current execution context.

Legacy API: Will be deprecated in Zephyr 1.9

This routine returns the type of execution context currently executing.

Return
The type of the current execution context.
Return Value
  • NANO_CTX_ISR: (0): executing an interrupt service routine.
  • NANO_CTX_FIBER: (1): current thread is a fiber.
  • NANO_CTX_TASK: (2): current thread is a task.

static k_tid_t fiber_start(char *stack, unsigned stack_size, nano_fiber_entry_t entry, int arg1, int arg2, unsigned prio, unsigned options)

Initialize and start a fiber.

Legacy API: Will be deprecated in Zephyr 1.9

This routine initializes and starts a fiber. It can be called from either a fiber or a task. When this routine is called from a task, the newly created fiber will start executing immediately.

Return
nanokernel thread identifier
Parameters
  • stack: Pointer to the stack space.
  • stack_size: Stack size in bytes.
  • entry: Fiber entry.
  • arg1: 1st entry point parameter.
  • arg2: 2nd entry point parameter.
  • prio: The fiber’s priority.
  • options: Not used currently.

static k_tid_t fiber_delayed_start(char *stack, unsigned int stack_size_in_bytes, nano_fiber_entry_t entry_point, int param1, int param2, unsigned int priority, unsigned int options, int32_t timeout_in_ticks)

Start a fiber while delaying its execution.

Legacy API: Will be deprecated in Zephyr 1.9

Return
A handle potentially used to cancel the delayed start.
Parameters
  • stack: Pointer to the stack space.
  • stack_size_in_bytes: Stack size in bytes.
  • entry_point: The fiber’s entry point.
  • param1: 1st entry point parameter.
  • param2: 2nd entry point parameter.
  • priority: The fiber’s priority.
  • options: Not used currently.
  • timeout_in_ticks: Timeout duration in ticks.

static void fiber_delayed_start_cancel(k_tid_t handle)

Cancel a delayed fiber start.

Legacy API: Will be deprecated in Zephyr 1.9

Return
N/A
Parameters
  • handle: The handle returned when starting the delayed fiber.

static void fiber_yield(void)

Yield the current fiber.

Legacy API: Will be deprecated in Zephyr 1.9

Calling this routine results in the current fiber yielding to another fiber of the same or higher priority. If there are no other runnable fibers of the same or higher priority, the routine will return immediately.

This routine can only be called from a fiber.

Return
N/A

static void fiber_abort(void)

Abort the currently executing fiber.

Legacy API: Will be deprecated in Zephyr 1.9

This routine aborts the currently executing fiber. An abort can occur because of one of three reasons:

  • The fiber has explicitly aborted itself by calling this routine.
  • The fiber has implicitly aborted itself by returning from its entry point.
  • The fiber has encountered a fatal exception.

This routine can only be called from a fiber.

Return
N/A

void _legacy_sleep(int32_t ticks)
static void fiber_wakeup(k_tid_t fiber)

Wake the specified fiber from sleep.

Legacy API: Will be deprecated in Zephyr 1.9

This routine is a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Return
N/A
Parameters
  • fiber: Identifies fiber to wake

static void task_priority_set(k_tid_t task, uint32_t prio)

Set the priority of a task.

Legacy API: Will be deprecated in Zephyr 1.9

This routine changes the priority of the specified task.

The call has immediate effect. When the calling task no longer is the highest-priority runnable task, a task switch occurs.

Priority can be assigned in the range 0 to 62, where 0 is the highest priority.

Return
N/A
Parameters
  • task: Task whose priority is to be set.
  • prio: New priority.

static void task_entry_set(k_tid_t task, void (*entry)(void))

Set the entry point of a task.

Legacy API: Will be deprecated in Zephyr 1.9

This routine sets the entry point of a task to a given routine. It is needed only when an entry point differs from what is set in the project file. To have any effect, it must be called before task_start(), and it cannot work with members of the EXE group or with any group that starts automatically on application loading.

The routine is executed when the task is started.

Return
N/A
Parameters
  • task: Task to operate on.
  • entry: Entry point.

void task_abort_handler_set(void (*handler)(void))

Install an abort handler.

Legacy API: Will be deprecated in Zephyr 1.9

This routine installs an abort handler for the calling task.

The abort handler runs when the calling task is aborted by a _TaskAbort() or task_group_abort() call.

Each call to task_abort_handler_set() replaces the previously-installed handler.

To remove an abort handler, set the parameter to NULL as below: task_abort_handler_set (NULL)

Return
N/A
Parameters
  • handler: Abort handler.

int task_offload_to_fiber(int (*func)()void *argp, )

Process an “offload” request.

Legacy API: Will be deprecated in Zephyr 1.9

The routine places the func into the work queue. This allows the task to execute a routine uninterrupted by other tasks.

Note: this routine can be invoked only from a task. For the routine to work, the scheduler must be unlocked.

Return
result of func call
Parameters
  • func: function to call
  • argp: function arguments

static k_tid_t task_id_get(void)

Gets task identifier.

Legacy API: Will be deprecated in Zephyr 1.9

Return
identifier for current task

static uint32_t task_priority_get(void)

Gets task priority.

Legacy API: Will be deprecated in Zephyr 1.9

Return
priority of current task

static void task_abort(k_tid_t task)

Abort a task.

Legacy API: Will be deprecated in Zephyr 1.9

Return
N/A
Parameters
  • task: Task to abort

static void task_suspend(k_tid_t task)

Suspend a task.

Legacy API: Will be deprecated in Zephyr 1.9

Return
N/A
Parameters
  • task: Task to suspend

static void task_resume(k_tid_t task)

Resume a task.

Legacy API: Will be deprecated in Zephyr 1.9

Return
N/A
Parameters
  • task: Task to resume

void task_start(k_tid_t task)

Start a task.

Legacy API: Will be deprecated in Zephyr 1.9

Return
N/A
Parameters
  • task: Task to start

static void sys_scheduler_time_slice_set(int32_t ticks, uint32_t priority)

Set time-slicing period and scope.

Legacy API: Will be deprecated in Zephyr 1.9

This routine controls how task time slicing is performed by the task scheduler; it specifes the maximum time slice length (in ticks) and the highest priority task level for which time slicing is performed.

To enable time slicing, a non-zero time slice length must be specified. The task scheduler then ensures that no executing task runs for more than the specified number of ticks before giving other tasks of that priority a chance to execute. (However, any task whose priority is higher than the specified task priority level is exempted, and may execute as long as desired without being pre-empted due to time slicing.)

Time slicing limits only the maximum amount of time a task may continuously execute. Once the scheduler selects a task for execution, there is no minimum guaranteed time the task will execute before tasks of greater or equal priority are scheduled.

When the currently-executing task is the only one of that priority eligible for execution, this routine has no effect; the task is immediately rescheduled after the slice period expires.

To disable timeslicing, call the API with both parameters set to zero.

Return
N/A
Parameters
  • ticks: Maximum time slice length in ticks
  • priority: Highest priority task level for which time slicing is performed

void _k_thread_group_op(uint32_t groups, void (*func)(struct tcs *))
static uint32_t task_group_mask_get(void)

Get task groups for task.

Legacy API: Will be deprecated in Zephyr 1.9

Return
task groups associated with current task

static void task_group_join(uint32_t groups)

Add task to task group(s)

Legacy API: Will be deprecated in Zephyr 1.9

Return
N/A
Parameters
  • groups: Task Groups

static void task_group_leave(uint32_t groups)

Remove task from task group(s)

Legacy API: Will be deprecated in Zephyr 1.9

Return
N/A
Parameters
  • groups: Task Groups

static void task_group_start(uint32_t groups)

Start one or more task groups.

Legacy API: Will be deprecated in Zephyr 1.9

Return
N/A
Parameters
  • groups: Task groups to start

static void task_group_suspend(uint32_t groups)

Suspend one or more task groups.

Legacy API: Will be deprecated in Zephyr 1.9

Return
N/A
Parameters
  • groups: Task groups to suspend

static void task_group_resume(uint32_t groups)

Resume one or more task groups.

Legacy API: Will be deprecated in Zephyr 1.9

Return
N/A
Parameters
  • groups: Task groups to resume

static void task_group_abort(uint32_t groups)

Abort one or more task groups.

Legacy API: Will be deprecated in Zephyr 1.9

Return
N/A
Parameters
  • groups: Task groups to abort

static int task_mutex_lock(struct k_mutex *mutex, int32_t timeout)

Lock mutex.

Legacy API: Will be deprecated in Zephyr 1.9

This routine locks mutex mutex. When the mutex is locked by another task, the routine will either wait until it becomes available, or until a specified time limit is reached.

A task is permitted to lock a mutex it has already locked; in such a case, this routine immediately succeeds.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • mutex: Mutex name.
  • timeout: Determine the action to take when the mutex is already locked. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully locked mutex.
  • RC_TIME: Timed out while waiting for mutex.
  • RC_FAIL: Failed to immediately lock mutex when timeout = TICKS_NONE.

static void task_mutex_unlock(struct k_mutex *mutex)

Unlock mutex.

Legacy API: Will be deprecated in Zephyr 1.9

This routine unlocks mutex mutex. The mutex must already be locked by the requesting task.

The mutex cannot be claimed by another task until it has been unlocked by the requesting task as many times as it was locked by that task.

Return
N/A
Parameters
  • mutex: Mutex name.

static void nano_sem_init(struct k_sem *sem)

Initialize a nanokernel semaphore object.

Legacy API: Will be deprecated in Zephyr 1.9

This function initializes a nanokernel semaphore object structure. After initialization, the semaphore count is 0.

It can be called from either a fiber or task.

Return
N/A
Parameters
  • sem: Pointer to a nano_sem structure.

static void nano_sem_give(struct k_sem *sem)

Give a nanokernel semaphore.

Legacy API: Will be deprecated in Zephyr 1.9

This routine performs a “give” operation on a nanokernel sempahore object.

It is also a convenience wrapper for the execution of context-specific APIs and helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Return
N/A
Parameters
  • sem: Pointer to a nano_sem structure.

static int nano_sem_take(struct k_sem *sem, int32_t timeout_in_ticks)

Take a nanokernel semaphore, poll/pend if not available.

Legacy API: Will be deprecated in Zephyr 1.9

This routine performs a “give” operation on a nanokernel sempahore object.

It is also a convenience wrapper for the execution of context-specific APIs and is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Warning
If it is to be called from the context of an ISR, then timeout_in_ticks must be set to TICKS_NONE.
See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • sem: Pointer to a nano_sem structure.
  • timeout_in_ticks: Determines the action to take when the semaphore is unavailable. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • 1: When semaphore is available
  • 0: Otherwise

static int task_sem_take(struct k_sem *sem, int32_t timeout)

Take a semaphore or fail.

Legacy API: Will be deprecated in Zephyr 1.9

This routine takes the semaphore sem. If the semaphore’s count is zero the routine immediately returns a failure indication.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • sem: Semaphore name.
  • timeout: Determines the action to take when the semaphore is unavailable. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully took semaphore
  • RC_TIME: Timed out while waiting for semaphore
  • RC_FAIL: Failed to immediately take semaphore when timeout = TICKS_NONE

static void task_sem_reset(struct k_sem *sem)

Reset the semaphore’s count.

Legacy API: Will be deprecated in Zephyr 1.9

This routine resets the count of the semaphore sem to zero.

Return
N/A
Parameters
  • sem: Semaphore name.

static int task_sem_count_get(struct k_sem *sem)

Read a semaphore’s count.

Legacy API: Will be deprecated in Zephyr 1.9

This routine reads the current count of the semaphore sem.

Return
Semaphore count.
Parameters
  • sem: Semaphore name.

static int nano_sem_count_get(struct k_sem *sem)

Read a nanokernel semaphore’s count.

Legacy API: Will be deprecated in Zephyr 1.9

This routine reads the current count of the semaphore sem.

Return
Semaphore count.
Parameters
  • sem: Pointer to a nano_sem structure.

static void nano_work_init(struct k_work *work, k_work_handler_t handler)

Initialize work item.

Legacy API: Will be deprecated in Zephyr 1.9

Return
N/A
Parameters
  • work: Work item to initialize
  • handler: Handler to process work item

static void nano_work_submit_to_queue(struct k_work_q *wq, struct k_work *work)

Submit a work item to a workqueue.

Legacy API: Will be deprecated in Zephyr 1.9

This procedure schedules a work item to be processed. In the case where the work item has already been submitted and is pending execution, calling this function will result in a no-op. In this case, the work item must not be modified externally (e.g. by the caller of this function), since that could cause the work item to be processed in a corrupted state.

Return
N/A
Parameters
  • wq: Work queue
  • work: Work item

static void nano_workqueue_start(struct k_work_q *wq, const struct fiber_config *config)

Start a new workqueue.

Legacy API: Will be deprecated in Zephyr 1.9

This routine can be called from either fiber or task context.

Return
N/A
Parameters
  • wq: Work queue
  • config: Fiber configuration structure

static void nano_work_submit(struct k_work *work)

Submit a work item to the system workqueue.

Legacy API: Will be deprecated in Zephyr 1.9

nano_work_submit_to_queue

When using the system workqueue it is not recommended to block or yield on the handler since its fiber is shared system wide it may cause unexpected behavior.

static int task_event_handler_set(kevent_t legacy_event, kevent_handler_t handler)

Set event handler request.

Legacy API: Will be deprecated in Zephyr 1.9

This routine specifies the event handler that runs in the context of the microkernel server fiber when the associated event is signaled. Specifying a non-NULL handler installs a new handler, while specifying a NULL event handler removes the existing event handler.

A new event handler cannot be installed if one already exists for that event. The old handler must be removed first. However, the NULL event handler can be replaced with itself.

Parameters
  • legacy_event: Event upon which to register.
  • handler: Function pointer to handler.
Return Value
  • RC_FAIL: If an event handler exists or the event number is invalid.
  • RC_OK: Otherwise.

static int task_event_send(kevent_t legacy_event)

Signal an event request.

Legacy API: Will be deprecated in Zephyr 1.9

This routine signals the specified event from a task. If an event handler is installed for that event, it will run. If no event handler is installed, any task waiting on the event is released.

Parameters
  • legacy_event: Event to signal.
Return Value
  • RC_FAIL: If the event number is invalid.
  • RC_OK: Otherwise.

static int task_event_recv(kevent_t legacy_event, int32_t timeout)

Test for an event request with timeout.

Legacy API: Will be deprecated in Zephyr 1.9

This routine tests an event to see if it has been signaled.

Parameters
  • legacy_event: Event to test.
  • timeout: Determines the action to take when the event has not yet been signaled. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully received signaled event
  • RC_TIME: Timed out while waiting for signaled event
  • RC_FAIL: Failed to immediately receive signaled event when timeout = TICKS_NONE

static int task_mem_map_alloc(struct k_mem_slab *map, void **mptr, int32_t timeout)

Allocate memory map block.

Legacy API: Will be deprecated in Zephyr 1.9

This routine allocates a block from memory map map, and saves the block’s address in the area indicated by mptr. When no block is available, the routine waits until either one can be allocated, or until the specified time limit is reached.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • map: Memory map name.
  • mptr: Pointer to memory block address area.
  • timeout: Determines the action to take when the memory map is exhausted. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully allocated memory block.
  • RC_TIME: Timed out while waiting for memory block.
  • RC_FAIL: Failed to immediately allocate memory block when timeout = TICKS_NONE.

static void task_mem_map_free(struct k_mem_slab *m, void **p)

Return memory slab block.

Legacy API: Will be deprecated in Zephyr 1.9

This routine returns a block to the specified memory slab.

Return
N/A
Parameters
  • m: Memory slab name.
  • p: Memory block address.

static int task_mem_map_used_get(struct k_mem_slab *map)

Read the number of used blocks in a memory map.

Legacy API: Will be deprecated in Zephyr 1.9

This routine returns the number of blocks in use for the memory map.

Return
Number of used blocks.
Parameters
  • map: Memory map name.

static int task_mem_pool_alloc(struct k_mem_block *blockptr, struct k_mem_pool *pool_id, int reqsize, int32_t timeout)

Allocate memory pool block.

Legacy API: Will be deprecated in Zephyr 1.9

This routine allocates a block of at least reqsize bytes from memory pool pool_id, and saves its information in block descriptor blockptr. When no such block is available, the routine waits either until one can be allocated, or until the specified time limit is reached.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • blockptr: Pointer to block descriptor.
  • pool_id: Memory pool name.
  • reqsize: Requested block size, in bytes.
  • timeout: Determines the action to take when the memory pool is exhausted. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully allocated memory block
  • RC_TIME: Timed out while waiting for memory block
  • RC_FAIL: Failed to immediately allocate memory block when timeout = TICKS_NONE

static void task_mem_pool_free(struct k_mem_block *block)

Return memory pool block.

Legacy API: Will be deprecated in Zephyr 1.9

This routine returns a block to the memory pool from which it was allocated.

Return
N/A
Parameters
  • block: Pointer to block descriptor.

static void task_mem_pool_defragment(struct k_mem_pool *pool)

Defragment memory pool.

Legacy API: Will be deprecated in Zephyr 1.9

This routine concatenates unused blocks that can be merged in memory pool p.

Doing a full defragmentation of a memory pool before allocating a set of blocks may be more efficient than having the pool do an implicit partial defragmentation each time a block is allocated.

Return
N/A
Parameters
  • pool: Memory pool name.

static void *task_malloc(uint32_t size)

Allocate memory.

Legacy API: Will be deprecated in Zephyr 1.9

This routine provides traditional malloc semantics and is a wrapper on top of microkernel pool alloc API. It returns an aligned memory address which points to the start of a memory block of at least size bytes. This memory comes from heap memory pool, consequently the app should specify its intention to use a heap pool via the HEAP_SIZE keyword in MDEF file, if it uses this API. When not enough free memory is available in the heap pool, it returns NULL

Parameters
  • size: Size of memory requested by the caller.
Return Value
  • address: of the block if successful otherwise returns NULL

static void task_free(void *ptr)

Free memory allocated through task_malloc.

Legacy API: Will be deprecated in Zephyr 1.9

This routine provides traditional free semantics and is intended to free memory allocated using task_malloc API.

Return
NA
Parameters
  • ptr: pointer to be freed

static int task_fifo_put(struct k_msgq *queue, void *data, int32_t timeout)

FIFO enqueue request.

Legacy API: Will be deprecated in Zephyr 1.9

This routine adds an item to the FIFO queue. When the FIFO is full, the routine will wait either for space to become available, or until the specified time limit is reached.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • queue: FIFO queue.
  • data: Pointer to data to add to queue.
  • timeout: Determines the action to take when the FIFO is full. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully added item to FIFO.
  • RC_TIME: Timed out while waiting to add item to FIFO.
  • RC_FAIL: Failed to immediately add item to FIFO when timeout = TICKS_NONE.

static int task_fifo_get(struct k_msgq *queue, void *data, int32_t timeout)

FIFO dequeue request.

Legacy API: Will be deprecated in Zephyr 1.9

This routine fetches the oldest item from the FIFO queue. When the FIFO is found empty, the routine will wait either until an item is added to the FIFO queue or until the specified time limit is reached.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • queue: FIFO queue.
  • data: Pointer to storage location of the FIFO entry.
  • timeout: Affects the action to take when the FIFO is empty. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully fetched item from FIFO.
  • RC_TIME: Timed out while waiting to fetch item from FIFO.
  • RC_FAIL: Failed to immediately fetch item from FIFO when timeout = TICKS_NONE.

static int task_fifo_purge(struct k_msgq *queue)

Purge the FIFO of all its entries.

Legacy API: Will be deprecated in Zephyr 1.9

Return
RC_OK on purge.
Parameters
  • queue: FIFO queue.

static int task_fifo_size_get(struct k_msgq *queue)

Query the number of FIFO entries.

Legacy API: Will be deprecated in Zephyr 1.9

Return
# of FIFO entries on query.
Parameters
  • queue: FIFO queue.

int task_mbox_put(struct k_mbox *mbox, uint32_t prio, struct k_msg *msg, int32_t timeout)

Send a message to a mailbox.

Legacy API: Will be deprecated in Zephyr 1.9

This routine sends a message to a mailbox and looks for a matching receiver.

Return
RC_OK Successfully delivered message.
Return
RC_TIME Timed out while waiting to deliver message.
Return
RC_FAIL Failed to immediately deliver message when timeout = TICKS_NONE.
See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • mbox: Mailbox.
  • prio: Priority of data transfer.
  • msg: Pointer to message to send.
  • timeout: Determines the action to take when there is no waiting receiver. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.

void task_mbox_block_put(struct k_mbox *mbox, uint32_t prio, struct k_msg *msg, struct k_sem *sema)

Send a message asynchronously to a mailbox.

Legacy API: Will be deprecated in Zephyr 1.9

This routine sends a message to a mailbox and does not wait for a matching receiver. No exchange header is returned to the sender. When the data has been transferred to the receiver, the semaphore signaling is performed.

Return
N/A
Parameters
  • mbox: Mailbox to which to send message.
  • prio: Priority of data transfer.
  • msg: Pointer to message to send.
  • sema: Semaphore to signal when transfer is complete.

int task_mbox_get(struct k_mbox *mbox, struct k_msg *msg, int32_t timeout)

Get struct k_msg message header structure information from.

Legacy API: Will be deprecated in Zephyr 1.9

Return
RC_OK Successfully received message.
Return
RC_TIME Timed out while waiting to receive message.
Return
RC_FAIL Failed to immediately receive message when timeout = TICKS_NONE.
See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • mbox: Mailbox.
  • msg: Pointer to message.
  • timeout: Determines the action to take when there is no waiting receiver. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.

void task_mbox_data_get(struct k_msg *msg)

Get message data.

Legacy API: Will be deprecated in Zephyr 1.9

Call this routine for one of two reasons:

  1. To transfer data when the call to task_mbox_get() yields an existing field in the struct k_msg header structure.
  2. To wake up and release a transmitting task currently blocked from calling task_mbox_put().

Return
N/A
Parameters
  • msg: Message from which to get data.

int task_mbox_data_block_get(struct k_msg *msg, struct k_mem_block *block, struct k_mem_pool *pool_id, int32_t timeout)

Retrieve message data into a block, with time-limited waiting.

Legacy API: Will be deprecated in Zephyr 1.9

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • msg: Message from which to get data.
  • block: Block.
  • pool_id: Memory pool name.
  • timeout: Determines the action to take when no waiting sender exists. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successful retrieval of message data.
  • RC_TIME: Timed out while waiting to receive message data.
  • RC_FAIL: Failed to immediately receive message data when timeout = TICKS_NONE.

static int task_pipe_put(struct k_pipe *id, void *buffer, int bytes_to_write, int *bytes_written, K_PIPE_OPTION options, int32_t timeout)

Pipe write request.

Legacy API: Will be deprecated in Zephyr 1.9

Attempt to write data from a memory-buffer area to the specified pipe with a timeout option.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • id: Pipe ID.
  • buffer: Buffer.
  • bytes_to_write: Number of bytes to write.
  • bytes_written: Pointer to number of bytes written.
  • options: Pipe options.
  • timeout: Determines the action to take when the pipe is already full. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully wrote data to pipe.
  • RC_ALIGNMENT: Data is improperly aligned.
  • RC_INCOMPLETE: Only some of the data was written to the pipe when options = _ALL_N.
  • RC_TIME: Timed out while waiting to write to pipe.
  • RC_FAIL: Failed to immediately write to pipe when timeout = TICKS_NONE

static int task_pipe_get(struct k_pipe *id, void *buffer, int bytes_to_read, int *bytes_read, K_PIPE_OPTION options, int32_t timeout)

Pipe read request.

Legacy API: Will be deprecated in Zephyr 1.9

Attempt to read data into a memory buffer area from the specified pipe with a timeout option.

See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • id: Pipe ID.
  • buffer: Buffer.
  • bytes_to_read: Number of bytes to read.
  • bytes_read: Pointer to number of bytes read.
  • options: Pipe options.
  • timeout: Determines the action to take when the pipe is already full. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • RC_OK: Successfully read data from pipe.
  • RC_ALIGNMENT: Data is improperly aligned.
  • RC_INCOMPLETE: Only some of the data was read from the pipe when options = _ALL_N.
  • RC_TIME: Timed out waiting to read from pipe.
  • RC_FAIL: Failed to immediately read from pipe when timeout = TICKS_NONE.

static void nano_fifo_init(struct k_fifo *fifo)

Initialize a nanokernel FIFO (fifo) object.

Legacy API: Will be deprecated in Zephyr 1.9

This function initializes a nanokernel FIFO (fifo) object structure.

It can be called from either a fiber or task.

Return
N/A
Parameters
  • fifo: FIFO to initialize.

static void nano_fifo_put(struct k_fifo *fifo, void *data)

Add an element to the end of a FIFO.

Legacy API: Will be deprecated in Zephyr 1.9

This routine is a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

FIFO data items must be aligned on a 4-byte boundary, as the kernel reserves the first 32 bits of each item for use as a pointer to the next data item in the FIFO’s link list. Each data item added to the FIFO must include and reserve these first 32 bits.

Return
N/A
Parameters
  • fifo: FIFO on which to interact.
  • data: Data to send.

void nano_fifo_put_list(struct k_fifo *fifo, void *head, void *tail)
static void nano_fifo_put_slist(struct k_fifo *fifo, sys_slist_t *list)

Atomically add a list of elements to the end of a FIFO.

Legacy API: Will be deprecated in Zephyr 1.9

See nano_fifo_put_list for the description of the behaviour.

It takes a pointer to a sys_slist_t object instead of the head and tail of a custom singly-linked list. The sys_slist_t object is invalid afterwards and must be re-initialized via sys_slist_init().

This routine is a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Return
N/A
See
nano_fifo_put_list, nano_isr_fifo_put_slist, nano_fiber_fifo_put_slist, nano_task_fifo_put_slist
Parameters
  • fifo: FIFO on which to interact.
  • list: pointer to singly-linked list

void *nano_fifo_get(struct k_fifo *fifo, int32_t timeout_in_ticks)
static void nano_lifo_init(struct k_lifo *lifo)

Initialize a nanokernel linked list LIFO (lifo) object.

Legacy API: Will be deprecated in Zephyr 1.9

This function initializes a nanokernel system-level linked list LIFO (lifo) object structure.

It is called from either a fiber or task.

Return
N/A
Parameters
  • lifo: LIFO to initialize.

static void nano_lifo_put(struct k_lifo *lifo, void *data)

Prepend an element to a LIFO.

Legacy API: Will be deprecated in Zephyr 1.9

This routine adds an element to the LIFOs’ object head

This routine is a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Return
N/A
Parameters
  • lifo: LIFO on which to put.
  • data: Data to insert.

static void *nano_lifo_get(struct k_lifo *lifo, int32_t timeout_in_ticks)

Get the first element from a LIFO.

Legacy API: Will be deprecated in Zephyr 1.9

This routine is a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Warning
If it is to be called from the context of an ISR, then timeout_in_ticks must be set to TICKS_NONE.
Return
Pointer to head element in the list when available. NULL Otherwise.
See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • lifo: LIFO on which to receive.
  • timeout_in_ticks: Affects the action taken should the LIFO be empty. If TICKS_NONE, then return immediately. If TICKS_UNLIMITED, then wait as long as necesssary. Otherwise wait up to the specified number of ticks before timing out.

static void nano_stack_init(struct k_stack *stack, uint32_t *data)

Initialize a nanokernel stack object.

Legacy API: Will be deprecated in Zephyr 1.9

This function initializes a nanokernel stack object structure.

It is called from either a fiber or a task.

Return
N/A

static void nano_stack_push(struct k_stack *stack, uint32_t data)

Push data onto a stack.

Legacy API: Will be deprecated in Zephyr 1.9

This routine pushes a data item onto a stack object. It is a convenience wrapper for the execution of context-specific APIs and is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Return
N/A
Parameters
  • stack: Stack on which to interact.
  • data: Data to push on stack.

static int nano_stack_pop(struct k_stack *stack, uint32_t *data, int32_t timeout_in_ticks)

Pop data off a stack.

Legacy API: Will be deprecated in Zephyr 1.9

This routine pops the first data word from a nanokernel stack object. It is a convenience wrapper for the execution of context-specific APIs and is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

When the stack is not empty, a data word is popped and copied to the provided address data and a non-zero value is returned. When the routine finds an empty stack, zero is returned.

Parameters
  • stack: Stack on which to interact.
  • data: Container for data to pop
  • timeout_in_ticks: Determines the action to take when the FIFO is empty. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary. Otherwise, wait up to the specified number of ticks before timing out.
Return Value
  • 1: When data is popped from the stack.
  • 0: Otherwise.

int64_t sys_tick_get(void)

Return the current system tick count.

Legacy API: Will be deprecated in Zephyr 1.9

Return
The current system tick count.

uint32_t sys_tick_get_32(void)

Return the lower part of the current system tick count.

Legacy API: Will be deprecated in Zephyr 1.9

Return
The current system tick count.

int64_t sys_tick_delta(int64_t *reftime)

Return number of ticks elapsed since a reference time.

Legacy API: Will be deprecated in Zephyr 1.9

Return
The tick count since reference time; undefined for first invocation.
Parameters
  • reftime: Reference time.

uint32_t sys_tick_delta_32(int64_t *reftime)

Return 32-bit number of ticks since a reference time.

Legacy API: Will be deprecated in Zephyr 1.9

Return
A 32-bit tick count since reference time. Undefined for first invocation.
Parameters
  • reftime: Reference time.

static void nano_timer_init(struct k_timer *timer, void *data)

Initialize a nanokernel timer object.

Legacy API: Will be deprecated in Zephyr 1.9

This function initializes a nanokernel timer object structure.

It can be called from either a fiber or task.

The data passed to this function is a pointer to a data structure defined by the user. It contains data that the user wishes to store when initializing the timer and recover when the timer expires. However, the first field of this data structure must be a pointer reserved for the API’s use that can be overwritten by the API and, as such, should not contain user data.

Return
N/A
Parameters
  • timer: Timer.
  • data: User Data.

static void nano_timer_start(struct k_timer *timer, int ticks)

Start a nanokernel timer.

Legacy API: Will be deprecated in Zephyr 1.9

This routine starts a previously initialized nanokernel timer object. The timer will expire in ticks system clock ticks. It is also a convenience wrapper for the execution of context-specific APIs and is helpful when the the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Return
N/A
Parameters
  • timer: Timer.
  • ticks: Number of ticks.

void *nano_timer_test(struct k_timer *timer, int32_t timeout_in_ticks)

Wait for a nanokernel timer to expire.

Legacy API: Will be deprecated in Zephyr 1.9

This routine checks if a previously started nanokernel timer object has expired. It is also a convenience wrapper for the execution of context- specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Warning
If called from an ISR, then timeout_in_ticks must be TICKS_NONE.
See
TICKS_NONE, TICKS_UNLIMITED
Parameters
  • timer: Timer.
  • timeout_in_ticks: Determines the action to take when the timer has not expired. For TICKS_NONE, return immediately. For TICKS_UNLIMITED, wait as long as necessary.
Return Value
  • Pointer: to timer initialization data.
  • NULL: If timer not expired.

static void nano_timer_stop(struct k_timer *timer)

Stop a nanokernel timer.

Legacy API: Will be deprecated in Zephyr 1.9

This routine stops a previously started nanokernel timer object. It is also a convenience wrapper for the execution of context-specific APIs. It is helpful when the exact execution context is not known. However, it should be avoided when the context is known up-front to avoid unnecessary overhead.

Return
N/A
Parameters
  • timer: Timer to stop.

static int32_t nano_timer_ticks_remain(struct k_timer *timer)

Get nanokernel timer remaining ticks.

Legacy API: Will be deprecated in Zephyr 1.9

This function returns the remaining ticks of the previously started nanokernel timer object.

Return
remaining ticks or 0 if the timer has expired
Parameters
  • timer: Timer to query

static void nano_cpu_idle(void)

Make the CPU idle.

Legacy API: Will be deprecated in Zephyr 1.9

This function makes the CPU idle until an event wakes it up.

Return
N/A

static void nano_cpu_atomic_idle(unsigned int key)

Make the CPU idle in an atomic fashion.

Legacy API: Will be deprecated in Zephyr 1.9

Similar to k_cpu_idle(), but called with interrupts locked if operations must be done atomically before making the CPU idle.

Return
N/A
Parameters
  • key: Interrupt locking key obtained from irq_lock().

DEFINE_TASK(name, priority, entry, stack_size, groups) extern void entry(void); \ char __noinit __stack _k_thread_obj_##name[stack_size]; \ struct _static_thread_data _k_thread_data_##name __aligned(4) \ __in_section(_static_thread_data, static, name) = \ _THREAD_INITIALIZER(_k_thread_obj_##name, stack_size, \ entry, NULL, NULL, NULL, \ priority, 0, K_FOREVER, \ NULL, (uint32_t)(groups)); \ k_tid_t const name = (k_tid_t)_k_thread_obj_##name

Define a private microkernel task.

Legacy API: Will be deprecated in Zephyr 1.9

This declares and initializes a private task. The new task can be passed to the microkernel task functions.

Parameters
  • name: Name of the task.
  • priority: Priority of task.
  • entry: Entry function.
  • stack_size: Size of stack (in bytes)
  • groups: Groups this task belong to.

fiber_fiber_start fiber_start

Initialize and start a fiber from a fiber.

Legacy API: Will be deprecated in Zephyr 1.9

Like fiber_start(), but may only be called from a fiber.

See
fiber_start

task_fiber_start fiber_start

Initialize and start a fiber from a task.

Legacy API: Will be deprecated in Zephyr 1.9

Like fiber_start(), but may only be called from a task.

See
fiber_start

fiber_start_config(config, entry, arg1, arg2, options) fiber_start(config->stack, config->stack_size, \ entry, arg1, arg2, \ config->prio, options)

Start a fiber based on a fiber_config.

Legacy API: Will be deprecated in Zephyr 1.9

This routine can be called from either a fiber or a task.

Return
thread ID
Parameters
  • config: Pointer to fiber configuration structure
  • entry: Fiber entry.
  • arg1: 1st entry point parameter.
  • arg2: 2nd entry point parameter.
  • options: Not used currently.

fiber_fiber_start_config fiber_start_config

Start a fiber based on a fiber_config, from fiber context.

Legacy API: Will be deprecated in Zephyr 1.9

Like fiber_start_config(), but may only be called from a fiber.

See
fiber_start_config()

task_fiber_start_config fiber_start_config

Start a fiber based on a fiber_config, from task context.

Legacy API: Will be deprecated in Zephyr 1.9

Like fiber_start_config(), but may only be called from a task.

See
fiber_start_config()

fiber_fiber_delayed_start fiber_delayed_start

Start a fiber while delaying its execution.

Legacy API: Will be deprecated in Zephyr 1.9

Like fiber_delayed_start(), but may only be called from a fiber.

See
fiber_delayed_start

task_fiber_delayed_start fiber_delayed_start

Start a fiber while delaying its execution.

Legacy API: Will be deprecated in Zephyr 1.9

Like fiber_delayed_start(), but may only be called from a task.

See
fiber_delayed_start

fiber_fiber_delayed_start_cancel fiber_delayed_start_cancel

Cancel a delayed fiber start from a fiber.

Legacy API: Will be deprecated in Zephyr 1.9

Like fiber_delayed_start_cancel(), but may only be called from a fiber.

See
fiber_delayed_start_cancel

task_fiber_delayed_start_cancel fiber_delayed_start_cancel

Cancel a delayed fiber start from a task.

Legacy API: Will be deprecated in Zephyr 1.9

Like fiber_delayed_start_cancel(), but may only be called from a fiber.

See
fiber_delayed_start_cancel

fiber_sleep _legacy_sleep

Put the current fiber to sleep.

Legacy API: Will be deprecated in Zephyr 1.9

This routine puts the currently running fiber to sleep for the number of system ticks passed in the timeout_in_ticks parameter.

Return
N/A
Parameters
  • timeout_in_ticks: Number of system ticks the fiber sleeps.

task_sleep _legacy_sleep

Put the task to sleep.

Legacy API: Will be deprecated in Zephyr 1.9

This routine puts the currently running task to sleep for the number of system ticks passed in the timeout_in_ticks parameter.

Warning
A value of TICKS_UNLIMITED is considered invalid and may result in unexpected behavior.
Return
N/A
See
TICKS_UNLIMITED
Parameters
  • timeout_in_ticks: Number of system ticks the task sleeps.

isr_fiber_wakeup fiber_wakeup

Wake the specified fiber from sleep.

Legacy API: Will be deprecated in Zephyr 1.9

Like fiber_wakeup(), but may only be called from an ISR.

See
fiber_wakeup

fiber_fiber_wakeup fiber_wakeup

Wake the specified fiber from sleep.

Legacy API: Will be deprecated in Zephyr 1.9

Like fiber_wakeup, but may only be called from a fiber.

See
fiber_wakeup

task_fiber_wakeup fiber_wakeup

Wake the specified fiber from sleep.

Legacy API: Will be deprecated in Zephyr 1.9

Like fiber_wakeup, but may only be called from a task.

See
fiber_wakeup

task_yield fiber_yield

Yield the CPU to another task.

Legacy API: Will be deprecated in Zephyr 1.9

This routine yields the processor to the next-equal priority runnable task. With task_yield(), the effect of round-robin scheduling is possible. When no task of equal priority is runnable, no task switch occurs, and the calling task resumes execution.

Return
N/A

isr_task_group_mask_get task_group_mask_get

Get task groups for task.

Legacy API: Will be deprecated in Zephyr 1.9

Return
task groups associated with current task

isr_task_id_get task_id_get

Get task identifier.

Legacy API: Will be deprecated in Zephyr 1.9

Return
identifier for current task

isr_task_priority_get task_priority_get

Get task priority.

Legacy API: Will be deprecated in Zephyr 1.9

Return
priority of current task

kmutex_t struct k_mutex *
DEFINE_MUTEX(name) K_MUTEX_DEFINE(_k_mutex_obj_##name); \ struct k_mutex * const name = &_k_mutex_obj_##name

Define a private mutex.

Legacy API: Will be deprecated in Zephyr 1.9

Parameters
  • name: Mutex name.

nano_sem k_sem
ksem_t struct k_sem *
nano_isr_sem_give nano_sem_give

Give a nanokernel semaphore (no context switch).

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_sem_give(), but may only be called from an ISR. A fiber pending on the semaphore object will be made ready, but will NOT be scheduled to execute.

See
nano_sem_give
Parameters
  • sem: Pointer to a nano_sem structure.

nano_fiber_sem_give nano_sem_give

Give a nanokernel semaphore (no context switch).

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_sem_give(), but may only be called from a fiber.

See
nano_sem_give
Parameters
  • sem: Pointer to a nano_sem structure.

nano_task_sem_give nano_sem_give

Give a nanokernel semaphore.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_sem_give(), but may only be called from a task. A fiber pending on the semaphore object will be made ready, and will preempt the running task immediately.

See
nano_sem_give
Parameters
  • sem: Pointer to a nano_sem structure.

nano_isr_sem_take nano_sem_take

Take a nanokernel semaphore, fail if unavailable.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_sem_take(), but must only be called from an ISR with a timeout of TICKS_NONE.

See
nano_sem_take

nano_fiber_sem_take nano_sem_take

Take a nanokernel semaphore, wait or fail if unavailable.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_sem_take(), but may only be called from a fiber.

See
nano_sem_take

nano_task_sem_take nano_sem_take

Take a nanokernel semaphore, fail if unavailable.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_sem_take(), but may only be called from a task.

See
nano_sem_take

isr_sem_give nano_sem_give

Give semaphore from an ISR.

Legacy API: Will be deprecated in Zephyr 1.9

This routine gives semaphore sem from an ISR, rather than a task.

Return
N/A
Parameters
  • sem: Semaphore name.

fiber_sem_give nano_sem_give

Give semaphore from a fiber.

Legacy API: Will be deprecated in Zephyr 1.9

This routine gives semaphore sem from a fiber, rather than a task.

Return
N/A
Parameters
  • sem: Semaphore name.

task_sem_give nano_sem_give

Give semaphore.

Legacy API: Will be deprecated in Zephyr 1.9

This routine gives semaphore sem.

Return
N/A
Parameters
  • sem: Semaphore name.

DEFINE_SEMAPHORE(name) K_SEM_DEFINE(_k_sem_obj_##name, 0, UINT_MAX); \ struct k_sem * const name = &_k_sem_obj_##name

Define a private microkernel semaphore.

Legacy API: Will be deprecated in Zephyr 1.9

Parameters
  • name: Semaphore name.

nano_work k_work
work_handler_t k_work_handler_t
nano_workqueue k_work_q

A workqueue is a fiber that executes nano_work items that are queued to it. This is useful for drivers which need to schedule execution of code which might sleep from ISR context. The actual fiber identifier is not stored in the structure in order to save space.

nano_delayed_work k_delayed_work

An item which can be scheduled on a nano_workqueue with a delay.

Legacy API: Will be deprecated in Zephyr 1.9

nano_task_workqueue_start nano_workqueue_start

Start a new workqueue.

Legacy API: Will be deprecated in Zephyr 1.9

Call this from task context.

See
nano_workqueue_start

nano_fiber_workqueue_start nano_workqueue_start

Start a new workqueue.

Legacy API: Will be deprecated in Zephyr 1.9

Call this from fiber context.

See
nano_workqueue_start

isr_event_send task_event_send

Signal an event from an ISR.

Legacy API: Will be deprecated in Zephyr 1.9

This routine does not validate the specified event number.

Return
N/A
Parameters
  • event: Event to signal.

fiber_event_send task_event_send

Signal an event from a fiber.

Legacy API: Will be deprecated in Zephyr 1.9

This routine does not validate the specified event number.

Return
N/A
Parameters
  • event: Event to signal.

DEFINE_EVENT(name, event_handler) K_ALERT_DEFINE(_k_event_obj_##name, event_handler, 1); \ struct k_alert * const name = &(_k_event_obj_##name)

Define a private microkernel event.

Legacy API: Will be deprecated in Zephyr 1.9

This declares and initializes a private event. The new event can be passed to the microkernel event functions.

Parameters
  • name: Name of the event
  • event_handler: Function to handle the event (can be NULL)

kmemory_map_t struct k_mem_slab *
DEFINE_MEM_MAP(name, map_num_blocks, map_block_size) K_MEM_SLAB_DEFINE(_k_mem_map_obj_##name, map_block_size, \ map_num_blocks, 4); \ struct k_mem_slab *const name = &_k_mem_map_obj_##name

Define a private microkernel memory map.

Legacy API: Will be deprecated in Zephyr 1.9

Parameters
  • name: Memory map name.
  • map_num_blocks: Number of blocks.
  • map_block_size: Size of each block, in bytes.

k_block k_mem_block
kmemory_pool_t struct k_mem_pool *
pool_struct k_mem_pool
kfifo_t struct k_msgq *
DEFINE_FIFO(name, q_depth, q_width) K_MSGQ_DEFINE(_k_fifo_obj_##name, q_width, q_depth, 4); \ struct k_msgq * const name = &_k_fifo_obj_##name

Define a private microkernel FIFO.

Legacy API: Will be deprecated in Zephyr 1.9

This declares and initializes a private FIFO. The new FIFO can be passed to the microkernel FIFO functions.

Parameters
  • name: Name of the FIFO.
  • q_depth: Depth of the FIFO.
  • q_width: Width of the FIFO.

kmbox_t struct k_mbox *
DEFINE_MAILBOX(name) K_MBOX_DEFINE(_k_mbox_obj_##name); \ struct k_mbox * const name = &_k_mbox_obj_##name

Define a private microkernel mailbox.

Legacy API: Will be deprecated in Zephyr 1.9

This routine declares and initializes a private mailbox. The new mailbox can be passed to the microkernel mailbox functions.

Parameters
  • name: Name of the mailbox

kpipe_t struct k_pipe *
DEFINE_PIPE(name, pipe_buffer_size) K_PIPE_DEFINE(_k_pipe_obj_##name, pipe_buffer_size, 4); \ struct k_pipe * const name = &_k_pipe_obj_##name

Define a private microkernel pipe.

Legacy API: Will be deprecated in Zephyr 1.9

Parameters
  • name: Name of the pipe.
  • pipe_buffer_size: Size of the pipe buffer (in bytes)

nano_fifo k_fifo
nano_isr_fifo_put nano_fifo_put

Add an element to the end of a FIFO from an ISR context.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_fifo_put(), but may only be called from an ISR.

See
nano_fifo_put

nano_fiber_fifo_put nano_fifo_put

Add an element to the end of a FIFO from a fiber.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_fifo_put(), but may only be called from a fiber.

See
nano_fifo_put

nano_task_fifo_put nano_fifo_put

Add an element to the end of a FIFO.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_fifo_put(), but may only be called from a task.

See
nano_fifo_put

nano_isr_fifo_put_list nano_fifo_put_list

Atomically add a list of elements to the end of a FIFO from an ISR.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_fifo_put_list(), but may only be called from an ISR.

See
nano_fifo_put_list

nano_fiber_fifo_put_list nano_fifo_put_list

Atomically add a list of elements to the end of a FIFO from a fiber.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_fifo_put_list(), but may only be called from a fiber.

See
nano_fifo_put_list

nano_task_fifo_put_list nano_fifo_put_list

Atomically add a list of elements to the end of a FIFO from a fiber.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_fifo_put_list(), but may only be called from a task.

See
nano_fifo_put_list

nano_isr_fifo_put_slist nano_fifo_put_slist

Atomically add a list of elements to the end of a FIFO from an ISR.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_fifo_put_slist(), but may only be called from an ISR.

See
nano_fifo_put_slist

nano_fiber_fifo_put_slist nano_fifo_put_slist

Atomically add a list of elements to the end of a FIFO from a fiber.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_fifo_put_slist(), but may only be called from a fiber.

See
nano_fifo_put_slist

nano_task_fifo_put_slist nano_fifo_put_slist

Atomically add a list of elements to the end of a FIFO from a fiber.

Like nano_fifo_put_slist(), but may only be called from a fiber.

See
nano_fifo_put_slist

nano_isr_fifo_get nano_fifo_get

Get an element from the head of a FIFO from an ISR context.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_fifo_get(), but may only be called from an ISR with a timeout of TICKS_NONE.

See
nano_fifo_get

nano_fiber_fifo_get nano_fifo_get

Get an element from the head of a FIFO from a fiber.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_fifo_get(), but may only be called from a fiber.

See
nano_fifo_get

nano_task_fifo_get nano_fifo_get

Get an element from a FIFO’s head that comes from a task, poll if empty.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_fifo_get(), but may only be called from a task.

See
nano_fifo_get

nano_lifo k_lifo
nano_isr_lifo_put nano_lifo_put

Prepend an element to a LIFO without a context switch.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_lifo_put(), but may only be called from an ISR. A fiber pending on the LIFO object will be made ready, but will NOT be scheduled to execute.

See
nano_lifo_put

nano_fiber_lifo_put nano_lifo_put

Prepend an element to a LIFO without a context switch.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_lifo_put(), but may only be called from a fiber. A fiber pending on the LIFO object will be made ready, but will NOT be scheduled to execute.

See
nano_lifo_put

nano_task_lifo_put nano_lifo_put

Add an element to the LIFO’s linked list head.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_lifo_put(), but may only be called from a task. A fiber pending on the LIFO object will be made ready, and will preempty the running task immediately.

See
nano_lifo_put

nano_isr_lifo_get nano_lifo_get

Remove the first element from a LIFO linked list.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_lifo_get(), but may only be called from an ISR with a timeout of TICKS_NONE.

See
nano_lifo_get

nano_fiber_lifo_get nano_lifo_get

Prepend an element to a LIFO without a context switch.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_lifo_get(), but may only be called from a fiber.

See
nano_lifo_get

nano_task_lifo_get nano_lifo_get

Remove the first element from a LIFO linked list.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_lifo_get(), but may only be called from a task.

See
nano_lifo_get

nano_stack k_stack
nano_isr_stack_push nano_stack_push

Push data onto a stack (no context switch).

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_stack_push(), but may only be called from an ISR. A fiber that pends on the stack object becomes ready but will NOT be scheduled to execute.

See
nano_stack_push

nano_fiber_stack_push nano_stack_push

Push data onto a stack (no context switch).

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_stack_push(), but may only be called from a fiber. A fiber that pends on the stack object becomes ready but will NOT be scheduled to execute.

See
nano_stack_push

nano_task_stack_push nano_stack_push

Push data onto a nanokernel stack.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_stack_push(), but may only be called from a task. A fiber that pends on the stack object becomes ready and preempts the running task immediately.

See
nano_stack_push

nano_isr_stack_pop nano_stack_pop

Pop data from a nanokernel stack.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_stack_pop(), but may only be called from an ISR.

See
nano_stack_pop

nano_fiber_stack_pop nano_stack_pop

Pop data from a nanokernel stack.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_stack_pop(), but may only be called from a fiber.

See
nano_stack_pop

nano_task_stack_pop nano_stack_pop

Pop data from a nanokernel stack.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_stack_pop(), but may only be called from a task.

See
nano_stack_pop

sys_cycle_get_32 k_cycle_get_32

Return a time stamp in high-resolution format.

Legacy API: Will be deprecated in Zephyr 1.9

This routine reads the counter register on the processor’s high precision timer device. This counter register increments at a relatively high rate (e.g. 20 MHz), and is thus considered a high-resolution timer. This is in contrast to sys_tick_get_32() which returns the value of the system ticks variable.

Return
The current high-precision clock value.

nano_timer k_timer
nano_isr_timer_start nano_timer_start

Start a nanokernel timer from an ISR.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_timer_start(), but may only be called from an ISR with a timeout of TICKS_NONE.

See
nano_timer_start

nano_fiber_timer_start nano_timer_start

Start a nanokernel timer from a fiber.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_timer_start(), but may only be called from a fiber.

See
nano_timer_start

nano_task_timer_start nano_timer_start

Start a nanokernel timer from a task.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_timer_start(), but may only be called from a task.

See
nano_timer_start

nano_isr_timer_test nano_timer_test

Make the current ISR check for a timer expiry.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_timer_test(), but may only be called from an ISR with a timeout of TICKS_NONE.

See
nano_timer_test

nano_fiber_timer_test nano_timer_test

Make the current fiber check for a timer expiry.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_timer_test(), but may only be called from a fiber.

See
nano_timer_test

nano_task_timer_test nano_timer_test

Make the current task check for a timer expiry.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_timer_test(), but may only be called from a task.

See
nano_timer_test

task_timer_stop nano_timer_stop

Stop a timer.

Legacy API: Will be deprecated in Zephyr 1.9

This routine stops the specified timer. If the timer period has already elapsed, the call has no effect.

Return
N/A
Parameters
  • timer: Timer to stop.

nano_isr_timer_stop nano_timer_stop

Stop a nanokernel timer from an ISR.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_timer_stop(), but may only be called from an ISR.

See
nano_timer_stop

nano_fiber_timer_stop nano_timer_stop

Stop a nanokernel timer.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_timer_stop(), but may only be called from a fiber.

See
nano_timer_stop

nano_task_timer_stop nano_timer_stop

Stop a nanokernel timer from a task.

Legacy API: Will be deprecated in Zephyr 1.9

Like nano_timer_stop(), but may only be called from a task.

See
nano_timer_stop

struct fiber_config
#include <legacy.h>

Fiber configuration structure.

Legacy API: Will be deprecated in Zephyr 1.9

Parameters such as stack size and fiber priority are often user configurable. This structure makes it simple to specify such a configuration.

union

internal use only

Public Members

for 2-steps data transfer operation

semaphore to signal when asynchr. call