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_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
304 /**
305 * @brief Indicate how much additional memory is reserved for stack objects
306 *
307 * Any given stack declaration may have additional memory in it for guard
308 * areas, supervisor mode stacks, or platform-specific data. This macro
309 * indicates how much space is reserved for this.
310 *
311 * This value only indicates memory that is permanently reserved in the stack
312 * object. Memory that is "borrowed" from the thread's stack buffer is never
313 * accounted for here.
314 *
315 * Reserved memory is at the beginning of the stack object. The reserved area
316 * must be appropriately sized such that the stack buffer immediately following
317 * it is correctly aligned.
318 */
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
325 /**
326 * @brief Properly align the lowest address of a stack object
327 *
328 * Return an alignment value for the lowest address of a stack object, taking
329 * into consideration all alignment constraints imposed by the CPU, ABI, and
330 * any memory management policies, including any alignment required by
331 * reserved platform data within the stack object. This will always be at least
332 * ARCH_STACK_PTR_ALIGN or an even multiple thereof.
333 *
334 * Depending on hardware, this is either a fixed value or a function of the
335 * provided size. The requested size is significant only if
336 * CONFIG_MPU_REQUIRES_POWER_OF_TWO_ALIGNMENT is enabled.
337 *
338 * If CONFIG_USERSPACE is enabled, this determines the alignment of stacks
339 * which may be used by user mode threads, or threads running in supervisor
340 * mode which may later drop privileges to user mode.
341 *
342 * Arches define this with ARCH_THREAD_STACK_OBJ_ALIGN().
343 *
344 * If ARCH_THREAD_STACK_OBJ_ALIGN is not defined assume ARCH_STACK_PTR_ALIGN
345 * is appropriate.
346 *
347 * @param size Requested size of the stack buffer (which could be ignored)
348 * @return Alignment of the stack object
349 */
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
357 /**
358 * @brief Round up a requested stack size to satisfy constraints
359 *
360 * Given a requested stack buffer size, return an adjusted size value for
361 * the entire stack object which takes into consideration:
362 *
363 * - Reserved memory for platform data
364 * - Alignment of stack buffer bounds to CPU/ABI constraints
365 * - Alignment of stack buffer bounds to satisfy memory management hardware
366 * constraints such that a protection region can cover the stack buffer area
367 *
368 * If CONFIG_USERSPACE is enabled, this determines the size of stack objects
369 * which may be used by user mode threads, or threads running in supervisor
370 * mode which may later drop privileges to user mode.
371 *
372 * Arches define this with ARCH_THREAD_STACK_SIZE_ADJUST().
373 *
374 * If ARCH_THREAD_STACK_SIZE_ADJUST is not defined, assume rounding up to
375 * ARCH_STACK_PTR_ALIGN is appropriate.
376 *
377 * Any memory reserved for platform data is also included in the total
378 * returned.
379 *
380 * @param size Requested size of the stack buffer
381 * @return Adjusted size of the stack object
382 */
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
391 /**
392 * @addtogroup thread_stack_api
393 * @{
394 */
395
396 /**
397 * @brief Declare a reference to a thread stack
398 *
399 * This macro declares the symbol of a thread stack defined elsewhere in the
400 * current scope.
401 *
402 * @param sym Thread stack symbol name
403 * @param size Size of the stack memory region
404 */
405 #define K_THREAD_STACK_DECLARE(sym, size) \
406 extern struct z_thread_stack_element \
407 sym[K_THREAD_STACK_LEN(size)]
408
409 /**
410 * @brief Declare a reference to a thread stack array
411 *
412 * This macro declares the symbol of a thread stack array defined elsewhere in
413 * the current scope.
414 *
415 * @param sym Thread stack symbol name
416 * @param nmemb Number of stacks defined
417 * @param size Size of the stack memory region
418 */
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
423 /**
424 * @brief Return the size in bytes of a stack memory region
425 *
426 * Convenience macro for passing the desired stack size to k_thread_create()
427 * since the underlying implementation may actually create something larger
428 * (for instance a guard area).
429 *
430 * The value returned here is not guaranteed to match the 'size' parameter
431 * passed to K_THREAD_STACK_DEFINE and may be larger, but is always safe to
432 * pass to k_thread_create() for the associated stack object.
433 *
434 * @param sym Stack memory symbol
435 * @return Size of the stack buffer
436 */
437 #define K_THREAD_STACK_SIZEOF(sym) (sizeof(sym) - K_THREAD_STACK_RESERVED)
438
439 /**
440 * @brief Define a toplevel thread stack memory region in specified region
441 *
442 * This defines a region of memory suitable for use as a thread's stack
443 * in specified region.
444 *
445 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
446 * and put in 'noinit' section so that it isn't zeroed at boot
447 *
448 * The defined symbol will always be a k_thread_stack_t which can be passed to
449 * k_thread_create(), but should otherwise not be manipulated. If the buffer
450 * inside needs to be examined, examine thread->stack_info for the associated
451 * thread object to obtain the boundaries.
452 *
453 * It is legal to precede this definition with the 'static' keyword.
454 *
455 * It is NOT legal to take the sizeof(sym) and pass that to the stackSize
456 * parameter of k_thread_create(), it may not be the same as the
457 * 'size' parameter. Use K_THREAD_STACK_SIZEOF() instead.
458 *
459 * Some arches may round the size of the usable stack region up to satisfy
460 * alignment constraints. K_THREAD_STACK_SIZEOF() will return the aligned
461 * size.
462 *
463 * @param sym Thread stack symbol name
464 * @param size Size of the stack memory region
465 * @param lsect Linker section for this stack
466 */
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
472 /**
473 * @brief Define a toplevel array of thread stack memory regions in specified region
474 *
475 * Create an array of equally sized stacks. See Z_THREAD_STACK_DEFINE_IN
476 * definition for additional details and constraints.
477 *
478 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
479 * and put in specified section so that it isn't zeroed at boot
480 *
481 * @param sym Thread stack symbol name
482 * @param nmemb Number of stacks to define
483 * @param size Size of the stack memory region
484 * @param lsect Linker section for this stack
485 */
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
491 /**
492 * @brief Define a toplevel thread stack memory region
493 *
494 * This defines a region of memory suitable for use as a thread's stack.
495 *
496 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
497 * and put in 'noinit' section so that it isn't zeroed at boot
498 *
499 * The defined symbol will always be a k_thread_stack_t which can be passed to
500 * k_thread_create(), but should otherwise not be manipulated. If the buffer
501 * inside needs to be examined, examine thread->stack_info for the associated
502 * thread object to obtain the boundaries.
503 *
504 * It is legal to precede this definition with the 'static' keyword.
505 *
506 * It is NOT legal to take the sizeof(sym) and pass that to the stackSize
507 * parameter of k_thread_create(), it may not be the same as the
508 * 'size' parameter. Use K_THREAD_STACK_SIZEOF() instead.
509 *
510 * Some arches may round the size of the usable stack region up to satisfy
511 * alignment constraints. K_THREAD_STACK_SIZEOF() will return the aligned
512 * size.
513 *
514 * @param sym Thread stack symbol name
515 * @param size Size of the stack memory region
516 */
517 #define K_THREAD_STACK_DEFINE(sym, size) \
518 Z_THREAD_STACK_DEFINE_IN(sym, size, __stackmem)
519
520 /**
521 * @brief Define a toplevel thread stack memory region in pinned section
522 *
523 * This defines a region of memory suitable for use as a thread's stack.
524 *
525 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
526 * and put in 'noinit' section so that it isn't zeroed at boot
527 *
528 * The defined symbol will always be a k_thread_stack_t which can be passed to
529 * k_thread_create(), but should otherwise not be manipulated. If the buffer
530 * inside needs to be examined, examine thread->stack_info for the associated
531 * thread object to obtain the boundaries.
532 *
533 * It is legal to precede this definition with the 'static' keyword.
534 *
535 * It is NOT legal to take the sizeof(sym) and pass that to the stackSize
536 * parameter of k_thread_create(), it may not be the same as the
537 * 'size' parameter. Use K_THREAD_STACK_SIZEOF() instead.
538 *
539 * Some arches may round the size of the usable stack region up to satisfy
540 * alignment constraints. K_THREAD_STACK_SIZEOF() will return the aligned
541 * size.
542 *
543 * This puts the stack into the pinned noinit linker section if
544 * CONFIG_LINKER_USE_PINNED_SECTION is enabled, or else it would
545 * put the stack into the same section as K_THREAD_STACK_DEFINE().
546 *
547 * @param sym Thread stack symbol name
548 * @param size Size of the stack memory region
549 */
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
558 /**
559 * @brief Calculate size of stacks to be allocated in a stack array
560 *
561 * This macro calculates the size to be allocated for the stacks
562 * inside a stack array. It accepts the indicated "size" as a parameter
563 * and if required, pads some extra bytes (e.g. for MPU scenarios). Refer
564 * K_THREAD_STACK_ARRAY_DEFINE definition to see how this is used.
565 * The returned size ensures each array member will be aligned to the
566 * required stack base alignment.
567 *
568 * @param size Size of the stack memory region
569 * @return Appropriate size for an array member
570 */
571 #define K_THREAD_STACK_LEN(size) \
572 ROUND_UP(Z_THREAD_STACK_SIZE_ADJUST(size), \
573 Z_THREAD_STACK_OBJ_ALIGN(size))
574
575 /**
576 * @brief Define a toplevel array of thread stack memory regions
577 *
578 * Create an array of equally sized stacks. See K_THREAD_STACK_DEFINE
579 * definition for additional details and constraints.
580 *
581 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
582 * and put in 'noinit' section so that it isn't zeroed at boot
583 *
584 * @param sym Thread stack symbol name
585 * @param nmemb Number of stacks to define
586 * @param size Size of the stack memory region
587 */
588 #define K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size) \
589 Z_THREAD_STACK_ARRAY_DEFINE_IN(sym, nmemb, size, __stackmem)
590
591 /**
592 * @brief Define a toplevel array of thread stack memory regions in pinned section
593 *
594 * Create an array of equally sized stacks. See K_THREAD_STACK_DEFINE
595 * definition for additional details and constraints.
596 *
597 * This is the generic, historical definition. Align to Z_THREAD_STACK_OBJ_ALIGN
598 * and put in 'noinit' section so that it isn't zeroed at boot
599 *
600 * This puts the stack into the pinned noinit linker section if
601 * CONFIG_LINKER_USE_PINNED_SECTION is enabled, or else it would
602 * put the stack into the same section as K_THREAD_STACK_DEFINE().
603 *
604 * @param sym Thread stack symbol name
605 * @param nmemb Number of stacks to define
606 * @param size Size of the stack memory region
607 */
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
616 /**
617 * @brief Define an embedded stack memory region
618 *
619 * Used for stacks embedded within other data structures. Use is highly
620 * discouraged but in some cases necessary. For memory protection scenarios,
621 * it is very important that any RAM preceding this member not be writable
622 * by threads else a stack overflow will lead to silent corruption. In other
623 * words, the containing data structure should live in RAM owned by the kernel.
624 *
625 * A user thread can only be started with a stack defined in this way if
626 * the thread starting it is in supervisor mode.
627 *
628 * @deprecated This is now deprecated, as stacks defined in this way are not
629 * usable from user mode. Use K_KERNEL_STACK_MEMBER.
630 *
631 * @param sym Thread stack symbol name
632 * @param size Size of the stack memory region
633 */
634 #define K_THREAD_STACK_MEMBER(sym, size) __DEPRECATED_MACRO \
635 Z_THREAD_STACK_DEFINE_IN(sym, size,)
636
637 /** @} */
638
639 /**
640 * @brief Get a pointer to the physical stack buffer
641 *
642 * Obtain a pointer to the non-reserved area of a stack object.
643 * This is not guaranteed to be the beginning of the thread-writable region;
644 * this does not account for any memory carved-out for MPU stack overflow
645 * guards.
646 *
647 * Use with care. The true bounds of the stack buffer are available in the
648 * stack_info member of its associated thread.
649 *
650 * @param sym defined stack symbol name
651 * @return The buffer itself, a char *
652 */
K_THREAD_STACK_BUFFER(k_thread_stack_t * sym)653 static inline char *K_THREAD_STACK_BUFFER(k_thread_stack_t *sym)
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 */
666
