cloud-hypervisor/docs/memory.md

1 # Memory  chapter
3 Cloud Hypervisor has many ways to expose memory to the guest VM. This document
9 `MemoryConfig` or what is known as `--memory` from the CLI perspective is the
29 --memory <memory>	Memory parameters "size=<guest_memory_size>,mergeable=on|off,shared=on|off,hugepa…
36 This option is mandatory when using the `--memory` parameter.
43 --memory size=1G
54 on a single host, as it will reduce the amount of memory consumed by each VM.
61 --memory size=1G,mergeable=on
66 Selects the way of adding and/or removing memory to/from a booted VM.
73 --memory size=1G,hotplug_method=acpi
78 Amount of memory that can be dynamically added to the VM.
85 --memory size=1G,hotplug_size=1G
90 Amount of memory that will be dynamically added to the VM at boot. This option
91 allows for starting a VM with a certain amount of memory that can be reduced
95 make sense for the `acpi` use case. When using ACPI, the memory can't be
106 --memory size=1G,hotplug_method=virtio-mem,hotplug_size=1G,hotplugged_size=512M
111 Specifies if the memory must be `mmap(2)` with `MAP_SHARED` flag.
113 By sharing a memory mapping, one can share the guest RAM with other processes
127 --memory size=1G,shared=on
132 Specifies if the memory must be created and `mmap(2)` with `MAP_HUGETLB` and size
133 flags. This performs a memory mapping relying on the specified huge page size.
155 --memory size=1G,hugepages=on,hugepage_size=2M
160 Specifies if the memory must be `mmap(2)` with `MAP_POPULATE` flag.
162 By triggering prefault, one can allocate all required physical memory and create
163 its page tables while calling `mmap`. With physical memory allocated, the number
167 physical memory and creating page tables in advance, and physical memory of the
171 restore and its choice will overwrite `prefault` in memory.
178 --memory size=1G,prefault=on
183 Specifies if private anonymous memory for the guest (i.e. `shared=off` and no
185 to the kernel that this memory may be backed with huge pages transparently.
197 --memory size=1G,thp=on
202 `MemoryZoneConfig` or what is known as `--memory-zone` from the CLI perspective
204 describing how every memory region is backed and exposed to the guest.
222 --memory-zone <memory-zone>	User defined memory zone parameters "size=<guest_memory_region_size>,fi…
225 This parameter expects one or more occurrences, allowing for a list of memory
226 zones to be defined. It must be used with `--memory size=0`, clearly indicating
227 that the memory will be described through advanced parameters.
234 Memory zone identifier. This identifier must be unique, otherwise an error will
237 This option is useful when referring to a memory zone previously created. In
238 particular, the `--numa` parameter can associate a memory zone to a specific
239 NUMA node based on the memory zone identifier.
241 This option is mandatory when using the `--memory-zone` parameter.
248 --memory size=0
249 --memory-zone id=mem0,size=1G
254 Size of the memory zone.
256 This option is mandatory when using the `--memory-zone` parameter.
263 --memory size=0
264 --memory-zone id=mem0,size=1G
269 Path to the file backing the memory zone. The file will be opened and used as
275 copy of the guest RAM content for this specific memory zone since the user has
284 --memory size=0
285 --memory-zone id=mem0,size=1G,file=/foo/bar
290 Specifies if the memory zone must be `mmap(2)` with `MAP_SHARED` flag.
292 By sharing a memory zone mapping, one can share part of the guest RAM with
306 --memory size=0
307 --memory-zone id=mem0,size=1G,shared=on
312 Specifies if the memory must be created and `mmap(2)` with `MAP_HUGETLB` and size
313 flags. This performs a memory mapping relying on the specified huge page size.
335 --memory size=0
336 --memory-zone id=mem0,size=1G,hugepages=on,hugepage_size=2M
342 pick a specific NUMA node from which the memory must be allocated. After the
343 memory zone is `mmap(2)`, the NUMA policy for this memory mapping will be
347 This option is useful when trying to back a VM memory with a specific type of
348 memory from the host. Assuming a host has two types of memory, with one slower
350 with slower memory accesses by backing the entire guest RAM from the furthest
353 This option also gives the opportunity to create a VM with non uniform memory
354 accesses as one could define a first memory zone backed by fast memory, and a
355 second memory zone backed by slow memory.
362 --memory size=0
363 --memory-zone id=mem0,size=1G,host_numa_node=0
368 Amount of memory that can be dynamically added to the memory zone. Since
369 `virtio-mem` is the only way of resizing a memory zone, one must specify
370 the `hotplug_method=virtio-mem` to the `--memory` parameter.
377 --memory size=0,hotplug_method=virtio-mem
378 --memory-zone id=mem0,size=1G,hotplug_size=1G
383 Amount of memory that will be dynamically added to a memory zone at VM's boot.
384 This option allows for starting a VM with a certain amount of memory that can
388 make sense for the `acpi` use case. When using ACPI, the memory can't be
399 --memory size=0,hotplug_method=virtio-mem
400 --memory-zone id=mem0,size=1G,hotplug_size=1G,hotplugged_size=512M
405 Specifies if the memory must be `mmap(2)` with `MAP_POPULATE` flag.
407 By triggering prefault, one can allocate all required physical memory and create
408 its page tables while calling `mmap`. With physical memory allocated, the number
412 physical memory and creating page tables in advance, and physical memory of the
416 restore and its choice will overwrite `prefault` in memory.
423 --memory size=0
424 --memory-zone id=mem0,size=1G,prefault=on
431 about the CPUs and memory ranges associated with each NUMA node. Additionally
499 provide an accurate description of the way non uniform memory accesses will
524 List of memory zones attached to the guest NUMA node identified by the
525 `guest_numa_id` option. This allows for describing a list of memory ranges
529 option from `--memory-zone` parameter as it allows for creating a VM with non
530 uniform memory accesses, and let the guest know about it. It allows for
531 exposing memory zones through different NUMA nodes, which can help the guest
535 referring to an existing memory zone identifier. Values are separated from
541 Note that a memory zone must belong to a single NUMA node. The following
548 --memory size=0
549 --memory-zone id=mem0,size=1G id=mem1,size=1G id=mem2,size=1G
583 --memory-zone size=16G,host_numa_node=0,id=mem0
584 --memory-zone size=16G,host_numa_node=1,id=mem1