docs/virtio-pmem.rst

   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.