hw/arm/virt: pass VirtMachineState instead of VirtGuestInfo
[qemu.git] / docs / memory-hotplug.txt
1 QEMU memory hotplug
2 ===================
3
4 This document explains how to use the memory hotplug feature in QEMU,
5 which is present since v2.1.0.
6
7 Guest support is required for memory hotplug to work.
8
9 Basic RAM hotplug
10 -----------------
11
12 In order to be able to hotplug memory, QEMU has to be told how many
13 hotpluggable memory slots to create and what is the maximum amount of
14 memory the guest can grow. This is done at startup time by means of
15 the -m command-line option, which has the following format:
16
17  -m [size=]megs[,slots=n,maxmem=size]
18
19 Where,
20
21  - "megs" is the startup RAM. It is the RAM the guest will boot with
22  - "slots" is the number of hotpluggable memory slots
23  - "maxmem" is the maximum RAM size the guest can have
24
25 For example, the following command-line:
26
27  qemu [...] 1G,slots=3,maxmem=4G
28
29 Creates a guest with 1GB of memory and three hotpluggable memory slots.
30 The hotpluggable memory slots are empty when the guest is booted, so all
31 memory the guest will see after boot is 1GB. The maximum memory the
32 guest can reach is 4GB. This means that three additional gigabytes can be
33 hotplugged by using any combination of the available memory slots.
34
35 Two monitor commands are used to hotplug memory:
36
37  - "object_add": creates a memory backend object
38  - "device_add": creates a front-end pc-dimm device and inserts it
39                  into the first empty slot
40
41 For example, the following commands add another 1GB to the guest
42 discussed earlier:
43
44   (qemu) object_add memory-backend-ram,id=mem1,size=1G
45   (qemu) device_add pc-dimm,id=dimm1,memdev=mem1
46
47 Using the file backend
48 ----------------------
49
50 Besides basic RAM hotplug, QEMU also supports using files as a memory
51 backend. This is useful for using hugetlbfs in Linux, which provides
52 access to bigger page sizes.
53
54 For example, assuming that the host has 1GB hugepages available in
55 the /mnt/hugepages-1GB directory, a 1GB hugepage could be hotplugged
56 into the guest from the previous section with the following commands:
57
58   (qemu) object_add memory-backend-file,id=mem1,size=1G,mem-path=/mnt/hugepages-1GB
59   (qemu) device_add pc-dimm,id=dimm1,memdev=mem1
60
61 It's also possible to start a guest with memory cold-plugged into the
62 hotpluggable memory slots. This might seem counterintuitive at first,
63 but this allows for a lot of flexibility when using the file backend.
64
65 In the following command-line example, a 8GB guest is created where 6GB
66 comes from regular RAM, 1GB is a 1GB hugepage page and 256MB is from
67 2MB pages. Also, the guest has additional memory slots to hotplug more
68 2GB if needed:
69
70  qemu [...] -m 6GB,slots=4,maxmem=10G \
71    -object memory-backend-file,id=mem1,size=1G,mem-path=/mnt/hugepages-1G \
72    -device pc-dimm,id=dimm1,memdev=mem1 \
73    -object memory-backend-file,id=mem2,size=256M,mem-path=/mnt/hugepages-2MB \
74    -device pc-dimm,id=dimm2,memdev=mem2
75
76
77 RAM hot-unplug
78 ---------------
79
80 In order to be able to hot unplug pc-dimm device, QEMU has to be told the ids
81 of pc-dimm device and memory backend object. The ids were assigned when you hot
82 plugged memory.
83
84 Two monitor commands are used to hot unplug memory:
85
86  - "device_del": deletes a front-end pc-dimm device
87  - "object_del": deletes a memory backend object
88
89 For example, assuming that the pc-dimm device with id "dimm1" exists, and its memory
90 backend is "mem1", the following commands tries to remove it.
91
92   (qemu) device_del dimm1
93   (qemu) object_del mem1