Data Structures
struct	k_thread

Macros
#define	K_ESSENTIAL (BIT(0))
	system thread that must not abort More...

#define	K_FP_REGS (BIT(1))
	FPU registers are managed by context switch. More...

#define	K_USER (BIT(2))
	user mode thread More...

#define	K_INHERIT_PERMS (BIT(3))
	Inherit Permissions. More...

#define	K_CALLBACK_STATE (BIT(4))
	Callback item state. More...

#define	k_thread_access_grant(thread, ...) FOR_EACH_FIXED_ARG(k_object_access_grant, (;), thread, __VA_ARGS__)
	Grant a thread access to a set of kernel objects. More...

#define	K_THREAD_DEFINE(name, stack_size, entry, p1, p2, p3, prio, options, delay)
	Statically define and initialize a thread. More...

Typedefs
typedef void(*	k_thread_user_cb_t) (const struct k_thread thread, void user_data)

Functions
void	k_thread_foreach (k_thread_user_cb_t user_cb, void *user_data)
	Iterate over all the threads in the system. More...

void	k_thread_foreach_unlocked (k_thread_user_cb_t user_cb, void *user_data)
	Iterate over all the threads in the system without locking. More...

k_tid_t	k_thread_create (struct k_thread new_thread, k_thread_stack_t stack, size_t stack_size, k_thread_entry_t entry, void p1, void p2, void *p3, int prio, uint32_t options, k_timeout_t delay)
	Create a thread. More...

FUNC_NORETURN void	k_thread_user_mode_enter (k_thread_entry_t entry, void p1, void p2, void *p3)
	Drop a thread's privileges permanently to user mode. More...

static void	k_thread_heap_assign (struct k_thread thread, struct k_heap heap)
	Assign a resource memory pool to a thread. More...

void	k_thread_system_pool_assign (struct k_thread *thread)
	Assign the system heap as a thread's resource pool. More...

int	k_thread_join (struct k_thread *thread, k_timeout_t timeout)
	Sleep until a thread exits. More...

int32_t	k_sleep (k_timeout_t timeout)
	Put the current thread to sleep. More...

static int32_t	k_msleep (int32_t ms)
	Put the current thread to sleep. More...

int32_t	k_usleep (int32_t us)
	Put the current thread to sleep with microsecond resolution. More...

void	k_busy_wait (uint32_t usec_to_wait)
	Cause the current thread to busy wait. More...

void	k_yield (void)
	Yield the current thread. More...

void	k_wakeup (k_tid_t thread)
	Wake up a sleeping thread. More...

static __attribute_const__ k_tid_t	k_current_get (void)
	Get thread ID of the current thread. More...

void	k_thread_abort (k_tid_t thread)
	Abort a thread. More...

void	k_thread_start (k_tid_t thread)
	Start an inactive thread. More...

k_ticks_t	k_thread_timeout_expires_ticks (const struct k_thread *t)
	Get time when a thread wakes up, in system ticks. More...

k_ticks_t	k_thread_timeout_remaining_ticks (const struct k_thread *t)
	Get time remaining before a thread wakes up, in system ticks. More...

int	k_thread_priority_get (k_tid_t thread)
	Get a thread's priority. More...

void	k_thread_priority_set (k_tid_t thread, int prio)
	Set a thread's priority. More...

void	k_thread_deadline_set (k_tid_t thread, int deadline)
	Set deadline expiration time for scheduler. More...

int	k_thread_cpu_mask_clear (k_tid_t thread)
	Sets all CPU enable masks to zero. More...

int	k_thread_cpu_mask_enable_all (k_tid_t thread)
	Sets all CPU enable masks to one. More...

int	k_thread_cpu_mask_enable (k_tid_t thread, int cpu)
	Enable thread to run on specified CPU. More...

int	k_thread_cpu_mask_disable (k_tid_t thread, int cpu)
	Prevent thread to run on specified CPU. More...

void	k_thread_suspend (k_tid_t thread)
	Suspend a thread. More...

void	k_thread_resume (k_tid_t thread)
	Resume a suspended thread. More...

void	k_sched_time_slice_set (int32_t slice, int prio)
	Set time-slicing period and scope. More...

void	k_sched_lock (void)
	Lock the scheduler. More...

void	k_sched_unlock (void)
	Unlock the scheduler. More...

void	k_thread_custom_data_set (void *value)
	Set current thread's custom data. More...

