Luiz Capitulino | a3b0421 | 2015-02-26 14:43:07 -0500 | [diff] [blame] | 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 | |
Zhu Guihua | 4fccb48 | 2015-04-27 16:47:15 +0800 | [diff] [blame] | 7 | Guest support is required for memory hotplug to work. |
Luiz Capitulino | a3b0421 | 2015-02-26 14:43:07 -0500 | [diff] [blame] | 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 | |
Thomas Huth | 77fc026 | 2017-09-19 11:02:26 +0200 | [diff] [blame] | 27 | qemu [...] -m 1G,slots=3,maxmem=4G |
Luiz Capitulino | a3b0421 | 2015-02-26 14:43:07 -0500 | [diff] [blame] | 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 | |
Ville Skyttä | 9277d81 | 2018-06-12 09:51:50 +0300 | [diff] [blame] | 65 | In the following command-line example, an 8GB guest is created where 6GB |
Luiz Capitulino | a3b0421 | 2015-02-26 14:43:07 -0500 | [diff] [blame] | 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 |
Zhu Guihua | 4fccb48 | 2015-04-27 16:47:15 +0800 | [diff] [blame] | 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 |