virNodeGetInfo: Improve description of the case when fake data is reported

virNodeGetInfo due to the rigid desing of the filled struct can't
faithfully represent all topologies. Improve the description when that
happens and outline the fallback topology.

The function docs already state that users ought to use
virConnectGetCapabilities() instead.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>

diff --git a/src/libvirt-host.c b/src/libvirt-host.c
index 9845549e36d0b281d839d16debddbb174cab8ef9..d82ff993c2dc64f11d90c1aebda1fd2754b7b695 100644 (file)
--- a/src/libvirt-host.c
+++ b/src/libvirt-host.c
@@ -414,10 +414,13 @@ virConnectGetMaxVcpus(virConnectPtr conn,
  * speed that the first CPU in the machine is currently running at. This speed
  * may vary across CPUs and changes continually as the host OS throttles.
  *
- * The nodes/sockets/cores/threads data is potentially inaccurate as
- * it assumes a symmetric installation. If one NUMA node has more
- * sockets populated that another NUMA node this information will be
- * wrong. It is also not able to report about CPU dies.
+ * The virNodeInfo structure is not extensible thus only supports global
+ * nodes/sockets/cores/threads (sockets/cores/threads is per NUMA node)
+ * topology information. If the host CPU has any further groupings (e.g.
+ * dies, clusters, etc) or the NUMA topology is non-symmetrical the structure
+ * can't faithfully represent the system. In such cases a fake topology
+ * (nodes = 1, sockets = 1, cores = number of host cpus, threads = 1) which
+ * only correctly represents the total host CPU count is reported.
  *
  * Applications are recommended to use the virConnectGetCapabilities()
  * call instead, which provides all the information except CPU frequency,