Thread Stack APIs

Thread Stack APIs. More...

Macros
#define	K_KERNEL_STACK_ARRAY_EXTERN(sym, nmemb, size)
	Obtain an extern reference to a stack array. More...
#define	K_KERNEL_PINNED_STACK_ARRAY_EXTERN(sym, nmemb, size)
	Obtain an extern reference to a pinned stack array. More...
#define	K_KERNEL_STACK_DEFINE(sym, size)    Z_KERNEL_STACK_DEFINE_IN(sym, size, __kstackmem)
	Define a toplevel kernel stack memory region. More...
#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. More...
#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. More...
#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. More...
#define	K_KERNEL_STACK_MEMBER(sym, size)    Z_KERNEL_STACK_DEFINE_IN(sym, size,)
	Declare an embedded stack memory region. More...
#define	K_KERNEL_STACK_SIZEOF(sym)   (sizeof(sym) - K_KERNEL_STACK_RESERVED)
#define	K_THREAD_STACK_SIZEOF(sym)   (sizeof(sym) - K_THREAD_STACK_RESERVED)
	Return the size in bytes of a stack memory region. More...
#define	K_THREAD_STACK_DEFINE(sym, size)    Z_THREAD_STACK_DEFINE_IN(sym, size, __stackmem)
	Declare a toplevel thread stack memory region. More...
#define	K_THREAD_PINNED_STACK_DEFINE(sym, size)    K_THREAD_STACK_DEFINE(sym, size)
	Define a toplevel thread stack memory region in pinned section. More...
#define	K_THREAD_STACK_LEN(size)
	Calculate size of stacks to be allocated in a stack array. More...
#define	K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size)    Z_THREAD_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __stackmem)
	Declare a toplevel array of thread stack memory regions. More...
#define	K_THREAD_PINNED_STACK_ARRAY_DEFINE(sym, nmemb, size)    K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size)
	Declare a toplevel array of thread stack memory regions in pinned section. More...
#define	K_THREAD_STACK_MEMBER(sym, size)    Z_THREAD_STACK_DEFINE_IN(sym, size,)
	Declare an embedded stack memory region. More...

Detailed Description

Thread Stack APIs.

Macro Definition Documentation

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 <include/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

sym	Kernel stack array symbol name
nmemb	Number of stacks to declare
size	Size of the stack memory region

K_KERNEL_PINNED_STACK_ARRAY_EXTERN

#define K_KERNEL_PINNED_STACK_ARRAY_EXTERN	(		sym,
			nmemb,
			size
	)

#include <include/kernel/thread_stack.h>

Value:

        extern struct z_thread_stack_element \
                sym[nmemb][Z_KERNEL_STACK_LEN(size)]

Obtain an extern reference to a pinned stack array.

This macro properly brings the symbol of a pinned stack array declared elsewhere into scope.

Parameters

sym	Thread stack symbol name
nmemb	Number of stacks to declare
size	Size 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 <include/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

sym	Thread stack symbol name
size	Size 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 <include/kernel/thread_stack.h>

Define a toplevel array of kernel stack memory regions.

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

Parameters

sym	Kernel stack array symbol name
nmemb	Number of stacks to declare
size	Size of the stack memory region

K_KERNEL_STACK_ARRAY_EXTERN

#define K_KERNEL_STACK_ARRAY_EXTERN	(		sym,
			nmemb,
			size
	)

#include <include/kernel/thread_stack.h>

Value:

        extern struct z_thread_stack_element \
                sym[nmemb][Z_KERNEL_STACK_LEN(size)]

Obtain an extern reference to a stack array.

This macro properly brings the symbol of a stack array declared elsewhere into scope.

Parameters

sym	Thread stack symbol name
nmemb	Number of stacks to declare
size	Size 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 <include/kernel/thread_stack.h>

Define a toplevel kernel stack memory region.

This declares 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 declared 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

sym	Thread stack symbol name
size	Size of the stack memory region

K_KERNEL_STACK_MEMBER

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

#include <include/kernel/thread_stack.h>

Declare an embedded stack memory region.

Used for kernel stacks embedded within other data structures.

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

Parameters

sym	Thread stack symbol name
size	Size of the stack memory region

K_KERNEL_STACK_SIZEOF

#define K_KERNEL_STACK_SIZEOF

(

sym

)

(sizeof(sym) - K_KERNEL_STACK_RESERVED)

#include <include/kernel/thread_stack.h>

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 <include/kernel/thread_stack.h>

Declare 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

sym	Thread stack symbol name
nmemb	Number of stacks to declare
size	Size 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 <include/kernel/thread_stack.h>

Define a toplevel thread stack memory region in pinned section.

This declares 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 declared 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

sym	Thread stack symbol name
size	Size 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 <include/kernel/thread_stack.h>

Declare 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

sym	Thread stack symbol name
nmemb	Number of stacks to declare
size	Size 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 <include/kernel/thread_stack.h>

Declare a toplevel thread stack memory region.

This declares 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 declared 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

sym	Thread stack symbol name
size	Size of the stack memory region

K_THREAD_STACK_LEN

#define K_THREAD_STACK_LEN

(

size

)

#include <include/kernel/thread_stack.h>

Value:

        ROUND_UP(Z_THREAD_STACK_SIZE_ADJUST(size), \
                 Z_THREAD_STACK_OBJ_ALIGN(Z_THREAD_STACK_SIZE_ADJUST(size)))

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

size	Size of the stack memory region

Returns

Appropriate size for an array member

K_THREAD_STACK_MEMBER

#define K_THREAD_STACK_MEMBER	(		sym,
			size
	)		Z_THREAD_STACK_DEFINE_IN(sym, size,)

#include <include/kernel/thread_stack.h>

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

This is now deprecated, as stacks defined in this way are not usable from user mode. Use K_KERNEL_STACK_MEMBER.

Parameters

sym	Thread stack symbol name
size	Size of the stack memory region

K_THREAD_STACK_SIZEOF

#define K_THREAD_STACK_SIZEOF

(

sym

)

(sizeof(sym) - K_THREAD_STACK_RESERVED)

#include <include/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

sym	Stack memory symbol

Returns

Size of the stack buffer