Luyao Zhong
2018-11-28 14:09:19 UTC
Update news.xml and add description about new supported configurations
about NVDIMM in html, including 'alignsize', 'pmem', 'unarmed' and
'persistence'.
Signed-off-by: Luyao Zhong <***@intel.com>
---
docs/formatdomain.html.in | 94 ++++++++++++++++++++++++++++++++-------
docs/news.xml | 9 ++++
2 files changed, 88 insertions(+), 15 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 84259c45e4..a79ffbdcde 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -8317,6 +8317,8 @@ qemu-kvm -net nic,model=? /dev/null
<memory model='nvdimm'>
<source>
<path>/tmp/nvdimm</path>
+ <alignsize unit='KiB'>2048</alignsize>
+ <pmem/>
</source>
<target>
<size unit='KiB'>524288</size>
@@ -8324,6 +8326,8 @@ qemu-kvm -net nic,model=? /dev/null
<label>
<size unit='KiB'>128</size>
</label>
+ <persistence>cpu</persistence>
+ <unarmed/>
</target>
</memory>
</devices>
@@ -8398,10 +8402,37 @@ qemu-kvm -net nic,model=? /dev/null
</dl>
<p>
- For model <code>nvdimm</code> this element is mandatory and has a
- single child element <code>path</code> that represents a path
- in the host that backs the nvdimm module in the guest.
+ For model <code>nvdimm</code> this element is mandatory. The
+ mandatory child element <code>path</code> represents a path in
+ the host that backs the nvdimm module in the guest. If
+ <code>nvdimm</code> is provided, then the following optional
+ elements can be provided as well:
</p>
+
+ <dl>
+ <dt><code>alignsize</code></dt>
+ <dd>
+ <p>
+ This element can be used to specify a proper alignment.
+ When mmap(2) the backend files, QEMU uses the host page
+ size by default as the alignment of mapping address. However,
+ some backends may require alignments different from the page.
+ For example, mmap a real NVDIMM device maybe 2M-aligned required.
+ <span class="since">Since 4.9.0</span>
+ </p>
+ </dd>
+
+ <dt><code>pmem</code></dt>
+ <dd>
+ <p>
+ This element can be used to specify whether the backend storage
+ of memory-backend-file is a real persistent memory. If the backend
+ is a real persistence memory and <code>pmem</code> is set, QEMU
+ will guarantee the persistence of its own writes to the vNVDIMM
+ backend.<span class="since">Since 4.9.0</span>
+ </p>
+ </dd>
+ </dl>
</dd>
<dt><code>target</code></dt>
@@ -8420,19 +8451,52 @@ qemu-kvm -net nic,model=? /dev/null
NUMA nodes configured.
</p>
<p>
- For NVDIMM type devices one can optionally use
- <code>label</code> and its subelement <code>size</code>
- to configure the size of namespaces label storage
- within the NVDIMM module. The <code>size</code> element
- has usual meaning described
- <a href="#elementsMemoryAllocation">here</a>.
- For QEMU domains the following restrictions apply:
+ Besides, the following optional elements can be provided as well for
+ NVDIMM type devices:
</p>
- <ol>
- <li>the minimum label size is 128KiB,</li>
- <li>the remaining size (total-size - label-size) has to be aligned to
- 4KiB</li>
- </ol>
+
+ <dl>
+ <dt><code>label</code></dt>
+ <dd>
+ <p>
+ For NVDIMM type devices one can optionally use
+ <code>label</code> and its subelement <code>size</code>
+ to configure the size of namespaces label storage
+ within the NVDIMM module. The <code>size</code> element
+ has usual meaning described
+ <a href="#elementsMemoryAllocation">here</a>.
+ For QEMU domains the following restrictions apply:
+ </p>
+ <ol>
+ <li>the minimum label size is 128KiB,</li>
+ <li>the remaining size (total-size - label-size) will be aligned to
+ 4KiB as default.</li>
+ </ol>
+ </dd>
+
+ <dt><code>persistence</code></dt>
+ <dd>
+ <p>
+ The <code>persistence</code> element can be set to "mem-ctrl" or "cpu",
+ which indicate platform-supported features about NVDIMM data persistence.
+ 'mem-ctrl' means the platform supports flushing dirty data from the memory
+ controller to the NVDIMMs in the event of power loss, 'cpu' means the platform
+ supports flushing dirty data from the CPU cache (and the memory controller)
+ to the NVDIMMs in the event of power loss.
+ <span class="since">Since 4.9.0</span>
+ </p>
+ </dd>
+
+ <dt><code>unarmed</code></dt>
+ <dd>
+ <p>
+ The <code>unarmed</code> element can be used to mark vNVDIMM read-only.
+ Currently, only real NVDIMM device backend can guarantee the guest write
+ persistence, so please set <code>unarmed</code> when using other types
+ of backends.<span class="since">Since 4.9.0</span>
+ </p>
+ </dd>
+ </dl>
</dd>
</dl>
diff --git a/docs/news.xml b/docs/news.xml
index 3983613f8a..35f743f6a3 100644
--- a/docs/news.xml
+++ b/docs/news.xml
@@ -25,6 +25,15 @@
<section title="New features">
</section>
<section title="Improvements">
+ <change>
+ <summary>
+ NVDIMM: support more configurations
+ </summary>
+ <description>
+ Introduce more configuration options supported by QEMU community,
+ including 'alignsize', 'pmem', 'unarmed' and 'persistence'.
+ </description>
+ </change>
</section>
<section title="Bug fixes">
</section>
about NVDIMM in html, including 'alignsize', 'pmem', 'unarmed' and
'persistence'.
Signed-off-by: Luyao Zhong <***@intel.com>
---
docs/formatdomain.html.in | 94 ++++++++++++++++++++++++++++++++-------
docs/news.xml | 9 ++++
2 files changed, 88 insertions(+), 15 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 84259c45e4..a79ffbdcde 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -8317,6 +8317,8 @@ qemu-kvm -net nic,model=? /dev/null
<memory model='nvdimm'>
<source>
<path>/tmp/nvdimm</path>
+ <alignsize unit='KiB'>2048</alignsize>
+ <pmem/>
</source>
<target>
<size unit='KiB'>524288</size>
@@ -8324,6 +8326,8 @@ qemu-kvm -net nic,model=? /dev/null
<label>
<size unit='KiB'>128</size>
</label>
+ <persistence>cpu</persistence>
+ <unarmed/>
</target>
</memory>
</devices>
@@ -8398,10 +8402,37 @@ qemu-kvm -net nic,model=? /dev/null
</dl>
<p>
- For model <code>nvdimm</code> this element is mandatory and has a
- single child element <code>path</code> that represents a path
- in the host that backs the nvdimm module in the guest.
+ For model <code>nvdimm</code> this element is mandatory. The
+ mandatory child element <code>path</code> represents a path in
+ the host that backs the nvdimm module in the guest. If
+ <code>nvdimm</code> is provided, then the following optional
+ elements can be provided as well:
</p>
+
+ <dl>
+ <dt><code>alignsize</code></dt>
+ <dd>
+ <p>
+ This element can be used to specify a proper alignment.
+ When mmap(2) the backend files, QEMU uses the host page
+ size by default as the alignment of mapping address. However,
+ some backends may require alignments different from the page.
+ For example, mmap a real NVDIMM device maybe 2M-aligned required.
+ <span class="since">Since 4.9.0</span>
+ </p>
+ </dd>
+
+ <dt><code>pmem</code></dt>
+ <dd>
+ <p>
+ This element can be used to specify whether the backend storage
+ of memory-backend-file is a real persistent memory. If the backend
+ is a real persistence memory and <code>pmem</code> is set, QEMU
+ will guarantee the persistence of its own writes to the vNVDIMM
+ backend.<span class="since">Since 4.9.0</span>
+ </p>
+ </dd>
+ </dl>
</dd>
<dt><code>target</code></dt>
@@ -8420,19 +8451,52 @@ qemu-kvm -net nic,model=? /dev/null
NUMA nodes configured.
</p>
<p>
- For NVDIMM type devices one can optionally use
- <code>label</code> and its subelement <code>size</code>
- to configure the size of namespaces label storage
- within the NVDIMM module. The <code>size</code> element
- has usual meaning described
- <a href="#elementsMemoryAllocation">here</a>.
- For QEMU domains the following restrictions apply:
+ Besides, the following optional elements can be provided as well for
+ NVDIMM type devices:
</p>
- <ol>
- <li>the minimum label size is 128KiB,</li>
- <li>the remaining size (total-size - label-size) has to be aligned to
- 4KiB</li>
- </ol>
+
+ <dl>
+ <dt><code>label</code></dt>
+ <dd>
+ <p>
+ For NVDIMM type devices one can optionally use
+ <code>label</code> and its subelement <code>size</code>
+ to configure the size of namespaces label storage
+ within the NVDIMM module. The <code>size</code> element
+ has usual meaning described
+ <a href="#elementsMemoryAllocation">here</a>.
+ For QEMU domains the following restrictions apply:
+ </p>
+ <ol>
+ <li>the minimum label size is 128KiB,</li>
+ <li>the remaining size (total-size - label-size) will be aligned to
+ 4KiB as default.</li>
+ </ol>
+ </dd>
+
+ <dt><code>persistence</code></dt>
+ <dd>
+ <p>
+ The <code>persistence</code> element can be set to "mem-ctrl" or "cpu",
+ which indicate platform-supported features about NVDIMM data persistence.
+ 'mem-ctrl' means the platform supports flushing dirty data from the memory
+ controller to the NVDIMMs in the event of power loss, 'cpu' means the platform
+ supports flushing dirty data from the CPU cache (and the memory controller)
+ to the NVDIMMs in the event of power loss.
+ <span class="since">Since 4.9.0</span>
+ </p>
+ </dd>
+
+ <dt><code>unarmed</code></dt>
+ <dd>
+ <p>
+ The <code>unarmed</code> element can be used to mark vNVDIMM read-only.
+ Currently, only real NVDIMM device backend can guarantee the guest write
+ persistence, so please set <code>unarmed</code> when using other types
+ of backends.<span class="since">Since 4.9.0</span>
+ </p>
+ </dd>
+ </dl>
</dd>
</dl>
diff --git a/docs/news.xml b/docs/news.xml
index 3983613f8a..35f743f6a3 100644
--- a/docs/news.xml
+++ b/docs/news.xml
@@ -25,6 +25,15 @@
<section title="New features">
</section>
<section title="Improvements">
+ <change>
+ <summary>
+ NVDIMM: support more configurations
+ </summary>
+ <description>
+ Introduce more configuration options supported by QEMU community,
+ including 'alignsize', 'pmem', 'unarmed' and 'persistence'.
+ </description>
+ </change>
</section>
<section title="Bug fixes">
</section>
--
2.17.1
2.17.1