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 <pagu...@redhat.com> --- docs/virtio-pmem.txt | 65 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/virtio-pmem.txt diff --git a/docs/virtio-pmem.txt b/docs/virtio-pmem.txt new file mode 100644 index 0000000000..fc61eebb20 --- /dev/null +++ b/docs/virtio-pmem.txt @@ -0,0 +1,65 @@ + +QEMU virtio pmem +=================== + + This document explains the usage of virtio pmem device + which is available since QEMU v4.1.0. + + The virtio pmem is paravirtualized persistent memory device + on regular(non-NVDIMM) storage. + +Usecase +-------- + Allows to bypass the guest page cache and directly use host page cache. + This reduces guest memory footprint as 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(non-NVDIMM) host storage does not persists + the guest writes as there are no defined semantecs in the device specification. + With virtio pmem device, guest write persistence on non-NVDIMM storage is + supported. + +virtio pmem usage +----------------- + virtio pmem device is created with a memory-backend-file with the below + options: + + -machine pc -m 8G,slots=$N,maxmem=$MAX_SIZE + -object memory-backend-file,id=mem1,share,mem-path=$PATH,size=$SIZE + -device virtio-pmem-pci,memdev=mem1,id=nv1 + + where: + - "object memory-backend-file,id=mem1,share,mem-path=$PATH,size=$VIRTIO_PMEM_SIZE" + creates a backend storage of size $SIZE on a file $PATH. All + accesses to the virtio pmem device go to the file $PATH. + + - "device virtio-pmem-pci,id=nvdimm1,memdev=mem1" creates a virtio pmem + 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 +------- +Accomplished by two monitor commands "object_add" and "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 than real nvdimm backend where no additional +fsync/msync is required for data 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. -- 2.21.0
