[Qemu-devel] [PATCH 0/2] improve memory hotplug documentation

[Qemu-devel] [PATCH 0/2] improve memory hotplug documentation

[Luiz Capitulino]

Hi,

I started playing with memory hotplug the other day and missed some
good documentation explaining how to use the feature.

I figured I could contribute some documentation myself, although
I'm new to the feature so the chances of making mistakes is high.
Review is very much appreciated.

Luiz Capitulino (2):
  qemu-options.hx: improve -m description
  docs: add memory-hotplug.txt

 docs/memory-hotplug.txt | 77 +++++++++++++++++++++++++++++++++++++++++++++++++
 qemu-options.hx         | 23 +++++++++++----
 2 files changed, 95 insertions(+), 5 deletions(-)
 create mode 100644 docs/memory-hotplug.txt

-- 
1.9.3

[Qemu-devel] [PATCH 1/2] qemu-options.hx: improve -m description

[Luiz Capitulino]

Add memory hotplug options to the command-line format. Also,
add a complete command-line example and improve description.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 qemu-options.hx | 23 ++++++++++++++++++-----
 1 file changed, 18 insertions(+), 5 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index 85ca3ad..1634175 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -237,12 +237,25 @@ DEF("m", HAS_ARG, QEMU_OPTION_m,
     "NOTE: Some architectures might enforce a specific granularity\n",
     QEMU_ARCH_ALL)
 STEXI
-@item -m [size=]@var{megs}
+@item -m [size=]@var{megs}[,slots=n,maxmem=size]
 @findex -m
-Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB.  Optionally,
-a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
-gigabytes respectively. Optional pair @var{slots}, @var{maxmem} could be used
-to set amount of hotluggable memory slots and possible maximum amount of memory.
+Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB.
+Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in
+megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem}
+could be used to set amount of hotpluggable memory slots and maximum amount of
+memory.
+
+For example, the following command-line sets the guest startup RAM size to
+1GB, creates 3 slots to hotplug additional memory and sets the maximum
+memory the guest can reach to 4GB:
+
+@example
+qemy-system-i386 -m 1G,slots=3,maxmem=4G
+@end example
+
+If @var{slots} and @var{maxmem} are not specified, memory hotplug won't
+be enabled and the guest startup RAM will never increase (although it can
+be decreased with the use of ballooning).
 ETEXI
 
 DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
-- 
1.9.3

[Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Luiz Capitulino]

This document describes how to use memory hotplug in QEMU.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 docs/memory-hotplug.txt | 77 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 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..e821449
--- /dev/null
+++ b/docs/memory-hotplug.txt
@@ -0,0 +1,77 @@
+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 hot unplug is not supported yet. This means
+that you're able to add memory, but you're not able to remove it.
+Also, proper 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
+ - "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 gigas 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 the 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 commnands:
+
+  (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
-- 
1.9.3

Re: [Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 1341 bytes --]

On 02/26/2015 12:49 PM, Luiz Capitulino wrote:
> This document describes how to use memory hotplug in QEMU.
> 
> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> ---
>  docs/memory-hotplug.txt | 77 +++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 77 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..e821449
> --- /dev/null
> +++ b/docs/memory-hotplug.txt
> @@ -0,0 +1,77 @@
> +QEMU memory hotplug
> +===================
> +

Might be worth adding a copyright and license notice.


> +
> +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 gigas can be

s/gigas/gigabytes/


> +
> +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 commnands:

s/commnands/commands/

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]

Re: [Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Paulo Ricardo Paz Vital]

In addition to Eric's review.

On Thu, 2015-02-26 at 14:49 -0500, Luiz Capitulino wrote:
> This document describes how to use memory hotplug in QEMU.
> 
> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> ---
>  docs/memory-hotplug.txt | 77 +++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 77 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..e821449
> --- /dev/null
> +++ b/docs/memory-hotplug.txt
> @@ -0,0 +1,77 @@
> +QEMU memory hotplug

