[Qemu-devel] [PATCH 0/2] qemu-options: Rewrite -numa documentation

[Qemu-devel] [PATCH 0/2] qemu-options: Rewrite -numa documentation

[Eduardo Habkost]

The first patch is a trivial fix to an issue reported by Peter
Maydell. The second patch rewrites all the rest.

Eduardo Habkost (2):
  qemu-options: Rename variables on the -numa "cpus" option
  qemu-options: Rewrite -numa documentation

 qemu-options.hx | 46 ++++++++++++++++++++++++++++++++--------------
 1 file changed, 32 insertions(+), 14 deletions(-)

-- 
2.11.0.259.g40922b1

[Qemu-devel] [PATCH 1/2] qemu-options: Rename variables on the -numa "cpus" option

[Eduardo Habkost]

Use @var{firstcpu} and @var{lastcpu} to make the metasyntatic
variables a bit clearer. While doing this, use @var only around
the metasyntatic variables, not including the square brackets and
hyphen.

The semantics of the "cpus" option will be clarified by rewriting
the whole -numa documentation in a follow-up patch.

Reported-by: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 qemu-options.hx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index 80df52651a..780528d6ad 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -119,11 +119,11 @@ specifies the maximum number of hotpluggable CPUs.
 ETEXI
 
 DEF("numa", HAS_ARG, QEMU_OPTION_numa,
-    "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n"
-    "-numa node[,memdev=id][,cpus=cpu[-cpu]][,nodeid=node]\n", QEMU_ARCH_ALL)
+    "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
+    "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n", QEMU_ARCH_ALL)
 STEXI
-@item -numa node[,mem=@var{size}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}]
-@itemx -numa node[,memdev=@var{id}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}]
+@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
+@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
 @findex -numa
 Simulate a multi node NUMA system. If @samp{mem}, @samp{memdev}
 and @samp{cpus} are omitted, resources are split equally. Also, note
-- 
2.11.0.259.g40922b1

[Qemu-devel] [PATCH 2/2] qemu-options: Rewrite -numa documentation

[Eduardo Habkost]

Rewrite the -numa documentation to clarify what exactly it does.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 qemu-options.hx | 38 ++++++++++++++++++++++++++++----------
 1 file changed, 28 insertions(+), 10 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index 780528d6ad..a2c5d6668d 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -125,16 +125,34 @@ STEXI
 @item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
 @itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
 @findex -numa
-Simulate a multi node NUMA system. If @samp{mem}, @samp{memdev}
-and @samp{cpus} are omitted, resources are split equally. Also, note
-that the -@option{numa} option doesn't allocate any of the specified
-resources. That is, it just assigns existing resources to NUMA nodes. This
-means that one still has to use the @option{-m}, @option{-smp} options
-to allocate RAM and VCPUs respectively, and possibly @option{-object}
-to specify the memory backend for the @samp{memdev} suboption.
-
-@samp{mem} and @samp{memdev} are mutually exclusive.  Furthermore, if one
-node uses @samp{memdev}, all of them have to use it.
+Define a NUMA node and assign RAM and VCPUs to it.
+
+@var{firstcpu} and @var{lastcpu} are CPU indexes. Each
+@samp{cpus} option represent a contiguous range of CPU indexes
+(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous
+set of VCPUs can be represented by providing multiple @samp{cpus}
+options. If @samp{cpus} is omitted on all nodes, VCPUs are automatically
+split between them.
+
+For example, the following option assigns VCPUs 0, 1, 2 and 5 to
+a NUMA node:
+@example
+-numa node,cpus=0-2,cpus=5
+@end example
+
+@samp{mem} assigns a given RAM amount to a node. @samp{memdev}
+assigns RAM from a given memory backend device to a node. If
+@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is
+split equally between them.
+
+@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore,
+if one node uses @samp{memdev}, all of them have to use it.
+
+Note that the -@option{numa} option doesn't allocate any of the
+specified resources, it just assigns existing resources to NUMA
+nodes. This means that one still has to use the @option{-m},
+@option{-smp} options to allocate RAM and VCPUs respectively.
+
 ETEXI
 
 DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
-- 
2.11.0.259.g40922b1

Re: [Qemu-devel] [PATCH 1/2] qemu-options: Rename variables on the -numa "cpus" option

[Peter Maydell]

On 23 January 2017 at 18:06, Eduardo Habkost <ehabkost@redhat.com> wrote:
> Use @var{firstcpu} and @var{lastcpu} to make the metasyntatic
> variables a bit clearer. While doing this, use @var only around
> the metasyntatic variables, not including the square brackets and
> hyphen.
>
> The semantics of the "cpus" option will be clarified by rewriting
> the whole -numa documentation in a follow-up patch.
>
> Reported-by: Peter Maydell <peter.maydell@linaro.org>
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  qemu-options.hx | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 80df52651a..780528d6ad 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -119,11 +119,11 @@ specifies the maximum number of hotpluggable CPUs.
>  ETEXI
>
>  DEF("numa", HAS_ARG, QEMU_OPTION_numa,
> -    "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n"
> -    "-numa node[,memdev=id][,cpus=cpu[-cpu]][,nodeid=node]\n", QEMU_ARCH_ALL)
> +    "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
> +    "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n", QEMU_ARCH_ALL)
>  STEXI
> -@item -numa node[,mem=@var{size}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}]
> -@itemx -numa node[,memdev=@var{id}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}]
> +@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
> +@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
>  @findex -numa
>  Simulate a multi node NUMA system. If @samp{mem}, @samp{memdev}
>  and @samp{cpus} are omitted, resources are split equally. Also, note

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

