[PATCH 30/32] docs: formatdomain-devices: Split out <memory>

Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- 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