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.
-
-
-    '\ ``mem``\ ' and '\ ``memdev``\ ' are mutually exclusive.
-    Furthermore, if one node uses '\ ``memdev``\ ', all of them have to
-    use it.
+    '\ ``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).
+
+    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.
+
+    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.
 
     '\ ``initiator``\ ' is an additional option that points to an
     initiator NUMA node that has best performance (the lowest latency or
-- 
2.39.2

Yohei Kojima <y-koj@outlook.jp> writes:

> 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.
> -
> -
> -    '\ ``mem``\ ' and '\ ``memdev``\ ' are mutually exclusive.
> -    Furthermore, if one node uses '\ ``memdev``\ ', all of them have to
> -    use it.
> +    '\ ``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).
> +
> +    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.
> +
> +    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.

I think this mixes up memdev and mem too much. It would be better to
make the lead up to the example just talk about memdev (as it is the
preferred option) and move the discussion about backwards compatibility
to after the example. You can use the .. note:: annotation to put it in
a nice little box, something like:

.. note::

    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 of the nodes must also use the '\
    ``memdev``\ ' option, and vice versa.


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


-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Thank you for the review. I will reflect them in the next version.

On 2023/04/11 21:57, Alex Bennée wrote:
> 
> Yohei Kojima <y-koj@outlook.jp> writes:
> 
>> 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.
>> -
>> -
>> -    '\ ``mem``\ ' and '\ ``memdev``\ ' are mutually exclusive.
>> -    Furthermore, if one node uses '\ ``memdev``\ ', all of them have to
>> -    use it.
>> +    '\ ``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).
>> +
>> +    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.
>> +
>> +    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.
> 
> I think this mixes up memdev and mem too much. It would be better to
> make the lead up to the example just talk about memdev (as it is the
> preferred option) and move the discussion about backwards compatibility
> to after the example. You can use the .. note:: annotation to put it in
> a nice little box, something like:
> 
> .. note::
> 
>     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 of the nodes must also use the '\
>     ``memdev``\ ' option, and vice versa.
> 
> 
>>  
>>      '\ ``initiator``\ ' is an additional option that points to an
>>      initiator NUMA node that has best performance (the lowest latency or
> 
> 

ping


This patch updates an outdated description in qemu-options.hx .
The patch reflects the changes in qemu behavior already described in
another documentation, and it also changes paragraph structure for
further readability.

The original patch is:
https://patchew.org/QEMU/TYZPR06MB5418D6B0175A49E8E76988439D8E9@TYZPR06MB5418.apcprd06.prod.outlook.com/


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.
> -
> -
> -    '\ ``mem``\ ' and '\ ``memdev``\ ' are mutually exclusive.
> -    Furthermore, if one node uses '\ ``memdev``\ ', all of them have to
> -    use it.
> +    '\ ``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).
> +
> +    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.
> +
> +    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.
>  
>      '\ ``initiator``\ ' is an additional option that points to an
>      initiator NUMA node that has best performance (the lowest latency or

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