[Qemu-devel] [PATCH 0/2] qemu-options: document missing memory backend items

[Qemu-devel] [PATCH 0/2] qemu-options: document missing memory backend items

[Stefan Hajnoczi]

This series adds several missing items to the QEMU documentation on memory
backends.

Stefan Hajnoczi (2):
  qemu-options: document missing memory-backend-file options
  qemu-options: document memory-backend-ram

 qemu-options.hx | 55 ++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 48 insertions(+), 7 deletions(-)

-- 
2.14.3

[Qemu-devel] [PATCH 1/2] qemu-options: document missing memory-backend-file options

[Stefan Hajnoczi]

This patch adds undocumented memory-backend-file options to the
documentation.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 qemu-options.hx | 48 +++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 41 insertions(+), 7 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index 3728e9b4dd..f2cf0be193 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -4189,18 +4189,24 @@ property must be set.  These objects are placed in the
 
 @table @option
 
-@item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off},discard-data=@var{on|off}
+@item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off},discard-data=@var{on|off},merge=@var{on|off},dump=@var{on|off},prealloc=@var{on|off},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave}
 
 Creates a memory file backend object, which can be used to back
-the guest RAM with huge pages. The @option{id} parameter is a
-unique ID that will be used to reference this memory region
-when configuring the @option{-numa} argument. The @option{size}
-option provides the size of the memory region, and accepts
-common suffixes, eg @option{500M}. The @option{mem-path} provides
-the path to either a shared memory or huge page filesystem mount.
+the guest RAM with huge pages.
+
+The @option{id} parameter is a unique ID that will be used to reference this
+memory region when configuring the @option{-numa} argument.
+
+The @option{size} option provides the size of the memory region, and accepts
+common suffixes, eg @option{500M}.
+
+The @option{mem-path} provides the path to either a shared memory or huge page
+filesystem mount.
+
 The @option{share} boolean option determines whether the memory
 region is marked as private to QEMU, or shared. The latter allows
 a co-operating external process to access the QEMU memory region.
+
 Setting the @option{discard-data} boolean option to @var{on}
 indicates that file contents can be destroyed when QEMU exits,
 to avoid unnecessarily flushing data to the backing file.  Note
@@ -4208,6 +4214,34 @@ that @option{discard-data} is only an optimization, and QEMU
 might not discard file contents if it aborts unexpectedly or is
 terminated using SIGKILL.
 
+The @option{merge} boolean option enables memory merge, also known as
+MADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for
+memory deduplication.
+
+Setting the @option{dump} boolean option to @var{off} excludes the memory from
+core dumps. This feature is also known as MADV_DONTDUMP.
+
+The @option{prealloc} boolean option enables memory preallocation.
+
+The @option{host-nodes} option binds the memory range to a list of NUMA host
+nodes.
+
+The @option{policy} option sets the NUMA policy to one of the following values:
+
+@table @option
+@item @var{default}
+default host policy
+
+@item @var{preferred}
+prefer the given host node list for allocation
+
+@item @var{bind}
+restrict memory allocation to the given host node list
+
+@item @var{interleave}
+interleave memory allocations across the given host node list
+@end table
+
 @item -object rng-random,id=@var{id},filename=@var{/dev/random}
 
 Creates a random number generator backend which obtains entropy from
-- 
2.14.3

[Qemu-devel] [PATCH 2/2] qemu-options: document memory-backend-ram

[Stefan Hajnoczi]

The documentation should mention -object memory-backend-ram.

Suggested-by: Yumei Huang <yuhuang@redhat.com>
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 qemu-options.hx | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/qemu-options.hx b/qemu-options.hx
index f2cf0be193..65123ae177 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -4242,6 +4242,13 @@ restrict memory allocation to the given host node list
 interleave memory allocations across the given host node list
 @end table
 
+@item -object memory-backend-ram,id=@var{id},merge=@var{on|off},dump=@var{on|off},prealloc=@var{on|off},size=@var{size},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave}
+
+Creates a memory backend object, which can be used to back the guest RAM.
+Memory backend objects offer more control than the @option{-m} option that is
+traditionally used to define guest RAM. Please refer to
+@option{memory-backend-file} for a description of the options.
+
 @item -object rng-random,id=@var{id},filename=@var{/dev/random}
 
 Creates a random number generator backend which obtains entropy from
-- 
2.14.3

Re: [Qemu-devel] [PATCH 0/2] qemu-options: document missing memory backend items

[Eric Blake]

On 11/28/2017 10:15 AM, Stefan Hajnoczi wrote:
> This series adds several missing items to the QEMU documentation on memory
> backends.
> 
> Stefan Hajnoczi (2):
>    qemu-options: document missing memory-backend-file options
>    qemu-options: document memory-backend-ram
> 
>   qemu-options.hx | 55 ++++++++++++++++++++++++++++++++++++++++++++++++-------
>   1 file changed, 48 insertions(+), 7 deletions(-)

As documentation, it could still make it into 2.11, although you're 
cutting it close.  It's also fine if it waits for 2.12.

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

Re: [Qemu-devel] [PATCH 0/2] qemu-options: document missing memory backend items

[Eduardo Habkost]

On Tue, Nov 28, 2017 at 04:15:27PM +0000, Stefan Hajnoczi wrote:
> This series adds several missing items to the QEMU documentation on memory
> backends.

Reviewed-by: Eduardo Habkost <ehabkost@redhat.com>

I'm queueing it for 2.12 on machine-next.  Thanks.

-- 
Eduardo