From nobody Sun Apr 28 19:47:40 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zoho.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1486082021015416.94329869372314; Thu, 2 Feb 2017 16:33:41 -0800 (PST) Received: from localhost ([::1]:59583 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cZRoo-0007CV-KK for importer@patchew.org; Thu, 02 Feb 2017 19:33:38 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:54959) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cZRny-0006uC-2E for qemu-devel@nongnu.org; Thu, 02 Feb 2017 19:32:47 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cZRnt-0007f5-4i for qemu-devel@nongnu.org; Thu, 02 Feb 2017 19:32:46 -0500 Received: from mga07.intel.com ([134.134.136.100]:46218) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1cZRns-0007b0-RR for qemu-devel@nongnu.org; Thu, 02 Feb 2017 19:32:41 -0500 Received: from fmsmga004.fm.intel.com ([10.253.24.48]) by orsmga105.jf.intel.com with ESMTP; 02 Feb 2017 16:32:36 -0800 Received: from hz-desktop.sh.intel.com (HELO localhost) ([10.239.159.133]) by fmsmga004.fm.intel.com with ESMTP; 02 Feb 2017 16:32:34 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.33,326,1477983600"; d="scan'208";a="220760538" From: Haozhong Zhang To: qemu-devel@nongnu.org Date: Fri, 3 Feb 2017 08:32:12 +0800 Message-Id: <20170203003212.21992-1-haozhong.zhang@intel.com> X-Mailer: git-send-email 2.10.1 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 134.134.136.100 Subject: [Qemu-devel] [RESEND PATCH v2] docs: add document to explain the usage of vNVDIMM X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Stefan Hajnoczi , Xiao Guangrong , "Dr . David Alan Gilbert" , Haozhong Zhang , "Michael S . Tsirkin" Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Signed-off-by: Haozhong Zhang Reviewed-by: Xiao Guangrong Reviewed-by: Stefan Hajnoczi --- Changes since v1: * explicitly state the block window mode is not supported (Stefan Hajnoczi) * typo fix: label_size =3D=3D> label-size (David Alan Gilbert) --- docs/nvdimm.txt | 124 ++++++++++++++++++++++++++++++++++++++++++++++++++++= ++++ 1 file changed, 124 insertions(+) create mode 100644 docs/nvdimm.txt diff --git a/docs/nvdimm.txt b/docs/nvdimm.txt new file mode 100644 index 0000000..2d9f8c0 --- /dev/null +++ b/docs/nvdimm.txt @@ -0,0 +1,124 @@ +QEMU Virtual NVDIMM +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +This document explains the usage of virtual NVDIMM (vNVDIMM) feature +which is available since QEMU v2.6.0. + +The current QEMU only implements the persistent memory mode of vNVDIMM +device and not the block window mode. + +Basic Usage +----------- + +The storage of a vNVDIMM device in QEMU is provided by the memory +backend (i.e. memory-backend-file and memory-backend-ram). A simple +way to create a vNVDIMM device at startup time is done via the +following command line options: + + -machine pc,nvdimm + -m $RAM_SIZE,slots=3D$N,maxmem=3D$MAX_SIZE + -object memory-backend-file,id=3Dmem1,share=3Don,mem-path=3D$PATH,size=3D= $NVDIMM_SIZE + -device nvdimm,id=3Dnvdimm1,memdev=3Dmem1 + +Where, + + - the "nvdimm" machine option enables vNVDIMM feature. + + - "slots=3D$N" should be equal to or larger than the total amount of + normal RAM devices and vNVDIMM devices, e.g. $N should be >=3D 2 here. + + - "maxmem=3D$MAX_SIZE" should be equal to or larger than the total size + of normal RAM devices and vNVDIMM devices, e.g. $MAX_SIZE should be + >=3D $RAM_SIZE + $NVDIMM_SIZE here. + + - "object memory-backend-file,id=3Dmem1,share=3Don,mem-path=3D$PATH,size= =3D$NVDIMM_SIZE" + creates a backend storage of size $NVDIMM_SIZE on a file $PATH. All + accesses to the virtual NVDIMM device go to the file $PATH. + + "share=3Don/off" controls the visibility of guest writes. If + "share=3Don", then guest writes will be applied to the backend + file. If another guest uses the same backend file with option + "share=3Don", then above writes will be visible to it as well. If + "share=3Doff", then guest writes won't be applied to the backend + file and thus will be invisible to other guests. + + - "device nvdimm,id=3Dnvdimm1,memdev=3Dmem1" creates a virtual NVDIMM + device whose storage is provided by above memory backend device. + +Multiple vNVDIMM devices can be created if multiple pairs of "-object" +and "-device" are provided. + +For above command line options, if the guest OS has the proper NVDIMM +driver, it should be able to detect a NVDIMM device which is in the +persistent memory mode and whose size is $NVDIMM_SIZE. + +Note: + +1. Prior to QEMU v2.8.0, if memory-backend-file is used and the actual + backend file size is not equal to the size given by "size" option, + QEMU will truncate the backend file by ftruncate(2), which will + corrupt the existing data in the backend file, especially for the + shrink case. + + QEMU v2.8.0 and later check the backend file size and the "size" + option. If they do not match, QEMU will report errors and abort in + order to avoid the data corruption. + +2. QEMU v2.6.0 only puts a basic alignment requirement on the "size" + option of memory-backend-file, e.g. 4KB alignment on x86. However, + QEMU v.2.7.0 puts an additional alignment requirement, which may + require a larger value than the basic one, e.g. 2MB on x86. This + change breaks the usage of memory-backend-file that only satisfies + the basic alignment. + + QEMU v2.8.0 and later remove the additional alignment on non-s390x + architectures, so the broken memory-backend-file can work again. + +Label +----- + +QEMU v2.7.0 and later implement the label support for vNVDIMM devices. +To enable label on vNVDIMM devices, users can simply add +"label-size=3D$SZ" option to "-device nvdimm", e.g. + + -device nvdimm,id=3Dnvdimm1,memdev=3Dmem1,label-size=3D128K + +Note: + +1. The minimal label size is 128KB. + +2. QEMU v2.7.0 and later store labels at the end of backend storage. + If a memory backend file, which was previously used as the backend + of a vNVDIMM device without labels, is now used for a vNVDIMM + device with label, the data in the label area at the end of file + will be inaccessible to the guest. If any useful data (e.g. the + meta-data of the file system) was stored there, the latter usage + may result guest data corruption (e.g. breakage of guest file + system). + +Hotplug +------- + +QEMU v2.8.0 and later implement the hotplug support for vNVDIMM +devices. Similarly to the RAM hotplug, the vNVDIMM hotplug is +accomplished by two monitor commands "object_add" and "device_add". + +For example, the following commands add another 4GB vNVDIMM device to +the guest: + + (qemu) object_add memory-backend-file,id=3Dmem2,share=3Don,mem-path=3Dnew= _nvdimm.img,size=3D4G + (qemu) device_add nvdimm,id=3Dnvdimm2,memdev=3Dmem2 + +Note: + +1. Each hotplugged vNVDIMM device consumes one memory slot. Users + should always ensure the memory option "-m ...,slots=3DN" specifies + enough number of slots, i.e. + N >=3D number of RAM devices + + number of statically plugged vNVDIMM devices + + number of hotplugged vNVDIMM devices + +2. The similar is required for the memory option "-m ...,maxmem=3DM", i.e. + M >=3D size of RAM devices + + size of statically plugged vNVDIMM devices + + size of hotplugged vNVDIMM devices --=20 2.10.1