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

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(a)intel.com&gt; --- 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 &lt;memory model='nvdimm'&gt; &lt;source&gt; &lt;path&gt;/tmp/nvdimm&lt;/path&gt; + &lt;alignsize unit='KiB'&gt;2048&lt;/alignsize&gt; + &lt;pmem/&gt; &lt;/source&gt; &lt;target&gt; &lt;size unit='KiB'&gt;524288&lt;/size&gt; @@ -8324,6 +8326,8 @@ qemu-kvm -net nic,model=? /dev/null &lt;label&gt; &lt;size unit='KiB'&gt;128&lt;/size&gt; &lt;/label&gt; + &lt;persistence&gt;cpu&lt;/persistence&gt; + &lt;unarmed/&gt; &lt;/target&gt; &lt;/memory&gt; &lt;/devices&gt; @@ -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