Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Thread Stack APIs

Thread Stack APIs. More...

Macros

#define K_KERNEL_STACK_DECLARE(sym, size)
 Declare a reference to a thread stack.
 
#define K_KERNEL_STACK_ARRAY_DECLARE(sym, nmemb, size)
 Declare a reference to a thread stack array.
 
#define K_KERNEL_PINNED_STACK_ARRAY_DECLARE(sym, nmemb, size)
 Declare a reference to a pinned thread stack array.
 
#define K_KERNEL_STACK_DEFINE(sym, size)    Z_KERNEL_STACK_DEFINE_IN(sym, size, __kstackmem)
 Define a toplevel kernel stack memory region.
 
#define K_KERNEL_PINNED_STACK_DEFINE(sym, size)    Z_KERNEL_STACK_DEFINE_IN(sym, size, __kstackmem)
 Define a toplevel kernel stack memory region in pinned section.
 
#define K_KERNEL_STACK_ARRAY_DEFINE(sym, nmemb, size)    Z_KERNEL_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __kstackmem)
 Define a toplevel array of kernel stack memory regions.
 
#define K_KERNEL_PINNED_STACK_ARRAY_DEFINE(sym, nmemb, size)    Z_KERNEL_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __kstackmem)
 Define a toplevel array of kernel stack memory regions in pinned section.
 
#define K_KERNEL_STACK_MEMBER(sym, size)    Z_KERNEL_STACK_DEFINE_IN(sym, size,)
 Define an embedded stack memory region.
 
#define K_KERNEL_STACK_SIZEOF(sym)   (sizeof(sym) - K_KERNEL_STACK_RESERVED)
 
#define K_THREAD_STACK_DECLARE(sym, size)
 Declare a reference to a thread stack.
 
#define K_THREAD_STACK_ARRAY_DECLARE(sym, nmemb, size)
 Declare a reference to a thread stack array.
 
#define K_THREAD_STACK_SIZEOF(sym)   (sizeof(sym) - K_THREAD_STACK_RESERVED)
 Return the size in bytes of a stack memory region.
 
#define K_THREAD_STACK_DEFINE(sym, size)    Z_THREAD_STACK_DEFINE_IN(sym, size, __stackmem)
 Define a toplevel thread stack memory region.
 
#define K_THREAD_PINNED_STACK_DEFINE(sym, size)    K_THREAD_STACK_DEFINE(sym, size)
 Define a toplevel thread stack memory region in pinned section.
 
#define K_THREAD_STACK_LEN(size)
 Calculate size of stacks to be allocated in a stack array.
 
#define K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size)    Z_THREAD_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __stackmem)
 Define a toplevel array of thread stack memory regions.
 
#define K_THREAD_PINNED_STACK_ARRAY_DEFINE(sym, nmemb, size)    K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size)
 Define a toplevel array of thread stack memory regions in pinned section.
 
#define K_THREAD_STACK_MEMBER(sym, size)
 Define an embedded stack memory region.
 

Detailed Description

Thread Stack APIs.

Macro Definition Documentation

◆ K_KERNEL_PINNED_STACK_ARRAY_DECLARE

#define K_KERNEL_PINNED_STACK_ARRAY_DECLARE (   sym,
  nmemb,
  size 
)

#include <zephyr/kernel/thread_stack.h>

Value:
extern struct z_thread_stack_element \
sym[nmemb][K_KERNEL_STACK_LEN(size)]
#define K_KERNEL_STACK_LEN(size)
Definition: thread_stack.h:107

Declare a reference to a pinned thread stack array.

This macro declares the symbol of a pinned thread stack array defined elsewhere in the current scope.

Parameters
symThread stack symbol name
nmembNumber of stacks defined
sizeSize of the stack memory region

◆ K_KERNEL_PINNED_STACK_ARRAY_DEFINE

#define K_KERNEL_PINNED_STACK_ARRAY_DEFINE (   sym,
  nmemb,
  size 
)     Z_KERNEL_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __kstackmem)

