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

@@ -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
+   This element describes the host CPU topology in detail.
-   want to learn this information when orchestrating new guests - e.g. due to
+
-   reduce inter-NUMA node transfers. Note that the ``sockets`` value reported
+   Management applications may want to use this information when defining new
-   here is per-NUMA-node; this is in contrast to the value given in domain
+   guests: for example, in order to ensure that all vCPUs are scheduled on
-   definitions, which is interpreted as a total number of sockets for the
+   CPUs that are in the same NUMA node or even CPU core.
-   domain.
+
+   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

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
+   to the guest.
-   ``threads``, accept non-zero positive integer values. They refer to the
+   Its attributes ``sockets``, ``dies`` (:since:`Since 6.1.0`), ``cores``,
-   total number of CPU sockets, number of dies per socket, number of cores per
+   and ``threads`` accept non-zero positive integer values.
-   die, and number of threads per core, respectively. The ``dies`` attribute is
+   They refer to the total number of CPU sockets, number of dies per socket,
-   optional and will default to 1 if omitted, while the other attributes are all
+   number of cores per die, and number of threads per core, respectively.
-   mandatory. Hypervisors may require that the maximum number of vCPUs specified
+   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