On Thu, Jan 11, 2024 at 15:26:41 +0100, Andrea Bolognani wrote:
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 <abologna(a)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
[....]
@@ -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``.
IIRC the bit about 'core_id' is not true, at least for some older AMD
cpus which had two fixed point units (each having it's own core id)
sharing a FPU and some other less-used modules.
That was a long time ago though, but the distinction was that the lowest
level cache was shared at this level (again IIRC)
See commit 828820e2d371205d6a6061301165d58a1a92e611 ; the 'bulldozer'
example.
``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 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 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 toa
I'm not sure what to do with the siblings thing, but the rest:
Reviewed-by: Peter Krempa <pkrempa(a)redhat.com>