#include <zephyr/kernel/thread_stack.h>

Define a toplevel array of kernel stack memory regions in pinned section.

See K_KERNEL_STACK_ARRAY_DEFINE() for more information and constraints.

This puts the stack into the pinned noinit linker section if CONFIG_LINKER_USE_PINNED_SECTION is enabled, or else it would put the stack into the same section as K_KERNEL_STACK_ARRAY_DEFINE().

Parameters
symKernel stack array symbol name
nmembNumber of stacks to define
sizeSize of the stack memory region

◆ K_KERNEL_PINNED_STACK_DEFINE

#define K_KERNEL_PINNED_STACK_DEFINE (   sym,
  size 
)     Z_KERNEL_STACK_DEFINE_IN(sym, size, __kstackmem)

#include <zephyr/kernel/thread_stack.h>

Define a toplevel kernel stack memory region in pinned section.

See K_KERNEL_STACK_DEFINE() for more information and constraints.

This puts the stack into the pinned noinit linker section if CONFIG_LINKER_USE_PINNED_SECTION is enabled, or else it would put the stack into the same section as K_KERNEL_STACK_DEFINE().

Parameters
symThread stack symbol name
sizeSize of the stack memory region

◆ K_KERNEL_STACK_ARRAY_DECLARE

#define K_KERNEL_STACK_ARRAY_DECLARE (   sym,
  nmemb,
  size 
)

#include <zephyr/kernel/thread_stack.h>

Value:
extern struct z_thread_stack_element \
sym[nmemb][K_KERNEL_STACK_LEN(size)]

Declare a reference to a thread stack array.

This macro declares the symbol of a thread stack array defined elsewhere in the current scope.

Parameters
symThread stack symbol name
nmembNumber of stacks defined
sizeSize of the stack memory region

◆ K_KERNEL_STACK_ARRAY_DEFINE

#define K_KERNEL_STACK_ARRAY_DEFINE (   sym,
  nmemb,
  size 
)     Z_KERNEL_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __kstackmem)

#include <zephyr/kernel/thread_stack.h>

Define a toplevel array of kernel stack memory regions.

Stacks defined with this macro may not host user mode threads.

Parameters
symKernel stack array symbol name
nmembNumber of stacks to define
sizeSize of the stack memory region

◆ K_KERNEL_STACK_DECLARE

#define K_KERNEL_STACK_DECLARE (   sym,
  size 
)

#include <zephyr/kernel/thread_stack.h>

Value:
extern struct z_thread_stack_element \
sym[K_KERNEL_STACK_LEN(size)]

Declare a reference to a thread stack.

This macro declares the symbol of a thread stack defined elsewhere in the current scope.

Parameters
symThread stack symbol name
sizeSize of the stack memory region

◆ K_KERNEL_STACK_DEFINE

#define K_KERNEL_STACK_DEFINE (   sym,
  size 
)     Z_KERNEL_STACK_DEFINE_IN(sym, size, __kstackmem)

#include <zephyr/kernel/thread_stack.h>

Define a toplevel kernel stack memory region.

This defines a region of memory for use as a thread stack, for threads that exclusively run in supervisor mode. This is also suitable for declaring special stacks for interrupt or exception handling.

Stacks defined with this macro may not host user mode threads.

It is legal to precede this definition with the 'static' keyword.

It is NOT legal to take the sizeof(sym) and pass that to the stackSize parameter of k_thread_create(), it may not be the same as the 'size' parameter. Use K_KERNEL_STACK_SIZEOF() instead.

The total amount of memory allocated may be increased to accommodate fixed-size stack overflow guards.

Parameters
symThread stack symbol name
sizeSize of the stack memory region

◆ K_KERNEL_STACK_MEMBER

#define K_KERNEL_STACK_MEMBER (   sym,
  size 
)     Z_KERNEL_STACK_DEFINE_IN(sym, size,)

