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

Message ID 1425394046-20064-3-git-send-email-lcapitulino@redhat.com
State New
Headers show

Commit Message

Luiz Capitulino March 3, 2015, 2:47 p.m. UTC
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

Comments

Paulo Ricardo Paz Vital March 3, 2015, 3:12 p.m. UTC | #1
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
Luiz Capitulino March 3, 2015, 4:16 p.m. UTC | #2
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
>
Paulo Ricardo Paz Vital March 4, 2015, 8:16 a.m. UTC | #3
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
> > 
>
Igor Mammedov March 4, 2015, 12:04 p.m. UTC | #4
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
Luiz Capitulino March 4, 2015, 3:50 p.m. UTC | #5
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
> > > 
> > 
>
Paulo Ricardo Paz Vital March 4, 2015, 5 p.m. UTC | #6
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>

Patch
diff mbox

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