From patchwork Mon Mar 2 22:14:48 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Capitulino X-Patchwork-Id: 445454 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [IPv6:2001:4830:134:3::11]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id E17FB1400F1 for ; Tue, 3 Mar 2015 09:17:06 +1100 (AEDT) Received: from localhost ([::1]:59957 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YSYe8-0002BM-SF for incoming@patchwork.ozlabs.org; Mon, 02 Mar 2015 17:17:04 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:35828) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YSYc8-0006xk-N0 for qemu-devel@nongnu.org; Mon, 02 Mar 2015 17:15:04 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YSYc2-0001uV-HH for qemu-devel@nongnu.org; Mon, 02 Mar 2015 17:15:00 -0500 Received: from mx1.redhat.com ([209.132.183.28]:56442) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YSYc2-0001uO-AD for qemu-devel@nongnu.org; Mon, 02 Mar 2015 17:14:54 -0500 Received: from int-mx11.intmail.prod.int.phx2.redhat.com (int-mx11.intmail.prod.int.phx2.redhat.com [10.5.11.24]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id t22MEqIR030150 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Mon, 2 Mar 2015 17:14:53 -0500 Received: from localhost (ovpn-113-132.phx2.redhat.com [10.3.113.132]) by int-mx11.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id t22MEpb7018854; Mon, 2 Mar 2015 17:14:52 -0500 From: Luiz Capitulino To: qemu-devel@nongnu.org Date: Mon, 2 Mar 2015 17:14:48 -0500 Message-Id: <1425334488-28123-3-git-send-email-lcapitulino@redhat.com> In-Reply-To: <1425334488-28123-1-git-send-email-lcapitulino@redhat.com> References: <1425334488-28123-1-git-send-email-lcapitulino@redhat.com> X-Scanned-By: MIMEDefang 2.68 on 10.5.11.24 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 209.132.183.28 Cc: imammedo@redhat.com, pkrempa@redhat.com, paulo.vital@profitbricks.com Subject: [Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org This document describes how to use memory hotplug in QEMU. Signed-off-by: Luiz Capitulino --- docs/memory-hotplug.txt | 76 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 docs/memory-hotplug.txt diff --git a/docs/memory-hotplug.txt b/docs/memory-hotplug.txt new file mode 100644 index 0000000..70bac79 --- /dev/null +++ b/docs/memory-hotplug.txt @@ -0,0 +1,76 @@ +QEMU memory hotplug +=================== + +This document explains how to use the memory hotplug feature in QEMU, +which is present since v2.1.0. + +Please, note that memory hotunplug is not supported yet. This means +that you're able to add memory, but you're not able to remove it. +Also, proper guest support is required for memory hotplug to work. + +Basic RAM hotplug +----------------- + +In order to be able to hotplug memory, QEMU has to be told how many +hotpluggable memory slots to create and what is the maximum amount of +memory the guest can grow. This is done at startup time by means of +the -m command-line option, which has the following format: + + -m [size=]megs[,slots=n,maxmem=size] + +Where, + + - "megs" is the startup RAM. It is the RAM the guest will boot with + - "slots" is the number of hotpluggable memory slots (limit is 256 slots) + - "maxmem" is the maximum RAM size the guest can grow + +For example, the following command-line: + + qemu [...] 1G,slots=3,maxmem=4G + +Creates a guest with 1GB of memory and three hotpluggable memory slots. +The hotpluggable memory slots are empty when the guest is booted, so all +memory the guest will see after boot is 1GB. The maximum memory the +guest can reach is 4GB. This means that three additional gigabytes can be +hotplugged by using any combination of the available memory slots. + +Two monitor commands are used to hotplug memory: + + - "object_add": creates a memory backend object + - "device_add": creates a front-end pc-dimm device and inserts it + into an empty slot + +For example, the following commands add another 1GB to the guest +discussed earlier: + + (qemu) object_add memory-backend-ram,id=mem1,size=1G + (qemu) device_add pc-dimm,id=dimm1,memdev=mem1 + +Using the file backend +---------------------- + +Besides basic RAM hotplug, QEMU also supports using files as a memory +backend. This is useful for using hugetlbfs in Linux, which provides +access to bigger page sizes. + +For example, assuming that the host has 1GB hugepages available in +the /mnt/hugepages-1GB directory, a 1GB hugepage could be hotplugged +into the guest from the previous section with the following commands: + + (qemu) object_add memory-backend-file,id=mem1,size=1G,mem-path=/mnt/hugepages-1GB + (qemu) device_add pc-dimm,id=dimm1,memdev=mem1 + +It's also possible to start a guest with memory plugged into the +hotpluggable memory slots. This might seem counterintuitive at first, +but this allows for a lot of flexibility when using the file backend. + +In the following command-line example, a 8GB guest is created where 6GB +comes from regular RAM, 1GB is a 1GB hugepage page and 256MB is from +2MB pages. Also, the guest has additional memory slots to hotplug more +2GB if needed: + + qemu [...] -m 6GB,slots=4,maxmem=10G \ + -object memory-backend-file,id=mem1,size=1G,mem-path=/mnt/hugepages-1G \ + -device pc-dimm,id=dimm1,memdev=mem1 \ + -object memory-backend-file,id=mem2,size=256M,mem-path=/mnt/hugepages-2MB \ + -device pc-dimm,id=dimm2,memdev=mem2