From 35d7f3c8b34744d8430eb9487a106e3a98f372e4 Mon Sep 17 00:00:00 2001
From: Andrea Bolognani <abologna@redhat.com>
Date: Mon, 8 Jan 2024 16:13:25 +0100
Subject: [PATCH] docs: Improve documentation for CPU topology

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
architecture 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 <abologna@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
---
 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 ``<host/>`` 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 ``<host/>`` element consists of the following child elements:
    This element exposes information on the hypervisor's migration capabilities,
    like live migration, supported URI transports, and so on.
 ``topology``
-   This element embodies the host internal topology. Management applications may
-   want to learn this information when orchestrating new guests - e.g. due to
-   reduce inter-NUMA node transfers. Note that the ``sockets`` value reported
-   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 ``cpus``
+   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 <formatdomain.html#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 need to
    parse this element. In contrast with the former elements, this is repeated
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index 310d2bc427..366918b32c 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 provided
-   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`` attribute is
-   optional and will default to 1 if omitted, while the other attributes are all
-   mandatory. Hypervisors may require that the maximum number of vCPUs specified
+   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 socket,
+   number of cores per die, and number of threads per core, respectively.
+   The ``dies`` attribute is optional and will default to 1 if omitted, while
+   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
-- 
2.27.0