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 /**
116 * @brief Declare a reference to a thread stack
117 *
118 * This macro declares the symbol of a thread stack defined elsewhere in the
119 * current scope.
120 *
121 * @param sym Thread stack symbol name
122 * @param size Size of the stack memory region
123 */
124 #define K_KERNEL_STACK_DECLARE(sym, size) \
125 extern struct z_thread_stack_element \
126 sym[K_KERNEL_STACK_LEN(size)]
127
128 /**
129 * @brief Declare a reference to a thread stack array
130 *
131 * This macro declares the symbol of a thread stack array defined elsewhere in
132 * the current scope.
133 *
134 * @param sym Thread stack symbol name
135 * @param nmemb Number of stacks defined
136 * @param size Size of the stack memory region
137 */
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
142 /**
143 * @brief Declare a reference to a pinned thread stack array
144 *
145 * This macro declares the symbol of a pinned thread stack array defined
146 * elsewhere in the current scope.
147 *
148 * @param sym Thread stack symbol name
149 * @param nmemb Number of stacks defined
150 * @param size Size of the stack memory region
151 */
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
156 /**
157 * @brief Define a toplevel kernel stack memory region in specified section
158 *
159 * This defines a region of memory for use as a thread stack in
160 * the specified linker section.
161 *
162 * It is legal to precede this definition with the 'static' keyword.
163 *
164 * It is NOT legal to take the sizeof(sym) and pass that to the stackSize
165 * parameter of k_thread_create(), it may not be the same as the
166 * 'size' parameter. Use K_KERNEL_STACK_SIZEOF() instead.
167 *
168 * The total amount of memory allocated may be increased to accommodate
169 * fixed-size stack overflow guards.
170 *
171 * @param sym Thread stack symbol name
172 * @param size Size of the stack memory region
173 * @param lsect Linker section for this stack
174 */
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
180 /**
181 * @brief Define a toplevel array of kernel stack memory regions in specified section
182 *
183 * @param sym Kernel stack array symbol name
184 * @param nmemb Number of stacks to define
185 * @param size Size of the stack memory region
186 * @param lsect Linker section for this array of stacks
187 */
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
193 /**
194 * @brief Define a toplevel kernel stack memory region
195 *
196 * This defines a region of memory for use as a thread stack, for threads
197 * that exclusively run in supervisor mode. This is also suitable for
198 * declaring special stacks for interrupt or exception handling.
199 *
200 * Stacks defined with this macro may not host user mode threads.
201 *
202 * It is legal to precede this definition with the 'static' keyword.
203 *
204 * It is NOT legal to take the sizeof(sym) and pass that to the stackSize
205 * parameter of k_thread_create(), it may not be the same as the
206 * 'size' parameter. Use K_KERNEL_STACK_SIZEOF() instead.
207 *
208 * The total amount of memory allocated may be increased to accommodate
209 * fixed-size stack overflow guards.
210 *
211 * @param sym Thread stack symbol name
212 * @param size Size of the stack memory region
213 */
214 #define K_KERNEL_STACK_DEFINE(sym, size) \
215 Z_KERNEL_STACK_DEFINE_IN(sym, size, __kstackmem)
216
217 /**
218 * @brief Define a toplevel kernel stack memory region in pinned section
219 *
220 * See K_KERNEL_STACK_DEFINE() for more information and constraints.
221 *
222 * This puts the stack into the pinned noinit linker section if
223 * CONFIG_LINKER_USE_PINNED_SECTION is enabled, or else it would
224 * put the stack into the same section as K_KERNEL_STACK_DEFINE().
225 *
226 * @param sym Thread stack symbol name
227 * @param size Size of the stack memory region
228 */
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
237 /**
238 * @brief Define a toplevel array of kernel stack memory regions
239 *
240 * Stacks defined with this macro may not host user mode threads.
241 *
242 * @param sym Kernel stack array symbol name
243 * @param nmemb Number of stacks to define
244 * @param size Size of the stack memory region
245 */
246 #define K_KERNEL_STACK_ARRAY_DEFINE(sym, nmemb, size) \
247 Z_KERNEL_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __kstackmem)
248
249 /**
250 * @brief Define a toplevel array of kernel stack memory regions in pinned section
251 *
252 * See K_KERNEL_STACK_ARRAY_DEFINE() for more information and constraints.
253 *
254 * This puts the stack into the pinned noinit linker section if
255 * CONFIG_LINKER_USE_PINNED_SECTION is enabled, or else it would
256 * put the stack into the same section as K_KERNEL_STACK_ARRAY_DEFINE().
257 *
258 * @param sym Kernel stack array symbol name
259 * @param nmemb Number of stacks to define
260 * @param size Size of the stack memory region
261 */
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
270 /**
271 * @brief Define an embedded stack memory region
272 *
273 * Used for kernel stacks embedded within other data structures.
274 *
275 * Stacks defined with this macro may not host user mode threads.
276 * @param sym Thread stack symbol name
277 * @param size Size of the stack memory region
278 */
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
284 /** @} */
285
K_KERNEL_STACK_BUFFER(k_thread_stack_t * sym)286 static inline char *K_KERNEL_STACK_BUFFER(k_thread_stack_t *sym)
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_BUFFER K_KERNEL_STACK_BUFFER
297 #define K_THREAD_STACK_DECLARE K_KERNEL_STACK_DECLARE
298 #define K_THREAD_STACK_ARRAY_DECLARE K_KERNEL_STACK_ARRAY_DECLARE
299 #define K_THREAD_PINNED_STACK_DEFINE K_KERNEL_PINNED_STACK_DEFINE
300 #define K_THREAD_PINNED_STACK_ARRAY_DEFINE \
301 K_KERNEL_PINNED_STACK_ARRAY_DEFINE
302 #else
303 /**
304 * @brief Indicate how much additional memory is reserved for stack objects
305 *
306 * Any given stack declaration may have additional memory in it for guard
307 * areas, supervisor mode stacks, or platform-specific data. This macro
308 * indicates how much space is reserved for this.
309 *
310 * This value only indicates memory that is permanently reserved in the stack
311 * object. Memory that is "borrowed" from the thread's stack buffer is never
312 * accounted for here.
313 *
314 * Reserved memory is at the beginning of the stack object. The reserved area
315 * must be appropriately sized such that the stack buffer immediately following
316 * it is correctly aligned.
317 */
318 #ifdef ARCH_THREAD_STACK_RESERVED
319 #define K_THREAD_STACK_RESERVED ((size_t)(ARCH_THREAD_STACK_RESERVED))
320 #else
321 #define K_THREAD_STACK_RESERVED ((size_t)0U)
322 #endif /* ARCH_THREAD_STACK_RESERVED */
323
324 /**
325 * @brief Properly align the lowest address of a stack object
326 *
327 * Return an alignment value for the lowest address of a stack object, taking
328 * into consideration all alignment constraints imposed by the CPU, ABI, and
329 * any memory management policies, including any alignment required by
330 * reserved platform data within the stack object. This will always be at least
331 * ARCH_STACK_PTR_ALIGN or an even multiple thereof.
332 *
333 * Depending on hardware, this is either a fixed value or a function of the
334 * provided size. The requested size is significant only if
335 * CONFIG_MPU_REQUIRES_POWER_OF_TWO_ALIGNMENT is enabled.
336 *
337 * If CONFIG_USERSPACE is enabled, this determines the alignment of stacks
338 * which may be used by user mode threads, or threads running in supervisor
339 * mode which may later drop privileges to user mode.
340 *
341 * Arches define this with ARCH_THREAD_STACK_OBJ_ALIGN().
342 *
343 * If ARCH_THREAD_STACK_OBJ_ALIGN is not defined assume ARCH_STACK_PTR_ALIGN
344 * is appropriate.
345 *
346 * @param size Requested size of the stack buffer (which could be ignored)
347 * @return Alignment of the stack object
348 */
349 #if defined(ARCH_THREAD_STACK_OBJ_ALIGN)
350 #define Z_THREAD_STACK_OBJ_ALIGN(size) \
351 ARCH_THREAD_STACK_OBJ_ALIGN(Z_THREAD_STACK_SIZE_ADJUST(size))
352 #else
353 #define Z_THREAD_STACK_OBJ_ALIGN(size) ARCH_STACK_PTR_ALIGN
354 #endif /* ARCH_THREAD_STACK_OBJ_ALIGN */
355
356 /**
357 * @brief Round up a requested stack size to satisfy constraints
358 *
359 * Given a requested stack buffer size, return an adjusted size value for
360 * the entire stack object which takes into consideration:
361 *
362 * - Reserved memory for platform data
363 * - Alignment of stack buffer bounds to CPU/ABI constraints
364 * - Alignment of stack buffer bounds to satisfy memory management hardware
365 * constraints such that a protection region can cover the stack buffer area
366 *
367 * If CONFIG_USERSPACE is enabled, this determines the size of stack objects
368 * which may be used by user mode threads, or threads running in supervisor
369 * mode which may later drop privileges to user mode.
370 *
371 * Arches define this with ARCH_THREAD_STACK_SIZE_ADJUST().
372 *
373 * If ARCH_THREAD_STACK_SIZE_ADJUST is not defined, assume rounding up to
374 * ARCH_STACK_PTR_ALIGN is appropriate.
375 *
376 * Any memory reserved for platform data is also included in the total
377 * returned.
378 *
379 * @param size Requested size of the stack buffer
380 * @return Adjusted size of the stack object
381 */
382 #if defined(ARCH_THREAD_STACK_SIZE_ADJUST)
383 #define Z_THREAD_STACK_SIZE_ADJUST(size) \
384 ARCH_THREAD_STACK_SIZE_ADJUST((size) + K_THREAD_STACK_RESERVED)
385 #else
386 #define Z_THREAD_STACK_SIZE_ADJUST(size) \
387 (ROUND_UP((size), ARCH_STACK_PTR_ALIGN) + K_THREAD_STACK_RESERVED)
388 #endif /* ARCH_THREAD_STACK_SIZE_ADJUST */
389
390 /**
391 * @addtogroup thread_stack_api
392 * @{
393 */
394
395 /**
396 * @brief Declare a reference to a thread stack
397 *
398 * This macro declares the symbol of a thread stack defined elsewhere in the
399 * current scope.
400 *
401 * @param sym Thread stack symbol name
402 * @param size Size of the stack memory region
403 */
404 #define K_THREAD_STACK_DECLARE(sym, size) \
405 extern struct z_thread_stack_element \
406 sym[K_THREAD_STACK_LEN(size)]
407
408 /**
409 * @brief Declare a reference to a thread stack array
410 *
411 * This macro declares the symbol of a thread stack array defined elsewhere in
412 * the current scope.
413 *
414 * @param sym Thread stack symbol name
415 * @param nmemb Number of stacks defined
416 * @param size Size of the stack memory region
417 */
418 #define K_THREAD_STACK_ARRAY_DECLARE(sym, nmemb, size) \
419 extern struct z_thread_stack_element \
420 sym[nmemb][K_THREAD_STACK_LEN(size)]
421
422 /**
423 * @brief Return the size in bytes of a stack memory region
424 *
425 * Convenience macro for passing the desired stack size to k_thread_create()
426 * since the underlying implementation may actually create something larger
427 * (for instance a guard area).
428 *
429 * The value returned here is not guaranteed to match the 'size' parameter
430 * passed to K_THREAD_STACK_DEFINE and may be larger, but is always safe to
431 * pass to k_thread_create() for the associated stack object.
432 *
433 * @param sym Stack memory symbol
434 * @return Size of the stack buffer
435 */
436 #define K_THREAD_STACK_SIZEOF(sym) (sizeof(sym) - K_THREAD_STACK_RESERVED)
437
438 /**
439 * @brief Define a toplevel thread stack memory region in specified region
440 *
441 * This defines a region of memory suitable for use as a thread's stack
442 * in specified region.
443 *
444 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
445 * and put in 'noinit' section so that it isn't zeroed at boot
446 *
447 * The defined symbol will always be a k_thread_stack_t which can be passed to
448 * k_thread_create(), but should otherwise not be manipulated. If the buffer
449 * inside needs to be examined, examine thread->stack_info for the associated
450 * thread object to obtain the boundaries.
451 *
452 * It is legal to precede this definition with the 'static' keyword.
453 *
454 * It is NOT legal to take the sizeof(sym) and pass that to the stackSize
455 * parameter of k_thread_create(), it may not be the same as the
456 * 'size' parameter. Use K_THREAD_STACK_SIZEOF() instead.
457 *
458 * Some arches may round the size of the usable stack region up to satisfy
459 * alignment constraints. K_THREAD_STACK_SIZEOF() will return the aligned
460 * size.
461 *
462 * @param sym Thread stack symbol name
463 * @param size Size of the stack memory region
464 * @param lsect Linker section for this stack
465 */
466 #define Z_THREAD_STACK_DEFINE_IN(sym, size, lsect) \
467 struct z_thread_stack_element lsect \
468 __aligned(Z_THREAD_STACK_OBJ_ALIGN(size)) \
469 sym[K_THREAD_STACK_LEN(size)]
470
471 /**
472 * @brief Define a toplevel array of thread stack memory regions in specified region
473 *
474 * Create an array of equally sized stacks. See Z_THREAD_STACK_DEFINE_IN
475 * definition for additional details and constraints.
476 *
477 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
478 * and put in specified section so that it isn't zeroed at boot
479 *
480 * @param sym Thread stack symbol name
481 * @param nmemb Number of stacks to define
482 * @param size Size of the stack memory region
483 * @param lsect Linker section for this stack
484 */
485 #define Z_THREAD_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, lsect) \
486 struct z_thread_stack_element lsect \
487 __aligned(Z_THREAD_STACK_OBJ_ALIGN(size)) \
488 sym[nmemb][K_THREAD_STACK_LEN(size)]
489
490 /**
491 * @brief Define a toplevel thread stack memory region
492 *
493 * This defines a region of memory suitable for use as a thread's stack.
494 *
495 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
496 * and put in 'noinit' section so that it isn't zeroed at boot
497 *
498 * The defined symbol will always be a k_thread_stack_t which can be passed to
499 * k_thread_create(), but should otherwise not be manipulated. If the buffer
500 * inside needs to be examined, examine thread->stack_info for the associated
501 * thread object to obtain the boundaries.
502 *
503 * It is legal to precede this definition with the 'static' keyword.
504 *
505 * It is NOT legal to take the sizeof(sym) and pass that to the stackSize
506 * parameter of k_thread_create(), it may not be the same as the
507 * 'size' parameter. Use K_THREAD_STACK_SIZEOF() instead.
508 *
509 * Some arches may round the size of the usable stack region up to satisfy
510 * alignment constraints. K_THREAD_STACK_SIZEOF() will return the aligned
511 * size.
512 *
513 * @param sym Thread stack symbol name
514 * @param size Size of the stack memory region
515 */
516 #define K_THREAD_STACK_DEFINE(sym, size) \
517 Z_THREAD_STACK_DEFINE_IN(sym, size, __stackmem)
518
519 /**
520 * @brief Define a toplevel thread stack memory region in pinned section
521 *
522 * This defines a region of memory suitable for use as a thread's stack.
523 *
524 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
525 * and put in 'noinit' section so that it isn't zeroed at boot
526 *
527 * The defined symbol will always be a k_thread_stack_t which can be passed to
528 * k_thread_create(), but should otherwise not be manipulated. If the buffer
529 * inside needs to be examined, examine thread->stack_info for the associated
530 * thread object to obtain the boundaries.
531 *
532 * It is legal to precede this definition with the 'static' keyword.
533 *
534 * It is NOT legal to take the sizeof(sym) and pass that to the stackSize
535 * parameter of k_thread_create(), it may not be the same as the
536 * 'size' parameter. Use K_THREAD_STACK_SIZEOF() instead.
537 *
538 * Some arches may round the size of the usable stack region up to satisfy
539 * alignment constraints. K_THREAD_STACK_SIZEOF() will return the aligned
540 * size.
541 *
542 * This puts the stack into the pinned noinit linker section if
543 * CONFIG_LINKER_USE_PINNED_SECTION is enabled, or else it would
544 * put the stack into the same section as K_THREAD_STACK_DEFINE().
545 *
546 * @param sym Thread stack symbol name
547 * @param size Size of the stack memory region
548 */
549 #if defined(CONFIG_LINKER_USE_PINNED_SECTION)
550 #define K_THREAD_PINNED_STACK_DEFINE(sym, size) \
551 Z_THREAD_STACK_DEFINE_IN(sym, size, __pinned_noinit)
552 #else
553 #define K_THREAD_PINNED_STACK_DEFINE(sym, size) \
554 K_THREAD_STACK_DEFINE(sym, size)
555 #endif /* CONFIG_LINKER_USE_PINNED_SECTION */
556
557 /**
558 * @brief Calculate size of stacks to be allocated in a stack array
559 *
560 * This macro calculates the size to be allocated for the stacks
561 * inside a stack array. It accepts the indicated "size" as a parameter
562 * and if required, pads some extra bytes (e.g. for MPU scenarios). Refer
563 * K_THREAD_STACK_ARRAY_DEFINE definition to see how this is used.
564 * The returned size ensures each array member will be aligned to the
565 * required stack base alignment.
566 *
567 * @param size Size of the stack memory region
568 * @return Appropriate size for an array member
569 */
570 #define K_THREAD_STACK_LEN(size) \
571 ROUND_UP(Z_THREAD_STACK_SIZE_ADJUST(size), \
572 Z_THREAD_STACK_OBJ_ALIGN(size))
573
574 /**
575 * @brief Define a toplevel array of thread stack memory regions
576 *
577 * Create an array of equally sized stacks. See K_THREAD_STACK_DEFINE
578 * definition for additional details and constraints.
579 *
580 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
581 * and put in 'noinit' section so that it isn't zeroed at boot
582 *
583 * @param sym Thread stack symbol name
584 * @param nmemb Number of stacks to define
585 * @param size Size of the stack memory region
586 */
587 #define K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size) \
588 Z_THREAD_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __stackmem)
589
590 /**
591 * @brief Define a toplevel array of thread stack memory regions in pinned section
592 *
593 * Create an array of equally sized stacks. See K_THREAD_STACK_DEFINE
594 * definition for additional details and constraints.
595 *
596 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
597 * and put in 'noinit' section so that it isn't zeroed at boot
598 *
599 * This puts the stack into the pinned noinit linker section if
600 * CONFIG_LINKER_USE_PINNED_SECTION is enabled, or else it would
601 * put the stack into the same section as K_THREAD_STACK_DEFINE().
602 *
603 * @param sym Thread stack symbol name
604 * @param nmemb Number of stacks to define
605 * @param size Size of the stack memory region
606 */
607 #if defined(CONFIG_LINKER_USE_PINNED_SECTION)
608 #define K_THREAD_PINNED_STACK_ARRAY_DEFINE(sym, nmemb, size) \
609 Z_THREAD_PINNED_STACK_DEFINE_IN(sym, nmemb, size, __pinned_noinit)
610 #else
611 #define K_THREAD_PINNED_STACK_ARRAY_DEFINE(sym, nmemb, size) \
612 K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size)
613 #endif /* CONFIG_LINKER_USE_PINNED_SECTION */
614
615 /** @} */
616
617 /**
618 * @brief Get a pointer to the physical stack buffer
619 *
620 * Obtain a pointer to the non-reserved area of a stack object.
621 * This is not guaranteed to be the beginning of the thread-writable region;
622 * this does not account for any memory carved-out for MPU stack overflow
623 * guards.
624 *
625 * Use with care. The true bounds of the stack buffer are available in the
626 * stack_info member of its associated thread.
627 *
628 * @param sym defined stack symbol name
629 * @return The buffer itself, a char *
630 */
K_THREAD_STACK_BUFFER(k_thread_stack_t * sym)631 static inline char *K_THREAD_STACK_BUFFER(k_thread_stack_t *sym)
632 {
633 return (char *)sym + K_THREAD_STACK_RESERVED;
634 }
635
636 #endif /* CONFIG_USERSPACE */
637
638 #ifdef __cplusplus
639 }
640 #endif
641
642 #endif /* _ASMLANGUAGE */
643 #endif /* ZEPHYR_INCLUDE_KERNEL_THREAD_STACK_H */
644
