machine: add missing doc for memory-backend option
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
@@ -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
@@ -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
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
Signed-off-by Igor Mammedov <[email protected]>--- backends/hostmem.c | 8 ++++++++ qemu-options.hx | 25 ++++++++++++++++++++++++- 2 files changed, 32 insertions(+), 1 deletion(-)
Michal
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
Signed-off-by Igor Mammedov <[email protected]>--- backends/hostmem.c | 8 ++++++++ qemu-options.hx | 25 ++++++++++++++++++++++++- 2 files changed, 32 insertions(+), 1 deletion(-)backends/hostmem.c +0
-0
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@@ -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.
Paolo Bonzini
AppliedQuoted 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.Signed-off-by Igor Mammedov <[email protected]>--- backends/hostmem.c | 8 ++++++++ qemu-options.hx | 25 ++++++++++++++++++++++++- 2 files changed, 32 insertions(+), 1 deletion(-)backends/hostmem.c +8
-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, +* 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@@ -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
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.Signed-off-by Igor Mammedov <[email protected]>--- backends/hostmem.c | 8 ++++++++ qemu-options.hx | 25 ++++++++++++++++++++++++- 2 files changed, 32 insertions(+), 1 deletion(-)backends/hostmem.c +8
-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, +* 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@@ -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
-0HXCOMM Deprecated by -machineQueued, 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