From nobody Wed Jan 15 14:58:17 2025 Delivered-To: importer@patchew.org Received-SPF: none (zohomail.com: 8.43.85.245 is neither permitted nor denied by domain of lists.libvirt.org) client-ip=8.43.85.245; envelope-from=devel-bounces@lists.libvirt.org; helo=lists.libvirt.org; Authentication-Results: mx.zohomail.com; spf=none (zohomail.com: 8.43.85.245 is neither permitted nor denied by domain of lists.libvirt.org) smtp.mailfrom=devel-bounces@lists.libvirt.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.libvirt.org (lists.libvirt.org [8.43.85.245]) by mx.zohomail.com with SMTPS id 1704984503075583.4381576842087; Thu, 11 Jan 2024 06:48:23 -0800 (PST) Received: by lists.libvirt.org (Postfix, from userid 996) id F2D6C1D5F; Thu, 11 Jan 2024 09:48:21 -0500 (EST) Received: from lists.libvirt.org (localhost [IPv6:::1]) by lists.libvirt.org (Postfix) with ESMTP id A03331D34; Thu, 11 Jan 2024 09:27:53 -0500 (EST) Received: by lists.libvirt.org (Postfix, from userid 996) id 6F5321C4E; Thu, 11 Jan 2024 09:27:01 -0500 (EST) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by lists.libvirt.org (Postfix) with ESMTPS id 7E3501C79 for ; Thu, 11 Jan 2024 09:26:56 -0500 (EST) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-231-luiipcKmOTWmyoeaXhP-fg-1; Thu, 11 Jan 2024 09:26:54 -0500 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 4F29B85A58E for ; Thu, 11 Jan 2024 14:26:54 +0000 (UTC) Received: from harajuku.usersys.redhat.com (unknown [10.45.226.144]) by smtp.corp.redhat.com (Postfix) with ESMTPS id CC2033C39 for ; Thu, 11 Jan 2024 14:26:53 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on lists.libvirt.org X-Spam-Level: X-Spam-Status: No, score=-0.8 required=5.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL,SPF_HELO_NONE,T_SCC_BODY_TEXT_LINE autolearn=unavailable autolearn_force=no version=3.4.4 X-MC-Unique: luiipcKmOTWmyoeaXhP-fg-1 From: Andrea Bolognani To: devel@lists.libvirt.org Subject: [PATCH v2 09/11] docs: Improve documentation for CPU topology Date: Thu, 11 Jan 2024 15:26:41 +0100 Message-ID: <20240111142644.658765-10-abologna@redhat.com> In-Reply-To: <20240111142644.658765-1-abologna@redhat.com> References: <20240111142644.658765-1-abologna@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Message-ID-Hash: JTJNT34R5GM4QDUCEDMGSJBMLRDMEKZS X-Message-ID-Hash: JTJNT34R5GM4QDUCEDMGSJBMLRDMEKZS X-MailFrom: abologna@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; header-match-config-2; header-match-config-3; header-match-devel.lists.libvirt.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header X-Mailman-Version: 3.2.2 Precedence: list List-Id: Development discussions about the libvirt library & tools Archived-At: List-Archive: List-Help: List-Post: List-Subscribe: List-Unsubscribe: Content-Type: text/plain; charset="utf-8"; x-default="true" Content-Transfer-Encoding: quoted-printable X-ZM-MESSAGEID: 1704984504309100001 On the guest configuration side, mention that support for the "dies" attribute was introduced in libvirt 6.1.0 and clarify that the ability to use non-default values is subject to architecuture and machine limitations. On the host capabilities side, the documentation was pretty much entirely missing. It's still far from perfect, but anything is better than having no information at all. Signed-off-by: Andrea Bolognani Reviewed-by: Peter Krempa --- docs/formatcaps.rst | 48 +++++++++++++++++++++++++++++++++++++------ docs/formatdomain.rst | 16 +++++++++------ 2 files changed, 52 insertions(+), 12 deletions(-) diff --git a/docs/formatcaps.rst b/docs/formatcaps.rst index 3cccf70882..60f8b7caca 100644 --- a/docs/formatcaps.rst +++ b/docs/formatcaps.rst @@ -37,6 +37,12 @@ The ```` element consists of the following child = elements: The host UUID. ``cpu`` The host CPU architecture and features. + + Note that, while this element contains a ``topology`` sub-element, + the information contained therein is farily high-level and likely + not very useful when it comes to optimizing guest vCPU placement. + Look into the ``topology`` *element*, described below, for more + detailed information. ``power_management`` whether host is capable of memory suspend, disk hibernation, or hybrid suspend. @@ -44,12 +50,42 @@ The ```` element consists of the following child= elements: This element exposes information on the hypervisor's migration capabili= ties, like live migration, supported URI transports, and so on. ``topology`` - This element embodies the host internal topology. Management applicatio= ns may - want to learn this information when orchestrating new guests - e.g. due= to - reduce inter-NUMA node transfers. Note that the ``sockets`` value repor= ted - here is per-NUMA-node; this is in contrast to the value given in domain - definitions, which is interpreted as a total number of sockets for the - domain. + This element describes the host CPU topology in detail. + + Management applications may want to use this information when defining = new + guests: for example, in order to ensure that all vCPUs are scheduled on + CPUs that are in the same NUMA node or even CPU core. + + The ``cells`` sub-element contains a list of NUMA nodes, each one + represented by a single ``cell`` element. Within each ``cell``, a ``cpu= s`` + sub-element contains a list of logical CPUs, each one represented by a + single ``cpu`` element. In both cases, the ``num`` attribute of the + top-level element contains the number of children. + + Each ``cpu`` element contains the following attributes: + + ``id`` + CPU identifier. Can be used to refer to it in the context of + `CPU tuning `__. + + ``socket_id`` + Identifier for the physical package the CPU is in. + + ``die_id`` + Identifier for the die the CPU is in. + + Note that not all architectures support CPU dies: if the current + architecture doesn't, the value will be 0 for all CPUs. + + ``core_id`` + Identifier for the core the CPU is in. + + ``siblings`` + List of CPUs that are in the same core. + + The list will include the current CPU, plus all other CPUs that have = the + same values for ``socket_id``, ``die_id`` and ``core_id``. + ``secmodel`` To find out default security labels for different security models you n= eed to parse this element. In contrast with the former elements, this is repea= ted diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 298ad46a45..73deaa5cb3 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -1578,14 +1578,18 @@ In case no restrictions need to be put on CPU model= and its features, a simpler supported vendors can be found in ``cpu_map/*_vendors.xml``. ``topology`` The ``topology`` element specifies requested topology of virtual CPU pr= ovided - to the guest. Four attributes, ``sockets``, ``dies``, ``cores``, and - ``threads``, accept non-zero positive integer values. They refer to the - total number of CPU sockets, number of dies per socket, number of cores= per - die, and number of threads per core, respectively. The ``dies`` attribu= te is - optional and will default to 1 if omitted, while the other attributes a= re all - mandatory. Hypervisors may require that the maximum number of vCPUs spe= cified + to the guest. + Its attributes ``sockets``, ``dies`` (:since:`Since 6.1.0`), ``cores``, + and ``threads`` accept non-zero positive integer values. + They refer to the total number of CPU sockets, number of dies per socke= t, + number of cores per die, and number of threads per core, respectively. + The ``dies`` attribute is optional and will default to 1 if omitted, wh= ile + the other attributes are all mandatory. + Hypervisors may require that the maximum number of vCPUs specified by the ``cpus`` element equals to the number of vcpus resulting from the topology. + Moreover, not all architectures and machine types support specifying a = value + other than 1 for all attributes. ``feature`` The ``cpu`` element can contain zero or more ``feature`` elements used = to fine-tune features provided by the selected CPU model. The list of known --=20 2.43.0 _______________________________________________ Devel mailing list -- devel@lists.libvirt.org To unsubscribe send an email to devel-leave@lists.libvirt.org