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 : /**
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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #define K_KERNEL_STACK_MEMBER(sym, size) \
280 : Z_KERNEL_STACK_DEFINE_IN(sym, size,)
281 :
282 0 : #define K_KERNEL_STACK_SIZEOF(sym) (sizeof(sym) - K_KERNEL_STACK_RESERVED)
283 :
284 : /** @} */
285 :
286 0 : 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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 : */
631 1 : 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 */
|