Not sure, but I guess the correct term is "hot plug" or "hot-plug". The
same approach should be used to "hot unplug" or "hot-unplug" and in the
first patch. Someone with better knowledge in English grammar than me
certainly can correct this. :-D

> +===================
> +
> +This document explains how to use the memory hotplug feature in QEMU,
> +which is present since v2.1.0.
> +
> +Please, note that memory hot unplug is not supported yet. This means
> +that you're able to add memory, but you're not able to remove it.
> +Also, proper proper guest support is required for memory hotplug

There are two "proper" words here.

> +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

Following the grammar question above, this should be "hot pluggable" or
"hot-pluggable".

> +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
> + - "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 gigas 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 the front-end pc-dimm device and inserts it
> +                 into an empty slot

s/the front-end/a front-end

> +
> +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 commnands:
> +
> +  (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

-- 
Paulo Ricardo Paz Vital <paulo.vital@profitbricks.com>
ProfitBricks GmbH

Re: [Qemu-devel] [PATCH 1/2] qemu-options.hx: improve -m description

[Peter Krempa]

[-- Attachment #1: Type: text/plain, Size: 2142 bytes --]

On Thu, Feb 26, 2015 at 14:49:15 -0500, Luiz Capitulino wrote:
> Add memory hotplug options to the command-line format. Also,
> add a complete command-line example and improve description.
> 
> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> ---
>  qemu-options.hx | 23 ++++++++++++++++++-----
>  1 file changed, 18 insertions(+), 5 deletions(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 85ca3ad..1634175 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -237,12 +237,25 @@ DEF("m", HAS_ARG, QEMU_OPTION_m,
>      "NOTE: Some architectures might enforce a specific granularity\n",
>      QEMU_ARCH_ALL)
>  STEXI
> -@item -m [size=]@var{megs}
> +@item -m [size=]@var{megs}[,slots=n,maxmem=size]
>  @findex -m
> -Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB.  Optionally,
> -a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
> -gigabytes respectively. Optional pair @var{slots}, @var{maxmem} could be used
> -to set amount of hotluggable memory slots and possible maximum amount of memory.
> +Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB.
> +Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in
> +megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem}
> +could be used to set amount of hotpluggable memory slots and maximum amount of
> +memory.
> +
> +For example, the following command-line sets the guest startup RAM size to
> +1GB, creates 3 slots to hotplug additional memory and sets the maximum
> +memory the guest can reach to 4GB:
> +
> +@example
> +qemy-system-i386 -m 1G,slots=3,maxmem=4G
> +@end example
> +
> +If @var{slots} and @var{maxmem} are not specified, memory hotplug won't
> +be enabled and the guest startup RAM will never increase (although it can
> +be decreased with the use of ballooning).
>  ETEXI

It might be also worth noting that maxmem has to be aligned to the page
size. See:
http://lists.gnu.org/archive/html/qemu-devel/2015-01/msg04345.html

(unfortunately it was not merged yet for some reason ...)

Peter

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Peter Krempa]

[-- Attachment #1: Type: text/plain, Size: 4150 bytes --]

On Thu, Feb 26, 2015 at 14:49:16 -0500, Luiz Capitulino wrote:
> This document describes how to use memory hotplug in QEMU.
> 
> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> ---
>  docs/memory-hotplug.txt | 77 +++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 77 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..e821449
> --- /dev/null
> +++ b/docs/memory-hotplug.txt
> @@ -0,0 +1,77 @@
> +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 hot unplug is not supported yet. This means
> +that you're able to add memory, but you're not able to remove it.
> +Also, proper 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 IIRC.

> + - "maxmem" is the maximum RAM size the guest can grow

And this has to be aligned properly (see reply to 1/2).

> +
> +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 gigas 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 the 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

The size here is also checked for alignment AFAIK. Also a sane minimum
for linux guests is 128MiB.

> +  (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 commnands:
> +
> +  (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

Otherwise a very helpful text :). Shame that it wasn't available sooner
I had to figure out the details myself.

Peter

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [Qemu-devel] [PATCH 1/2] qemu-options.hx: improve -m description

[Igor Mammedov]

On Mon, 2 Mar 2015 15:50:19 +0100
Peter Krempa <pkrempa@redhat.com> wrote:

> On Thu, Feb 26, 2015 at 14:49:15 -0500, Luiz Capitulino wrote:
> > Add memory hotplug options to the command-line format. Also,
> > add a complete command-line example and improve description.
> > 
> > Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> > ---
> >  qemu-options.hx | 23 ++++++++++++++++++-----
> >  1 file changed, 18 insertions(+), 5 deletions(-)
> > 
> > diff --git a/qemu-options.hx b/qemu-options.hx
> > index 85ca3ad..1634175 100644
> > --- a/qemu-options.hx
> > +++ b/qemu-options.hx
> > @@ -237,12 +237,25 @@ DEF("m", HAS_ARG, QEMU_OPTION_m,
> >      "NOTE: Some architectures might enforce a specific granularity\n",
> >      QEMU_ARCH_ALL)
> >  STEXI
> > -@item -m [size=]@var{megs}
> > +@item -m [size=]@var{megs}[,slots=n,maxmem=size]
> >  @findex -m
> > -Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB.  Optionally,
> > -a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
> > -gigabytes respectively. Optional pair @var{slots}, @var{maxmem} could be used
> > -to set amount of hotluggable memory slots and possible maximum amount of memory.
> > +Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB.
> > +Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in
> > +megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem}
> > +could be used to set amount of hotpluggable memory slots and maximum amount of
> > +memory.
> > +
> > +For example, the following command-line sets the guest startup RAM size to
> > +1GB, creates 3 slots to hotplug additional memory and sets the maximum
> > +memory the guest can reach to 4GB:
> > +
> > +@example
> > +qemy-system-i386 -m 1G,slots=3,maxmem=4G
> > +@end example
> > +
> > +If @var{slots} and @var{maxmem} are not specified, memory hotplug won't
> > +be enabled and the guest startup RAM will never increase (although it can
> > +be decreased with the use of ballooning).
> >  ETEXI
> 
> It might be also worth noting that maxmem has to be aligned to the page
> size. See:
> http://lists.gnu.org/archive/html/qemu-devel/2015-01/msg04345.html
> 
> (unfortunately it was not merged yet for some reason ...)
it wasn't lost, it's in the last (today's) pull req from PCI tree.

> 
> Peter

Re: [Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Igor Mammedov]

On Mon, 2 Mar 2015 15:52:48 +0100
Peter Krempa <pkrempa@redhat.com> wrote:

> On Thu, Feb 26, 2015 at 14:49:16 -0500, Luiz Capitulino wrote:
> > This document describes how to use memory hotplug in QEMU.
> > 
> > Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> > ---
> >  docs/memory-hotplug.txt | 77 +++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 77 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..e821449
> > --- /dev/null
> > +++ b/docs/memory-hotplug.txt
> > @@ -0,0 +1,77 @@
> > +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 hot unplug is not supported yet. This means
> > +that you're able to add memory, but you're not able to remove it.
> > +Also, proper 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 IIRC.
> 
> > + - "maxmem" is the maximum RAM size the guest can grow
> 
> And this has to be aligned properly (see reply to 1/2).
> 
> > +
> > +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 gigas 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 the 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
> 
> The size here is also checked for alignment AFAIK. Also a sane minimum
> for linux guests is 128MiB.
I've avoided mentioning minimum size limits as it's pure guest OS limitation
that has nothing to do with hardware (QEMU).
For example windows works just fine with 2M sizes.

> 
> > +  (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 commnands:
> > +
> > +  (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
> 
> Otherwise a very helpful text :). Shame that it wasn't available sooner
> I had to figure out the details myself.
> 
> Peter

Re: [Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Luiz Capitulino]

On Mon, 02 Mar 2015 10:59:59 +0100
Paulo Ricardo Paz Vital <paulo.vital@profitbricks.com> wrote:

> In addition to Eric's review.
> 
> On Thu, 2015-02-26 at 14:49 -0500, Luiz Capitulino wrote:
> > This document describes how to use memory hotplug in QEMU.
> > 
> > Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> > ---
> >  docs/memory-hotplug.txt | 77 +++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 77 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..e821449
> > --- /dev/null
> > +++ b/docs/memory-hotplug.txt
> > @@ -0,0 +1,77 @@
> > +QEMU memory hotplug
> 
> Not sure, but I guess the correct term is "hot plug" or "hot-plug". The
> same approach should be used to "hot unplug" or "hot-unplug" and in the
> first patch. Someone with better knowledge in English grammar than me
> certainly can correct this. :-D

Linux seems to call it hotplug in most docs. I have the impression that
we have used hotplug too in docs, changelog and code. Although we also
use hot-plug sometimes. As long as the doc can serve users well, I really
don't care.

I'll stick to hotplug, and had one inconsistency to fix.

I've fixed the other errors you found.

> > +===================
> > +
> > +This document explains how to use the memory hotplug feature in QEMU,
> > +which is present since v2.1.0.
> > +
> > +Please, note that memory hot unplug is not supported yet. This means
> > +that you're able to add memory, but you're not able to remove it.
> > +Also, proper proper guest support is required for memory hotplug
> 
> There are two "proper" words here.
> 
> > +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
> 
> Following the grammar question above, this should be "hot pluggable" or
> "hot-pluggable".
> 
> > +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
> > + - "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 gigas 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 the front-end pc-dimm device and inserts it
> > +                 into an empty slot
> 
> s/the front-end/a front-end
> 
> > +
> > +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 commnands:
> > +
> > +  (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
> 

Re: [Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Paulo Ricardo Paz Vital]

On Tue, 2015-03-03 at 09:47 -0500, Luiz Capitulino wrote:
> This document describes how to use memory hotplug in QEMU.
> 
> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> ---
>  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..f70571d
> --- /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
> + - "maxmem" is the maximum RAM size the guest can have
> +
> +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 the first 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 cold-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


Reviewed-by: Paulo Vital <paulo.vital@profitbricks.com>

Re: [Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Luiz Capitulino]

On Wed, 04 Mar 2015 09:16:53 +0100
Paulo Ricardo Paz Vital <paulo.vital@profitbricks.com> wrote:

> On Tue, 2015-03-03 at 11:16 -0500, Luiz Capitulino wrote:
> > On Tue, 03 Mar 2015 16:12:58 +0100
> > Paulo Ricardo Paz Vital <paulo.vital@profitbricks.com> wrote:
> > 
> > > On Tue, 2015-03-03 at 09:47 -0500, Luiz Capitulino wrote:
> > > > This document describes how to use memory hotplug in QEMU.
> > > > 
> > > > Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> > > > ---
> > > >  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..f70571d
> > > > --- /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
> > > 
> > > Igor suggested to s/grow/have in the line below, but I think you can
> > > change here also.
> > 
> > Right. If this is the only change required, then the maintainer could
> > change it when applying the series.
> > 
> 
> Ok!
> Should I reply the original patch with the reviewed-by mark?

That's always welcome.

> 
> > > 
> > > > +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
> > > 
> > > Here, for me, the sentence "It is the RAM the guest will boot with" is
> > > not necessary, since the first sentence ("is the startup RAM") already
> > > explain that VM will start with this amount of RAM.
> > 
> > I'm not strong about this, but I think that the term "startup RAM"
> > might not be obvious to everyone at first so I think it doesn't hurt
> > to define what it means in this context.
> > 
> 
> No problem! As I said, "for me the sentence is not necessary" :-D
> Nice work, BTW!
> 
> > > 
> > > > + - "slots" is the number of hotpluggable memory slots
> > > > + - "maxmem" is the maximum RAM size the guest can have
> > > > +
> > > > +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 the first 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 cold-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
> > > 
> > 
> 

Re: [Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Igor Mammedov]

On Tue,  3 Mar 2015 09:47:26 -0500
Luiz Capitulino <lcapitulino@redhat.com> wrote:

> This document describes how to use memory hotplug in QEMU.
> 
> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>

Reviewed-by: Igor Mammedov <imammedo@redhat.com>

> ---
>  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..f70571d
> --- /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
> + - "maxmem" is the maximum RAM size the guest can have
> +
> +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 the first 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 cold-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

Re: [Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Paulo Ricardo Paz Vital]

On Tue, 2015-03-03 at 11:16 -0500, Luiz Capitulino wrote:
> On Tue, 03 Mar 2015 16:12:58 +0100
> Paulo Ricardo Paz Vital <paulo.vital@profitbricks.com> wrote:
> 
> > On Tue, 2015-03-03 at 09:47 -0500, Luiz Capitulino wrote:
> > > This document describes how to use memory hotplug in QEMU.
> > > 
> > > Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> > > ---
> > >  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..f70571d
> > > --- /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
> > 
> > Igor suggested to s/grow/have in the line below, but I think you can
> > change here also.
> 
> Right. If this is the only change required, then the maintainer could
> change it when applying the series.
> 

Ok!
Should I reply the original patch with the reviewed-by mark?

> > 
> > > +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
> > 
> > Here, for me, the sentence "It is the RAM the guest will boot with" is
> > not necessary, since the first sentence ("is the startup RAM") already
> > explain that VM will start with this amount of RAM.
> 
> I'm not strong about this, but I think that the term "startup RAM"
> might not be obvious to everyone at first so I think it doesn't hurt
> to define what it means in this context.
> 

No problem! As I said, "for me the sentence is not necessary" :-D
Nice work, BTW!

> > 
> > > + - "slots" is the number of hotpluggable memory slots
> > > + - "maxmem" is the maximum RAM size the guest can have
> > > +
> > > +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 the first 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 cold-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
> > 
> 

-- 
Paulo Ricardo Paz Vital <paulo.vital@profitbricks.com>
ProfitBricks GmbH

Re: [Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Luiz Capitulino]

On Tue, 03 Mar 2015 10:40:23 -0700
Eric Blake <eblake@redhat.com> wrote:

> On 03/02/2015 03:14 PM, Luiz Capitulino wrote:
> > This document describes how to use memory hotplug in QEMU.
> > 
> > Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> > ---
> >  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
> > +===================
> > +
> 
> Is it worth having an explicit copyright/license blurb (this defaults to
> GPLv2+ per the top-level if you don't make it explicit).

That's fine with me.

Re: [Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 835 bytes --]

On 03/02/2015 03:14 PM, Luiz Capitulino wrote:
> This document describes how to use memory hotplug in QEMU.
> 
> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> ---
>  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
> +===================
> +

Is it worth having an explicit copyright/license blurb (this defaults to
GPLv2+ per the top-level if you don't make it explicit).

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]

Re: [Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Luiz Capitulino]

On Tue, 03 Mar 2015 16:12:58 +0100
Paulo Ricardo Paz Vital <paulo.vital@profitbricks.com> wrote:

> On Tue, 2015-03-03 at 09:47 -0500, Luiz Capitulino wrote:
> > This document describes how to use memory hotplug in QEMU.
> > 
> > Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> > ---
> >  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..f70571d
> > --- /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
> 
> Igor suggested to s/grow/have in the line below, but I think you can
> change here also.

Right. If this is the only change required, then the maintainer could
change it when applying the series.

> 
> > +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
> 
> Here, for me, the sentence "It is the RAM the guest will boot with" is
> not necessary, since the first sentence ("is the startup RAM") already
> explain that VM will start with this amount of RAM.

I'm not strong about this, but I think that the term "startup RAM"
might not be obvious to everyone at first so I think it doesn't hurt
to define what it means in this context.

> 
> > + - "slots" is the number of hotpluggable memory slots
> > + - "maxmem" is the maximum RAM size the guest can have
> > +
> > +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 the first 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 cold-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
> 

Re: [Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Paulo Ricardo Paz Vital]

On Tue, 2015-03-03 at 09:47 -0500, Luiz Capitulino wrote:
> This document describes how to use memory hotplug in QEMU.
> 
> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> ---
>  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..f70571d
> --- /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

Igor suggested to s/grow/have in the line below, but I think you can
change here also.

> +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

Here, for me, the sentence "It is the RAM the guest will boot with" is
not necessary, since the first sentence ("is the startup RAM") already
explain that VM will start with this amount of RAM.

> + - "slots" is the number of hotpluggable memory slots
> + - "maxmem" is the maximum RAM size the guest can have
> +
> +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 the first 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 cold-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

-- 
Paulo Ricardo Paz Vital <paulo.vital@profitbricks.com>
ProfitBricks GmbH

[Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Luiz Capitulino]

This document describes how to use memory hotplug in QEMU.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 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..f70571d
--- /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
+ - "maxmem" is the maximum RAM size the guest can have
+
+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 the first 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 cold-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
-- 
1.9.3

Re: [Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Luiz Capitulino]

On Tue, 3 Mar 2015 14:20:11 +0100
Igor Mammedov <imammedo@redhat.com> wrote:

> On Mon,  2 Mar 2015 17:14:48 -0500
> Luiz Capitulino <lcapitulino@redhat.com> wrote:
> 
> > This document describes how to use memory hotplug in QEMU.
> > 
> > Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> > ---
> >  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)
> 256 is implementation specific of target-i386, it might be different for other
> targets.
> I'd remove the limitation from generic doc.
> 
> > + - "maxmem" is the maximum RAM size the guest can grow
> s/grow/have/ - memory devices could be cold-plugged upto maxmem
> 
> > +
> > +For example, the following command-line:
> > +
> > + qemu [...] 1G,slots=3,maxmem=4G
> Maybe do the same in help message i.e. s/qemu-system-i386/qemu/

Well, in the manpage I did the same as other entries for consistency.
I think it doesn't matter much for this doc.

I've added most of your other comments though.

> 
> > +
> > +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
> s/an empty slot/the first empty it slot is not specified explicitly/
> 
> > +
> > +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
> s/plugged/cold-plugged/ prehaps?
> 
> > +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
> 

Re: [Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Igor Mammedov]

On Mon,  2 Mar 2015 17:14:48 -0500
Luiz Capitulino <lcapitulino@redhat.com> wrote:

> This document describes how to use memory hotplug in QEMU.
> 
> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> ---
>  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)
256 is implementation specific of target-i386, it might be different for other
targets.
I'd remove the limitation from generic doc.

> + - "maxmem" is the maximum RAM size the guest can grow
s/grow/have/ - memory devices could be cold-plugged upto maxmem

> +
> +For example, the following command-line:
> +
> + qemu [...] 1G,slots=3,maxmem=4G
Maybe do the same in help message i.e. s/qemu-system-i386/qemu/

> +
> +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
s/an empty slot/the first empty it slot is not specified explicitly/

> +
> +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
s/plugged/cold-plugged/ prehaps?

> +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

[Qemu-devel] [PATCH 2/2] docs: add memory-hotplug.txt

[Luiz Capitulino]

This document describes how to use memory hotplug in QEMU.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 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
-- 
1.9.3