Skip to contentSkip to conversation

machine: add missing doc for memory-backend option

PATCH Applied Igor Mammedov 4 participants 5 messages Jan 11, 2021 – Jan 20, 2021 Arm STM32

v1 of 3 Applied Latest is v3 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 machine: add missing doc for memory-backend option

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.

---
 backends/hostmem.c |  8 ++++++++
 qemu-options.hx    | 25 ++++++++++++++++++++++++-
 2 files changed, 32 insertions(+), 1 deletion(-)
backends/hostmem.c +8 -0
index 4bde00e8e7..f6f4e818c7 100644
@@ -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);
qemu-options.hx +24 -1
index 459c916d3d..c02628bd26 100644
@@ -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
Signature · 1 line
2.27.0
Reviewed-by on v1 1/1
#1 lore raw
Quoted 7 lines · 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.

Quoted 5 lines
---
  backends/hostmem.c |  8 ++++++++
  qemu-options.hx    | 25 ++++++++++++++++++++++++-
  2 files changed, 32 insertions(+), 1 deletion(-)

Michal

#2 lore raw
In reply to Igor Mammedov
Quoted 6 lines · 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.

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.

Quoted 12 lines
---
 backends/hostmem.c |  8 ++++++++
 qemu-options.hx    | 25 ++++++++++++++++++++++++-
 2 files changed, 32 insertions(+), 1 deletion(-)
backends/hostmem.c +0 -0
index 4bde00e8e7..f6f4e818c7 100644

backends/hostmem.c host_memory_backend_class_init(ObjectClass *oc, void *data) · line 501

Quoted 5 lines
backends/hostmem.c +2 -0
@@ -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.

Quoted 33 lines
backends/hostmem.c +6 -0
+     * 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);
qemu-options.hx +8 -1
index 459c916d3d..c02628bd26 100644
@@ -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:

qemu-options.hx SRST · line 115

Quoted 10 lines
qemu-options.hx +10 -0
+        ::
+        -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.

#3 lore raw
In reply to Igor Mammedov
Quoted 66 lines · 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.

---
  backends/hostmem.c |  8 ++++++++
  qemu-options.hx    | 25 ++++++++++++++++++++++++-
  2 files changed, 32 insertions(+), 1 deletion(-)
backends/hostmem.c +8 -0
index 4bde00e8e7..f6f4e818c7 100644
@@ -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);
qemu-options.hx +17 -1
index 459c916d3d..c02628bd26 100644
@@ -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

qemu-options.hx SRST · line 124

Quoted 10 lines
qemu-options.hx +7 -0
+        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

#4 lore raw
Quoted 59 lines · On Thu, 14 Jan 2021 20:38:01 +0100 Paolo Bonzini <[email protected]> wrote:
Quoted 58 lines · 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.

---
  backends/hostmem.c |  8 ++++++++
  qemu-options.hx    | 25 ++++++++++++++++++++++++-
  2 files changed, 32 insertions(+), 1 deletion(-)
backends/hostmem.c +8 -0
index 4bde00e8e7..f6f4e818c7 100644
@@ -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);
qemu-options.hx +10 -1
index 459c916d3d..c02628bd26 100644
@@ -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
Quoted 8 lines

qemu-options.hx SRST · line 115

Quoted 8 lines
qemu-options.hx +8 -0
+        -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/

Quoted 8 lines
Quoted 8 lines
qemu-options.hx +6 -0
+        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
 
Quoted 4 lines

qemu-options.hx SRST · line 124

Quoted 2 lines
qemu-options.hx +0 -0
  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.

Quoted 4 lines

Paolo