Lines Matching +full:memory +full:- +full:to +full:- +full:memory
3 Memory Protection Design
6 Zephyr's memory protection design is geared towards microcontrollers with MPU
7 (Memory Protection Unit) hardware. We do support some architectures, such as x86,
8 which have a paged MMU (Memory Management Unit), but in that case the MMU is
12 can be considered to have an MPU with an unlimited number of programmable
15 There are a few different levels on how memory access is configured when
16 Zephyr memory protection features are enabled, which we will describe here:
18 Boot Time Memory Configuration
24 - Any configuration of memory regions which need to have special caching or
25 write-back policies for basic hardware and driver function. Note that most
26 MPUs have the concept of a default memory access policy map, which can be
27 enabled as a "background" mapping for any area of memory that doesn't
28 have an MPU region configuring it. It is strongly recommended to use this
29 to maximize the number of available MPU regions for the end user. On
30 ARMv7-M/ARMv8-M this is called the System Address Map, other CPUs may
32 how to annotate the system map in the device tree.
34 - A read-only, executable region or regions for program text and ro-data, that
35 is accessible to user mode. This could be further sub-divided into a
36 read-only region for ro-data, and a read-only, executable region for text, but
38 threads running in user mode can read ro-data and fetch instructions.
40 - Depending on configuration, user-accessible read-write regions to support
43 Assuming there is a background map which allows supervisor mode to access any
44 memory it needs, and regions are defined which grant user mode access to
45 text/ro-data, this is sufficient for the boot time configuration.
53 individual stack frames, use compiler-assisted :kconfig:option:`CONFIG_STACK_CANARIES`
58 of this should be treated as a serious error. However it's still very useful to
64 which is set to be read-only and is at either the beginning or immediately
68 This feature is optional and is not required to catch stack overflows in user
69 mode; disabling this may free 1-2 MPU regions depending on the MPU design.
77 Any thread running in user mode will need access to its own stack buffer.
80 A thread exceeding its stack buffer will start pushing data onto memory
81 it doesn't have access to and a memory access violation exception will be
84 Note that user threads have access to the stacks of other user threads in
85 the same memory domain. This is the minimum required for architectures to
86 support memory domains. Architecture can further restrict access to stacks
87 so each user thread only has access to its own stack if such architecture
93 may decide to enable this all the time, and thus this option cannot be
95 the stacks of other user threads outside of their memory domains.
100 A small subset of kernel APIs, invoked as system calls, require heap memory
101 allocations. This memory is used only by the kernel and is not accessible
102 directly by user mode. In order to use these system calls, invoking threads
103 must assign themselves to a resource pool, which is a :c:struct:`k_heap`
104 object. Memory is drawn from a thread's resource pool using
110 - :c:func:`k_stack_alloc_init` sets up a k_stack with its storage
112 user. An alternative is to declare k_stacks that are automatically
113 initialized at boot with :c:macro:`K_STACK_DEFINE()`, or to initialize the
116 - :c:func:`k_pipe_alloc_init` sets up a k_pipe object with its
118 by the user. An alternative is to declare k_pipes that are automatically
119 initialized at boot with :c:macro:`K_PIPE_DEFINE()`, or to initialize the
122 - :c:func:`k_msgq_alloc_init` sets up a k_msgq object with its
124 by the user. An alternative is to declare a k_msgq that is automatically
125 initialized at boot with :c:macro:`K_MSGQ_DEFINE()`, or to initialize the
128 - :c:func:`k_poll` when invoked from user mode, needs to make a kernel-side
132 - :c:func:`k_queue_alloc_prepend` and :c:func:`k_queue_alloc_append`
133 allocate a container structure to place the data in, since the internal
135 memory provided by the user.
137 - :c:func:`k_object_alloc` allows for entire kernel objects to be
138 dynamically allocated at runtime and a usable pointer to them returned to
142 a k_heap to draw these allocations from for the target thread.
146 logical applications running on the system to have their own pools.
148 Memory Domains
151 The kernel ensures that any user thread will have access to its own stack
152 buffer, plus program text and read-only data. The memory domain APIs are the
153 way to grant access to additional blocks of memory to a user thread.
155 Conceptually, a memory domain is a collection of some number of memory
156 partitions. The maximum number of memory partitions in a domain
158 to minimize the number of boot-time MPU regions.
160 Memory domains are *not* intended to control access to memory from supervisor
162 not allow for the definition of regions which are read-only to user mode but
163 read-write to supervisor mode. A great deal of care must be taken when working
164 with such regions to not unintentionally cause the kernel to crash when
165 accessing such a region. Any attempt to use memory domain APIs to control
167 policy is only intended to be controlled by boot-time memory regions.
169 Memory domain APIs are only available to supervisor mode. The only control
170 user mode has over memory domains is that any user thread's child threads
173 All threads are members of a memory domain, including supervisor threads
174 (even though this has no implications on their memory access). There is a
175 default domain ``k_mem_domain_default`` which will be assigned to threads if
176 they have not been specifically assigned to a domain, or inherited a memory
180 Memory Partitions
183 Each memory partition consists of a memory address, a size,
184 and access attributes. It is intended that memory partitions are used to
185 control access to system memory. Defining memory partitions are subject
186 to the following constraints:
188 - The partition must represent a memory region that can be programmed by
189 the underlying memory management hardware, and needs to conform to any
190 underlying hardware constraints. For example, many MPU-based systems require
191 that partitions be sized to some power of two, and aligned to their own
192 size. For MMU-based systems, the partition must be aligned to a page and
195 - Partitions within the same memory domain may not overlap each other. There is
196 no notion of precedence among partitions within a memory domain. Partitions
197 within a memory domain are assumed to have a higher precedence than any
198 boot-time memory regions, however whether a memory domain partition can
199 overlap a boot-time memory region is architecture specific.
201 - The same partition may be specified in multiple memory domains. For example
202 there may be a shared memory area that multiple domains grant access to.
204 - Care must be taken in determining what memory to expose in a partition.
205 It is not appropriate to provide direct user mode access to any memory
208 - Memory domain partitions are intended to control access to system RAM.
209 Configuration of memory partitions which do not correspond to RAM
210 may not be supported by the architecture; this is true for MMU-based systems.
212 There are two ways to define memory partitions: either manually or
215 Manual Memory Partitions
216 ------------------------
219 a read-write partition for it which may be added to a domain:
221 .. code-block:: c
228 This does not scale particularly well when we are trying to contain multiple
231 Automatic Memory Partitions
232 ---------------------------
234 Automatic memory partitions are created by the build system. All globals
235 which need to be placed inside a partition are tagged with their destination
237 contiguous block of memory, zero any BSS variables at boot, and define
238 a memory partition of appropriate base address and size which contains all
242 :alt: Automatic Memory Domain build flow
245 Automatic Memory Domain build flow
247 Automatic memory partitions are only configured as read-write
249 Global variables are then routed to this partition using
253 .. code-block:: c
257 /* Declare a k_mem_partition "my_partition" that is read-write to
274 be properly aligned, and the total size of the region conforms to the memory
280 .. code-block:: c
287 The build-time logic for setting up automatic memory partitions is in
289 it is possible to route all the globals in that library to a specific
290 memory partition with the ``--library`` argument.
293 to be placed in ``z_libc_partition``. The invocation of the script in the
294 top-level ``CMakeLists.txt`` adds the following:
296 .. code-block:: none
298 gen_app_partitions.py ... --library libc.a z_libc_partition ..
300 For pre-compiled libraries there is no support for expressing this in the
301 project-level configuration or build files; the toplevel ``CMakeLists.txt`` must
305 the ``zephyr_library_app_memory`` function can be used to specify the memory
310 Pre-defined Memory Partitions
311 -----------------------------
313 There are a few memory partitions which are pre-defined by the system:
315 - ``z_malloc_partition`` - This partition contains the system-wide pool of
316 memory used by libc malloc(). Due to possible starvation issues, it is
317 not recommended to draw heap memory from a global pool, instead
318 it is better to define various sys_heap objects and assign them
319 to specific memory domains.
321 - ``z_libc_partition`` - Contains globals required by the C library and runtime.
325 Library-specific partitions are listed in ``include/app_memory/partitions.h``.
326 For example, to use the MBEDTLS library from user mode, the
327 ``k_mbedtls_partition`` must be added to the domain.
329 Memory Domain Usage
332 Create a Memory Domain
333 ----------------------
335 A memory domain is defined using a variable of type
339 The following code defines and initializes an empty memory domain.
341 .. code-block:: c
347 Add Memory Partitions into a Memory Domain
348 ------------------------------------------
350 There are two ways to add memory partitions into a memory domain.
352 This first code sample shows how to add memory partitions while creating
353 a memory domain.
355 .. code-block:: c
357 /* the start address of the MPU region needs to align with its size */
374 This second code sample shows how to add memory partitions into an initialized
375 memory domain one by one.
377 .. code-block:: c
379 /* the start address of the MPU region needs to align with its size */
393 The maximum number of memory partitions is limited by the maximum
396 Memory Domain Assignment
397 ------------------------
399 Any thread may join a memory domain, and any memory domain may have multiple
400 threads assigned to it. Threads are assigned to memory domains with an API
403 .. code-block:: c
410 In addition, if a thread is a member of a memory domain, and it creates a
411 child thread, that thread will belong to the domain as well.
413 Remove a Memory Partition from a Memory Domain
414 ----------------------------------------------
416 The following code shows how to remove a memory partition from a memory
419 .. code-block:: c
423 The k_mem_domain_remove_partition() API finds the memory partition
425 memory domain.
428 ------------------------------
430 When defining a partition, we need to set access permission attributes
431 to the partition. Since the access control of memory partitions relies on
436 is found in the architecture-specific include file
440 .. code-block:: c
444 /* Denote partition is privileged read/write, unprivileged read-only */
459 The following memory domain APIs are provided by :zephyr_file:`include/zephyr/kernel.h`: