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