fix documentation for sockets topology

In 0895a0e, it was noted that the "sockets" value in the topology
section of capabilities reflects not the number of sockets per NUMA
node, not the total number.

Unfortunately, the fix was applied to the wrong place: the domain XML
format documentation, not that for the capabilities output. And, in
fact, the domain XML interprets "sockets" as the total number, not a
per-node value.

Back out this change in favour of a note in the capabilities
documentation instead.

Fixes: 0895a0e75d13874254218e16dc66dcad673671d3
Suggested-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: John Levon <john.levon@nutanix.com>

diff --git a/docs/formatcaps.html.in b/docs/formatcaps.html.in
index 09662f78c8f9f252524cfd7038bce9ddf8d228e0..a4abad5d209fc5dcee196adbce11b4cfe84fff57 100644 (file)
--- a/docs/formatcaps.html.in
+++ b/docs/formatcaps.html.in
@@ -51,7 +51,10 @@
       <dt><code>topology</code></dt>
       <dd>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.</dd>
+      guests - e.g. due to reduce inter-NUMA node transfers. Note that the
+      <code>sockets</code> 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.</dd>
 
       <dt><code>secmodel</code></dt>
       <dd>To find out default security labels for different security models you

diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index e4925320047fe6a7b6ebf0c2b572f74cfffda659..9652e97eecbd9126d3445b0a7873f341fed248d9 100644 (file)
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -1489,12 +1489,12 @@ In case no restrictions need to be put on CPU model and its features, a simpler
    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
-   number of CPU sockets per NUMA node, 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.
+   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.
 ``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