1.. _memory_management_api_virtual_memory:
2
3Virtual Memory
4##############
5
6Virtual memory (VM) in Zephyr provides developers with the ability to fine tune
7access to memory. To utilize virtual memory, the platform must support
8Memory Management Unit (MMU) and it must be enabled in the build. Due to
9the target of Zephyr mainly being embedded systems, virtual memory
10support in Zephyr differs a bit from that in traditional operating
11systems:
12
13Mapping of Kernel Image
14  Default is to do 1:1 mapping for the kernel image (including code and data)
15  between physical and virtual memory address spaces, if demand paging
16  is not enabled. Deviation from this requires careful manipulation of
17  linker script.
18
19Secondary Storage
20  Basic virtual memory support does not utilize secondary storage to
21  extend usable memory. The maximum usable memory is the same as
22  the physical memory.
23
24  * :ref:`memory_management_api_demand_paging` enables utilizing
25    secondary storage as a backing store for virtual memory, thus
26    allowing larger usable memory than the available physical memory.
27    Note that demand paging needs to be explicitly enabled.
28
29  * Although the virtual memory space can be larger than physical
30    memory space, without enabling demand paging, all virtually
31    mapped memory must be backed by physical memory.
32
33
34Kconfigs
35********
36
37Required
38========
39
40These are the Kconfigs that need to be enabled or defined for kernel to support
41virtual memory.
42
43* :kconfig:option:`CONFIG_MMU`: must be enabled for virtual memory support in
44  kernel.
45
46* :kconfig:option:`CONFIG_MMU_PAGE_SIZE`: size of a memory page. Default is 4KB.
47
48* :kconfig:option:`CONFIG_KERNEL_VM_BASE`: base address of virtual address space.
49
50* :kconfig:option:`CONFIG_KERNEL_VM_SIZE`: size of virtual address space.
51  Default is 8MB.
52
53* :kconfig:option:`CONFIG_KERNEL_VM_OFFSET`: kernel image starts at this offset
54  from :kconfig:option:`CONFIG_KERNEL_VM_BASE`.
55
56Optional
57========
58
59* :kconfig:option:`CONFIG_KERNEL_DIRECT_MAP`: permits 1:1 mappings between
60  virtual and physical addresses, instead of kernel choosing addresses within
61  the virtual address space. This is useful for mapping device MMIO regions for
62  more precise access control.
63
64
65Memory Map Overview
66*******************
67
68This is an overview of the memory map of the virtual memory address space.
69Note that the ``Z_*`` macros, which are used in code, may have different
70meanings depending on architecture and Kconfigs, which will be explained
71below.
72
73.. code-block:: none
74   :emphasize-lines: 1, 3, 9, 22, 24
75
76   +--------------+ <- K_MEM_VIRT_RAM_START
77   | Undefined VM | <- architecture specific reserved area
78   +--------------+ <- K_MEM_KERNEL_VIRT_START
79   | Mapping for  |
80   | main kernel  |
81   | image        |
82   |              |
83   |              |
84   +--------------+ <- K_MEM_VM_FREE_START
85   |              |
86   | Unused,      |
87   | Available VM |
88   |              |
89   |..............| <- grows downward as more mappings are made
90   | Mapping      |
91   +--------------+
92   | Mapping      |
93   +--------------+
94   | ...          |
95   +--------------+
96   | Mapping      |
97   +--------------+ <- memory mappings start here
98   | Reserved     | <- special purpose virtual page(s) of size K_MEM_VM_RESERVED
99   +--------------+ <- K_MEM_VIRT_RAM_END
100
101* ``K_MEM_VIRT_RAM_START`` is the beginning of the virtual memory address space.
102  This needs to be page aligned. Currently, it is the same as
103  :kconfig:option:`CONFIG_KERNEL_VM_BASE`.
104
105* ``K_MEM_VIRT_RAM_SIZE`` is the size of the virtual memory address space.
106  This needs to be page aligned. Currently, it is the same as
107  :kconfig:option:`CONFIG_KERNEL_VM_SIZE`.
108
109* ``K_MEM_VIRT_RAM_END`` is simply (``K_MEM_VIRT_RAM_START`` + ``K_MEM_VIRT_RAM_SIZE``).
110
111* ``K_MEM_KERNEL_VIRT_START`` is the same as ``z_mapped_start`` specified in the linker
112  script. This is the virtual address of the beginning of the kernel image at
113  boot time.
114
115* ``K_MEM_KERNEL_VIRT_END`` is the same as ``z_mapped_end`` specified in the linker
116  script. This is the virtual address of the end of the kernel image at boot time.
117
118* ``K_MEM_VM_FREE_START`` is the beginning of the virtual address space where addresses
119  can be allocated for memory mapping. This depends on whether
120  :kconfig:option:`CONFIG_ARCH_MAPS_ALL_RAM` is enabled.
121
122  * If it is enabled, which means all physical memory are mapped in virtual
123    memory address space, and it is the same as
124    (:kconfig:option:`CONFIG_SRAM_BASE_ADDRESS` + :kconfig:option:`CONFIG_SRAM_SIZE`).
125
126  * If it is disabled, ``K_MEM_VM_FREE_START`` is the same ``K_MEM_KERNEL_VIRT_END`` which
127    is the end of the kernel image.
128
129* ``K_MEM_VM_RESERVED`` is an area reserved to support kernel functions. For example,
130  some addresses are reserved to support demand paging.
131
132
133Virtual Memory Mappings
134***********************
135
136Setting up Mappings at Boot
137===========================
138
139In general, most supported architectures set up the memory mappings at boot as
140following:
141
142* ``.text`` section is read-only and executable. It is accessible in
143  both kernel and user modes.
144
145* ``.rodata`` section is read-only and non-executable. It is accessible
146  in both kernel and user modes.
147
148* Other kernel sections, such as ``.data``, ``.bss`` and ``.noinit``, are
149  read-write and non-executable. They are only accessible in kernel mode.
150
151  * Stacks for user mode threads are automatically granted read-write access
152    to their corresponding user mode threads during thread creation.
153
154  * Global variables, by default, are not accessible to user mode threads.
155    Refer to :ref:`Memory Domains and Partitions<memory_domain>` on how to
156    use global variables in user mode threads, and on how to share data
157    between user mode threads.
158
159Caching modes for these mappings are architecture specific. They can be
160none, write-back, or write-through.
161
162Note that SoCs have their own additional mappings required to boot where
163these mappings are defined under their own SoC configurations. These mappings
164usually include device MMIO regions needed to setup the hardware.
165
166
167Mapping Anonymous Memory
168========================
169
170The unused physical memory can be mapped in virtual address space on demand.
171This is conceptually similar to memory allocation from heap, but these
172mappings must be aligned on page size and have finer access control.
173
174* :c:func:`k_mem_map` can be used to map unused physical memory:
175
176  * The requested size must be multiple of page size.
177
178  * The address returned is inside the virtual address space between
179    ``K_MEM_VM_FREE_START`` and ``K_MEM_VIRT_RAM_END``.
180
181  * The mapped region is not guaranteed to be physically contiguous in memory.
182
183  * Guard pages immediately before and after the mapped virtual region are
184    automatically allocated to catch access issue due to buffer underrun
185    or overrun.
186
187* The mapped region can be unmapped (i.e. freed) via :c:func:`k_mem_unmap`:
188
189  * Caution must be exercised to give the pass the same region size to
190    both :c:func:`k_mem_map` and :c:func:`k_mem_unmap`. The unmapping
191    function does not check if it is a valid mapped region before unmapping.
192
193
194API Reference
195*************
196
197.. doxygengroup:: kernel_memory_management
198