void *	k_thread_custom_data_get (void)
	Get current thread's custom data. More...

int	k_thread_name_set (k_tid_t thread, const char *str)
	Set current thread name. More...

const char *	k_thread_name_get (k_tid_t thread)
	Get thread name. More...

int	k_thread_name_copy (k_tid_t thread, char *buf, size_t size)
	Copy the thread name into a supplied buffer. More...

const char *	k_thread_state_str (k_tid_t thread_id)
	Get thread state string. More...

Detailed Description

Macro Definition Documentation

◆ K_CALLBACK_STATE

#define K_CALLBACK_STATE (BIT(4))

#include <include/kernel.h>

Callback item state.

This is a single bit of state reserved for "callback manager" utilities (p4wq initially) who need to track operations invoked from within a user-provided callback they have been invoked. Effectively it serves as a tiny bit of zero-overhead TLS data.

◆ K_ESSENTIAL

#define K_ESSENTIAL (BIT(0))

#include <include/kernel.h>

system thread that must not abort

◆ K_FP_REGS

#define K_FP_REGS (BIT(1))

#include <include/kernel.h>

FPU registers are managed by context switch.

This option indicates that the thread uses the CPU's floating point registers. This instructs the kernel to take additional steps to save and restore the contents of these registers when scheduling the thread. No effect if

embed:rst:inline :kconfig:`CONFIG_FPU_SHARING`

is not enabled.

◆ K_INHERIT_PERMS

#define K_INHERIT_PERMS (BIT(3))

#include <include/kernel.h>

Inherit Permissions.

Indicates that the thread being created should inherit all kernel object permissions from the thread that created it. No effect if

embed:rst:inline :kconfig:`CONFIG_USERSPACE`

is not enabled.

◆ k_thread_access_grant

#define k_thread_access_grant	(	thread,
		...
	)	FOR_EACH_FIXED_ARG(k_object_access_grant, (;), thread, __VA_ARGS__)

#include <include/kernel.h>

Grant a thread access to a set of kernel objects.

This is a convenience function. For the provided thread, grant access to the remaining arguments, which must be pointers to kernel objects.

The thread object must be initialized (i.e. running). The objects don't need to be. Note that NULL shouldn't be passed as an argument.

Parameters

thread	Thread to grant access to objects
...	list of kernel object pointers

◆ K_THREAD_DEFINE

#define K_THREAD_DEFINE	(	name,
		stack_size,
		entry,
		p1,
		p2,
		p3,
		prio,
		options,
		delay
	)

#include <include/kernel.h>

Value:

        K_THREAD_STACK_DEFINE(_k_thread_stack_##name, stack_size);       \
        struct k_thread _k_thread_obj_##name;                            \
        STRUCT_SECTION_ITERABLE(_static_thread_data, _k_thread_data_##name) = \
                Z_THREAD_INITIALIZER(&_k_thread_obj_##name,              \
                                    _k_thread_stack_##name, stack_size,  \
                                entry, p1, p2, p3, prio, options, delay, \
                                NULL, name);                                     \
        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), zero for no delay.

◆ K_USER

#define K_USER (BIT(2))

#include <include/kernel.h>

user mode thread

This thread has dropped from supervisor mode to user mode and consequently has additional restrictions

Typedef Documentation

◆ k_thread_user_cb_t

typedef void(* k_thread_user_cb_t) (const struct k_thread *thread, void *user_data)

#include <include/kernel.h>

Function Documentation

◆ k_busy_wait()

void k_busy_wait ( uint32_t usec_to_wait )

#include <include/kernel.h>

Cause the current thread to busy wait.

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

Note: The clock used for the microsecond-resolution delay here may be skewed relative to the clock used for system timeouts like k_sleep(). For example k_busy_wait(1000) may take slightly more or less time than k_sleep(K_MSEC(1)), with the offset dependent on clock tolerances.

Returns: N/A

◆ k_current_get()

static __attribute_const__ k_tid_t k_current_get ( void )

inlinestatic

#include <include/kernel.h>

Get thread ID of the current thread.

Returns: ID of current thread.

◆ k_msleep()

static int32_t k_msleep ( int32_t ms )

inlinestatic

#include <include/kernel.h>

Put the current thread to sleep.

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

Parameters

ms	Number of milliseconds to sleep.

Returns: Zero if the requested time has elapsed or the number of milliseconds left to sleep, if thread was woken up by k_wakeup call.

◆ k_sched_lock()

void k_sched_lock ( void )

#include <include/kernel.h>

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

Returns: N/A

◆ k_sched_time_slice_set()

void k_sched_time_slice_set	(	int32_t	slice,
		int	prio
	)

#include <include/kernel.h>

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

Parameters

slice	Maximum time slice length (in milliseconds).
prio	Highest thread priority level eligible for time slicing.

Returns: N/A

◆ k_sched_unlock()

void k_sched_unlock ( void )

#include <include/kernel.h>

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.

Returns: N/A

◆ k_sleep()

int32_t k_sleep ( k_timeout_t timeout )

#include <include/kernel.h>

Put the current thread to sleep.

This routine puts the current thread to sleep for duration, specified as a k_timeout_t object.

Note: if timeout is set to K_FOREVER then the thread is suspended.

Parameters

timeout Desired duration of sleep.

Returns: Zero if the requested time has elapsed or the number of milliseconds left to sleep, if thread was woken up by k_wakeup call.

◆ k_thread_abort()

void k_thread_abort ( k_tid_t thread )

#include <include/kernel.h>

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.

After k_thread_abort() returns, the thread is guaranteed not to be running or to become runnable anywhere on the system. Normally this is done via blocking the caller (in the same manner as k_thread_join()), but in interrupt context on SMP systems the implementation is required to spin for threads that are running on other CPUs. Note that as specified, this means that on SMP platforms it is possible for application code to create a deadlock condition by simultaneously aborting a cycle of threads using at least one termination from interrupt context. Zephyr cannot detect all such conditions.

Parameters

thread ID of thread to abort.

Returns: N/A

◆ k_thread_cpu_mask_clear()

int k_thread_cpu_mask_clear ( k_tid_t thread )

#include <include/kernel.h>

Sets all CPU enable masks to zero.

After this returns, the thread will no longer be schedulable on any CPUs. The thread must not be currently runnable.

Note

You should enable

embed:rst:inline :kconfig:`CONFIG_SCHED_DEADLINE`

in your project configuration.

Parameters

thread Thread to operate upon

Returns: Zero on success, otherwise error code

◆ k_thread_cpu_mask_disable()

int k_thread_cpu_mask_disable	(	k_tid_t	thread,
		int	cpu
	)

#include <include/kernel.h>

Prevent thread to run on specified CPU.

The thread must not be currently runnable.

Note

You should enable

embed:rst:inline :kconfig:`CONFIG_SCHED_DEADLINE`

in your project configuration.

Parameters

thread	Thread to operate upon
cpu	CPU index

Returns: Zero on success, otherwise error code

◆ k_thread_cpu_mask_enable()

int k_thread_cpu_mask_enable	(	k_tid_t	thread,
		int	cpu
	)

#include <include/kernel.h>

Enable thread to run on specified CPU.

The thread must not be currently runnable.

Note

You should enable

embed:rst:inline :kconfig:`CONFIG_SCHED_DEADLINE`

in your project configuration.

Parameters

thread	Thread to operate upon
cpu	CPU index

Returns: Zero on success, otherwise error code

◆ k_thread_cpu_mask_enable_all()

int k_thread_cpu_mask_enable_all ( k_tid_t thread )

#include <include/kernel.h>

Sets all CPU enable masks to one.

After this returns, the thread will be schedulable on any CPU. The thread must not be currently runnable.

Note

You should enable

embed:rst:inline :kconfig:`CONFIG_SCHED_DEADLINE`

in your project configuration.

Parameters

thread Thread to operate upon

Returns: Zero on success, otherwise error code

◆ k_thread_create()

k_tid_t k_thread_create	(	struct k_thread *	new_thread,
		k_thread_stack_t *	stack,
		size_t	stack_size,
		k_thread_entry_t	entry,
		void *	p1,
		void *	p2,
		void *	p3,
		int	prio,
		uint32_t	options,
		k_timeout_t	delay
	)

#include <include/kernel.h>

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

Stack objects passed to this function must be originally defined with either of these macros in order to be portable:

K_THREAD_STACK_DEFINE() - For stacks that may support either user or supervisor threads.
K_KERNEL_STACK_DEFINE() - For stacks that may support supervisor threads only. These stacks use less memory if CONFIG_USERSPACE is enabled.

The stack_size parameter has constraints. It must either be:

The original size value passed to K_THREAD_STACK_DEFINE() or K_KERNEL_STACK_DEFINE()
The return value of K_THREAD_STACK_SIZEOF(stack) if the stack was defined with K_THREAD_STACK_DEFINE()
The return value of K_KERNEL_STACK_SIZEOF(stack) if the stack was defined with K_KERNEL_STACK_DEFINE().

Using other values, or sizeof(stack) may produce undefined behavior.

Parameters

new_thread	Pointer to uninitialized struct k_thread
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, or K_NO_WAIT (for no delay).

Returns: ID of new thread.

◆ k_thread_custom_data_get()

void * k_thread_custom_data_get ( void )

#include <include/kernel.h>

Get current thread's custom data.

This routine returns the custom data for the current thread.

Returns: Current custom data value.

◆ k_thread_custom_data_set()

void k_thread_custom_data_set ( void * value )

#include <include/kernel.h>

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.

Parameters

value New custom data value.

Returns: N/A

◆ k_thread_deadline_set()

void k_thread_deadline_set	(	k_tid_t	thread,
		int	deadline
	)

#include <include/kernel.h>

Set deadline expiration time for scheduler.

This sets the "deadline" expiration as a time delta from the current time, in the same units used by k_cycle_get_32(). The scheduler (when deadline scheduling is enabled) will choose the next expiring thread when selecting between threads at the same static priority. Threads at different priorities will be scheduled according to their static priority.

Note

Deadlines are stored internally using 32 bit unsigned integers. The number of cycles between the "first" deadline in the scheduler queue and the "last" deadline must be less than 2^31 (i.e a signed non-negative quantity). Failure to adhere to this rule may result in scheduled threads running in an incorrect dealine order.

Despite the API naming, the scheduler makes no guarantees the the thread WILL be scheduled within that deadline, nor does it take extra metadata (like e.g. the "runtime" and "period" parameters in Linux sched_setattr()) that allows the kernel to validate the scheduling for achievability. Such features could be implemented above this call, which is simply input to the priority selection logic.

You should enable

embed:rst:inline :kconfig:`CONFIG_SCHED_DEADLINE`

in your project configuration.

Parameters

thread	A thread on which to set the deadline
deadline	A time delta, in cycle units

◆ k_thread_foreach()

void k_thread_foreach	(	k_thread_user_cb_t	user_cb,
		void *	user_data
	)

#include <include/kernel.h>

Iterate over all the threads in the system.

This routine iterates over all the threads in the system and calls the user_cb function for each thread.

Parameters

user_cb	Pointer to the user callback function.
user_data	Pointer to user data.

Note

embed:rst:inline :kconfig:`CONFIG_THREAD_MONITOR`

must be set for this function to be effective.

This API uses k_spin_lock to protect the _kernel.threads list which means creation of new threads and terminations of existing threads are blocked until this API returns.

Returns: N/A

◆ k_thread_foreach_unlocked()

void k_thread_foreach_unlocked	(	k_thread_user_cb_t	user_cb,
		void *	user_data
	)

#include <include/kernel.h>

Iterate over all the threads in the system without locking.

This routine works exactly the same like k_thread_foreach but unlocks interrupts when user_cb is executed.

Parameters

user_cb	Pointer to the user callback function.
user_data	Pointer to user data.

Note

embed:rst:inline :kconfig:`CONFIG_THREAD_MONITOR`

must be set for this function to be effective.

This API uses k_spin_lock only when accessing the _kernel.threads queue elements. It unlocks it during user callback function processing. If a new task is created when this foreach function is in progress, the added new task would not be included in the enumeration. If a task is aborted during this enumeration, there would be a race here and there is a possibility that this aborted task would be included in the enumeration.

If the task is aborted and the memory occupied by its k_thread structure is reused when this k_thread_foreach_unlocked is in progress it might even lead to the system behave unstable. This function may never return, as it would follow some next task pointers treating given pointer as a pointer to the k_thread structure while it is something different right now. Do not reuse the memory that was occupied by k_thread structure of aborted task if it was aborted after this function was called in any context.

◆ k_thread_heap_assign()

static void k_thread_heap_assign	(	struct k_thread *	thread,
		struct k_heap *	heap
	)

inlinestatic

#include <include/kernel.h>

Assign a resource memory pool to a thread.

By default, threads have no resource pool assigned unless their parent thread has a resource pool, in which case it is inherited. Multiple threads may be assigned to the same memory pool.

Changing a thread's resource pool will not migrate allocations from the previous pool.

Parameters

thread	Target thread to assign a memory pool for resource requests.
heap	Heap object to use for resources, or NULL if the thread should no longer have a memory pool.

◆ k_thread_join()

int k_thread_join	(	struct k_thread *	thread,
		k_timeout_t	timeout
	)

#include <include/kernel.h>

Sleep until a thread exits.

The caller will be put to sleep until the target thread exits, either due to being aborted, self-exiting, or taking a fatal error. This API returns immediately if the thread isn't running.

This API may only be called from ISRs with a K_NO_WAIT timeout, where it can be useful as a predicate to detect when a thread has aborted.

Parameters

thread	Thread to wait to exit
timeout	upper bound time to wait for the thread to exit.

Return values

0	success, target thread has exited or wasn't running
-EBUSY	returned without waiting
-EAGAIN	waiting period timed out
-EDEADLK	target thread is joining on the caller, or target thread is the caller

◆ k_thread_name_copy()

int k_thread_name_copy	(	k_tid_t	thread,
		char *	buf,
		size_t	size
	)

#include <include/kernel.h>

Copy the thread name into a supplied buffer.

Parameters

thread	Thread to obtain name information
buf	Destination buffer
size	Destination buffer size

Return values

-ENOSPC	Destination buffer too small
-EFAULT	Memory access error
-ENOSYS	Thread name feature not enabled
0	Success

◆ k_thread_name_get()

const char * k_thread_name_get ( k_tid_t thread )

#include <include/kernel.h>

Get thread name.

Get the name of a thread

Parameters

thread Thread ID

Return values

Thread name, or NULL if configuration not enabled

◆ k_thread_name_set()

int k_thread_name_set	(	k_tid_t	thread,
		const char *	str
	)

#include <include/kernel.h>

Set current thread name.

Set the name of the thread to be used when

embed:rst:inline :kconfig:`CONFIG_THREAD_MONITOR`

is enabled for tracing and debugging.

Parameters

thread	Thread to set name, or NULL to set the current thread
str	Name string

Return values

0	on success
-EFAULT	Memory access error with supplied string
-ENOSYS	Thread name configuration option not enabled
-EINVAL	Thread name too long

◆ k_thread_priority_get()

int k_thread_priority_get ( k_tid_t thread )

#include <include/kernel.h>

Get a thread's priority.

This routine gets the priority of thread.

Parameters

thread ID of thread whose priority is needed.

Returns: Priority of thread.

◆ k_thread_priority_set()

void k_thread_priority_set	(	k_tid_t	thread,
		int	prio
	)

#include <include/kernel.h>

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.

Parameters

thread	ID of thread whose priority is to be set.
prio	New priority.

Warning: Changing the priority of a thread currently involved in mutex priority inheritance may result in undefined behavior.

Returns: N/A

◆ k_thread_resume()

void k_thread_resume ( k_tid_t thread )

#include <include/kernel.h>

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.

Parameters

thread ID of thread to resume.

Returns: N/A

◆ k_thread_start()

void k_thread_start ( k_tid_t thread )

#include <include/kernel.h>

Start an inactive thread.

If a thread was created with K_FOREVER in the delay parameter, it will not be added to the scheduling queue until this function is called on it.

Parameters

thread thread to start

◆ k_thread_state_str()

const char * k_thread_state_str ( k_tid_t thread_id )

#include <include/kernel.h>

Get thread state string.

Get the human friendly thread state string

Parameters

thread_id Thread ID

Return values

Thread state string, empty if no state flag is set

◆ k_thread_suspend()

void k_thread_suspend ( k_tid_t thread )

#include <include/kernel.h>

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, kernel objects it is waiting on are still handed to it. Note that any existing timeouts (e.g. k_sleep(), or a timeout argument to k_sem_take() et. al.) will be canceled. On resume, the thread will begin running immediately and return from the blocked call.

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

Parameters

thread ID of thread to suspend.

Returns: N/A

◆ k_thread_system_pool_assign()

void k_thread_system_pool_assign ( struct k_thread * thread )

#include <include/kernel.h>

Assign the system heap as a thread's resource pool.

Similar to z_thread_heap_assign(), but the thread will use the kernel heap to draw memory.

Use with caution, as a malicious thread could perform DoS attacks on the kernel heap.

Parameters

thread Target thread to assign the system heap for resource requests

◆ k_thread_timeout_expires_ticks()

k_ticks_t k_thread_timeout_expires_ticks ( const struct k_thread * t )

#include <include/kernel.h>

Get time when a thread wakes up, in system ticks.

This routine computes the system uptime when a waiting thread next executes, in units of system ticks. If the thread is not waiting, it returns current system time.

◆ k_thread_timeout_remaining_ticks()

k_ticks_t k_thread_timeout_remaining_ticks ( const struct k_thread * t )

#include <include/kernel.h>

Get time remaining before a thread wakes up, in system ticks.

This routine computes the time remaining before a waiting thread next executes, in units of system ticks. If the thread is not waiting, it returns zero.

◆ k_thread_user_mode_enter()

FUNC_NORETURN void k_thread_user_mode_enter	(	k_thread_entry_t	entry,
		void *	p1,
		void *	p2,
		void *	p3
	)

#include <include/kernel.h>

Drop a thread's privileges permanently to user mode.

This allows a supervisor thread to be re-used as a user thread. This function does not return, but control will transfer to the provided entry point as if this was a new user thread.

The implementation ensures that the stack buffer contents are erased. Any thread-local storage will be reverted to a pristine state.

Memory domain membership, resource pool assignment, kernel object permissions, priority, and thread options are preserved.

A common use of this function is to re-use the main thread as a user thread once all supervisor mode-only tasks have been completed.

Parameters

entry	Function to start executing from
p1	1st entry point parameter
p2	2nd entry point parameter
p3	3rd entry point parameter

◆ k_usleep()

int32_t k_usleep ( int32_t us )

#include <include/kernel.h>

Put the current thread to sleep with microsecond resolution.

This function is unlikely to work as expected without kernel tuning. In particular, because the lower bound on the duration of a sleep is the duration of a tick,

embed:rst:inline :kconfig:`CONFIG_SYS_CLOCK_TICKS_PER_SEC`

must be adjusted to achieve the resolution desired. The implications of doing this must be understood before attempting to use k_usleep(). Use with caution.

Parameters

us	Number of microseconds to sleep.

Returns: Zero if the requested time has elapsed or the number of microseconds left to sleep, if thread was woken up by k_wakeup call.

◆ k_wakeup()

void k_wakeup ( k_tid_t thread )

#include <include/kernel.h>

Wake up a sleeping thread.

This routine prematurely wakes up thread from sleeping.

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

Parameters

thread ID of thread to wake.

Returns: N/A

◆ k_yield()

void k_yield ( void )

#include <include/kernel.h>

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.

Returns: N/A

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ K_CALLBACK_STATE

◆ K_ESSENTIAL

◆ K_FP_REGS

◆ K_INHERIT_PERMS

◆ k_thread_access_grant

◆ K_THREAD_DEFINE

◆ K_USER

Typedef Documentation

◆ k_thread_user_cb_t

Function Documentation

◆ k_busy_wait()

◆ k_current_get()

◆ k_msleep()

◆ k_sched_lock()

◆ k_sched_time_slice_set()

◆ k_sched_unlock()

◆ k_sleep()

◆ k_thread_abort()

◆ k_thread_cpu_mask_clear()

◆ k_thread_cpu_mask_disable()

◆ k_thread_cpu_mask_enable()

◆ k_thread_cpu_mask_enable_all()

◆ k_thread_create()

◆ k_thread_custom_data_get()

◆ k_thread_custom_data_set()

◆ k_thread_deadline_set()

◆ k_thread_foreach()

◆ k_thread_foreach_unlocked()

◆ k_thread_heap_assign()

◆ k_thread_join()

◆ k_thread_name_copy()

◆ k_thread_name_get()

◆ k_thread_name_set()

◆ k_thread_priority_get()

◆ k_thread_priority_set()

◆ k_thread_resume()

◆ k_thread_start()

◆ k_thread_state_str()

◆ k_thread_suspend()

◆ k_thread_system_pool_assign()

◆ k_thread_timeout_expires_ticks()

◆ k_thread_timeout_remaining_ticks()

◆ k_thread_user_mode_enter()

◆ k_usleep()

◆ k_wakeup()

◆ k_yield()