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 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 to
    fine-tune features provided by the selected CPU model. The list of known