Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
docs/formatdomain-devices-memory.rst | 151 ++++++++++++++++++++++++++
docs/formatdomain-devices.rst | 154 +--------------------------
docs/meson.build | 1 +
3 files changed, 153 insertions(+), 153 deletions(-)
create mode 100644 docs/formatdomain-devices-memory.rst
diff --git a/docs/formatdomain-devices-memory.rst b/docs/formatdomain-devices-memory.rst
new file mode 100644
index 0000000000..f773a3d63a
--- /dev/null
+++ b/docs/formatdomain-devices-memory.rst
@@ -0,0 +1,151 @@
+:anchor:`<a id="elementsMemory"/>`
+
+Memory devices
+~~~~~~~~~~~~~~
+
+In addition to the initial memory assigned to the guest, memory devices allow
+additional memory to be assigned to the guest in the form of memory modules. A
+memory device can be hot-plugged or hot-unplugged depending on the guests'
+memory resource needs. Some hypervisors may require NUMA configured for the
+guest.
+
+Example: usage of the memory devices
+
+::
+
+ ...
+ <devices>
+ <memory model='dimm' access='private' discard='yes'>
+ <target>
+ <size unit='KiB'>524287</size>
+ <node>0</node>
+ </target>
+ </memory>
+ <memory model='dimm'>
+ <source>
+ <pagesize unit='KiB'>4096</pagesize>
+ <nodemask>1-3</nodemask>
+ </source>
+ <target>
+ <size unit='KiB'>524287</size>
+ <node>1</node>
+ </target>
+ </memory>
+ <memory model='nvdimm'>
+ <uuid>
+ <source>
+ <path>/tmp/nvdimm</path>
+ </source>
+ <target>
+ <size unit='KiB'>524288</size>
+ <node>1</node>
+ <label>
+ <size unit='KiB'>128</size>
+ </label>
+ <readonly/>
+ </target>
+ </memory>
+ <memory model='nvdimm' access='shared'>
+ <uuid>
+ <source>
+ <path>/dev/dax0.0</path>
+ <alignsize unit='KiB'>2048</alignsize>
+ <pmem/>
+ </source>
+ <target>
+ <size unit='KiB'>524288</size>
+ <node>1</node>
+ <label>
+ <size unit='KiB'>128</size>
+ </label>
+ </target>
+ </memory>
+ </devices>
+ ...
+
+``model``
+ Provide ``dimm`` to add a virtual DIMM module to the guest. :since:`Since
+ 1.2.14` Provide ``nvdimm`` model adds a Non-Volatile DIMM module.
+ :since:`Since 3.2.0`
+
+``access``
+ An optional attribute ``access`` ( :since:`since 3.2.0` ) that provides
+ capability to fine tune mapping of the memory on per module basis. Values are
+ the same as `Memory Backing <#elementsMemoryBacking>`__: ``shared`` and
+ ``private``. For ``nvdimm`` model, if using real NVDIMM DAX device as
+ backend, ``shared`` is required.
+
+``discard``
+ An optional attribute ``discard`` ( :since:`since 4.4.0` ) that provides
+ capability to fine tune discard of data on per module basis. Accepted values
+ are ``yes`` and ``no``. The feature is described here: `Memory
+ Backing <#elementsMemoryBacking>`__. This attribute is allowed only for
+ ``model='dimm'``.
+
+``uuid``
+ For pSeries guests, an uuid can be set to identify the nvdimm module. If
+ absent, libvirt will generate an uuid. automatically. This attribute is
+ allowed only for ``model='nvdimm'`` for pSeries guests. :since:`Since 6.2.0`
+
+``source``
+ For model ``dimm`` this element is optional and allows to fine tune the
+ source of the memory used for the given memory device. If the element is not
+ provided defaults configured via ``numatune`` are used. If ``dimm`` is
+ provided, then the following optional elements can be provided as well:
+
+ ``pagesize``
+ This element can be used to override the default host page size used for
+ backing the memory device. The configured value must correspond to a page
+ size supported by the host.
+
+ ``nodemask``
+ This element can be used to override the default set of NUMA nodes where
+ the memory would be allocated.
+
+ For model ``nvdimm`` this element is mandatory. The mandatory child element
+ ``path`` represents a path in the host that backs the nvdimm module in the
+ guest. The following optional elements may be used:
+
+ ``alignsize``
+ The ``alignsize`` element defines the page size alignment used to mmap the
+ address range for the backend ``path``. If not supplied the host page size
+ is used. For example, to mmap a real NVDIMM device a 2M-aligned page may
+ be required, and host page size is 4KB, then we need to set this element
+ to 2MB. :since:`Since 5.0.0`
+
+ ``pmem``
+ If persistent memory is supported and enabled by the hypervisor in order
+ to guarantee the persistence of writes to the vNVDIMM backend, then use
+ the ``pmem`` element in order to utilize the feature. :since:`Since 5.0.0`
+
+``target``
+ The mandatory ``target`` element configures the placement and sizing of the
+ added memory from the perspective of the guest.
+
+ The mandatory ``size`` subelement configures the size of the added memory as
+ a scaled integer.
+
+ The ``node`` subelement configures the guest NUMA node to attach the memory
+ to. The element shall be used only if the guest has NUMA nodes configured.
+
+ The following optional elements may be used:
+
+ ``label``
+ For NVDIMM type devices one can use ``label`` and its subelement ``size``
+ to configure the size of namespaces label storage within the NVDIMM
+ module. The ``size`` element has usual meaning described
+ `here <#elementsMemoryAllocation>`__. ``label`` is mandatory for pSeries
+ guests and optional for all other architectures. For QEMU domains the
+ following restrictions apply:
+
+ #. the minimum label size is 128KiB,
+ #. the remaining size (total-size - label-size), also called guest area,
+ will be aligned to 4KiB as default. For pSeries guests, the guest area
+ will be aligned down to 256MiB, and the minimum size of the guest area
+ must be at least 256MiB.
+
+ ``readonly``
+ The ``readonly`` element is used to mark the vNVDIMM as read-only. Only
+ the real NVDIMM device backend can guarantee the guest write persistence,
+ so other backend types should use the ``readonly`` element. :since:`Since
+ 5.0.0`
diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst
index 8b81662442..827233af64 100644
--- a/docs/formatdomain-devices.rst
+++ b/docs/formatdomain-devices.rst
@@ -62,159 +62,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
.. include:: formatdomain-devices-nvram.rst
.. include:: formatdomain-devices-panic.rst
.. include:: formatdomain-devices-shmem.rst
-
-
-:anchor:`<a id="elementsMemory"/>`
-
-Memory devices
-~~~~~~~~~~~~~~
-
-In addition to the initial memory assigned to the guest, memory devices allow
-additional memory to be assigned to the guest in the form of memory modules. A
-memory device can be hot-plugged or hot-unplugged depending on the guests'
-memory resource needs. Some hypervisors may require NUMA configured for the
-guest.
-
-Example: usage of the memory devices
-
-::
-
- ...
- <devices>
- <memory model='dimm' access='private' discard='yes'>
- <target>
- <size unit='KiB'>524287</size>
- <node>0</node>
- </target>
- </memory>
- <memory model='dimm'>
- <source>
- <pagesize unit='KiB'>4096</pagesize>
- <nodemask>1-3</nodemask>
- </source>
- <target>
- <size unit='KiB'>524287</size>
- <node>1</node>
- </target>
- </memory>
- <memory model='nvdimm'>
- <uuid>
- <source>
- <path>/tmp/nvdimm</path>
- </source>
- <target>
- <size unit='KiB'>524288</size>
- <node>1</node>
- <label>
- <size unit='KiB'>128</size>
- </label>
- <readonly/>
- </target>
- </memory>
- <memory model='nvdimm' access='shared'>
- <uuid>
- <source>
- <path>/dev/dax0.0</path>
- <alignsize unit='KiB'>2048</alignsize>
- <pmem/>
- </source>
- <target>
- <size unit='KiB'>524288</size>
- <node>1</node>
- <label>
- <size unit='KiB'>128</size>
- </label>
- </target>
- </memory>
- </devices>
- ...
-
-``model``
- Provide ``dimm`` to add a virtual DIMM module to the guest. :since:`Since
- 1.2.14` Provide ``nvdimm`` model adds a Non-Volatile DIMM module.
- :since:`Since 3.2.0`
-
-``access``
- An optional attribute ``access`` ( :since:`since 3.2.0` ) that provides
- capability to fine tune mapping of the memory on per module basis. Values are
- the same as `Memory Backing <#elementsMemoryBacking>`__: ``shared`` and
- ``private``. For ``nvdimm`` model, if using real NVDIMM DAX device as
- backend, ``shared`` is required.
-
-``discard``
- An optional attribute ``discard`` ( :since:`since 4.4.0` ) that provides
- capability to fine tune discard of data on per module basis. Accepted values
- are ``yes`` and ``no``. The feature is described here: `Memory
- Backing <#elementsMemoryBacking>`__. This attribute is allowed only for
- ``model='dimm'``.
-
-``uuid``
- For pSeries guests, an uuid can be set to identify the nvdimm module. If
- absent, libvirt will generate an uuid. automatically. This attribute is
- allowed only for ``model='nvdimm'`` for pSeries guests. :since:`Since 6.2.0`
-
-``source``
- For model ``dimm`` this element is optional and allows to fine tune the
- source of the memory used for the given memory device. If the element is not
- provided defaults configured via ``numatune`` are used. If ``dimm`` is
- provided, then the following optional elements can be provided as well:
-
- ``pagesize``
- This element can be used to override the default host page size used for
- backing the memory device. The configured value must correspond to a page
- size supported by the host.
-
- ``nodemask``
- This element can be used to override the default set of NUMA nodes where
- the memory would be allocated.
-
- For model ``nvdimm`` this element is mandatory. The mandatory child element
- ``path`` represents a path in the host that backs the nvdimm module in the
- guest. The following optional elements may be used:
-
- ``alignsize``
- The ``alignsize`` element defines the page size alignment used to mmap the
- address range for the backend ``path``. If not supplied the host page size
- is used. For example, to mmap a real NVDIMM device a 2M-aligned page may
- be required, and host page size is 4KB, then we need to set this element
- to 2MB. :since:`Since 5.0.0`
-
- ``pmem``
- If persistent memory is supported and enabled by the hypervisor in order
- to guarantee the persistence of writes to the vNVDIMM backend, then use
- the ``pmem`` element in order to utilize the feature. :since:`Since 5.0.0`
-
-``target``
- The mandatory ``target`` element configures the placement and sizing of the
- added memory from the perspective of the guest.
-
- The mandatory ``size`` subelement configures the size of the added memory as
- a scaled integer.
-
- The ``node`` subelement configures the guest NUMA node to attach the memory
- to. The element shall be used only if the guest has NUMA nodes configured.
-
- The following optional elements may be used:
-
- ``label``
- For NVDIMM type devices one can use ``label`` and its subelement ``size``
- to configure the size of namespaces label storage within the NVDIMM
- module. The ``size`` element has usual meaning described
- `here <#elementsMemoryAllocation>`__. ``label`` is mandatory for pSeries
- guests and optional for all other architectures. For QEMU domains the
- following restrictions apply:
-
- #. the minimum label size is 128KiB,
- #. the remaining size (total-size - label-size), also called guest area,
- will be aligned to 4KiB as default. For pSeries guests, the guest area
- will be aligned down to 256MiB, and the minimum size of the guest area
- must be at least 256MiB.
-
- ``readonly``
- The ``readonly`` element is used to mark the vNVDIMM as read-only. Only
- the real NVDIMM device backend can guarantee the guest write persistence,
- so other backend types should use the ``readonly`` element. :since:`Since
- 5.0.0`
+.. include:: formatdomain-devices-memory.rst
:anchor:`<a id="elementsIommu"/>`
diff --git a/docs/meson.build b/docs/meson.build
index c0437aea62..f0f7690d54 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -147,6 +147,7 @@ docs_rst_files = [
'formatdomain-devices-nvram.rst',
'formatdomain-devices-panic.rst',
'formatdomain-devices-shmem.rst',
+ 'formatdomain-devices-memory.rst',
]
},
{ 'name': 'hacking' },
--
2.26.2