#include <zephyr/kernel/thread_stack.h>

Define an embedded stack memory region.

Used for kernel stacks embedded within other data structures.

Stacks defined with this macro may not host user mode threads.

Parameters
symThread stack symbol name
sizeSize of the stack memory region

◆ K_KERNEL_STACK_SIZEOF

#define K_KERNEL_STACK_SIZEOF (   sym)    (sizeof(sym) - K_KERNEL_STACK_RESERVED)

◆ K_THREAD_PINNED_STACK_ARRAY_DEFINE

#define K_THREAD_PINNED_STACK_ARRAY_DEFINE (   sym,
  nmemb,
  size 
)     K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size)

#include <zephyr/kernel/thread_stack.h>

Define a toplevel array of thread stack memory regions in pinned section.

Create an array of equally sized stacks. See K_THREAD_STACK_DEFINE definition for additional details and constraints.

This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN and put in 'noinit' section so that it isn't zeroed at boot

This puts the stack into the pinned noinit linker section if CONFIG_LINKER_USE_PINNED_SECTION is enabled, or else it would put the stack into the same section as K_THREAD_STACK_DEFINE().

Parameters
symThread stack symbol name
nmembNumber of stacks to define
sizeSize of the stack memory region

◆ K_THREAD_PINNED_STACK_DEFINE

#define K_THREAD_PINNED_STACK_DEFINE (   sym,
  size 
)     K_THREAD_STACK_DEFINE(sym, size)

#include <zephyr/kernel/thread_stack.h>

Define a toplevel thread stack memory region in pinned section.

This defines a region of memory suitable for use as a thread's stack.

This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN and put in 'noinit' section so that it isn't zeroed at boot

The defined symbol will always be a k_thread_stack_t which can be passed to k_thread_create(), but should otherwise not be manipulated. If the buffer inside needs to be examined, examine thread->stack_info for the associated thread object to obtain the boundaries.

It is legal to precede this definition with the 'static' keyword.

It is NOT legal to take the sizeof(sym) and pass that to the stackSize parameter of k_thread_create(), it may not be the same as the 'size' parameter. Use K_THREAD_STACK_SIZEOF() instead.

Some arches may round the size of the usable stack region up to satisfy alignment constraints. K_THREAD_STACK_SIZEOF() will return the aligned size.

This puts the stack into the pinned noinit linker section if CONFIG_LINKER_USE_PINNED_SECTION is enabled, or else it would put the stack into the same section as K_THREAD_STACK_DEFINE().

Parameters
symThread stack symbol name
sizeSize of the stack memory region

◆ K_THREAD_STACK_ARRAY_DECLARE

#define K_THREAD_STACK_ARRAY_DECLARE (   sym,
  nmemb,
  size 
)

#include <zephyr/kernel/thread_stack.h>

Value:
extern struct z_thread_stack_element \
sym[nmemb][K_THREAD_STACK_LEN(size)]
#define K_THREAD_STACK_LEN(size)
Calculate size of stacks to be allocated in a stack array.
Definition: thread_stack.h:571

Declare a reference to a thread stack array.

This macro declares the symbol of a thread stack array defined elsewhere in the current scope.

Parameters
symThread stack symbol name
nmembNumber of stacks defined
sizeSize of the stack memory region

◆ K_THREAD_STACK_ARRAY_DEFINE

#define K_THREAD_STACK_ARRAY_DEFINE (   sym,
  nmemb,
  size 
)     Z_THREAD_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __stackmem)

#include <zephyr/kernel/thread_stack.h>

Define a toplevel array of thread stack memory regions.

Create an array of equally sized stacks. See K_THREAD_STACK_DEFINE definition for additional details and constraints.

This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN and put in 'noinit' section so that it isn't zeroed at boot

Parameters
symThread stack symbol name
nmembNumber of stacks to define
sizeSize of the stack memory region

◆ K_THREAD_STACK_DECLARE

