6000a6205a
Linking to API material requires knowing the pecularities of how doxygen, sphinx, and breathe work. In an attempt to hide some of this we're preparing the current docs to allow use of configuration defaults that will let us more simply use a default role that will hunt for a reference target in the various domains that are available by using a default "role" of "all". This will let us use the simple notation `functionname` or `typename` without fully specifying the reference as :c:func:`functionname`. This patch cleans up exising docs that were (incorrectly) using single backtics where double backtics should have been used, and also found some typos (such as a space between the role name and the reference, such as :file: `filename`, and a missing colon such as c:func:`functionname`) This is a start to address issue #14313 Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
66 lines
2.8 KiB
ReStructuredText
66 lines
2.8 KiB
ReStructuredText
.. _mpu_stack_objects:
|
|
|
|
MPU Stack Objects
|
|
#################
|
|
|
|
Thread Stack Creation
|
|
*********************
|
|
|
|
Thread stacks are declared statically with :c:macro:`K_THREAD_STACK_DEFINE()`
|
|
or embedded within structures using :c:macro:`K_THREAD_STACK_MEMBER()`
|
|
|
|
For architectures which utilize memory protection unit (MPU) hardware,
|
|
stacks are physically contiguous allocations. This contiguous allocation
|
|
has implications for the placement of stacks in memory, as well as the
|
|
implementation of other features such as stack protection and userspace. The
|
|
implications for placement are directly attributed to the alignment
|
|
requirements for MPU regions. This is discussed in the memory placement
|
|
section below.
|
|
|
|
Stack Guards
|
|
************
|
|
|
|
Stack protection mechanisms require hardware support that can restrict access
|
|
to memory. Memory protection units can provide this kind of support.
|
|
The MPU provides a fixed number of regions. Each region contains information
|
|
about the start, end, size, and access attributes to be enforced on that
|
|
particular region.
|
|
|
|
Stack guards are implemented by using a single MPU region and setting the
|
|
attributes for that region to not allow write access. If invalid accesses
|
|
occur, a fault ensues. The stack guard is defined at the bottom (the lowest
|
|
address) of the stack.
|
|
|
|
Memory Placement
|
|
****************
|
|
|
|
During stack creation, a set of constraints are enforced on the allocation of
|
|
memory. These constraints include determining the alignment of the stack and
|
|
the correct sizing of the stack. During linking of the binary, these
|
|
constraints are used to place the stacks properly.
|
|
|
|
The main source of the memory constraints is the MPU design for the SoC. The
|
|
MPU design may require specific constraints on the region definition. These
|
|
can include alignment of beginning and end addresses, sizes of allocations,
|
|
or even interactions between overlapping regions.
|
|
|
|
Some MPUs require that each region be aligned to a power of two. These SoCs
|
|
will have :option:`CONFIG_MPU_REQUIRES_POWER_OF_TWO_ALIGNMENT` defined.
|
|
This means that a 1500 byte stack should be aligned to a 2kB boundary and the
|
|
stack size should also be adjusted to 2kB to ensure that nothing else is
|
|
placed in the remainder of the region. SoCs which include the unmodified ARM
|
|
v7m MPU will have these constraints.
|
|
|
|
Some ARM MPUs use start and end addresses to define MPU regions and both the
|
|
start and end addresses require 32 byte alignment. An example of this kind of
|
|
MPU is found in the NXP FRDM K64F.
|
|
|
|
MPUs may have a region priority mechanisms that use the highest priority region
|
|
that covers the memory access to determine the enforcement policy. Others may
|
|
logically OR regions to determine enforcement policy.
|
|
|
|
Size and alignment constraints may result in stack allocations being larger
|
|
than the requested size. Region priority mechanisms may result in
|
|
some added complexity when implementing stack guards.
|
|
|