[libvirt] [RFC v2 3/3] nvdimm: update docs for introducing more NVDIMM configurations

[Luyao Zhong]

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 <luyao.zhong at 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