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

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

[Igor Mammedov]

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

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

[Michal Privoznik]

On 1/11/21 11:27 PM, 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(-)

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>

Michal

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.

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

[Paolo Bonzini]

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

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

[Igor Mammedov]

On Thu, 14 Jan 2021 20:38:01 +0100
Paolo Bonzini <pbonzini@redhat.com> wrote:

> 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,
1) should be
s/on=off/

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

can you drop this patch fro your queue, pls?
it has a mistake (1)

v3 is in process of cooking, once there is some agreement I'll post it.

> 
> Paolo
> 
>