projects / qemu.git / blame
| Commit | Line | Data |
|---|---|---|
| 5dbf3359 PG |
1 | |
| 2 | ======================== | |
| 3 | QEMU 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 | ||
| 12 | Usecase | |
| 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 | ||
| 19 | o 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 | ||
| 26 | virtio 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 | - "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 | ||
| 42 | Multiple virtio pmem devices can be created if multiple pairs of "-object" | |
| 43 | and "-device" are provided. | |
| 44 | ||
| 45 | Hotplug | |
| 46 | ------- | |
| 47 | ||
| 48 | Virtio pmem devices can be hotplugged via the QEMU monitor. First, the | |
| 49 | memory backing has to be added via 'object_add'; afterwards, the virtio | |
| 50 | pmem device can be added via 'device_add'. | |
| 51 | ||
| 52 | For example, the following commands add another 4GB virtio pmem device to | |
| 53 | the 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 | ||
| 58 | Guest Data Persistence | |
| 59 | ---------------------- | |
| 60 | ||
| 61 | Guest data persistence on non-NVDIMM requires guest userspace applications | |
| 62 | to perform fsync/msync. This is different from a real nvdimm backend where | |
| 63 | no additional fsync/msync is required. This is to persist guest writes in | |
| 64 | host backing file which otherwise remains in host page cache and there is | |
| 65 | risk of losing the data in case of power failure. | |
| 66 | ||
| 67 | With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides | |
| 68 | a hint to application to perform fsync for write persistence. | |
| 69 | ||
| 70 | Limitations | |
| 71 | ------------ | |
| 72 | - Real nvdimm device backend is not supported. | |
| 73 | - virtio pmem hotunplug is not supported. | |
| 74 | - ACPI NVDIMM features like regions/namespaces are not supported. | |
| 75 | - ndctl command is not supported. |