diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index aae5e9c071..b1e38f00e4 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -1401,7 +1401,10 @@
virtual CPU provided to the guest. Three non-zero values have to be
given for sockets
, cores
, and
threads
: total number of CPU sockets, number of cores per
- socket, and number of threads per core, respectively.
+ socket, and number of threads per core, respectively. 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
cpu
element can contain zero or more
diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index 4670c54e5e..310b91b373 100644
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -7010,7 +7010,8 @@ virDomainSetVcpus(virDomainPtr domain, unsigned int nvcpus)
* CPU limit is altered; generally, this value must be less than or
* equal to virConnectGetMaxVcpus(). Otherwise, this call affects the
* current virtual CPU limit, which must be less than or equal to the
- * maximum limit.
+ * maximum limit. Note that hypervisors may not allow changing the maximum
+ * vcpu count if processor topology is specified.
*
* If @flags includes VIR_DOMAIN_VCPU_GUEST, then the state of processors is
* modified inside the guest instead of the hypervisor. This flag can only
diff --git a/tools/virsh.pod b/tools/virsh.pod
index 9a52d67163..d1030808a3 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -2477,7 +2477,8 @@ marked as hotpluggable.
The I<--maximum> flag controls the maximum number of virtual cpus that can
be hot-plugged the next time the domain is booted. As such, it must only be
used with the I<--config> flag, and not with the I<--live> or the I<--current>
-flag.
+flag. Note that it may not be possible to change the maximum vcpu count if
+the processor topology is specified for the guest.
=item B