#define K_THREAD_STACK_DECLARE (   sym,
  size 
)

#include <zephyr/kernel/thread_stack.h>

Value:
extern struct z_thread_stack_element \
sym[K_THREAD_STACK_LEN(size)]

Declare a reference to a thread stack.

This macro declares the symbol of a thread stack defined elsewhere in the current scope.

Parameters
symThread stack symbol name
sizeSize of the stack memory region

◆ K_THREAD_STACK_DEFINE

#define K_THREAD_STACK_DEFINE (   sym,
  size 
)     Z_THREAD_STACK_DEFINE_IN(sym, size, __stackmem)

#include <zephyr/kernel/thread_stack.h>

Define a toplevel thread stack memory region.

This defines a region of memory suitable for use as a thread's stack.

This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN and put in 'noinit' section so that it isn't zeroed at boot

The defined symbol will always be a k_thread_stack_t which can be passed to k_thread_create(), but should otherwise not be manipulated. If the buffer inside needs to be examined, examine thread->stack_info for the associated thread object to obtain the boundaries.

It is legal to precede this definition with the 'static' keyword.

It is NOT legal to take the sizeof(sym) and pass that to the stackSize parameter of k_thread_create(), it may not be the same as the 'size' parameter. Use K_THREAD_STACK_SIZEOF() instead.

Some arches may round the size of the usable stack region up to satisfy alignment constraints. K_THREAD_STACK_SIZEOF() will return the aligned size.

Parameters
symThread stack symbol name
sizeSize of the stack memory region

◆ K_THREAD_STACK_LEN

#define K_THREAD_STACK_LEN (   size)

#include <zephyr/kernel/thread_stack.h>

Value:
ROUND_UP(Z_THREAD_STACK_SIZE_ADJUST(size), \
Z_THREAD_STACK_OBJ_ALIGN(size))
#define ROUND_UP(x, align)
Value of x rounded up to the next multiple of align.
Definition: util.h:306

Calculate size of stacks to be allocated in a stack array.

This macro calculates the size to be allocated for the stacks inside a stack array. It accepts the indicated "size" as a parameter and if required, pads some extra bytes (e.g. for MPU scenarios). Refer K_THREAD_STACK_ARRAY_DEFINE definition to see how this is used. The returned size ensures each array member will be aligned to the required stack base alignment.

Parameters
sizeSize of the stack memory region
Returns
Appropriate size for an array member

◆ K_THREAD_STACK_MEMBER

#define K_THREAD_STACK_MEMBER (   sym,
  size 
)

#include <zephyr/kernel/thread_stack.h>

Value:
__DEPRECATED_MACRO \
Z_THREAD_STACK_DEFINE_IN(sym, size,)

Define an embedded stack memory region.

Used for stacks embedded within other data structures. Use is highly discouraged but in some cases necessary. For memory protection scenarios, it is very important that any RAM preceding this member not be writable by threads else a stack overflow will lead to silent corruption. In other words, the containing data structure should live in RAM owned by the kernel.

A user thread can only be started with a stack defined in this way if the thread starting it is in supervisor mode.

Deprecated:
This is now deprecated, as stacks defined in this way are not usable from user mode. Use K_KERNEL_STACK_MEMBER.
Parameters
symThread stack symbol name
sizeSize of the stack memory region

◆ K_THREAD_STACK_SIZEOF

#define K_THREAD_STACK_SIZEOF (   sym)    (sizeof(sym) - K_THREAD_STACK_RESERVED)

#include <zephyr/kernel/thread_stack.h>

Return the size in bytes of a stack memory region.

Convenience macro for passing the desired stack size to k_thread_create() since the underlying implementation may actually create something larger (for instance a guard area).

The value returned here is not guaranteed to match the 'size' parameter passed to K_THREAD_STACK_DEFINE and may be larger, but is always safe to pass to k_thread_create() for the associated stack object.

Parameters
symStack memory symbol
Returns
Size of the stack buffer