Re: [PATCH v4] numa: forbid '-numa node,mem' for 5.1 and newer machine types

[Eric Blake <eblake@redhat.com>]

On 6/8/20 7:03 AM, Igor Mammedov wrote:
> Deprecation period is run out and it's a time to flip the switch
> introduced by cd5ff8333a.  Disable legacy option for new machine
> types (since 5.1) and amend documentation.
> 
> '-numa node,memdev' shall be used instead of disabled option
> with new machine types.
> 
> Signed-off-by: Igor Mammedov <imammedo@redhat.com>
> Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
> ---

> +++ b/docs/system/deprecated.rst
> @@ -101,23 +101,6 @@ error in the future.
>   The ``-realtime mlock=on|off`` argument has been replaced by the
>   ``-overcommit mem-lock=on|off`` argument.
>   
> -``-numa node,mem=``\ *size* (since 4.1)
> -'''''''''''''''''''''''''''''''''''''''
> -
> -The parameter ``mem`` of ``-numa node`` is used to assign a part of

Present tense in the old text made sense because the old way still worked...

> -guest RAM to a NUMA node. But when using it, it's impossible to manage specified
> -RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
> -so guest end-ups with the fake NUMA configuration with suboptiomal performance.
> -However since 2014 there is an alternative way to assign RAM to a NUMA node
> -using parameter ``memdev``, which does the same as ``mem`` and adds
> -means to actualy manage node RAM on the host side. Use parameter ``memdev``
> -with *memory-backend-ram* backend as an replacement for parameter ``mem``
> -to achieve the same fake NUMA effect or a properly configured
> -*memory-backend-file* backend to actually benefit from NUMA configuration.
> -In future new machine versions will not accept the option but it will still
> -work with old machine types. User can check QAPI schema to see if the legacy
> -option is supported by looking at MachineInfo::numa-mem-supported property.
> -
>   ``-numa`` node (without memory specified) (since 4.1)
>   '''''''''''''''''''''''''''''''''''''''''''''''''''''
>   
> @@ -516,3 +499,23 @@ long starting at 1MiB, the old command::
>   can be rewritten as::
>   
>     qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2
> +
> +Command line options
> +--------------------
> +
> +``-numa node,mem=``\ *size* (removed in 5.1)
> +''''''''''''''''''''''''''''''''''''''''''''
> +
> +The parameter ``mem`` of ``-numa node`` is used to assign a part of

...but in the new text, if we completely got rid of 'mem', then past 
tense is preferred to describe what used to work.  s/is/was/

Other pre-existing typo and grammar problems worth fixing now:

> +guest RAM to a NUMA node. But when using it, it's impossible to manage specified

s/manage/manage a/

> +RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
> +so guest end-ups with the fake NUMA configuration with suboptiomal performance.

s/so guest end-ups/so the guest ends up/

> +However since 2014 there is an alternative way to assign RAM to a NUMA node
> +using parameter ``memdev``, which does the same as ``mem`` and adds
> +means to actualy manage node RAM on the host side. Use parameter ``memdev``

s/actualy/actually/

> +with *memory-backend-ram* backend as an replacement for parameter ``mem``

s/an/a/

> +to achieve the same fake NUMA effect or a properly configured
> +*memory-backend-file* backend to actually benefit from NUMA configuration.
> +In future new machine versions will not accept the option but it will still

If this sentence is still true:
s/In future new/New/

If the sentence is false (that is, we completely dropped 'mem' even for 
old machine versions), drop it.

> +work with old machine types. User can check QAPI schema to see if the legacy

s/check/check the/

> +option is supported by looking at MachineInfo::numa-mem-supported property.

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