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