1 .. SPDX-License-Identifier: GPL-2.0
2
3 =====================
4 Physical Memory Model
5 =====================
6
7 Physical memory in a system may be addressed i
8 simplest case is when the physical memory star
9 spans a contiguous range up to the maximal add
10 however, that this range contains small holes
11 for the CPU. Then there could be several conti
12 completely distinct addresses. And, don't forg
13 different memory banks are attached to differe
14
15 Linux abstracts this diversity using one of th
16 FLATMEM and SPARSEMEM. Each architecture defin
17 memory models it supports, what the default me
18 whether it is possible to manually override th
19
20 All the memory models track the status of phys
21 struct page arranged in one or more arrays.
22
23 Regardless of the selected memory model, there
24 mapping between the physical page frame number
25 corresponding `struct page`.
26
27 Each memory model defines :c:func:`pfn_to_page
28 helpers that allow the conversion from PFN to
29 versa.
30
31 FLATMEM
32 =======
33
34 The simplest memory model is FLATMEM. This mod
35 non-NUMA systems with contiguous, or mostly co
36 memory.
37
38 In the FLATMEM memory model, there is a global
39 maps the entire physical memory. For most arch
40 have entries in the `mem_map` array. The `stru
41 corresponding to the holes are never fully ini
42
43 To allocate the `mem_map` array, architecture
44 call :c:func:`free_area_init` function. Yet, t
45 usable until the call to :c:func:`memblock_fre
46 memory to the page allocator.
47
48 An architecture may free parts of the `mem_map
49 actual physical pages. In such case, the archi
50 :c:func:`pfn_valid` implementation should take
51 `mem_map` into account.
52
53 With FLATMEM, the conversion between a PFN and
54 straightforward: `PFN - ARCH_PFN_OFFSET` is an
55 `mem_map` array.
56
57 The `ARCH_PFN_OFFSET` defines the first page f
58 systems with physical memory starting at addre
59
60 SPARSEMEM
61 =========
62
63 SPARSEMEM is the most versatile memory model a
64 is the only memory model that supports several
65 as hot-plug and hot-remove of the physical mem
66 maps for non-volatile memory devices and defer
67 the memory map for larger systems.
68
69 The SPARSEMEM model presents the physical memo
70 sections. A section is represented with struct
71 that contains `section_mem_map` that is, logic
72 array of struct pages. However, it is stored w
73 that aids the sections management. The section
74 of section is specified using `SECTION_SIZE_BI
75 `MAX_PHYSMEM_BITS` constants defined by each a
76 supports SPARSEMEM. While `MAX_PHYSMEM_BITS` i
77 physical address that an architecture supports
78 `SECTION_SIZE_BITS` is an arbitrary value.
79
80 The maximal number of sections is denoted `NR_
81 defined as
82
83 .. math::
84
85 NR\_MEM\_SECTIONS = 2 ^ {(MAX\_PHYSMEM\_BIT
86
87 The `mem_section` objects are arranged in a tw
88 called `mem_sections`. The size and placement
89 on `CONFIG_SPARSEMEM_EXTREME` and the maximal
90 sections:
91
92 * When `CONFIG_SPARSEMEM_EXTREME` is disabled,
93 array is static and has `NR_MEM_SECTIONS` ro
94 single `mem_section` object.
95 * When `CONFIG_SPARSEMEM_EXTREME` is enabled,
96 array is dynamically allocated. Each row con
97 `mem_section` objects and the number of rows
98 all the memory sections.
99
100 The architecture setup code should call sparse
101 initialize the memory sections and the memory
102
103 With SPARSEMEM there are two possible ways to
104 corresponding `struct page` - a "classic spars
105 vmemmap". The selection is made at build time
106 the value of `CONFIG_SPARSEMEM_VMEMMAP`.
107
108 The classic sparse encodes the section number
109 and uses high bits of a PFN to access the sect
110 frame. Inside a section, the PFN is the index
111
112 The sparse vmemmap uses a virtually mapped mem
113 pfn_to_page and page_to_pfn operations. There
114 page *vmemmap` pointer that points to a virtua
115 `struct page` objects. A PFN is an index to th
116 offset of the `struct page` from `vmemmap` is
117 page.
118
119 To use vmemmap, an architecture has to reserve
120 addresses that will map the physical pages con
121 map and make sure that `vmemmap` points to tha
122 the architecture should implement :c:func:`vme
123 that will allocate the physical memory and cre
124 virtual memory map. If an architecture does no
125 requirements for the vmemmap mappings, it can
126 :c:func:`vmemmap_populate_basepages` provided
127 management.
128
129 The virtually mapped memory map allows storing
130 for persistent memory devices in pre-allocated
131 devices. This storage is represented with stru
132 that is eventually passed to vmemmap_populate(
133 of function calls. The vmemmap_populate() impl
134 `vmem_altmap` along with :c:func:`vmemmap_allo
135 allocate memory map on the persistent memory d
136
137 ZONE_DEVICE
138 ===========
139 The `ZONE_DEVICE` facility builds upon `SPARSE
140 `struct page` `mem_map` services for device dr
141 address ranges. The "device" aspect of `ZONE_D
142 that the page objects for these address ranges
143 and that a reference must be taken against the
144 to keep the memory pinned for active use. `ZON
145 :c:func:`devm_memremap_pages`, performs just e
146 turn on :c:func:`pfn_to_page`, :c:func:`page_t
147 :c:func:`get_user_pages` service for the given
148 page reference count never drops below 1 the p
149 free memory and the page's `struct list_head l
150 for back referencing to the host device / driv
151
152 While `SPARSEMEM` presents memory as a collect
153 optionally collected into memory blocks, `ZONE
154 for smaller granularity of populating the `mem
155 `ZONE_DEVICE` memory is never marked online it
156 subject to its memory ranges being exposed thr
157 hotplug api on memory block boundaries. The im
158 this lack of user-api constraint to allow sub-
159 ranges to be specified to :c:func:`arch_add_me
160 memory hotplug. Sub-section support allows for
161 common alignment granularity for :c:func:`devm
162
163 The users of `ZONE_DEVICE` are:
164
165 * pmem: Map platform persistent memory to be u
166 via DAX mappings.
167
168 * hmm: Extend `ZONE_DEVICE` with `->page_fault
169 event callbacks to allow a device-driver to
170 events related to device-memory, typically G
171 Documentation/mm/hmm.rst.
172
173 * p2pdma: Create `struct page` objects to allo
174 PCI/-E topology to coordinate direct-DMA ope
175 i.e. bypass host memory.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.