Re: [Qemu-devel] [PATCH 2/2] qemu-options: Rewrite -numa documentation

[Igor Mammedov]

On Mon, 23 Jan 2017 16:06:32 -0200
Eduardo Habkost <ehabkost@redhat.com> wrote:

> Rewrite the -numa documentation to clarify what exactly it does.
> 
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
Reviewed-by: Igor Mammedov <imammedo@redhat.com>

> ---
>  qemu-options.hx | 38 ++++++++++++++++++++++++++++----------
>  1 file changed, 28 insertions(+), 10 deletions(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 780528d6ad..a2c5d6668d 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -125,16 +125,34 @@ STEXI
>  @item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
>  @itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
>  @findex -numa
> -Simulate a multi node NUMA system. If @samp{mem}, @samp{memdev}
> -and @samp{cpus} are omitted, resources are split equally. Also, note
> -that the -@option{numa} option doesn't allocate any of the specified
> -resources. That is, it just assigns existing resources to NUMA nodes. This
> -means that one still has to use the @option{-m}, @option{-smp} options
> -to allocate RAM and VCPUs respectively, and possibly @option{-object}
> -to specify the memory backend for the @samp{memdev} suboption.
> -
> -@samp{mem} and @samp{memdev} are mutually exclusive.  Furthermore, if one
> -node uses @samp{memdev}, all of them have to use it.
> +Define a NUMA node and assign RAM and VCPUs to it.
> +
> +@var{firstcpu} and @var{lastcpu} are CPU indexes. Each
> +@samp{cpus} option represent a contiguous range of CPU indexes
> +(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous
> +set of VCPUs can be represented by providing multiple @samp{cpus}
> +options. If @samp{cpus} is omitted on all nodes, VCPUs are automatically
> +split between them.
> +
> +For example, the following option assigns VCPUs 0, 1, 2 and 5 to
> +a NUMA node:
> +@example
> +-numa node,cpus=0-2,cpus=5
> +@end example
> +
> +@samp{mem} assigns a given RAM amount to a node. @samp{memdev}
> +assigns RAM from a given memory backend device to a node. If
> +@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is
> +split equally between them.
> +
> +@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore,
> +if one node uses @samp{memdev}, all of them have to use it.
> +
> +Note that the -@option{numa} option doesn't allocate any of the
> +specified resources, it just assigns existing resources to NUMA
> +nodes. This means that one still has to use the @option{-m},
> +@option{-smp} options to allocate RAM and VCPUs respectively.
> +
>  ETEXI
>  
>  DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,