Re: [PATCH] qemu-options.hx: Update descriptions of memory options for NUMA node

[Yohei Kojima]

I add more detailed explanation for the documentation update here.

On 2023/03/30 19:09, Yohei Kojima wrote:
> This commit adds the following description:
> 1. `memdev` option is recommended over `mem` option (see [1,2])
> 2. users must specify memory for all NUMA nodes (see [2])
> 
> This commit also separates descriptions for `mem` and `memdev` into two
> paragraphs. The old doc describes legacy `mem` option first, and it was
> a bit confusing.
> 
> Related documantations:
> [1] https://wiki.qemu.org/ChangeLog/5.1#Incompatible_changes
> [2] https://www.qemu.org/docs/master/about/removed-features.html
> 
> Signed-off-by: Yohei Kojima <y-koj@outlook.jp>
> ---
>  qemu-options.hx | 25 ++++++++++++++++---------
>  1 file changed, 16 insertions(+), 9 deletions(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 59bdf67a2c..174f0d0c2d 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -405,15 +405,22 @@ SRST
>          -numa node,nodeid=0 -numa node,nodeid=1 \
>          -numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
>  
> -    Legacy '\ ``mem``\ ' assigns a given RAM amount to a node (not supported
> -    for 5.1 and newer machine types). '\ ``memdev``\ ' assigns RAM from
> -    a given memory backend device to a node. If '\ ``mem``\ ' and
> -    '\ ``memdev``\ ' are omitted in all nodes, RAM is split equally between 
> them.

RAM is no longer split equally in this situation. For example, the
command below fails and emits an error. It also reproduces on other
machine types (e.g. pc-q35-5.0).

$ qemu-system-x86_64 -m 2G -machine pc-q35-7.2 \
    -numa node,nodeid=0 -numa node,nodeid=1

qemu-system-x86_64: total memory for NUMA nodes (0x0) should equal RAM size 
(0x80000000)

> -
> -
> -    '\ ``mem``\ ' and '\ ``memdev``\ ' are mutually exclusive.
> -    Furthermore, if one node uses '\ ``memdev``\ ', all of them have to
> -    use it.

And if one node uses ``mem`` (on supported machine type), all of the
rest have to use ``mem``, because omitting the memory option is no
longer supported.

> +    '\ ``memdev``\ ' option assigns RAM from a given memory backend
> +    device to a node. It is recommended to use '\ ``memdev``\ ' option
> +    over legacy '\ ``mem``\ ' option. This is because '\ ``memdev``\ '
> +    option provides better performance and more control over the
> +    backend's RAM (e.g. '\ ``prealloc``\ ' parameter of
> +    '\ ``-memory-backend-ram``\ ' allows memory preallocation).

``memdev`` is described first, because ``mem`` is not supported on
machine type 5.1 and later. Readers will see the supported option first.

> +
> +    For compatibility reasons, legacy '\ ``mem``\ ' option is
> +    supported in 5.0 and older machine types. Note that '\ ``mem``\ '
> +    and '\ ``memdev``\ ' are mutually exclusive. If one node uses
> +    '\ ``memdev``\ ', the rest nodes have to use '\ ``memdev``\ '
> +    option, and vice versa.

Description for ``mem`` is moved here. It also describes that ``mem``
and ``memdev`` is mutually exclusive.

> +
> +    Users must specify memory for all NUMA nodes by '\ ``memdev``\ '
> +    (or legacy '\ ``mem``\ ' if available). In QEMU 5.2, the support
> +    for '\ ``-numa node``\ ' without memory specified was removed.

Users must specify the memory size for each node like
either (A) or (B), instead of (C). Note that (A) emits warnings (A1).
Also note that, as described above, the machine type for (A) should be
5.0 or older (pc-q35-5.0 here).

(A) qemu-system-x86_64 -m 2G -machine pc-q35-5.0 \
    -numa node,nodeid=0,mem=1G -numa node,nodeid=1,mem=1G

(A1)
qemu-system-x86_64: -numa node,nodeid=0,mem=1G: warning: Parameter -numa 
node,mem is deprecated, use -numa node,memdev instead
qemu-system-x86_64: -numa node,nodeid=1,mem=1G: warning: Parameter -numa 
node,mem is deprecated, use -numa node,memdev instead

(B) qemu-system-x86_64 -m 2G -machine pc-q35-7.2 \
    -object memory-backend-ram,size=1G,id=m0 \
    -object memory-backend-ram,size=1G,id=m1 \
    -numa node,nodeid=0,memdev=m0 -numa node,nodeid=1,memdev=m1

(C) qemu-system-x86_64 -m 2G -machine pc-q35-7.2 \
    -numa node,nodeid=0 -numa node,nodeid=1

>  
>      '\ ``initiator``\ ' is an additional option that points to an
>      initiator NUMA node that has best performance (the lowest latency or