Skip to contentSkip to conversation

virtio pmem: user document

PATCH Superseded Pankaj Gupta 2 participants 3 messages Aug 21, 2019

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

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
new file mode 100644
index 0000000000..0346e61674
@@ -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
#1 lore raw
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.

---
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 +0 -0
new file mode 100644
index 0000000000..0346e61674

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.

#2 lore raw

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.

---
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
Quoted 14 lines

docs/virtio-pmem.rst line 6

Quoted 12 lines
docs/virtio-pmem.rst new file +6 -0
new file mode 100644
index 0000000000..0346e61674
@@ -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/

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 on

s/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 not

missing 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:
+
+  -object

memory-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_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

docs/virtio-pmem.rst new file +5 -0
+
+Guest Data Persistence
+----------------------
+
+ Guest data persistence on non-NVDIMM requires guest userspace application
Quoted 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_SYNC mmap 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

Quoted 1 line