Clarify documentation of virConnectBaselineHypervisorCPU

The API was apparently never considered for being used on a host that is
not represented in the input set of CPU definitions. The result is
limited to the set of features and CPU models known to the host's
hypervisor. This would likely not be a big issue, but thanks to a side
effect of commit v3.8.0-99-g9c9620af1d usability blockers come to play
as well. When converting CPU data (CPUID and MSR bits) to each named
model for comparison, we disable features that block usability of the
model on the current hypervisor, the rest of the features are set
according to the data without taking host capabilities into account.
Thus the process of comparing and selecting the most appropriate CPU
model for the given data is significantly influenced by the host, but it
doesn't behave as if the host CPU model was included in the input data.

The documentation tried to say the result was tied to the host's
hypervisor, but it wasn't very clear.

Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>

diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst
index e13b5020b56db1d996962ac1206559cf23b0b4a6..7082ca773aedaebfece44d609b622198a2d1cea0 100644 (file)
--- a/docs/manpages/virsh.rst
+++ b/docs/manpages/virsh.rst
@@ -1015,9 +1015,14 @@ hypervisor-cpu-baseline
       [--features] [--migratable] [model]
 
 Compute a baseline CPU which will be compatible with all CPUs defined in an XML
-*file* and with the CPU the hypervisor is able to provide on the host. (This
-is different from ``cpu-baseline`` which does not consider any hypervisor
-abilities when computing the baseline CPU.)
+*FILE*. This command must be called on one of the hosts described in *FILE*.
+Calling it on another host results in an undefined behavior as the computed CPU
+model is influenced by the hypervisor (the result may use an unexpected CPU
+model or some features may disabled even though they are supported on all input
+CPUs).
+
+This is different from ``cpu-baseline`` which does not consider any hypervisor
+abilities when computing the baseline CPU.
 
 As an alternative for *FILE* in case the XML would only contain a CPU model
 with no additional features the CPU model name itself can be passed as *model*.

diff --git a/src/libvirt-host.c b/src/libvirt-host.c
index d82ff993c2dc64f11d90c1aebda1fd2754b7b695..8d2107fd62ee640c353d84242d03b2591b5d7f8b 100644 (file)
--- a/src/libvirt-host.c
+++ b/src/libvirt-host.c
@@ -1300,24 +1300,30 @@ virConnectBaselineCPU(virConnectPtr conn,
  * @ncpus: number of CPUs in xmlCPUs
  * @flags: bitwise-OR of virConnectBaselineCPUFlags
  *
- * Computes the most feature-rich CPU which is compatible with all given CPUs
- * and can be provided by the specified hypervisor. For best results the
- * host-model CPUs as advertised by virConnectGetDomainCapabilities() should be
- * passed in @xmlCPUs. Any of @emulator, @arch, @machine, and @virttype
- * parameters may be NULL; libvirt will choose sensible defaults tailored to
- * the host and its current configuration.
+ * Computes the most feature-rich CPU which is compatible with all given CPUs.
+ * This API must be called on one of the hosts specified in @xmlCPUs. Calling
+ * it on another host results in an undefined behavior as the computed CPU
+ * model is influenced by the hypervisor (the result may use an unexpected CPU
+ * model or some features may disabled even though they are supported on all
+ * input CPUs).
  *
  * This is different from virConnectBaselineCPU() which doesn't consider any
  * hypervisor abilities when computing the best CPU.
  *
+ * The @xmlCPUs array should contain guest CPU definitions created from the
+ * host CPU model description as advertised by virConnectGetDomainCapabilities()
+ * in <mode name="host-model"> element. Any of @emulator, @arch, @machine, and
+ * @virttype parameters may be NULL; libvirt will choose sensible defaults
+ * tailored to the host and its current configuration.
+ *
  * If @ncpus == 1, the result will be the first (and only) CPU in @xmlCPUs
  * tailored to what the hypervisor can support on the current host.
  * Specifically if this single CPU definition contains no feature elements and
  * a CPU model listed as usable='no' in domain capabilities XML, the result
  * will contain a list usability blockers, i.e., a list of features that would
- * need to be disabled to for the model to be usable on this host. This list
- * may contain more features than what the hypervisor reports as blockers in
- * case the CPU model definition in libvirt differs from QEMU definition.
+ * need to be disabled for the model to be usable on this host. This list may
+ * contain more features than what the hypervisor reports as blockers in case
+ * the CPU model definition in libvirt differs from QEMU definition.
  *
  * If @flags includes VIR_CONNECT_BASELINE_CPU_EXPAND_FEATURES then libvirt
  * will explicitly list all CPU features that are part of the computed CPU,