Lines Matching +full:memory +full:- +full:to +full:- +full:memory
2 Memory Hot(Un)Plug
5 This document describes generic Linux support for memory hot(un)plug with
13 Memory hot(un)plug allows for increasing and decreasing the size of physical
14 memory available to a machine at runtime. In the simplest case, it consists of
18 Memory hot(un)plug is used for various purposes:
20 - The physical memory available to a machine can be adjusted at runtime, up- or
21 downgrading the memory capacity. This dynamic memory resizing, sometimes
22 referred to as "capacity on demand", is frequently used with virtual machines
25 - Replacing hardware, such as DIMMs or whole NUMA nodes, without downtime. One
26 example is replacing failing memory modules.
28 - Reducing energy consumption either by physically unplugging memory modules or
29 by logically unplugging (parts of) memory modules from Linux.
31 Further, the basic memory hot(un)plug infrastructure in Linux is nowadays also
32 used to expose persistent memory, other performance-differentiated memory and
33 reserved memory regions as ordinary system RAM to Linux.
35 Linux only supports memory hot(un)plug on selected 64 bit architectures, such as
38 Memory Hot(Un)Plug Granularity
39 ------------------------------
41 Memory hot(un)plug in Linux uses the SPARSEMEM memory model, which divides the
42 physical memory address space into chunks of the same size: memory sections. The
43 size of a memory section is architecture dependent. For example, x86_64 uses
46 Memory sections are combined into chunks referred to as "memory blocks". The
47 size of a memory block is architecture dependent and corresponds to the smallest
48 granularity that can be hot(un)plugged. The default size of a memory block is
49 the same as memory section size, unless an architecture specifies otherwise.
51 All memory blocks have the same size.
53 Phases of Memory Hotplug
54 ------------------------
56 Memory hotplug consists of two phases:
58 (1) Adding the memory to Linux
59 (2) Onlining memory blocks
61 In the first phase, metadata, such as the memory map ("memmap") and page tables
62 for the direct mapping, is allocated and initialized, and memory blocks are
63 created; the latter also creates sysfs files for managing newly created memory
66 In the second phase, added memory is exposed to the page allocator. After this
67 phase, the memory is visible in memory statistics, such as free and total
68 memory, of the system.
70 Phases of Memory Hotunplug
71 --------------------------
73 Memory hotunplug consists of two phases:
75 (1) Offlining memory blocks
76 (2) Removing the memory from Linux
78 In the first phase, memory is "hidden" from the page allocator again, for
79 example, by migrating busy memory to other memory locations and removing all
80 relevant free pages from the page allocator After this phase, the memory is no
81 longer visible in memory statistics of the system.
83 In the second phase, the memory blocks are removed and metadata is freed.
85 Memory Hotplug Notifications
88 There are various ways how Linux is notified about memory hotplug events such
89 that it can start adding hotplugged memory. This description is limited to
90 systems that support ACPI; mechanisms specific to other firmware interfaces or
94 ------------------
96 Platforms that support ACPI, such as x86_64, can support memory hotplug
99 In general, a firmware supporting memory hotplug defines a memory class object
100 HID "PNP0C80". When notified about hotplug of a new memory device, the ACPI
101 driver will hotplug the memory to Linux.
105 assigned memory devices are added to Linux by the ACPI driver.
107 Similarly, Linux can be notified about requests to hotunplug a memory device or
108 a NUMA node via ACPI. The ACPI driver will try offlining all relevant memory
109 blocks, and, if successful, hotunplug the memory from Linux.
112 --------------
114 On some architectures, the firmware may not be able to notify the operating
115 system about a memory hotplug event. Instead, the memory has to be manually
120 /sys/devices/system/memory/probe
122 Only complete memory blocks can be probed. Individual memory blocks are probed
123 by providing the physical start address of the memory block::
125 % echo addr > /sys/devices/system/memory/probe
127 Which results in a memory block for the range [addr, addr + memory_block_size)
132 Using the probe interface is discouraged as it is easy to crash the kernel,
136 Onlining and Offlining Memory Blocks
139 After a memory block has been created, Linux has to be instructed to actually
140 make use of that memory: the memory block has to be "online".
142 Before a memory block can be removed, Linux has to stop using any memory part of
143 the memory block: the memory block has to be "offlined".
145 The Linux kernel can be configured to automatically online added memory blocks
146 and drivers automatically trigger offlining of memory blocks when trying
147 hotunplug of memory. Memory blocks can only be removed once offlining succeeded
148 and drivers may trigger offlining of memory blocks when attempting hotunplug of
149 memory.
151 Onlining Memory Blocks Manually
152 -------------------------------
154 If auto-onlining of memory blocks isn't enabled, user-space has to manually
155 trigger onlining of memory blocks. Often, udev rules are used to automate this
158 Onlining of a memory block can be triggered via::
160 % echo online > /sys/devices/system/memory/memoryXXX/state
164 % echo 1 > /sys/devices/system/memory/memoryXXX/online
169 One can explicitly request to associate an offline memory block with
172 % echo online_movable > /sys/devices/system/memory/memoryXXX/state
176 % echo online_kernel > /sys/devices/system/memory/memoryXXX/state
178 In any case, if onlining succeeds, the state of the memory block is changed to
179 be "online". If it fails, the state of the memory block will remain unchanged
182 Onlining Memory Blocks Automatically
183 ------------------------------------
185 The kernel can be configured to try auto-onlining of newly added memory blocks.
186 If this feature is disabled, the memory blocks will stay offline until
189 The configured auto-online behavior can be observed via::
191 % cat /sys/devices/system/memory/auto_online_blocks
193 Auto-onlining can be enabled by writing ``online``, ``online_kernel`` or
194 ``online_movable`` to that file, like::
196 % echo online > /sys/devices/system/memory/auto_online_blocks
198 Similarly to manual onlining, with ``online`` the kernel will select the
201 Modifying the auto-online behavior will only affect all subsequently added
202 memory blocks only.
206 In corner cases, auto-onlining can fail. The kernel won't retry. Note that
207 auto-onlining is not expected to fail in default configurations.
212 memory blocks; if onlining fails, memory blocks are removed again.
214 Offlining Memory Blocks
215 -----------------------
217 In the current implementation, Linux's memory offlining will try migrating all
218 movable pages off the affected memory block. As most kernel allocations, such as
220 memory offlining from succeeding.
222 Having the memory provided by memory block managed by ZONE_MOVABLE significantly
223 increases memory offlining reliability; still, memory offlining can fail in
226 Further, memory offlining might retry for a long time (or even forever), until
229 Offlining of a memory block can be triggered via::
231 % echo offline > /sys/devices/system/memory/memoryXXX/state
235 % echo 0 > /sys/devices/system/memory/memoryXXX/online
237 If offlining succeeds, the state of the memory block is changed to be "offline".
238 If it fails, the state of the memory block will remain unchanged and the above
247 Observing the State of Memory Blocks
248 ------------------------------------
250 The state (online/offline/going-offline) of a memory block can be observed
253 % cat /sys/devices/system/memory/memoryXXX/state
257 % cat /sys/devices/system/memory/memoryXXX/online
259 For an online memory block, the managing zone can be observed via::
261 % cat /sys/devices/system/memory/memoryXXX/valid_zones
263 Configuring Memory Hot(Un)Plug
266 There are various ways how system administrators can configure memory
267 hot(un)plug and interact with memory blocks, especially, to online them.
269 Memory Hot(Un)Plug Configuration via Sysfs
270 ------------------------------------------
272 Some memory hot(un)plug properties can be configured or inspected via sysfs in::
274 /sys/devices/system/memory/
279 ``auto_online_blocks`` read-write: set or get the default state of new memory
280 blocks; configure auto-onlining.
286 See the ``state`` property of memory blocks for details.
287 ``block_size_bytes`` read-only: the size in bytes of a memory block.
288 ``probe`` write-only: add (probe) selected memory blocks manually
293 ``uevent`` read-write: generic udev file for device subsystems.
294 ``crash_hotplug`` read-only: when changes to the system memory map
295 occur due to hot un/plug of memory, this file contains
296 '1' if the kernel updates the kdump capture kernel memory
299 capture kernel memory map.
309 to trigger hwpoisoning of pages, for example, for testing purposes. Note that
310 this functionality is not really related to memory hot(un)plug or actual
311 offlining of memory blocks.
313 Memory Block Configuration via Sysfs
314 ------------------------------------
316 Each memory block is represented as a memory block device that can be
317 onlined or offlined. All memory blocks have their device information located in
318 sysfs. Each present memory block is listed under
319 ``/sys/devices/system/memory`` as::
321 /sys/devices/system/memory/memoryXXX
323 where XXX is the memory block id; the number of digits is variable.
325 A present memory block indicates that some memory in the range is present;
326 however, a memory block might span memory holes. A memory block spanning memory
329 For example, assume 1 GiB memory block size. A device for a memory starting at
330 0x100000000 is ``/sys/devices/system/memory/memory4``::
339 ``online`` read-write: simplified interface to trigger onlining /
340 offlining and to observe the state of a memory block.
342 ``phys_device`` read-only: legacy interface only ever used on s390x to
344 ``phys_index`` read-only: the memory block id (XXX).
345 ``removable`` read-only: legacy interface that indicated whether a memory
346 block was likely to be offlineable or not. Nowadays, the
347 kernel return ``1`` if and only if it supports memory
349 ``state`` read-write: advanced interface to trigger onlining /
350 offlining and to observe the state of a memory block.
355 ``online_movable`` specifies onlining to ZONE_MOVABLE.
356 ``online_kernel`` specifies onlining to the default kernel
357 zone for the memory block, such as ZONE_NORMAL.
360 When reading, ``online``, ``offline`` and ``going-offline``
362 ``uevent`` read-write: generic uevent file for devices.
363 ``valid_zones`` read-only: when a block is online, shows the zone it
364 belongs to; when a block is offline, shows what zone will
367 For online memory blocks, ``DMA``, ``DMA32``, ``Normal``,
369 that memory provided by a memory block is managed by
370 multiple zones or spans multiple nodes; such memory blocks
374 For offline memory blocks, the first column shows the
375 zone the kernel would select when onlining the memory block
390 /sys/devices/system/node/node0/memory9 -> ../../memory/memory9
394 /sys/devices/system/memory/memory9/node0 -> ../../node/node0
397 -----------------------
399 Some command line parameters affect memory hot(un)plug handling. The following
403 ``memhp_default_state`` configure auto-onlining by essentially setting
404 ``/sys/devices/system/memory/auto_online_blocks``.
406 using the ``contig-zones`` online policy. When
407 set, the kernel will default to ZONE_MOVABLE when
408 onlining a memory block, unless other zones can be kept
412 See Documentation/admin-guide/kernel-parameters.txt for a more generic
416 ------------------
432 ``memmap_on_memory`` read-write: Allocate memory for the memmap from
433 the added memory block itself. Even if enabled,
438 While allocating the memmap from the memory
439 block itself makes memory hotplug less likely
440 to fail and keeps the memmap on the same NUMA
442 memory in a way that huge pages in bigger
444 memory.
446 With value "force" it could result in memory
447 wastage due to memmap size limitations. For
448 example, if the memmap for a memory block
450 MiB, 1 MiB of hotplugged memory will be wasted.
457 ``online_policy`` read-write: Set the basic policy used for
458 automatic zone selection when onlining memory
460 ``contig-zones`` has been the kernel default
462 online policy was configured and memory was
466 When set to ``contig-zones``, the kernel will
467 try keeping zones contiguous. If a memory block
470 command line parameter: default to ZONE_MOVABLE
471 if set, default to the applicable kernel zone
474 When set to ``auto-movable``, the kernel will
475 try onlining memory blocks to ZONE_MOVABLE if
476 possible according to the configuration and
477 memory device details. With this policy, one
479 hotplugging a lot of memory later and still
480 wanting to be able to hotunplug as much as
487 memory might be exposed via the
488 firmware-provided memory map early during boot
489 to the system instead of getting detected,
491 done by virtio-mem or by some hypervisors
494 completely to ZONE_MOVABLE or completely to
496 As another example, as many memory blocks
497 belonging to a virtio-mem device will be
498 onlined to ZONE_MOVABLE as possible,
499 special-casing units of memory blocks that can
503 change the zone of memory blocks dynamically
505 ``auto_movable_ratio`` read-write: Set the maximum MOVABLE:KERNEL
506 memory ratio in % for the ``auto-movable``
512 All accounting is based on present memory pages
514 memory device. Memory dedicated to the CMA
519 allowing for hotplugging 24 GiB to a 8 GiB VM
521 memory to ZONE_MOVABLE in many setups. The
526 Note that ZONE_NORMAL memory provided by one
527 memory device does not allow for more
528 ZONE_MOVABLE memory for a different memory
529 device. As one example, onlining memory of a
530 hotplugged DIMM to ZONE_NORMAL will not allow
531 for another hotplugged DIMM to get onlined to
532 ZONE_MOVABLE automatically. In contrast, memory
533 hotplugged by a virtio-mem device that got
534 onlined to ZONE_NORMAL will allow for more
535 ZONE_MOVABLE memory within *the same*
536 virtio-mem device.
537 ``auto_movable_numa_aware`` read-write: Configure whether the
538 ``auto_movable_ratio`` in the ``auto-movable``
540 node in addition to the whole system across all
545 completely hotunpluggable, onlining the memory
546 completely to ZONE_MOVABLE automatically if
555 ZONE_MOVABLE is an important mechanism for more reliable memory offlining.
560 Most kernel allocations are unmovable. Important examples include the memory
561 map (usually 1/64ths of memory), page tables, and kmalloc(). Such allocations
564 Most user space pages, such as anonymous memory, and page cache pages are
568 allocations being limited to the kernel zones. Without ZONE_MOVABLE, there is
569 absolutely no guarantee whether a memory block can be offlined successfully.
572 ---------------
576 might crash because it runs out of free memory for unmovable allocations,
577 although there is still plenty of free memory left in ZONE_MOVABLE.
579 Usually, MOVABLE:KERNEL ratios of up to 3:1 or even 4:1 are fine. Ratios of 63:1
580 are definitely impossible due to the overhead for the memory map.
583 long-term pinning of pages, might not be able to deal with ZONE_MOVABLE at all.
587 CMA memory part of a kernel zone essentially behaves like memory in
592 ----------------------------------
599 managed by ZONE_MOVABLE. However, there are some things to consider when using
600 ZONE_MOVABLE, especially when fine-tuning zone ratios:
602 - Having a lot of offline memory blocks. Even offline memory blocks consume
603 memory for metadata and page tables in the direct map; having a lot of offline
604 memory blocks is not a typical case, though.
606 - Memory ballooning without balloon compaction is incompatible with
607 ZONE_MOVABLE. Only some implementations, such as virtio-balloon and
615 - Gigantic pages are unmovable, resulting in user space consuming a
616 lot of unmovable memory.
618 - Huge pages are unmovable when an architectures does not support huge
621 - Page tables are unmovable. Excessive swapping, mapping extremely large
622 files or ZONE_DEVICE memory can be problematic, although only really relevant
623 in corner cases. When we manage a lot of user space memory that has been
624 swapped out or is served from a file/persistent memory/... we still need a lot
625 of page tables to manage that memory once user space accessed that memory.
627 - In certain DAX configurations the memory map for the device memory will be
630 - KASAN can have a significant memory overhead, for example, consuming 1/8th of
631 the total system memory size as (unmovable) tracking metadata.
633 - Long-term pinning of pages. Techniques that rely on long-term pinnings
635 ZONE_MOVABLE, and therefore, memory offlining. Pinned pages cannot reside
637 have to be migrated off that zone while pinning. Pinning a page can fail
638 even if there is plenty of free memory in ZONE_MOVABLE.
643 By default, all the memory configured at boot time is managed by the kernel
646 To enable ZONE_MOVABLE to include the memory present at boot and to control the
649 Documentation/admin-guide/kernel-parameters.rst for their description.
651 Memory Offlining and ZONE_MOVABLE
652 ---------------------------------
654 Even with ZONE_MOVABLE, there are some corner cases where offlining a memory
657 - Memory blocks with memory holes; this applies to memory blocks present during
658 boot and can apply to memory blocks hotplugged via the XEN balloon and the
659 Hyper-V balloon.
661 - Mixed NUMA nodes and mixed zones within a single memory block prevent memory
662 offlining; this applies to memory blocks present during boot only.
664 - Special memory blocks prevented by the system from getting offlined. Examples
665 include any memory available during boot on arm64 or memory blocks spanning
666 the crashkernel area on s390x; this usually applies to memory blocks present
669 - Memory blocks overlapping with CMA areas cannot be offlined, this applies to
670 memory blocks present during boot only.
672 - Concurrent activity that operates on the same physical memory area, such as
675 - Out of memory when dissolving huge pages, especially when HugeTLB Vmemmap
678 Offlining code may be able to migrate huge page contents, but may not be able
679 to dissolve the source huge page because it fails allocating (unmovable) pages
680 for the vmemmap, because the system might not have free memory in the kernel
683 Users that depend on memory offlining to succeed for movable zones should
684 carefully consider whether the memory savings gained from this feature are
685 worth the risk of possibly not being able to offline memory in certain
688 Further, when running into out of memory situations while migrating pages, or
690 (-> BUG), memory offlining will keep retrying until it eventually succeeds.