Line data Source code
1 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 : */
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 0 : #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 0 : #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 0 : #define K_KERNEL_HW_SHADOW_STACK_DECLARE(sym, size)
260 0 : #define K_KERNEL_HW_SHADOW_STACK_ARRAY_DECLARE(sym, nmemb, size)
261 0 : #define K_THREAD_HW_SHADOW_STACK_DEFINE(sym, size)
262 0 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #define K_KERNEL_STACK_MEMBER(sym, size) \
443 : Z_KERNEL_STACK_DEFINE_IN(sym, size,)
444 :
445 0 : #define K_KERNEL_STACK_SIZEOF(sym) (sizeof(sym) - K_KERNEL_STACK_RESERVED)
446 :
447 : /** @} */
448 :
449 0 : 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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 : */
794 1 : 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 */
|
