1.. SPDX-License-Identifier: GPL-2.0 2 3=============== 4Physical Memory 5=============== 6 7Linux is available for a wide range of architectures so there is a need for an 8architecture-independent abstraction to represent the physical memory. This 9chapter describes the structures used to manage physical memory in a running 10system. 11 12The first principal concept prevalent in the memory management is 13`Non-Uniform Memory Access (NUMA) 14<https://en.wikipedia.org/wiki/Non-uniform_memory_access>`_. 15With multi-core and multi-socket machines, memory may be arranged into banks 16that incur a different cost to access depending on the “distance” from the 17processor. For example, there might be a bank of memory assigned to each CPU or 18a bank of memory very suitable for DMA near peripheral devices. 19 20Each bank is called a node and the concept is represented under Linux by a 21``struct pglist_data`` even if the architecture is UMA. This structure is 22always referenced to by it's typedef ``pg_data_t``. ``A pg_data_t`` structure 23for a particular node can be referenced by ``NODE_DATA(nid)`` macro where 24``nid`` is the ID of that node. 25 26For NUMA architectures, the node structures are allocated by the architecture 27specific code early during boot. Usually, these structures are allocated 28locally on the memory bank they represent. For UMA architectures, only one 29static ``pg_data_t`` structure called ``contig_page_data`` is used. Nodes will 30be discussed further in Section :ref:`Nodes <nodes>` 31 32The entire physical address space is partitioned into one or more blocks 33called zones which represent ranges within memory. These ranges are usually 34determined by architectural constraints for accessing the physical memory. 35The memory range within a node that corresponds to a particular zone is 36described by a ``struct zone``, typedeffed to ``zone_t``. Each zone has 37one of the types described below. 38 39* ``ZONE_DMA`` and ``ZONE_DMA32`` historically represented memory suitable for 40 DMA by peripheral devices that cannot access all of the addressable 41 memory. For many years there are better more and robust interfaces to get 42 memory with DMA specific requirements (Documentation/core-api/dma-api.rst), 43 but ``ZONE_DMA`` and ``ZONE_DMA32`` still represent memory ranges that have 44 restrictions on how they can be accessed. 45 Depending on the architecture, either of these zone types or even they both 46 can be disabled at build time using ``CONFIG_ZONE_DMA`` and 47 ``CONFIG_ZONE_DMA32`` configuration options. Some 64-bit platforms may need 48 both zones as they support peripherals with different DMA addressing 49 limitations. 50 51* ``ZONE_NORMAL`` is for normal memory that can be accessed by the kernel all 52 the time. DMA operations can be performed on pages in this zone if the DMA 53 devices support transfers to all addressable memory. ``ZONE_NORMAL`` is 54 always enabled. 55 56* ``ZONE_HIGHMEM`` is the part of the physical memory that is not covered by a 57 permanent mapping in the kernel page tables. The memory in this zone is only 58 accessible to the kernel using temporary mappings. This zone is available 59 only on some 32-bit architectures and is enabled with ``CONFIG_HIGHMEM``. 60 61* ``ZONE_MOVABLE`` is for normal accessible memory, just like ``ZONE_NORMAL``. 62 The difference is that the contents of most pages in ``ZONE_MOVABLE`` is 63 movable. That means that while virtual addresses of these pages do not 64 change, their content may move between different physical pages. Often 65 ``ZONE_MOVABLE`` is populated during memory hotplug, but it may be 66 also populated on boot using one of ``kernelcore``, ``movablecore`` and 67 ``movable_node`` kernel command line parameters. See 68 Documentation/mm/page_migration.rst and 69 Documentation/admin-guide/mm/memory-hotplug.rst for additional details. 70 71* ``ZONE_DEVICE`` represents memory residing on devices such as PMEM and GPU. 72 It has different characteristics than RAM zone types and it exists to provide 73 :ref:`struct page <Pages>` and memory map services for device driver 74 identified physical address ranges. ``ZONE_DEVICE`` is enabled with 75 configuration option ``CONFIG_ZONE_DEVICE``. 76 77It is important to note that many kernel operations can only take place using 78``ZONE_NORMAL`` so it is the most performance critical zone. Zones are 79discussed further in Section :ref:`Zones <zones>`. 80 81The relation between node and zone extents is determined by the physical memory 82map reported by the firmware, architectural constraints for memory addressing 83and certain parameters in the kernel command line. 84 85For example, with 32-bit kernel on an x86 UMA machine with 2 Gbytes of RAM the 86entire memory will be on node 0 and there will be three zones: ``ZONE_DMA``, 87``ZONE_NORMAL`` and ``ZONE_HIGHMEM``:: 88 89 0 2G 90 +-------------------------------------------------------------+ 91 | node 0 | 92 +-------------------------------------------------------------+ 93 94 0 16M 896M 2G 95 +----------+-----------------------+--------------------------+ 96 | ZONE_DMA | ZONE_NORMAL | ZONE_HIGHMEM | 97 +----------+-----------------------+--------------------------+ 98 99 100With a kernel built with ``ZONE_DMA`` disabled and ``ZONE_DMA32`` enabled and 101booted with ``movablecore=80%`` parameter on an arm64 machine with 16 Gbytes of 102RAM equally split between two nodes, there will be ``ZONE_DMA32``, 103``ZONE_NORMAL`` and ``ZONE_MOVABLE`` on node 0, and ``ZONE_NORMAL`` and 104``ZONE_MOVABLE`` on node 1:: 105 106 107 1G 9G 17G 108 +--------------------------------+ +--------------------------+ 109 | node 0 | | node 1 | 110 +--------------------------------+ +--------------------------+ 111 112 1G 4G 4200M 9G 9320M 17G 113 +---------+----------+-----------+ +------------+-------------+ 114 | DMA32 | NORMAL | MOVABLE | | NORMAL | MOVABLE | 115 +---------+----------+-----------+ +------------+-------------+ 116 117.. _nodes: 118 119Nodes 120===== 121 122As we have mentioned, each node in memory is described by a ``pg_data_t`` which 123is a typedef for a ``struct pglist_data``. When allocating a page, by default 124Linux uses a node-local allocation policy to allocate memory from the node 125closest to the running CPU. As processes tend to run on the same CPU, it is 126likely the memory from the current node will be used. The allocation policy can 127be controlled by users as described in 128Documentation/admin-guide/mm/numa_memory_policy.rst. 129 130Most NUMA architectures maintain an array of pointers to the node 131structures. The actual structures are allocated early during boot when 132architecture specific code parses the physical memory map reported by the 133firmware. The bulk of the node initialization happens slightly later in the 134boot process by free_area_init() function, described later in Section 135:ref:`Initialization <initialization>`. 136 137 138Along with the node structures, kernel maintains an array of ``nodemask_t`` 139bitmasks called ``node_states``. Each bitmask in this array represents a set of 140nodes with particular properties as defined by ``enum node_states``: 141 142``N_POSSIBLE`` 143 The node could become online at some point. 144``N_ONLINE`` 145 The node is online. 146``N_NORMAL_MEMORY`` 147 The node has regular memory. 148``N_HIGH_MEMORY`` 149 The node has regular or high memory. When ``CONFIG_HIGHMEM`` is disabled 150 aliased to ``N_NORMAL_MEMORY``. 151``N_MEMORY`` 152 The node has memory(regular, high, movable) 153``N_CPU`` 154 The node has one or more CPUs 155 156For each node that has a property described above, the bit corresponding to the 157node ID in the ``node_states[<property>]`` bitmask is set. 158 159For example, for node 2 with normal memory and CPUs, bit 2 will be set in :: 160 161 node_states[N_POSSIBLE] 162 node_states[N_ONLINE] 163 node_states[N_NORMAL_MEMORY] 164 node_states[N_HIGH_MEMORY] 165 node_states[N_MEMORY] 166 node_states[N_CPU] 167 168For various operations possible with nodemasks please refer to 169``include/linux/nodemask.h``. 170 171Among other things, nodemasks are used to provide macros for node traversal, 172namely ``for_each_node()`` and ``for_each_online_node()``. 173 174For instance, to call a function foo() for each online node:: 175 176 for_each_online_node(nid) { 177 pg_data_t *pgdat = NODE_DATA(nid); 178 179 foo(pgdat); 180 } 181 182Node structure 183-------------- 184 185The nodes structure ``struct pglist_data`` is declared in 186``include/linux/mmzone.h``. Here we briefly describe fields of this 187structure: 188 189General 190~~~~~~~ 191 192``node_zones`` 193 The zones for this node. Not all of the zones may be populated, but it is 194 the full list. It is referenced by this node's node_zonelists as well as 195 other node's node_zonelists. 196 197``node_zonelists`` 198 The list of all zones in all nodes. This list defines the order of zones 199 that allocations are preferred from. The ``node_zonelists`` is set up by 200 ``build_zonelists()`` in ``mm/page_alloc.c`` during the initialization of 201 core memory management structures. 202 203``nr_zones`` 204 Number of populated zones in this node. 205 206``node_mem_map`` 207 For UMA systems that use FLATMEM memory model the 0's node 208 ``node_mem_map`` is array of struct pages representing each physical frame. 209 210``node_page_ext`` 211 For UMA systems that use FLATMEM memory model the 0's node 212 ``node_page_ext`` is array of extensions of struct pages. Available only 213 in the kernels built with ``CONFIG_PAGE_EXTENSION`` enabled. 214 215``node_start_pfn`` 216 The page frame number of the starting page frame in this node. 217 218``node_present_pages`` 219 Total number of physical pages present in this node. 220 221``node_spanned_pages`` 222 Total size of physical page range, including holes. 223 224``node_size_lock`` 225 A lock that protects the fields defining the node extents. Only defined when 226 at least one of ``CONFIG_MEMORY_HOTPLUG`` or 227 ``CONFIG_DEFERRED_STRUCT_PAGE_INIT`` configuration options are enabled. 228 ``pgdat_resize_lock()`` and ``pgdat_resize_unlock()`` are provided to 229 manipulate ``node_size_lock`` without checking for ``CONFIG_MEMORY_HOTPLUG`` 230 or ``CONFIG_DEFERRED_STRUCT_PAGE_INIT``. 231 232``node_id`` 233 The Node ID (NID) of the node, starts at 0. 234 235``totalreserve_pages`` 236 This is a per-node reserve of pages that are not available to userspace 237 allocations. 238 239``first_deferred_pfn`` 240 If memory initialization on large machines is deferred then this is the first 241 PFN that needs to be initialized. Defined only when 242 ``CONFIG_DEFERRED_STRUCT_PAGE_INIT`` is enabled 243 244``deferred_split_queue`` 245 Per-node queue of huge pages that their split was deferred. Defined only when ``CONFIG_TRANSPARENT_HUGEPAGE`` is enabled. 246 247``__lruvec`` 248 Per-node lruvec holding LRU lists and related parameters. Used only when 249 memory cgroups are disabled. It should not be accessed directly, use 250 ``mem_cgroup_lruvec()`` to look up lruvecs instead. 251 252Reclaim control 253~~~~~~~~~~~~~~~ 254 255See also Documentation/mm/page_reclaim.rst. 256 257``kswapd`` 258 Per-node instance of kswapd kernel thread. 259 260``kswapd_wait``, ``pfmemalloc_wait``, ``reclaim_wait`` 261 Workqueues used to synchronize memory reclaim tasks 262 263``nr_writeback_throttled`` 264 Number of tasks that are throttled waiting on dirty pages to clean. 265 266``nr_reclaim_start`` 267 Number of pages written while reclaim is throttled waiting for writeback. 268 269``kswapd_order`` 270 Controls the order kswapd tries to reclaim 271 272``kswapd_highest_zoneidx`` 273 The highest zone index to be reclaimed by kswapd 274 275``kswapd_failures`` 276 Number of runs kswapd was unable to reclaim any pages 277 278``min_unmapped_pages`` 279 Minimal number of unmapped file backed pages that cannot be reclaimed. 280 Determined by ``vm.min_unmapped_ratio`` sysctl. Only defined when 281 ``CONFIG_NUMA`` is enabled. 282 283``min_slab_pages`` 284 Minimal number of SLAB pages that cannot be reclaimed. Determined by 285 ``vm.min_slab_ratio sysctl``. Only defined when ``CONFIG_NUMA`` is enabled 286 287``flags`` 288 Flags controlling reclaim behavior. 289 290Compaction control 291~~~~~~~~~~~~~~~~~~ 292 293``kcompactd_max_order`` 294 Page order that kcompactd should try to achieve. 295 296``kcompactd_highest_zoneidx`` 297 The highest zone index to be compacted by kcompactd. 298 299``kcompactd_wait`` 300 Workqueue used to synchronize memory compaction tasks. 301 302``kcompactd`` 303 Per-node instance of kcompactd kernel thread. 304 305``proactive_compact_trigger`` 306 Determines if proactive compaction is enabled. Controlled by 307 ``vm.compaction_proactiveness`` sysctl. 308 309Statistics 310~~~~~~~~~~ 311 312``per_cpu_nodestats`` 313 Per-CPU VM statistics for the node 314 315``vm_stat`` 316 VM statistics for the node. 317 318.. _zones: 319 320Zones 321===== 322 323.. admonition:: Stub 324 325 This section is incomplete. Please list and describe the appropriate fields. 326 327.. _pages: 328 329Pages 330===== 331 332.. admonition:: Stub 333 334 This section is incomplete. Please list and describe the appropriate fields. 335 336.. _folios: 337 338Folios 339====== 340 341.. admonition:: Stub 342 343 This section is incomplete. Please list and describe the appropriate fields. 344 345.. _initialization: 346 347Initialization 348============== 349 350.. admonition:: Stub 351 352 This section is incomplete. Please list and describe the appropriate fields. 353