Explicitly document the ordering of vcpu->mutex being taken *outside* of
kvm->slots_lock.  While extremely unintuitive, and arguably wrong, both
arm64 and x86 have gained flows that take kvm->slots_lock inside of
vcpu->mutex.  x86's kvm_inhibit_apic_access_page() is particularly
nasty, as slots_lock is taken quite deep within KVM_RUN, i.e. simply
swapping the ordering isn't an option.

Commit to the vcpu->mutex => kvm->slots_lock ordering even though taking a
VM-scoped lock inside a vCPU-scoped lock is odd, as vcpu->mutex really is
intended to be a "top-level" lock in most respects, whereas kvm->slots_lock
is "just" a helper lock.

Cc: Oliver Upton <oliver.upton@linux.dev>
Cc: Marc Zyngier <maz@kernel.org>
Signed-off-by: Sean Christopherson <seanjc@google.com>
---
 Documentation/virt/kvm/locking.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/locking.rst
index ae8bce7fecbe..2b4c786038be 100644
--- a/Documentation/virt/kvm/locking.rst
+++ b/Documentation/virt/kvm/locking.rst
@@ -17,6 +17,8 @@ The acquisition orders for mutexes are as follows:
 
 - kvm->lock is taken outside kvm->slots_lock and kvm->irq_lock
 
+- vcpu->mutex is taken outside kvm->slots_lock
+
 - kvm->slots_lock is taken outside kvm->irq_lock, though acquiring
   them together is quite rare.
 

base-commit: 6b36119b94d0b2bb8cea9d512017efafd461d6ac
-- 
2.51.0.858.gf9c4a03a3a-goog

On Thu, 16 Oct 2025 16:55:38 -0700, Sean Christopherson wrote:
> Explicitly document the ordering of vcpu->mutex being taken *outside* of
> kvm->slots_lock.  While extremely unintuitive, and arguably wrong, both
> arm64 and x86 have gained flows that take kvm->slots_lock inside of
> vcpu->mutex.  x86's kvm_inhibit_apic_access_page() is particularly
> nasty, as slots_lock is taken quite deep within KVM_RUN, i.e. simply
> swapping the ordering isn't an option.
> 
> [...]

Applied to kvm-x86 generic, thanks!

[1/1] Documentation: KVM: Formalizing taking vcpu->mutex *outside* of kvm->slots_lock
      https://github.com/kvm-x86/linux/commit/98333091750d

--
https://github.com/kvm-x86/linux/tree/next