1 /*
2 * Copyright (c) 2020 Intel Corporation
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /**
8 * @file
9 *
10 * @brief Macros for declaring thread stacks
11 */
12
13 /**
14 * @brief Thread Stack APIs
15 * @ingroup kernel_apis
16 * @defgroup thread_stack_api Thread Stack APIs
17 * @{
18 * @}
19 */
20
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
29 extern "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 */
47 struct __packed z_thread_stack_element {
48 char data;
49 };
50
51 /**
52 * @typedef k_thread_stack_t
53 * @brief Typedef of struct z_thread_stack_element
54 *
55 * @see z_thread_stack_element
56 */
57
58
59 /**
60 * @brief Properly align a CPU stack pointer value
61 *
62 * Take the provided value and round it down such that the value is aligned
63 * to the CPU and ABI requirements. This is not used for any memory protection
64 * hardware requirements.
65 *
66 * @param ptr Proposed stack pointer address
67 * @return Properly aligned stack pointer address
68 */
z_stack_ptr_align(char * ptr)69 static 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
75 /**
76 * @brief Helper macro for getting a stack frame struct
77 *
78 * It is very common for architectures to define a struct which contains
79 * all the data members that are pre-populated in arch_new_thread().
80 *
81 * Given a type and an initial stack pointer, return a properly cast
82 * pointer to the frame struct.
83 *
84 * @param type Type of the initial stack frame struct
85 * @param ptr Initial aligned stack pointer value
86 * @return Pointer to stack frame struct within the stack buffer
87 */
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
110 /**
111 * @addtogroup thread_stack_api
112 * @{
113 */
114
115 #ifdef CONFIG_HW_SHADOW_STACK
116 /**
117 * @typedef k_thread_hw_shadow_stack_t
118 * @brief Typedef of arch_thread_hw_shadow_stack_t
119 *
120 * This is an opaque type that represents a hardware shadow stack.
121 * The architecture implementation defines the actual type.
122 */
123 #define k_thread_hw_shadow_stack_t arch_thread_hw_shadow_stack_t
124
125 /**
126 * @brief Calculate the size of a hardware shadow stack
127 *
128 * This macro calculates the size to be allocated for a hardware shadow
129 * stack. It accepts the indicated "size" as a parameter and pads some
130 * extra bytes (e.g. for alignment).
131 *
132 * @param size Size of the shadow stack memory region
133 */
134 #define K_THREAD_HW_SHADOW_STACK_SIZE(size_) \
135 ARCH_THREAD_HW_SHADOW_STACK_SIZE(size_)
136
137 /**
138 * @brief Declare a hardware shadow stack
139 *
140 * This macro declares the symbol of a hardware shadow stack defined
141 * elsewhere in the current scope.
142 *
143 * @param sym Hardware shadow stack symbol name
144 * @param size Size of the shadow stack memory region
145 */
146 #define K_KERNEL_HW_SHADOW_STACK_DECLARE(sym, size) \
147 ARCH_THREAD_HW_SHADOW_STACK_DECLARE(__ ## sym ## _shstk, size)
148
149 /**
150 * @brief Declare a hardware shadow stack array
151 *
152 * This macro declares the symbol of a hardware shadow stack array defined
153 * elsewhere in the current scope.
154 *
155 * @param sym Hardware shadow stack array symbol name
156 * @param nmemb Number of stacks defined
157 * @param size Size of the shadow stack memory region
158 */
159 #define K_KERNEL_HW_SHADOW_STACK_ARRAY_DECLARE(sym, nmemb, size) \
160 ARCH_THREAD_HW_SHADOW_STACK_ARRAY_DECLARE(__ ## sym ## _shstk_arr, \
161 nmemb, size)
162
163 struct _stack_to_hw_shadow_stack {
164 k_thread_stack_t *stack;
165 k_thread_hw_shadow_stack_t *shstk_addr;
166 size_t size;
167 };
168
169
170 /**
171 * @brief Define a hardware shadow stack
172 *
173 * This macro defines a hardware shadow stack. Note that an application
174 * usually doesn't have to define a hardware shadow stack directly,
175 * as it is automatically defined by the kernel when a thread stack is
176 * defined with K_THREAD_STACK_DEFINE().
177 *
178 * @param sym Hardware shadow stack symbol name
179 * @param size Size of the shadow stack memory region
180 */
181 #define K_THREAD_HW_SHADOW_STACK_DEFINE(sym, size_) \
182 ARCH_THREAD_HW_SHADOW_STACK_DEFINE(__ ## sym ## _shstk, size_); \
183 static const STRUCT_SECTION_ITERABLE(_stack_to_hw_shadow_stack, \
184 sym ## _stack_to_shstk_attach) = { \
185 .stack = sym, \
186 .shstk_addr = __ ## sym ## _shstk, \
187 .size = size_, \
188 }
189
190 struct _stack_to_hw_shadow_stack_arr {
191 uintptr_t stack_addr;
192 uintptr_t shstk_addr;
193 size_t stack_size;
194 size_t shstk_size;
195 size_t nmemb;
196 };
197
198 /**
199 * @brief Define a hardware shadow stack array
200 *
201 * This macro defines a hardware shadow stack array. Note that an application
202 * usually doesn't have to define a hardware shadow stack array directly,
203 * as it is automatically defined by the kernel when a thread stack array is
204 * defined with K_THREAD_STACK_ARRAY_DEFINE().
205 *
206 * @param sym Hardware shadow stack array symbol name
207 * @param nmemb Number of stacks defined
208 * @param size Size of the shadow stack memory region
209 */
210 #define K_THREAD_HW_SHADOW_STACK_ARRAY_DEFINE(sym, nmemb_, size_) \
211 ARCH_THREAD_HW_SHADOW_STACK_ARRAY_DEFINE(__ ## sym ## _shstk_arr, nmemb_, \
212 K_THREAD_HW_SHADOW_STACK_SIZE(size_)); \
213 static const STRUCT_SECTION_ITERABLE(_stack_to_hw_shadow_stack_arr, \
214 sym ## _stack_to_shstk_attach) = { \
215 .stack_addr = (uintptr_t)sym, \
216 .stack_size = K_KERNEL_STACK_LEN(size_), \
217 .nmemb = nmemb_, \
218 .shstk_addr = (uintptr_t)__ ## sym ## _shstk_arr, \
219 .shstk_size = K_THREAD_HW_SHADOW_STACK_SIZE(size_), \
220 }
221
222 /**
223 * @brief Attach a hardware shadow stack to a thread
224 *
225 * This macro attaches a hardware shadow stack to a thread. Note that an
226 * application usually doesn't have to attach a hardware shadow stack
227 * directly, as it is automatically attached by the kernel when a thread
228 * is created.
229 */
230 #define k_thread_hw_shadow_stack_attach arch_thread_hw_shadow_stack_attach
231
232 struct _thread_hw_shadow_stack_static {
233 struct k_thread *thread;
234 k_thread_hw_shadow_stack_t *shstk_addr;
235 size_t size;
236 };
237
238 /**
239 * @brief Attach a hardware shadow stack to a thread
240 *
241 * This macro attaches a hardware shadow stack to a thread. Note that an
242 * application usually doesn't have to attach a hardware shadow stack
243 * directly, as it is automatically attached by the kernel when a thread
244 * is created.
245 *
246 * @param thread_ Thread to attach the hardware shadow stack to
247 * @param shstk_addr_ Address of the hardware shadow stack
248 * @param size_ Size of the hardware shadow stack memory region
249 */
250 #define K_THREAD_HW_SHADOW_STACK_ATTACH(thread_, shstk_addr_, size_) \
251 static const STRUCT_SECTION_ITERABLE(_thread_hw_shadow_stack_static, \
252 thread ## _shstk_attach_static) = { \
253 .thread = thread_, \
254 .shstk_addr = shstk_addr_, \
255 .size = size_, \
256 }
257
258 #else
259 #define K_KERNEL_HW_SHADOW_STACK_DECLARE(sym, size)
260 #define K_KERNEL_HW_SHADOW_STACK_ARRAY_DECLARE(sym, nmemb, size)
261 #define K_THREAD_HW_SHADOW_STACK_DEFINE(sym, size)
262 #define K_THREAD_HW_SHADOW_STACK_ARRAY_DEFINE(sym, nmemb, size_)
263 #endif
264
265 /**
266 * @brief Declare a reference to a thread stack
267 *
268 * This macro declares the symbol of a thread stack defined elsewhere in the
269 * current scope.
270 *
271 * @param sym Thread stack symbol name
272 * @param size Size of the stack memory region
273 */
274 #define K_KERNEL_STACK_DECLARE(sym, size) \
275 K_KERNEL_HW_SHADOW_STACK_DECLARE(sym, K_THREAD_HW_SHADOW_STACK_SIZE(size)); \
276 extern struct z_thread_stack_element \
277 sym[K_KERNEL_STACK_LEN(size)]
278
279 /**
280 * @brief Declare a reference to a thread stack array
281 *
282 * This macro declares the symbol of a thread stack array defined elsewhere in
283 * the current scope.
284 *
285 * @param sym Thread stack symbol name
286 * @param nmemb Number of stacks defined
287 * @param size Size of the stack memory region
288 */
289 #define K_KERNEL_STACK_ARRAY_DECLARE(sym, nmemb, size) \
290 K_KERNEL_HW_SHADOW_STACK_ARRAY_DECLARE(sym, nmemb, K_THREAD_HW_SHADOW_STACK_SIZE(size)); \
291 extern struct z_thread_stack_element \
292 sym[nmemb][K_KERNEL_STACK_LEN(size)]
293
294 /**
295 * @brief Declare a reference to a pinned thread stack array
296 *
297 * This macro declares the symbol of a pinned thread stack array defined
298 * elsewhere in the current scope.
299 *
300 * @param sym Thread stack symbol name
301 * @param nmemb Number of stacks defined
302 * @param size Size of the stack memory region
303 */
304 #define K_KERNEL_PINNED_STACK_ARRAY_DECLARE(sym, nmemb, size) \
305 K_KERNEL_HW_SHADOW_STACK_ARRAY_DECLARE(sym, nmemb, K_THREAD_HW_SHADOW_STACK_SIZE(size)); \
306 extern struct z_thread_stack_element \
307 sym[nmemb][K_KERNEL_STACK_LEN(size)]
308
309 /**
310 * @brief Define a toplevel kernel stack memory region in specified section
311 *
312 * This defines a region of memory for use as a thread stack in
313 * the specified linker section.
314 *
315 * It is legal to precede this definition with the 'static' keyword.
316 *
317 * It is NOT legal to take the sizeof(sym) and pass that to the stackSize
318 * parameter of k_thread_create(), it may not be the same as the
319 * 'size' parameter. Use K_KERNEL_STACK_SIZEOF() instead.
320 *
321 * The total amount of memory allocated may be increased to accommodate
322 * fixed-size stack overflow guards.
323 *
324 * @param sym Thread stack symbol name
325 * @param size Size of the stack memory region
326 * @param lsect Linker section for this stack
327 */
328 #define Z_KERNEL_STACK_DEFINE_IN(sym, size, lsect) \
329 struct z_thread_stack_element lsect \
330 __aligned(Z_KERNEL_STACK_OBJ_ALIGN) \
331 sym[K_KERNEL_STACK_LEN(size)]
332
333 /**
334 * @brief Define a toplevel array of kernel stack memory regions in specified section
335 *
336 * @param sym Kernel stack array symbol name
337 * @param nmemb Number of stacks to define
338 * @param size Size of the stack memory region
339 * @param lsect Linker section for this array of stacks
340 */
341 #define Z_KERNEL_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, lsect) \
342 struct z_thread_stack_element lsect \
343 __aligned(Z_KERNEL_STACK_OBJ_ALIGN) \
344 sym[nmemb][K_KERNEL_STACK_LEN(size)]
345
346 /**
347 * @brief Define a toplevel kernel stack memory region
348 *
349 * This defines a region of memory for use as a thread stack, for threads
350 * that exclusively run in supervisor mode. This is also suitable for
351 * declaring special stacks for interrupt or exception handling.
352 *
353 * Stacks defined with this macro may not host user mode threads.
354 *
355 * It is legal to precede this definition with the 'static' keyword.
356 *
357 * It is NOT legal to take the sizeof(sym) and pass that to the stackSize
358 * parameter of k_thread_create(), it may not be the same as the
359 * 'size' parameter. Use K_KERNEL_STACK_SIZEOF() instead.
360 *
361 * The total amount of memory allocated may be increased to accommodate
362 * fixed-size stack overflow guards.
363 *
364 * @param sym Thread stack symbol name
365 * @param size Size of the stack memory region
366 */
367 #define K_KERNEL_STACK_DEFINE(sym, size) \
368 Z_KERNEL_STACK_DEFINE_IN(sym, size, __kstackmem); \
369 K_THREAD_HW_SHADOW_STACK_DEFINE(sym, \
370 K_THREAD_HW_SHADOW_STACK_SIZE(size))
371
372 /**
373 * @brief Define a toplevel kernel stack memory region in pinned section
374 *
375 * See K_KERNEL_STACK_DEFINE() for more information and constraints.
376 *
377 * This puts the stack into the pinned noinit linker section if
378 * CONFIG_LINKER_USE_PINNED_SECTION is enabled, or else it would
379 * put the stack into the same section as K_KERNEL_STACK_DEFINE().
380 *
381 * @param sym Thread stack symbol name
382 * @param size Size of the stack memory region
383 */
384 #if defined(CONFIG_LINKER_USE_PINNED_SECTION)
385 #define K_KERNEL_PINNED_STACK_DEFINE(sym, size) \
386 Z_KERNEL_STACK_DEFINE_IN(sym, size, __pinned_noinit); \
387 K_THREAD_HW_SHADOW_STACK_DEFINE(sym, \
388 K_THREAD_HW_SHADOW_STACK_SIZE(size))
389 #else
390 #define K_KERNEL_PINNED_STACK_DEFINE(sym, size) \
391 Z_KERNEL_STACK_DEFINE_IN(sym, size, __kstackmem); \
392 K_THREAD_HW_SHADOW_STACK_DEFINE(sym, \
393 K_THREAD_HW_SHADOW_STACK_SIZE(size))
394 #endif /* CONFIG_LINKER_USE_PINNED_SECTION */
395
396 /**
397 * @brief Define a toplevel array of kernel stack memory regions
398 *
399 * Stacks defined with this macro may not host user mode threads.
400 *
401 * @param sym Kernel stack array symbol name
402 * @param nmemb Number of stacks to define
403 * @param size Size of the stack memory region
404 */
405 #define K_KERNEL_STACK_ARRAY_DEFINE(sym, nmemb, size) \
406 Z_KERNEL_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __kstackmem); \
407 K_THREAD_HW_SHADOW_STACK_ARRAY_DEFINE(sym, nmemb, size)
408
409
410 /**
411 * @brief Define a toplevel array of kernel stack memory regions in pinned section
412 *
413 * See K_KERNEL_STACK_ARRAY_DEFINE() for more information and constraints.
414 *
415 * This puts the stack into the pinned noinit linker section if
416 * CONFIG_LINKER_USE_PINNED_SECTION is enabled, or else it would
417 * put the stack into the same section as K_KERNEL_STACK_ARRAY_DEFINE().
418 *
419 * @param sym Kernel stack array symbol name
420 * @param nmemb Number of stacks to define
421 * @param size Size of the stack memory region
422 */
423 #if defined(CONFIG_LINKER_USE_PINNED_SECTION)
424 #define K_KERNEL_PINNED_STACK_ARRAY_DEFINE(sym, nmemb, size) \
425 Z_KERNEL_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __pinned_noinit); \
426 K_THREAD_HW_SHADOW_STACK_ARRAY_DEFINE(sym, nmemb, size)
427 #else
428 #define K_KERNEL_PINNED_STACK_ARRAY_DEFINE(sym, nmemb, size) \
429 Z_KERNEL_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __kstackmem); \
430 K_THREAD_HW_SHADOW_STACK_ARRAY_DEFINE(sym, nmemb, size)
431 #endif /* CONFIG_LINKER_USE_PINNED_SECTION */
432
433 /**
434 * @brief Define an embedded stack memory region
435 *
436 * Used for kernel stacks embedded within other data structures.
437 *
438 * Stacks defined with this macro may not host user mode threads.
439 * @param sym Thread stack symbol name
440 * @param size Size of the stack memory region
441 */
442 #define K_KERNEL_STACK_MEMBER(sym, size) \
443 Z_KERNEL_STACK_DEFINE_IN(sym, size,)
444
445 #define K_KERNEL_STACK_SIZEOF(sym) (sizeof(sym) - K_KERNEL_STACK_RESERVED)
446
447 /** @} */
448
K_KERNEL_STACK_BUFFER(k_thread_stack_t * sym)449 static inline char *K_KERNEL_STACK_BUFFER(k_thread_stack_t *sym)
450 {
451 return (char *)sym + K_KERNEL_STACK_RESERVED;
452 }
453 #ifndef CONFIG_USERSPACE
454 #define K_THREAD_STACK_RESERVED K_KERNEL_STACK_RESERVED
455 #define K_THREAD_STACK_SIZEOF K_KERNEL_STACK_SIZEOF
456 #define K_THREAD_STACK_LEN K_KERNEL_STACK_LEN
457 #define K_THREAD_STACK_DEFINE K_KERNEL_STACK_DEFINE
458 #define K_THREAD_STACK_ARRAY_DEFINE K_KERNEL_STACK_ARRAY_DEFINE
459 #define K_THREAD_STACK_BUFFER K_KERNEL_STACK_BUFFER
460 #define K_THREAD_STACK_DECLARE K_KERNEL_STACK_DECLARE
461 #define K_THREAD_STACK_ARRAY_DECLARE K_KERNEL_STACK_ARRAY_DECLARE
462 #define K_THREAD_PINNED_STACK_DEFINE K_KERNEL_PINNED_STACK_DEFINE
463 #define K_THREAD_PINNED_STACK_ARRAY_DEFINE \
464 K_KERNEL_PINNED_STACK_ARRAY_DEFINE
465 #else
466 /**
467 * @brief Indicate how much additional memory is reserved for stack objects
468 *
469 * Any given stack declaration may have additional memory in it for guard
470 * areas, supervisor mode stacks, or platform-specific data. This macro
471 * indicates how much space is reserved for this.
472 *
473 * This value only indicates memory that is permanently reserved in the stack
474 * object. Memory that is "borrowed" from the thread's stack buffer is never
475 * accounted for here.
476 *
477 * Reserved memory is at the beginning of the stack object. The reserved area
478 * must be appropriately sized such that the stack buffer immediately following
479 * it is correctly aligned.
480 */
481 #ifdef ARCH_THREAD_STACK_RESERVED
482 #define K_THREAD_STACK_RESERVED ((size_t)(ARCH_THREAD_STACK_RESERVED))
483 #else
484 #define K_THREAD_STACK_RESERVED ((size_t)0U)
485 #endif /* ARCH_THREAD_STACK_RESERVED */
486
487 /**
488 * @brief Properly align the lowest address of a stack object
489 *
490 * Return an alignment value for the lowest address of a stack object, taking
491 * into consideration all alignment constraints imposed by the CPU, ABI, and
492 * any memory management policies, including any alignment required by
493 * reserved platform data within the stack object. This will always be at least
494 * ARCH_STACK_PTR_ALIGN or an even multiple thereof.
495 *
496 * Depending on hardware, this is either a fixed value or a function of the
497 * provided size. The requested size is significant only if
498 * CONFIG_MPU_REQUIRES_POWER_OF_TWO_ALIGNMENT is enabled.
499 *
500 * If CONFIG_USERSPACE is enabled, this determines the alignment of stacks
501 * which may be used by user mode threads, or threads running in supervisor
502 * mode which may later drop privileges to user mode.
503 *
504 * Arches define this with ARCH_THREAD_STACK_OBJ_ALIGN().
505 *
506 * If ARCH_THREAD_STACK_OBJ_ALIGN is not defined assume ARCH_STACK_PTR_ALIGN
507 * is appropriate.
508 *
509 * @param size Requested size of the stack buffer (which could be ignored)
510 * @return Alignment of the stack object
511 */
512 #if defined(ARCH_THREAD_STACK_OBJ_ALIGN)
513 #define Z_THREAD_STACK_OBJ_ALIGN(size) \
514 ARCH_THREAD_STACK_OBJ_ALIGN(Z_THREAD_STACK_SIZE_ADJUST(size))
515 #else
516 #define Z_THREAD_STACK_OBJ_ALIGN(size) ARCH_STACK_PTR_ALIGN
517 #endif /* ARCH_THREAD_STACK_OBJ_ALIGN */
518
519 /**
520 * @brief Round up a requested stack size to satisfy constraints
521 *
522 * Given a requested stack buffer size, return an adjusted size value for
523 * the entire stack object which takes into consideration:
524 *
525 * - Reserved memory for platform data
526 * - Alignment of stack buffer bounds to CPU/ABI constraints
527 * - Alignment of stack buffer bounds to satisfy memory management hardware
528 * constraints such that a protection region can cover the stack buffer area
529 *
530 * If CONFIG_USERSPACE is enabled, this determines the size of stack objects
531 * which may be used by user mode threads, or threads running in supervisor
532 * mode which may later drop privileges to user mode.
533 *
534 * Arches define this with ARCH_THREAD_STACK_SIZE_ADJUST().
535 *
536 * If ARCH_THREAD_STACK_SIZE_ADJUST is not defined, assume rounding up to
537 * ARCH_STACK_PTR_ALIGN is appropriate.
538 *
539 * Any memory reserved for platform data is also included in the total
540 * returned.
541 *
542 * @param size Requested size of the stack buffer
543 * @return Adjusted size of the stack object
544 */
545 #if defined(ARCH_THREAD_STACK_SIZE_ADJUST)
546 #define Z_THREAD_STACK_SIZE_ADJUST(size) \
547 ARCH_THREAD_STACK_SIZE_ADJUST((size) + K_THREAD_STACK_RESERVED)
548 #else
549 #define Z_THREAD_STACK_SIZE_ADJUST(size) \
550 (ROUND_UP((size), ARCH_STACK_PTR_ALIGN) + K_THREAD_STACK_RESERVED)
551 #endif /* ARCH_THREAD_STACK_SIZE_ADJUST */
552
553 /**
554 * @addtogroup thread_stack_api
555 * @{
556 */
557
558 /**
559 * @brief Declare a reference to a thread stack
560 *
561 * This macro declares the symbol of a thread stack defined elsewhere in the
562 * current scope.
563 *
564 * @param sym Thread stack symbol name
565 * @param size Size of the stack memory region
566 */
567 #define K_THREAD_STACK_DECLARE(sym, size) \
568 extern struct z_thread_stack_element \
569 sym[K_THREAD_STACK_LEN(size)]
570
571 /**
572 * @brief Declare a reference to a thread stack array
573 *
574 * This macro declares the symbol of a thread stack array defined elsewhere in
575 * the current scope.
576 *
577 * @param sym Thread stack symbol name
578 * @param nmemb Number of stacks defined
579 * @param size Size of the stack memory region
580 */
581 #define K_THREAD_STACK_ARRAY_DECLARE(sym, nmemb, size) \
582 extern struct z_thread_stack_element \
583 sym[nmemb][K_THREAD_STACK_LEN(size)]
584
585 /**
586 * @brief Return the size in bytes of a stack memory region
587 *
588 * Convenience macro for passing the desired stack size to k_thread_create()
589 * since the underlying implementation may actually create something larger
590 * (for instance a guard area).
591 *
592 * The value returned here is not guaranteed to match the 'size' parameter
593 * passed to K_THREAD_STACK_DEFINE and may be larger, but is always safe to
594 * pass to k_thread_create() for the associated stack object.
595 *
596 * @param sym Stack memory symbol
597 * @return Size of the stack buffer
598 */
599 #define K_THREAD_STACK_SIZEOF(sym) (sizeof(sym) - K_THREAD_STACK_RESERVED)
600
601 /**
602 * @brief Define a toplevel thread stack memory region in specified region
603 *
604 * This defines a region of memory suitable for use as a thread's stack
605 * in specified region.
606 *
607 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
608 * and put in 'noinit' section so that it isn't zeroed at boot
609 *
610 * The defined symbol will always be a k_thread_stack_t which can be passed to
611 * k_thread_create(), but should otherwise not be manipulated. If the buffer
612 * inside needs to be examined, examine thread->stack_info for the associated
613 * thread object to obtain the boundaries.
614 *
615 * It is legal to precede this definition with the 'static' keyword.
616 *
617 * It is NOT legal to take the sizeof(sym) and pass that to the stackSize
618 * parameter of k_thread_create(), it may not be the same as the
619 * 'size' parameter. Use K_THREAD_STACK_SIZEOF() instead.
620 *
621 * Some arches may round the size of the usable stack region up to satisfy
622 * alignment constraints. K_THREAD_STACK_SIZEOF() will return the aligned
623 * size.
624 *
625 * @param sym Thread stack symbol name
626 * @param size Size of the stack memory region
627 * @param lsect Linker section for this stack
628 */
629 #define Z_THREAD_STACK_DEFINE_IN(sym, size, lsect) \
630 struct z_thread_stack_element lsect \
631 __aligned(Z_THREAD_STACK_OBJ_ALIGN(size)) \
632 sym[K_THREAD_STACK_LEN(size)]
633
634 /**
635 * @brief Define a toplevel array of thread stack memory regions in specified region
636 *
637 * Create an array of equally sized stacks. See Z_THREAD_STACK_DEFINE_IN
638 * definition for additional details and constraints.
639 *
640 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
641 * and put in specified section so that it isn't zeroed at boot
642 *
643 * @param sym Thread stack symbol name
644 * @param nmemb Number of stacks to define
645 * @param size Size of the stack memory region
646 * @param lsect Linker section for this stack
647 */
648 #define Z_THREAD_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, lsect) \
649 struct z_thread_stack_element lsect \
650 __aligned(Z_THREAD_STACK_OBJ_ALIGN(size)) \
651 sym[nmemb][K_THREAD_STACK_LEN(size)]
652
653 /**
654 * @brief Define a toplevel thread stack memory region
655 *
656 * This defines a region of memory suitable for use as a thread's stack.
657 *
658 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
659 * and put in 'noinit' section so that it isn't zeroed at boot
660 *
661 * The defined symbol will always be a k_thread_stack_t which can be passed to
662 * k_thread_create(), but should otherwise not be manipulated. If the buffer
663 * inside needs to be examined, examine thread->stack_info for the associated
664 * thread object to obtain the boundaries.
665 *
666 * It is legal to precede this definition with the 'static' keyword.
667 *
668 * It is NOT legal to take the sizeof(sym) and pass that to the stackSize
669 * parameter of k_thread_create(), it may not be the same as the
670 * 'size' parameter. Use K_THREAD_STACK_SIZEOF() instead.
671 *
672 * Some arches may round the size of the usable stack region up to satisfy
673 * alignment constraints. K_THREAD_STACK_SIZEOF() will return the aligned
674 * size.
675 *
676 * @param sym Thread stack symbol name
677 * @param size Size of the stack memory region
678 */
679 #define K_THREAD_STACK_DEFINE(sym, size) \
680 Z_THREAD_STACK_DEFINE_IN(sym, size, __stackmem)
681
682 /**
683 * @brief Define a toplevel thread stack memory region in pinned section
684 *
685 * This defines a region of memory suitable for use as a thread's stack.
686 *
687 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
688 * and put in 'noinit' section so that it isn't zeroed at boot
689 *
690 * The defined symbol will always be a k_thread_stack_t which can be passed to
691 * k_thread_create(), but should otherwise not be manipulated. If the buffer
692 * inside needs to be examined, examine thread->stack_info for the associated
693 * thread object to obtain the boundaries.
694 *
695 * It is legal to precede this definition with the 'static' keyword.
696 *
697 * It is NOT legal to take the sizeof(sym) and pass that to the stackSize
698 * parameter of k_thread_create(), it may not be the same as the
699 * 'size' parameter. Use K_THREAD_STACK_SIZEOF() instead.
700 *
701 * Some arches may round the size of the usable stack region up to satisfy
702 * alignment constraints. K_THREAD_STACK_SIZEOF() will return the aligned
703 * size.
704 *
705 * This puts the stack into the pinned noinit linker section if
706 * CONFIG_LINKER_USE_PINNED_SECTION is enabled, or else it would
707 * put the stack into the same section as K_THREAD_STACK_DEFINE().
708 *
709 * @param sym Thread stack symbol name
710 * @param size Size of the stack memory region
711 */
712 #if defined(CONFIG_LINKER_USE_PINNED_SECTION)
713 #define K_THREAD_PINNED_STACK_DEFINE(sym, size) \
714 Z_THREAD_STACK_DEFINE_IN(sym, size, __pinned_noinit)
715 #else
716 #define K_THREAD_PINNED_STACK_DEFINE(sym, size) \
717 K_THREAD_STACK_DEFINE(sym, size)
718 #endif /* CONFIG_LINKER_USE_PINNED_SECTION */
719
720 /**
721 * @brief Calculate size of stacks to be allocated in a stack array
722 *
723 * This macro calculates the size to be allocated for the stacks
724 * inside a stack array. It accepts the indicated "size" as a parameter
725 * and if required, pads some extra bytes (e.g. for MPU scenarios). Refer
726 * K_THREAD_STACK_ARRAY_DEFINE definition to see how this is used.
727 * The returned size ensures each array member will be aligned to the
728 * required stack base alignment.
729 *
730 * @param size Size of the stack memory region
731 * @return Appropriate size for an array member
732 */
733 #define K_THREAD_STACK_LEN(size) \
734 ROUND_UP(Z_THREAD_STACK_SIZE_ADJUST(size), \
735 Z_THREAD_STACK_OBJ_ALIGN(size))
736
737 /**
738 * @brief Define a toplevel array of thread stack memory regions
739 *
740 * Create an array of equally sized stacks. See K_THREAD_STACK_DEFINE
741 * definition for additional details and constraints.
742 *
743 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
744 * and put in 'noinit' section so that it isn't zeroed at boot
745 *
746 * @param sym Thread stack symbol name
747 * @param nmemb Number of stacks to define
748 * @param size Size of the stack memory region
749 */
750 #define K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size) \
751 Z_THREAD_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __stackmem)
752
753 /**
754 * @brief Define a toplevel array of thread stack memory regions in pinned section
755 *
756 * Create an array of equally sized stacks. See K_THREAD_STACK_DEFINE
757 * definition for additional details and constraints.
758 *
759 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
760 * and put in 'noinit' section so that it isn't zeroed at boot
761 *
762 * This puts the stack into the pinned noinit linker section if
763 * CONFIG_LINKER_USE_PINNED_SECTION is enabled, or else it would
764 * put the stack into the same section as K_THREAD_STACK_DEFINE().
765 *
766 * @param sym Thread stack symbol name
767 * @param nmemb Number of stacks to define
768 * @param size Size of the stack memory region
769 */
770 #if defined(CONFIG_LINKER_USE_PINNED_SECTION)
771 #define K_THREAD_PINNED_STACK_ARRAY_DEFINE(sym, nmemb, size) \
772 Z_THREAD_PINNED_STACK_DEFINE_IN(sym, nmemb, size, __pinned_noinit)
773 #else
774 #define K_THREAD_PINNED_STACK_ARRAY_DEFINE(sym, nmemb, size) \
775 K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size)
776 #endif /* CONFIG_LINKER_USE_PINNED_SECTION */
777
778 /** @} */
779
780 /**
781 * @brief Get a pointer to the physical stack buffer
782 *
783 * Obtain a pointer to the non-reserved area of a stack object.
784 * This is not guaranteed to be the beginning of the thread-writable region;
785 * this does not account for any memory carved-out for MPU stack overflow
786 * guards.
787 *
788 * Use with care. The true bounds of the stack buffer are available in the
789 * stack_info member of its associated thread.
790 *
791 * @param sym defined stack symbol name
792 * @return The buffer itself, a char *
793 */
K_THREAD_STACK_BUFFER(k_thread_stack_t * sym)794 static inline char *K_THREAD_STACK_BUFFER(k_thread_stack_t *sym)
795 {
796 return (char *)sym + K_THREAD_STACK_RESERVED;
797 }
798
799 #endif /* CONFIG_USERSPACE */
800
801 #ifdef __cplusplus
802 }
803 #endif
804
805 #endif /* _ASMLANGUAGE */
806 #endif /* ZEPHYR_INCLUDE_KERNEL_THREAD_STACK_H */
807
