From d8b92bd41822c053daa4dbf88cf36b14241a0279 Mon Sep 17 00:00:00 2001 From: Wei Yang Date: Thu, 1 Aug 2019 08:40:53 +0800 Subject: docs/nvdimm: add example on persistent backend setup Persistent backend setup requires some knowledge about nvdimm and ndctl tool. Some users report they may struggle to gather these knowledge and have difficulty to setup it properly. Here we provide two examples for persistent backend and gives the link to ndctl. By doing so, user could try it directly and do more investigation on persistent backend setup with ndctl. Signed-off-by: Wei Yang Reviewed-by: Pankaj Gupta Message-Id: <20190801004053.7021-1-richardw.yang@linux.intel.com> Reviewed-by: Stefan Hajnoczi Reviewed-by: Michael S. Tsirkin Signed-off-by: Michael S. Tsirkin --- docs/nvdimm.txt | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) (limited to 'docs') diff --git a/docs/nvdimm.txt b/docs/nvdimm.txt index b531cacd35..362e99109e 100644 --- a/docs/nvdimm.txt +++ b/docs/nvdimm.txt @@ -171,6 +171,35 @@ guest software that this vNVDIMM device contains a region that cannot accept persistent writes. In result, for example, the guest Linux NVDIMM driver, marks such vNVDIMM device as read-only. +Backend File Setup Example +-------------------------- + +Here are two examples showing how to setup these persistent backends on +linux using the tool ndctl [3]. + +A. DAX device + +Use the following command to set up /dev/dax0.0 so that the entirety of +namespace0.0 can be exposed as an emulated NVDIMM to the guest: + + ndctl create-namespace -f -e namespace0.0 -m devdax + +The /dev/dax0.0 could be used directly in "mem-path" option. + +B. DAX file + +Individual files on a DAX host file system can be exposed as emulated +NVDIMMS. First an fsdax block device is created, partitioned, and then +mounted with the "dax" mount option: + + ndctl create-namespace -f -e namespace0.0 -m fsdax + (partition /dev/pmem0 with name pmem0p1) + mount -o dax /dev/pmem0p1 /mnt + (create or copy a disk image file with qemu-img(1), cp(1), or dd(1) + in /mnt) + +Then the new file in /mnt could be used in "mem-path" option. + NVDIMM Persistence ------------------ @@ -212,3 +241,5 @@ References https://www.snia.org/sites/default/files/technical_work/final/NVMProgrammingModel_v1.2.pdf [2] Persistent Memory Development Kit (PMDK), formerly known as NVML project, home page: http://pmem.io/pmdk/ +[3] ndctl-create-namespace - provision or reconfigure a namespace + http://pmem.io/ndctl/ndctl-create-namespace.html -- cgit v1.2.3-55-g7522 From 5dbf335968faa45e5a1ee3083fb6816d90dc6ff3 Mon Sep 17 00:00:00 2001 From: Pankaj Gupta Date: Wed, 21 Aug 2019 17:46:24 +0530 Subject: virtio pmem: user document 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 Message-Id: <20190821121624.5382-1-pagupta@redhat.com> Reviewed-by: Cornelia Huck Reviewed-by: Michael S. Tsirkin Signed-off-by: Michael S. Tsirkin --- docs/virtio-pmem.rst | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 docs/virtio-pmem.rst (limited to 'docs') diff --git a/docs/virtio-pmem.rst b/docs/virtio-pmem.rst new file mode 100644 index 0000000000..e77881b26f --- /dev/null +++ b/docs/virtio-pmem.rst @@ -0,0 +1,75 @@ + +======================== +QEMU virtio pmem +======================== + + This document explains the setup and usage of the virtio pmem device + which is available since QEMU v4.1.0. + + The virtio pmem device is a paravirtualized persistent memory device + on regular (i.e non-NVDIMM) storage. + +Usecase +-------- + + Virtio pmem allows to bypass the guest page cache and directly use + host page cache. This reduces guest memory footprint as the 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 (i.e. non-NVDIMM) host storage does not + persist the guest writes as there are no defined semantics in the device + specification. The virtio pmem device provides guest write persistence + on non-NVDIMM host storage. + +virtio pmem usage +----------------- + + A virtio pmem device backed by a memory-backend-file can be created on + the QEMU command line as in the following example: + + -object memory-backend-file,id=mem1,share,mem-path=./virtio_pmem.img,size=4G + -device virtio-pmem-pci,memdev=mem1,id=nv1 + + where: + - "object memory-backend-file,id=mem1,share,mem-path=, size=" + creates a backend file with the specified size. + + - "device virtio-pmem-pci,id=nvdimm1,memdev=mem1" creates a virtio pmem + pci 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 +------- + +Virtio pmem devices can be hotplugged via the QEMU monitor. First, the +memory backing has to be added via 'object_add'; afterwards, the virtio +pmem device can be added via '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 applications + to perform fsync/msync. This is different from a real nvdimm backend where + no additional fsync/msync is required. This is to persist guest writes in + host backing file which otherwise remains in host page cache and there is + risk of losing the data in case of power failure. + + With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides + a hint to application to perform fsync for write 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. -- cgit v1.2.3-55-g7522