qemu/docs/memory-hotplug.txt
<<
>>
Prefs
   1QEMU memory hotplug
   2===================
   3
   4This document explains how to use the memory hotplug feature in QEMU,
   5which is present since v2.1.0.
   6
   7Guest support is required for memory hotplug to work.
   8
   9Basic RAM hotplug
  10-----------------
  11
  12In order to be able to hotplug memory, QEMU has to be told how many
  13hotpluggable memory slots to create and what is the maximum amount of
  14memory the guest can grow. This is done at startup time by means of
  15the -m command-line option, which has the following format:
  16
  17 -m [size=]megs[,slots=n,maxmem=size]
  18
  19Where,
  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
  25For example, the following command-line:
  26
  27 qemu [...] -m 1G,slots=3,maxmem=4G
  28
  29Creates a guest with 1GB of memory and three hotpluggable memory slots.
  30The hotpluggable memory slots are empty when the guest is booted, so all
  31memory the guest will see after boot is 1GB. The maximum memory the
  32guest can reach is 4GB. This means that three additional gigabytes can be
  33hotplugged by using any combination of the available memory slots.
  34
  35Two 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
  41For example, the following commands add another 1GB to the guest
  42discussed earlier:
  43
  44  (qemu) object_add memory-backend-ram,id=mem1,size=1G
  45  (qemu) device_add pc-dimm,id=dimm1,memdev=mem1
  46
  47Using the file backend
  48----------------------
  49
  50Besides basic RAM hotplug, QEMU also supports using files as a memory
  51backend. This is useful for using hugetlbfs in Linux, which provides
  52access to bigger page sizes.
  53
  54For example, assuming that the host has 1GB hugepages available in
  55the /mnt/hugepages-1GB directory, a 1GB hugepage could be hotplugged
  56into 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
  61It's also possible to start a guest with memory cold-plugged into the
  62hotpluggable memory slots. This might seem counterintuitive at first,
  63but this allows for a lot of flexibility when using the file backend.
  64
  65In the following command-line example, an 8GB guest is created where 6GB
  66comes from regular RAM, 1GB is a 1GB hugepage page and 256MB is from
  672MB pages. Also, the guest has additional memory slots to hotplug more
  682GB 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
  77RAM hot-unplug
  78---------------
  79
  80In order to be able to hot unplug pc-dimm device, QEMU has to be told the ids
  81of pc-dimm device and memory backend object. The ids were assigned when you hot
  82plugged memory.
  83
  84Two 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
  89For example, assuming that the pc-dimm device with id "dimm1" exists, and its memory
  90backend is "mem1", the following commands tries to remove it.
  91
  92  (qemu) device_del dimm1
  93  (qemu) object_del mem1
  94