Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
thread_stack.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2020 Intel Corporation
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
21#ifndef ZEPHYR_INCLUDE_KERNEL_THREAD_STACK_H
22#define ZEPHYR_INCLUDE_KERNEL_THREAD_STACK_H
23
24#if !defined(_ASMLANGUAGE)
25#include <zephyr/arch/cpu.h>
26#include <zephyr/sys/util.h>
27
28#ifdef __cplusplus
29extern "C" {
30#endif
31
32/* Using typedef deliberately here, this is quite intended to be an opaque
33 * type.
34 *
35 * The purpose of this data type is to clearly distinguish between the
36 * declared symbol for a stack (of type k_thread_stack_t) and the underlying
37 * buffer which composes the stack data actually used by the underlying
38 * thread; they cannot be used interchangeably as some arches precede the
39 * stack buffer region with guard areas that trigger a MPU or MMU fault
40 * if written to.
41 *
42 * APIs that want to work with the buffer inside should continue to use
43 * char *.
44 *
45 * Stacks should always be created with K_THREAD_STACK_DEFINE().
46 */
47struct __packed z_thread_stack_element {
48 char data;
49};
50
69static inline char *z_stack_ptr_align(char *ptr)
70{
71 return (char *)ROUND_DOWN(ptr, ARCH_STACK_PTR_ALIGN);
72}
73#define Z_STACK_PTR_ALIGN(ptr) ((uintptr_t)z_stack_ptr_align((char *)(ptr)))
74
88#define Z_STACK_PTR_TO_FRAME(type, ptr) \
89 (type *)((ptr) - sizeof(type))
90
91#ifdef ARCH_KERNEL_STACK_RESERVED
92#define K_KERNEL_STACK_RESERVED ((size_t)ARCH_KERNEL_STACK_RESERVED)
93#else
94#define K_KERNEL_STACK_RESERVED ((size_t)0)
95#endif /* ARCH_KERNEL_STACK_RESERVED */
96
97#define Z_KERNEL_STACK_SIZE_ADJUST(size) (ROUND_UP(size, \
98 ARCH_STACK_PTR_ALIGN) + \
99 K_KERNEL_STACK_RESERVED)
100
101#ifdef ARCH_KERNEL_STACK_OBJ_ALIGN
102#define Z_KERNEL_STACK_OBJ_ALIGN ARCH_KERNEL_STACK_OBJ_ALIGN
103#else
104#define Z_KERNEL_STACK_OBJ_ALIGN ARCH_STACK_PTR_ALIGN
105#endif /* ARCH_KERNEL_STACK_OBJ_ALIGN */
106
107#define K_KERNEL_STACK_LEN(size) \
108 ROUND_UP(Z_KERNEL_STACK_SIZE_ADJUST(size), Z_KERNEL_STACK_OBJ_ALIGN)
109
124#define K_KERNEL_STACK_DECLARE(sym, size) \
125 extern struct z_thread_stack_element \
126 sym[K_KERNEL_STACK_LEN(size)]
127
138#define K_KERNEL_STACK_ARRAY_DECLARE(sym, nmemb, size) \
139 extern struct z_thread_stack_element \
140 sym[nmemb][K_KERNEL_STACK_LEN(size)]
141
152#define K_KERNEL_PINNED_STACK_ARRAY_DECLARE(sym, nmemb, size) \
153 extern struct z_thread_stack_element \
154 sym[nmemb][K_KERNEL_STACK_LEN(size)]
155
175#define Z_KERNEL_STACK_DEFINE_IN(sym, size, lsect) \
176 struct z_thread_stack_element lsect \
177 __aligned(Z_KERNEL_STACK_OBJ_ALIGN) \
178 sym[K_KERNEL_STACK_LEN(size)]
179
188#define Z_KERNEL_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, lsect) \
189 struct z_thread_stack_element lsect \
190 __aligned(Z_KERNEL_STACK_OBJ_ALIGN) \
191 sym[nmemb][K_KERNEL_STACK_LEN(size)]
192
214#define K_KERNEL_STACK_DEFINE(sym, size) \
215 Z_KERNEL_STACK_DEFINE_IN(sym, size, __kstackmem)
216
229#if defined(CONFIG_LINKER_USE_PINNED_SECTION)
230#define K_KERNEL_PINNED_STACK_DEFINE(sym, size) \
231 Z_KERNEL_STACK_DEFINE_IN(sym, size, __pinned_noinit)
232#else
233#define K_KERNEL_PINNED_STACK_DEFINE(sym, size) \
234 Z_KERNEL_STACK_DEFINE_IN(sym, size, __kstackmem)
235#endif /* CONFIG_LINKER_USE_PINNED_SECTION */
236
246#define K_KERNEL_STACK_ARRAY_DEFINE(sym, nmemb, size) \
247 Z_KERNEL_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __kstackmem)
248
262#if defined(CONFIG_LINKER_USE_PINNED_SECTION)
263#define K_KERNEL_PINNED_STACK_ARRAY_DEFINE(sym, nmemb, size) \
264 Z_KERNEL_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __pinned_noinit)
265#else
266#define K_KERNEL_PINNED_STACK_ARRAY_DEFINE(sym, nmemb, size) \
267 Z_KERNEL_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __kstackmem)
268#endif /* CONFIG_LINKER_USE_PINNED_SECTION */
269
279#define K_KERNEL_STACK_MEMBER(sym, size) \
280 Z_KERNEL_STACK_DEFINE_IN(sym, size,)
281
282#define K_KERNEL_STACK_SIZEOF(sym) (sizeof(sym) - K_KERNEL_STACK_RESERVED)
283
287{
288 return (char *)sym + K_KERNEL_STACK_RESERVED;
289}
290#ifndef CONFIG_USERSPACE
291#define K_THREAD_STACK_RESERVED K_KERNEL_STACK_RESERVED
292#define K_THREAD_STACK_SIZEOF K_KERNEL_STACK_SIZEOF
293#define K_THREAD_STACK_LEN K_KERNEL_STACK_LEN
294#define K_THREAD_STACK_DEFINE K_KERNEL_STACK_DEFINE
295#define K_THREAD_STACK_ARRAY_DEFINE K_KERNEL_STACK_ARRAY_DEFINE
296#define K_THREAD_STACK_MEMBER K_KERNEL_STACK_MEMBER
297#define K_THREAD_STACK_BUFFER K_KERNEL_STACK_BUFFER
298#define K_THREAD_STACK_DECLARE K_KERNEL_STACK_DECLARE
299#define K_THREAD_STACK_ARRAY_DECLARE K_KERNEL_STACK_ARRAY_DECLARE
300#define K_THREAD_PINNED_STACK_DEFINE K_KERNEL_PINNED_STACK_DEFINE
301#define K_THREAD_PINNED_STACK_ARRAY_DEFINE \
302 K_KERNEL_PINNED_STACK_ARRAY_DEFINE
303#else
319#ifdef ARCH_THREAD_STACK_RESERVED
320#define K_THREAD_STACK_RESERVED ((size_t)(ARCH_THREAD_STACK_RESERVED))
321#else
322#define K_THREAD_STACK_RESERVED ((size_t)0U)
323#endif /* ARCH_THREAD_STACK_RESERVED */
324
350#if defined(ARCH_THREAD_STACK_OBJ_ALIGN)
351#define Z_THREAD_STACK_OBJ_ALIGN(size) \
352 ARCH_THREAD_STACK_OBJ_ALIGN(Z_THREAD_STACK_SIZE_ADJUST(size))
353#else
354#define Z_THREAD_STACK_OBJ_ALIGN(size) ARCH_STACK_PTR_ALIGN
355#endif /* ARCH_THREAD_STACK_OBJ_ALIGN */
356
383#if defined(ARCH_THREAD_STACK_SIZE_ADJUST)
384#define Z_THREAD_STACK_SIZE_ADJUST(size) \
385 ARCH_THREAD_STACK_SIZE_ADJUST((size) + K_THREAD_STACK_RESERVED)
386#else
387#define Z_THREAD_STACK_SIZE_ADJUST(size) \
388 (ROUND_UP((size), ARCH_STACK_PTR_ALIGN) + K_THREAD_STACK_RESERVED)
389#endif /* ARCH_THREAD_STACK_SIZE_ADJUST */
390
405#define K_THREAD_STACK_DECLARE(sym, size) \
406 extern struct z_thread_stack_element \
407 sym[K_THREAD_STACK_LEN(size)]
408
419#define K_THREAD_STACK_ARRAY_DECLARE(sym, nmemb, size) \
420 extern struct z_thread_stack_element \
421 sym[nmemb][K_THREAD_STACK_LEN(size)]
422
437#define K_THREAD_STACK_SIZEOF(sym) (sizeof(sym) - K_THREAD_STACK_RESERVED)
438
467#define Z_THREAD_STACK_DEFINE_IN(sym, size, lsect) \
468 struct z_thread_stack_element lsect \
469 __aligned(Z_THREAD_STACK_OBJ_ALIGN(size)) \
470 sym[K_THREAD_STACK_LEN(size)]
471
486#define Z_THREAD_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, lsect) \
487 struct z_thread_stack_element lsect \
488 __aligned(Z_THREAD_STACK_OBJ_ALIGN(size)) \
489 sym[nmemb][K_THREAD_STACK_LEN(size)]
490
517#define K_THREAD_STACK_DEFINE(sym, size) \
518 Z_THREAD_STACK_DEFINE_IN(sym, size, __stackmem)
519
550#if defined(CONFIG_LINKER_USE_PINNED_SECTION)
551#define K_THREAD_PINNED_STACK_DEFINE(sym, size) \
552 Z_THREAD_STACK_DEFINE_IN(sym, size, __pinned_noinit)
553#else
554#define K_THREAD_PINNED_STACK_DEFINE(sym, size) \
555 K_THREAD_STACK_DEFINE(sym, size)
556#endif /* CONFIG_LINKER_USE_PINNED_SECTION */
557
571#define K_THREAD_STACK_LEN(size) \
572 ROUND_UP(Z_THREAD_STACK_SIZE_ADJUST(size), \
573 Z_THREAD_STACK_OBJ_ALIGN(size))
574
588#define K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size) \
589 Z_THREAD_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __stackmem)
590
608#if defined(CONFIG_LINKER_USE_PINNED_SECTION)
609#define K_THREAD_PINNED_STACK_ARRAY_DEFINE(sym, nmemb, size) \
610 Z_THREAD_PINNED_STACK_DEFINE_IN(sym, nmemb, size, __pinned_noinit)
611#else
612#define K_THREAD_PINNED_STACK_ARRAY_DEFINE(sym, nmemb, size) \
613 K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size)
614#endif /* CONFIG_LINKER_USE_PINNED_SECTION */
615
634#define K_THREAD_STACK_MEMBER(sym, size) __DEPRECATED_MACRO \
635 Z_THREAD_STACK_DEFINE_IN(sym, size,)
636
654{
655 return (char *)sym + K_THREAD_STACK_RESERVED;
656}
657
658#endif /* CONFIG_USERSPACE */
659
660#ifdef __cplusplus
661}
662#endif
663
664#endif /* _ASMLANGUAGE */
665#endif /* ZEPHYR_INCLUDE_KERNEL_THREAD_STACK_H */
#define ARCH_STACK_PTR_ALIGN
Definition: arch.h:98
struct z_thread_stack_element k_thread_stack_t
Typedef of struct z_thread_stack_element.
Definition: arch_interface.h:45
#define ROUND_DOWN(x, align)
Value of x rounded down to the previous multiple of align.
Definition: util.h:313
#define K_THREAD_STACK_RESERVED
Indicate how much additional memory is reserved for stack objects.
Definition: thread_stack.h:322
static char * K_THREAD_STACK_BUFFER(k_thread_stack_t *sym)
Get a pointer to the physical stack buffer.
Definition: thread_stack.h:653
static char * K_KERNEL_STACK_BUFFER(k_thread_stack_t *sym)
Definition: thread_stack.h:286
#define K_KERNEL_STACK_RESERVED
Definition: thread_stack.h:94
Misc utilities.