From nobody Sun Feb 8 15:30:50 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) client-ip=207.211.31.120; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1595510656; cv=none; d=zohomail.com; s=zohoarc; b=ZzYBO66u2zJyXpZgTxhhqFTPDTk192+ZCu/2Fw2a86h0SyQhV3nXvvqRFGUa+SOwdeGx9Z+szRzQSD/L1vMcxr8yxhQc5zHyqK68P1B9uL7esryTyQn9Q84y8bkDSXUkPnrPhqRwpBfEn8FQaBtLuU5T+VxumC/IkXqV763deyE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1595510656; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=T4rkMkxfNFYySPdn23YMPfY6AIMjI6HFGE6tGU3DHZ0=; b=jIVnUI26KDxtR1guueEz4jxPlr2QvJUjiEygOys8RDLn5FWn/q2EWPsO9yVaJlKMkx0o7liwnpiR7NtzJI4eong+2Kli57kAxa0UV71iP0OipYgV/vYXYyN0PKhnXmq7cvAiiWzCcHxvlwPJbRayS1yxbU1BaCEWKITqBEocnrc= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [207.211.31.120]) by mx.zohomail.com with SMTPS id 159551065601961.58630941317256; Thu, 23 Jul 2020 06:24:16 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-304-2kAS9s9IMtC0W7L8HPlpOw-1; Thu, 23 Jul 2020 09:22:51 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id BEC94107BEFA; Thu, 23 Jul 2020 13:22:45 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 9DF83512FE; Thu, 23 Jul 2020 13:22:45 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 6EDE8A359D; Thu, 23 Jul 2020 13:22:45 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 06NDMhBP028816 for ; Thu, 23 Jul 2020 09:22:43 -0400 Received: by smtp.corp.redhat.com (Postfix) id 663161A90F; Thu, 23 Jul 2020 13:22:43 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.37]) by smtp.corp.redhat.com (Postfix) with ESMTP id BC3862E022 for ; Thu, 23 Jul 2020 13:22:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1595510654; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=T4rkMkxfNFYySPdn23YMPfY6AIMjI6HFGE6tGU3DHZ0=; b=hutkQPh0I6h967q8IrmGrZFm99lCi9Cmwn0El3CRUslgoTlai32XYYpb6+0t0GcjMBykNT 1QQ06jo5dDiutnL4b5NmPlmbd3LjCoU0jsdN0Td/JXcnSw/zGg3Mhe428Gmct3X6DtRbkJ VA0cGUHtWvmKU7v0SWK0ueiyxtsNS0I= X-MC-Unique: 2kAS9s9IMtC0W7L8HPlpOw-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 30/32] docs: formatdomain-devices: Split out Date: Thu, 23 Jul 2020 15:21:35 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa --- 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-devic= es-memory.rst new file mode 100644 index 0000000000..f773a3d63a --- /dev/null +++ b/docs/formatdomain-devices-memory.rst @@ -0,0 +1,151 @@ +:anchor:`` + +Memory devices +~~~~~~~~~~~~~~ + +In addition to the initial memory assigned to the guest, memory devices al= low +additional memory to be assigned to the guest in the form of memory module= s. 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 + +:: + + ... + + + + 524287 + 0 + + + + + 4096 + 1-3 + + + 524287 + 1 + + + + + + /tmp/nvdimm + + + 524288 + 1 + + + + + + + + /dev/dax0.0 + 2048 + + + + 524288 + 1 + + + + + ... + +``model`` + Provide ``dimm`` to add a virtual DIMM module to the guest. :since:`Sin= ce + 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. Valu= es 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 v= alues + are ``yes`` and ``no``. The feature is described here: `Memory + Backing <#elementsMemoryBacking>`__. This attribute is allowed only for + ``model=3D'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=3D'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 i= s 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 w= here + the memory would be allocated. + + For model ``nvdimm`` this element is mandatory. The mandatory child ele= ment + ``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 mm= ap the + address range for the backend ``path``. If not supplied the host pag= e 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 ele= ment + to 2MB. :since:`Since 5.0.0` + + ``pmem`` + If persistent memory is supported and enabled by the hypervisor in o= rder + 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 memo= ry as + a scaled integer. + + The ``node`` subelement configures the guest NUMA node to attach the me= mory + to. The element shall be used only if the guest has NUMA nodes configur= ed. + + The following optional elements may be used: + + ``label`` + For NVDIMM type devices one can use ``label`` and its subelement ``s= ize`` + 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 pSe= ries + 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 a= rea, + 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. O= nly + the real NVDIMM device backend can guarantee the guest write persist= ence, + 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:`` - -Memory devices -~~~~~~~~~~~~~~ - -In addition to the initial memory assigned to the guest, memory devices al= low -additional memory to be assigned to the guest in the form of memory module= s. 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 - -:: - - ... - - - - 524287 - 0 - - - - - 4096 - 1-3 - - - 524287 - 1 - - - - - - /tmp/nvdimm - - - 524288 - 1 - - - - - - - - /dev/dax0.0 - 2048 - - - - 524288 - 1 - - - - - ... - -``model`` - Provide ``dimm`` to add a virtual DIMM module to the guest. :since:`Sin= ce - 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. Valu= es 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 v= alues - are ``yes`` and ``no``. The feature is described here: `Memory - Backing <#elementsMemoryBacking>`__. This attribute is allowed only for - ``model=3D'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=3D'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 i= s 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 w= here - the memory would be allocated. - - For model ``nvdimm`` this element is mandatory. The mandatory child ele= ment - ``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 mm= ap the - address range for the backend ``path``. If not supplied the host pag= e 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 ele= ment - to 2MB. :since:`Since 5.0.0` - - ``pmem`` - If persistent memory is supported and enabled by the hypervisor in o= rder - 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 memo= ry as - a scaled integer. - - The ``node`` subelement configures the guest NUMA node to attach the me= mory - to. The element shall be used only if the guest has NUMA nodes configur= ed. - - The following optional elements may be used: - - ``label`` - For NVDIMM type devices one can use ``label`` and its subelement ``s= ize`` - 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 pSe= ries - 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 a= rea, - 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. O= nly - the real NVDIMM device backend can guarantee the guest write persist= ence, - so other backend types should use the ``readonly`` element. :since:`= Since - 5.0.0` +.. include:: formatdomain-devices-memory.rst :anchor:`` 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 =3D [ 'formatdomain-devices-nvram.rst', 'formatdomain-devices-panic.rst', 'formatdomain-devices-shmem.rst', + 'formatdomain-devices-memory.rst', ] }, { 'name': 'hacking' }, --=20 2.26.2