Re: [PATCH] machine: add missing doc for memory-backend option

[Paolo Bonzini <pbonzini@redhat.com>]

On 11/01/21 23:27, Igor Mammedov wrote:
> Add documentation for '-machine memory-backend' CLI option and
> how to use it.
> 
> PS:
> While at it add a comment to x-use-canonical-path-for-ramblock-id,
> to make sure it won't go away by accident.
> 
> Signed-off-by: Igor Mammedov <imammedo@redhat.com>
> ---
>   backends/hostmem.c |  8 ++++++++
>   qemu-options.hx    | 25 ++++++++++++++++++++++++-
>   2 files changed, 32 insertions(+), 1 deletion(-)
> 
> diff --git a/backends/hostmem.c b/backends/hostmem.c
> index 4bde00e8e7..f6f4e818c7 100644
> --- a/backends/hostmem.c
> +++ b/backends/hostmem.c
> @@ -497,6 +497,14 @@ host_memory_backend_class_init(ObjectClass *oc, void *data)
>           host_memory_backend_get_share, host_memory_backend_set_share);
>       object_class_property_set_description(oc, "share",
>           "Mark the memory as private to QEMU or shared");
> +    /*
> +     * Do not delete/rename option till 4.0 and older machine types exist,
> +     * Option will be used by upper layers to override (disable) canonical path
> +     * for ramblock-id set by compat properties on old machine types ( <= 4.0),
> +     * to keep migration working when backend is used for main RAM with
> +     * -machine memory-backend= option (main RAM historically used prefix-less
> +     * ramblock-id).
> +     */
>       object_class_property_add_bool(oc, "x-use-canonical-path-for-ramblock-id",
>           host_memory_backend_get_use_canonical_path,
>           host_memory_backend_set_use_canonical_path);
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 459c916d3d..c02628bd26 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -35,7 +35,8 @@ DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
>       "                suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
>       "                nvdimm=on|off controls NVDIMM support (default=off)\n"
>       "                memory-encryption=@var{} memory encryption object to use (default=none)\n"
> -    "                hmat=on|off controls ACPI HMAT support (default=off)\n",
> +    "                hmat=on|off controls ACPI HMAT support (default=off)\n"
> +    "                memory-backend='backend-id' specifies explicitly provided backend for main RAM (default=none)\n",
>       QEMU_ARCH_ALL)
>   SRST
>   ``-machine [type=]name[,prop=value[,...]]``
> @@ -96,6 +97,28 @@ SRST
>       ``hmat=on|off``
>           Enables or disables ACPI Heterogeneous Memory Attribute Table
>           (HMAT) support. The default is off.
> +
> +     ``memory-backend='id'``
> +        An alternative to legacy ``-mem-path`` and ``mem-prealloc`` options.
> +        Allows to use a memory backend as main RAM.
> +
> +        For example:
> +        ::
> +        -object memory-backend-file,id=pc.ram,size=512M,mem-path=/hugetlbfs,prealloc=on,share=on
> +        -machine memory-backend=pc.ram
> +        -m 512M
> +
> +        Migration compatibility note:
> +        a) as backend id one shall use value of 'default-ram-id', advertised by
> +        machine type (available via ``query-machines`` QMP command)
> +        b) for machine types 4.0 and older, user shall
> +        use ``x-use-canonical-path-for-ramblock-id=on`` backend option,
> +        if migration to/from old QEMU (<5.0) is expected.
> +        For example:
> +        ::
> +        -object memory-backend-ram,id=pc.ram,size=512M,x-use-canonical-path-for-ramblock-id=on
> +        -machine memory-backend=pc.ram
> +        -m 512M
>   ERST
>   
>   HXCOMM Deprecated by -machine
> 

Queued, thanks.

Paolo