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

[Peter Krempa]

On Mon, Jan 11, 2021 at 17:27:29 -0500, 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.

This should also be the main point of the patch, without it it's not
very useful to document how it's going to behave.

> 
> 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,

If libvirt is going to use this option, please make the statement
stronger:

This option must be considered stable (as if it didn't have the 'x-'
prefix including deprecation period) as long as 4.0 and older machine
types exists.


> +     * 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,

And also document here that this option is considered stable despite the
'x-' prefix.

The current wording doesn't entirely inspire confidence that it will be
considered as if it were stable.