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

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

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

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
>

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).

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.