virtio pmem: user document
PATCH v2 1/1 virtio pmem: user document
This patch documents the steps to use virtio pmem. It also documents other useful information about virtio pmem e.g use-case, comparison with Qemu NVDIMM backend and current limitations.
---v1->v2
- Fixes on text format and 'Guest Data persistence' section - Cornelia
docs/virtio-pmem.rst | 75 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 docs/virtio-pmem.rst
docs/virtio-pmem.rst new file +75 -0
@@ -0,0 +1,75 @@ + +======================== +QEMU virtio pmem +======================== + + This document explains the setup and usage of virtio pmem device + which is available since QEMU v4.1.0. + + The virtio pmem is a paravirtualized persistent memory device on + regular(i.e non-NVDIMM) storage. + +Usecase +-------- + + Allows to bypass the guest page cache and directly use host page cache. + This reduces guest memory footprint as the host can make efficient + memory reclaim decisions under memory pressure. + +o How does virtio-pmem compare to the nvdimm emulation supported by QEMU? + + NVDIMM emulation on regular(i.e. non-NVDIMM) host storage does not + persist the guest writes as there are no defined semantics in the device + specification. The virtio pmem device provides guest write persistence + on non-NVDIMM host storage. + +virtio pmem usage +----------------- + + A virtio pmem device backed by a memory-backend-file can be created on + the QEMU command line as in the following example: + + -object memory-backend-file,id=mem1,share,mem-path=./virtio_pmem.img,size=4G + -device virtio-pmem-pci,memdev=mem1,id=nv1 + + where: + - "object memory-backend-file,id=mem1,share,mem-path=<image>, size=<image size>" + creates a backend file of size on a mem-path. + + - "device virtio-pmem-pci,id=nvdimm1,memdev=mem1" creates a virtio pmem + pci device whose storage is provided by above memory backend device. + + Multiple virtio pmem devices can be created if multiple pairs of "-object" + and "-device" are provided. + +Hotplug +------- + +"Virtio pmem devices can be hotplugged via the QEMU monitor. First, the +memory backing has to be added via 'object_add'; afterwards, the virtio +pmem device can be added via 'device_add'." + +For example, the following commands add another 4GB virtio pmem device to +the guest: + + (qemu) object_add memory-backend-file,id=mem2,share=on,mem-path=virtio_pmem2.img,size=4G + (qemu) device_add virtio-pmem-pci,id=virtio_pmem2,memdev=mem2 + +Guest Data Persistence +---------------------- + + Guest data persistence on non-NVDIMM requires guest userspace application to + perform fsync/msync. This is different from a real nvdimm backend where no + additional fsync/msync is required. This is to persist guest writes in host + backing file which otherwise remains in host page cache and there is risk of + losing the data in case of power failure. + + With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides + a hint to application to perform fsync for write persistence. + +Limitations +------------ +- Real nvdimm device backend is not supported. +- virtio pmem hotunplug is not supported. +- ACPI NVDIMM features like regions/namespaces are not supported. +- ndctl command is not supported.
Signature · 1 line
2.21.0
Quoted 21 lines · On Wed, 21 Aug 2019 13:06:30 +0530 Pankaj Gupta <[email protected]> wrote:
This patch documents the steps to use virtio pmem. It also documents other useful information about virtio pmem e.g use-case, comparison with Qemu NVDIMM backend and current limitations.
Signed-off-by Pankaj Gupta <[email protected]>---
v1->v2
- Fixes on text format and 'Guest Data persistence' section - Corneliadocs/virtio-pmem.rst | 75 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 docs/virtio-pmem.rstdocs/virtio-pmem.rst new file +0
-0
docs/virtio-pmem.rst line 6
Quoted 6 lines
docs/virtio-pmem.rst new file +6
-0@@ -0,0 +1,75 @@ + +======================== +QEMU virtio pmem +======================== + + This document explains the setup and usage of virtio pmem device
s/virtio pmem device/the virtio pmem device/
docs/virtio-pmem.rst line 9
Quoted 3 lines
docs/virtio-pmem.rst new file +3
-0+ which is available since QEMU v4.1.0. + + The virtio pmem is a paravirtualized persistent memory device on
s/The virtio pmem/The virtio pmem device/
docs/virtio-pmem.rst line 10
Quoted 1 line
docs/virtio-pmem.rst new file +1
-0+ regular(i.e non-NVDIMM) storage.
missing blank before '('
docs/virtio-pmem.rst line 15
Quoted 5 lines
docs/virtio-pmem.rst new file +5
-0+ +Usecase +-------- + + Allows to bypass the guest page cache and directly use host page cache.
"Virtio pmem allows to..." ?
docs/virtio-pmem.rst line 21
Quoted 6 lines
docs/virtio-pmem.rst new file +6
-0+ This reduces guest memory footprint as the host can make efficient + memory reclaim decisions under memory pressure. + +o How does virtio-pmem compare to the nvdimm emulation supported by QEMU? + + NVDIMM emulation on regular(i.e. non-NVDIMM) host storage does not
missing blank before '('
Quoted 6 lines
docs/virtio-pmem.rst new file +6
-0+ persist the guest writes as there are no defined semantics in the device + specification. The virtio pmem device provides guest write persistence + on non-NVDIMM host storage. + +virtio pmem usage +-----------------
docs/virtio-pmem.rst line 37
Quoted 10 lines
docs/virtio-pmem.rst new file +10
-0+ + A virtio pmem device backed by a memory-backend-file can be created on + the QEMU command line as in the following example: + + -object memory-backend-file,id=mem1,share,mem-path=./virtio_pmem.img,size=4G + -device virtio-pmem-pci,memdev=mem1,id=nv1 + + where: + - "object memory-backend-file,id=mem1,share,mem-path=<image>, size=<image size>" + creates a backend file of size on a mem-path.
"a backend file with the specified size" ?
docs/virtio-pmem.rst line 50
Quoted 13 lines
docs/virtio-pmem.rst new file +13
-0+ + - "device virtio-pmem-pci,id=nvdimm1,memdev=mem1" creates a virtio pmem + pci device whose storage is provided by above memory backend device. + + Multiple virtio pmem devices can be created if multiple pairs of "-object" + and "-device" are provided. + +Hotplug +------- + +"Virtio pmem devices can be hotplugged via the QEMU monitor. First, the +memory backing has to be added via 'object_add'; afterwards, the virtio +pmem device can be added via 'device_add'."
Please lose the '"' (copy/paste leftover, I presume? :)
docs/virtio-pmem.rst line 61
Quoted 11 lines
docs/virtio-pmem.rst new file +11
-0+ +For example, the following commands add another 4GB virtio pmem device to +the guest: + + (qemu) object_add memory-backend-file,id=mem2,share=on,mem-path=virtio_pmem2.img,size=4G + (qemu) device_add virtio-pmem-pci,id=virtio_pmem2,memdev=mem2 + +Guest Data Persistence +---------------------- + + Guest data persistence on non-NVDIMM requires guest userspace application to
s/application/applications/ ?
Quoted 4 lines
docs/virtio-pmem.rst new file +4
-0+ perform fsync/msync. This is different from a real nvdimm backend where no + additional fsync/msync is required. This is to persist guest writes in host + backing file which otherwise remains in host page cache and there is risk of + losing the data in case of power failure.
docs/virtio-pmem.rst line 75
Quoted 10 lines
docs/virtio-pmem.rst new file +10
-0+ + With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides + a hint to application to perform fsync for write persistence. + +Limitations +------------ +- Real nvdimm device backend is not supported. +- virtio pmem hotunplug is not supported. +- ACPI NVDIMM features like regions/namespaces are not supported. +- ndctl command is not supported.
Only some nits from my side, otherwise looks good to me.
Hi Cornelia,
Quoted 15 lines
Quoted 15 lines
This patch documents the steps to use virtio pmem. It also documents other useful information about virtio pmem e.g use-case, comparison with Qemu NVDIMM backend and current limitations.
Signed-off-by Pankaj Gupta <[email protected]>---
v1->v2
- Fixes on text format and 'Guest Data persistence' section - Corneliadocs/virtio-pmem.rst | 75 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 docs/virtio-pmem.rst
Quoted 14 lines
docs/virtio-pmem.rst line 6
Quoted 12 lines
docs/virtio-pmem.rst new file +6
-0@@ -0,0 +1,75 @@ + +======================== +QEMU virtio pmem +======================== + + This document explains the setup and usage of virtio pmem devices/virtio pmem device/the virtio pmem device/
done
Quoted 6 lines
docs/virtio-pmem.rst line 9
Quoted 4 lines
docs/virtio-pmem.rst new file +3
-0+ which is available since QEMU v4.1.0. + + The virtio pmem is a paravirtualized persistent memory device ons/The virtio pmem/The virtio pmem device/
o.k
Quoted 4 lines
docs/virtio-pmem.rst line 10
Quoted 2 lines
docs/virtio-pmem.rst new file +1
-0+ regular(i.e non-NVDIMM) storage.missing blank before '('
sure
Quoted 8 lines
docs/virtio-pmem.rst line 15
Quoted 6 lines
docs/virtio-pmem.rst new file +5
-0+ +Usecase +-------- + + Allows to bypass the guest page cache and directly use host page cache."Virtio pmem allows to..." ?
done.
Quoted 9 lines
docs/virtio-pmem.rst line 21
Quoted 7 lines
docs/virtio-pmem.rst new file +6
-0+ This reduces guest memory footprint as the host can make efficient + memory reclaim decisions under memory pressure. + +o How does virtio-pmem compare to the nvdimm emulation supported by QEMU? + + NVDIMM emulation on regular(i.e. non-NVDIMM) host storage does notmissing blank before '('
done.
Quoted 13 lines
Quoted 13 lines
docs/virtio-pmem.rst new file +11
-0+ persist the guest writes as there are no defined semantics in the device + specification. The virtio pmem device provides guest write persistence + on non-NVDIMM host storage. + +virtio pmem usage +----------------- + + A virtio pmem device backed by a memory-backend-file can be created on + the QEMU command line as in the following example: + + -objectmemory-backend-file,id=mem1,share,mem-path=./virtio_pmem.img,size=4G
Quoted 8 lines
Quoted 6 lines
docs/virtio-pmem.rst new file +4
-0+ -device virtio-pmem-pci,memdev=mem1,id=nv1 + + where: + - "object memory-backend-file,id=mem1,share,mem-path=<image>,size=<image size>"
+ creates a backend file of size on a mem-path."a backend file with the specified size" ?
done.
Quoted 17 lines
Quoted 7 lines
docs/virtio-pmem.rst new file +5
-0+ + - "device virtio-pmem-pci,id=nvdimm1,memdev=mem1" creates a virtio pmem + pci device whose storage is provided by above memory backend device. + + Multiple virtio pmem devices can be created if multiple pairs of"-object"
docs/virtio-pmem.rst line 50
Quoted 8 lines
docs/virtio-pmem.rst new file +8
-0+ and "-device" are provided. + +Hotplug +------- + +"Virtio pmem devices can be hotplugged via the QEMU monitor. First, the +memory backing has to be added via 'object_add'; afterwards, the virtio +pmem device can be added via 'device_add'."Please lose the '"' (copy/paste leftover, I presume? :)
Done :)
Quoted 16 lines
Quoted 13 lines
docs/virtio-pmem.rst new file +5
-0+ +For example, the following commands add another 4GB virtio pmem device to +the guest: + + (qemu) object_addmemory-backend-file,id=mem2,share=on,mem-path=virtio_pmem2.img,size=4G
+ (qemu)device_addvirtio-pmem-pci,id=virtio_pmem2,memdev=mem2docs/virtio-pmem.rst new file +5
-0+ +Guest Data Persistence +---------------------- + + Guest data persistence on non-NVDIMM requires guest userspace applicationQuoted 1 line
to
s/application/applications/ ?
done.
Quoted 13 lines
Quoted 13 lines
+ perform fsync/msync. This is different from a real nvdimm backend where no
+ additional fsync/msync is required. This is to persist guest writes in host
+ backing file which otherwise remains in host page cache and there is risk of
+ losing the data in case of power failure.
+
+ With virtio pmem device,MAP_SYNCmmap flag is not supported. This provides
+ a hint to application to perform fsync for write persistence. +
Quoted 8 lines
Quoted 6 lines
+Limitations
+------------ +- Real nvdimm device backend is not supported. +- virtio pmem hotunplug is not supported. +- ACPI NVDIMM features like regions/namespaces are not supported. +- ndctl command is not supported.Only some nits from my side, otherwise looks good to me.
Thank you for the review. Will post a v3 with the changes.
Best regards,
Pankaj