1 2=========== 3virtio pmem 4=========== 5 6This document explains the setup and usage of the virtio pmem device. 7The virtio pmem device is a paravirtualized persistent memory device 8on regular (i.e non-NVDIMM) storage. 9 10Usecase 11------- 12 13Virtio pmem allows to bypass the guest page cache and directly use 14host page cache. This reduces guest memory footprint as the host can 15make efficient memory reclaim decisions under memory pressure. 16 17How does virtio-pmem compare to the nvdimm emulation? 18----------------------------------------------------- 19 20NVDIMM emulation on regular (i.e. non-NVDIMM) host storage does not 21persist the guest writes as there are no defined semantics in the device 22specification. The virtio pmem device provides guest write persistence 23on non-NVDIMM host storage. 24 25virtio pmem usage 26----------------- 27 28A virtio pmem device backed by a memory-backend-file can be created on 29the QEMU command line as in the following example:: 30 31 -object memory-backend-file,id=mem1,share,mem-path=./virtio_pmem.img,size=4G 32 -device virtio-pmem-pci,memdev=mem1,id=nv1 33 34where: 35 36 - "object memory-backend-file,id=mem1,share,mem-path=<image>, size=<image size>" 37 creates a backend file with the specified size. 38 39 - "device virtio-pmem-pci,id=nvdimm1,memdev=mem1" creates a virtio pmem 40 pci device whose storage is provided by above memory backend device. 41 42Multiple virtio pmem devices can be created if multiple pairs of "-object" 43and "-device" are provided. 44 45Hotplug 46------- 47 48Virtio pmem devices can be hotplugged via the QEMU monitor. First, the 49memory backing has to be added via 'object_add'; afterwards, the virtio 50pmem device can be added via 'device_add'. 51 52For example, the following commands add another 4GB virtio pmem device to 53the guest:: 54 55 (qemu) object_add memory-backend-file,id=mem2,share=on,mem-path=virtio_pmem2.img,size=4G 56 (qemu) device_add virtio-pmem-pci,id=virtio_pmem2,memdev=mem2 57 58Guest Data Persistence 59---------------------- 60 61Guest data persistence on non-NVDIMM requires guest userspace applications 62to perform fsync/msync. This is different from a real nvdimm backend where 63no additional fsync/msync is required. This is to persist guest writes in 64host backing file which otherwise remains in host page cache and there is 65risk of losing the data in case of power failure. 66 67With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides 68a hint to application to perform fsync for write persistence. 69 70Limitations 71----------- 72 73- Real nvdimm device backend is not supported. 74- virtio pmem hotunplug is not supported. 75- ACPI NVDIMM features like regions/namespaces are not supported. 76- ndctl command is not supported. 77