KVM: X86: improve documentation for KVM_CAP_X86_BUS_LOCK_EXIT
Subsystems (2)
PATCH v2 1/1 KVM: X86: improve documentation for KVM_CAP_X86_BUS_LOCK_EXIT
Improve the description for the KVM_CAP_X86_BUS_LOCK_EXIT capability, fixing a few typos and improving grammar for overall clarity.
---
v2: Corrected the name of the KVM_RUN_X86_BUS_LOCK flag
Documentation/virt/kvm/api.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-)
Documentation/virt/kvm/api.rst +14 -14
@@ -6256,9 +6256,9 @@ More architecture-specific flags detailing state of the VCPU that may affect the device's behavior. Current defined flags:: /* x86, set if the VCPU is in system management mode */ - #define KVM_RUN_X86_SMM (1 << 0) + #define KVM_RUN_X86_SMM (1 << 0) /* x86, set if bus lock detected in VM */ - #define KVM_RUN_BUS_LOCK (1 << 1) + #define KVM_RUN_X86_BUS_LOCK (1 << 1) /* arm64, set for KVM_EXIT_DEBUG */ #define KVM_DEBUG_ARCH_HSR_HIGH_VALID (1 << 0)
@@ -7582,20 +7582,20 @@ KVM_BUS_LOCK_DETECTION_OFF and KVM_BUS_LOCK_DETECTION_EXIT are supported currently and mutually exclusive with each other. More bits can be added in the future. -With KVM_BUS_LOCK_DETECTION_OFF set, bus locks in guest will not cause vm exits +With KVM_BUS_LOCK_DETECTION_OFF set, bus locks in guest will not cause VM exits so that no additional actions are needed. This is the default mode. -With KVM_BUS_LOCK_DETECTION_EXIT set, vm exits happen when bus lock detected -in VM. KVM just exits to userspace when handling them. Userspace can enforce -its own throttling or other policy based mitigations. - -This capability is aimed to address the thread that VM can exploit bus locks to -degree the performance of the whole system. Once the userspace enable this -capability and select the KVM_BUS_LOCK_DETECTION_EXIT mode, KVM will set the -KVM_RUN_BUS_LOCK flag in vcpu-run->flags field and exit to userspace. Concerning -the bus lock vm exit can be preempted by a higher priority VM exit, the exit -notifications to userspace can be KVM_EXIT_BUS_LOCK or other reasons. -KVM_RUN_BUS_LOCK flag is used to distinguish between them. +With KVM_BUS_LOCK_DETECTION_EXIT set, VM exits happen when a bus lock is +detected in VM. KVM just exits to userspace when handling them. Userspace can +enforce its own throttling or other policy based mitigations. + +This capability is aimed to address the fact that a VM can exploit bus locks to +impact the performance of the whole system. Once userspace enables this +capability and selects the KVM_BUS_LOCK_DETECTION_EXIT mode, KVM will set the +KVM_RUN_X86_BUS_LOCK flag in the vcpu->run->flags field and exit to userspace. +Concerning the bus lock, a VM exit can be preempted by a higher priority VM +exit, so the exit notification to userspace can be KVM_EXIT_BUS_LOCK or another +reason. KVM_RUN_X86_BUS_LOCK flag is used to distinguish between them. 7.23 KVM_CAP_PPC_DAWR1 ----------------------
Signature · 1 line
2.35.3
Sean Christopherson
reviewerQuoted 27 lines · Carlos López
Improve the description for the
KVM_CAP_X86_BUS_LOCK_EXITcapability, fixing a few typos and improving grammar for overall clarity.Signed-off-by Carlos López <[email protected]>---
v2: Corrected the name of theKVM_RUN_X86_BUS_LOCKflagDocumentation/virt/kvm/api.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-)Documentation/virt/kvm/api.rst +2
-2@@ -6256,9 +6256,9 @@ More architecture-specific flags detailing state of the VCPU that may affect the device's behavior. Current defined flags:: /* x86, set if the VCPU is in system management mode */ - #define KVM_RUN_X86_SMM (1 << 0) + #define KVM_RUN_X86_SMM (1 << 0) /* x86, set if bus lock detected in VM */ - #define KVM_RUN_BUS_LOCK (1 << 1) + #define KVM_RUN_X86_BUS_LOCK (1 << 1) /* arm64, set for KVM_EXIT_DEBUG */ #define KVM_DEBUG_ARCH_HSR_HIGH_VALID (1 << 0)
Documentation/virt/kvm/api.rst KVM_BUS_LOCK_DETECTION_OFF and KVM_BUS_LOCK_DETECTION_EXIT are supported · line 7583
Quoted 2 lines
Documentation/virt/kvm/api.rst +0
-0@@ -7582,20 +7582,20 @@ KVM_BUS_LOCK_DETECTION_OFF and KVM_BUS_LOCK_DETECTION_EXIT are supported currently and mutually exclusive with each other. More bits can be added in the future.
Meh, there's a lot of pointless boilerplate in here. These statements hold true for almost every KVM capability.
Documentation/virt/kvm/api.rst KVM_BUS_LOCK_DETECTION_OFF and KVM_BUS_LOCK_DETECTION_EXIT are supported · line 7586
Quoted 3 lines
Documentation/virt/kvm/api.rst +1
-1-With KVM_BUS_LOCK_DETECTION_OFF set, bus locks in guest will not cause vm exits +With KVM_BUS_LOCK_DETECTION_OFF set, bus locks in guest will not cause VM exits so that no additional actions are needed. This is the default mode.
Heh, this is technically wrong. KVM intercepts #AC when the non-virtualized split-lock detection is enabled, i.e. bus locks will cause VM-Exit, though they won't be forwarded to userspace.
Quoted 6 lines
Documentation/virt/kvm/api.rst +0
-6-With KVM_BUS_LOCK_DETECTION_EXIT set, vm exits happen when bus lock detected -in VM. KVM just exits to userspace when handling them. Userspace can enforce -its own throttling or other policy based mitigations. - -This capability is aimed to address the thread that VM can exploit bus locks to -degree the performance of the whole system. Once the userspace enable this
Documentation/virt/kvm/api.rst KVM_BUS_LOCK_DETECTION_OFF and KVM_BUS_LOCK_DETECTION_EXIT are supported · line 7592
Quoted 10 lines
Documentation/virt/kvm/api.rst +5
-5-capability and select the KVM_BUS_LOCK_DETECTION_EXIT mode, KVM will set the -KVM_RUN_BUS_LOCK flag in vcpu-run->flags field and exit to userspace. Concerning -the bus lock vm exit can be preempted by a higher priority VM exit, the exit -notifications to userspace can be KVM_EXIT_BUS_LOCK or other reasons. -KVM_RUN_BUS_LOCK flag is used to distinguish between them. +With KVM_BUS_LOCK_DETECTION_EXIT set, VM exits happen when a bus lock is +detected in VM. KVM just exits to userspace when handling them. Userspace can +enforce its own throttling or other policy based mitigations. + +This capability is aimed to address the fact that a VM can exploit bus locks to
I liked the attempt to capture that this is a threat mitigation, although the typo probably made that hard to see.
Documentation/virt/kvm/api.rst KVM_BUS_LOCK_DETECTION_OFF and KVM_BUS_LOCK_DETECTION_EXIT are supported · line 7595
Quoted 3 lines
Documentation/virt/kvm/api.rst +3
-0+impact the performance of the whole system. Once userspace enables this +capability and selects the KVM_BUS_LOCK_DETECTION_EXIT mode, KVM will set the +KVM_RUN_X86_BUS_LOCK flag in the vcpu->run->flags field and exit to userspace.
Oof, the existing wording is nonsensical. This reads like KVM unconditionally sets KVM_RUN_X86_BUS_LOCK whenever the capability is enabled.
Documentation/virt/kvm/api.rst KVM_BUS_LOCK_DETECTION_OFF and KVM_BUS_LOCK_DETECTION_EXIT are supported · line 7598
Quoted 3 lines
Documentation/virt/kvm/api.rst +3
-0+Concerning the bus lock, a VM exit can be preempted by a higher priority VM +exit, so the exit notification to userspace can be KVM_EXIT_BUS_LOCK or another +reason. KVM_RUN_X86_BUS_LOCK flag is used to distinguish between them.
This is also worded rather weirdly. It's not so much that VM exits can be preempted, it's that the CPU can detect a bus lock while also delivering an unrelated VM exit.
Something like this?
---
This capability allows userspace to force VM exits on bus locks detected in the guest, irrespective whether or not host has enabled split-lock detection (which triggers an #AC exception that KVM intercepts). This capability is intended to mitigate attacks where a malicious/buggy guest can exploit bus locks to degrade the performance of the whole system.
If bus lock detection is OFF, KVM doesn't force guest bus locks to VM exit, although the host kernel's split-lock #AC detection still applies, if enabled.
If bus lock detection is set to EXIT, KVM enables a CPU feature that ensures bus locks in the guest trigger a VM exit, and KVM exits to userspace for all such VM exits, e.g. to allow userspace to throttle the offending guest and/or apply some other policy-based mitigation. When exiting to userspace, KVM sets KVM_RUN_X86_BUS_LOCK in vcpu-run->flags, and conditionally sets the exit_reason to KVM_EXIT_X86_BUS_LOCK.
Note! Detected bus locks may be coincident with other exits to userspace, i.e. KVM_RUN_X86_BUS_LOCK should be checked regardless of the primary exit reason if userspace wants to take action on all detected bus locks.
PATCH v3 1/1 KVM: X86: improve documentation for KVM_CAP_X86_BUS_LOCK_EXIT
In reply to Carlos LópezImprove the description for the KVM_CAP_X86_BUS_LOCK_EXIT capability, fixing a few typos, grammarm and clarifying the purpose of the ioctl.
---
v3: Added Sean Christopherson's suggestions
v2: Corrected the name of the KVM_RUN_X86_BUS_LOCK flag
Documentation/virt/kvm/api.rst | 52 ++++++++++++++++++---------------- 1 file changed, 27 insertions(+), 25 deletions(-)
Documentation/virt/kvm/api.rst +27 -25
@@ -6416,9 +6416,9 @@ More architecture-specific flags detailing state of the VCPU that may affect the device's behavior. Current defined flags:: /* x86, set if the VCPU is in system management mode */ - #define KVM_RUN_X86_SMM (1 << 0) + #define KVM_RUN_X86_SMM (1 << 0) /* x86, set if bus lock detected in VM */ - #define KVM_RUN_BUS_LOCK (1 << 1) + #define KVM_RUN_X86_BUS_LOCK (1 << 1) /* arm64, set for KVM_EXIT_DEBUG */ #define KVM_DEBUG_ARCH_HSR_HIGH_VALID (1 << 0)
@@ -7757,29 +7757,31 @@ Valid bits in args[0] are:: #define KVM_BUS_LOCK_DETECTION_OFF (1 << 0) #define KVM_BUS_LOCK_DETECTION_EXIT (1 << 1) -Enabling this capability on a VM provides userspace with a way to select -a policy to handle the bus locks detected in guest. Userspace can obtain -the supported modes from the result of KVM_CHECK_EXTENSION and define it -through the KVM_ENABLE_CAP. - -KVM_BUS_LOCK_DETECTION_OFF and KVM_BUS_LOCK_DETECTION_EXIT are supported -currently and mutually exclusive with each other. More bits can be added in -the future. - -With KVM_BUS_LOCK_DETECTION_OFF set, bus locks in guest will not cause vm exits -so that no additional actions are needed. This is the default mode. - -With KVM_BUS_LOCK_DETECTION_EXIT set, vm exits happen when bus lock detected -in VM. KVM just exits to userspace when handling them. Userspace can enforce -its own throttling or other policy based mitigations. - -This capability is aimed to address the thread that VM can exploit bus locks to -degree the performance of the whole system. Once the userspace enable this -capability and select the KVM_BUS_LOCK_DETECTION_EXIT mode, KVM will set the -KVM_RUN_BUS_LOCK flag in vcpu-run->flags field and exit to userspace. Concerning -the bus lock vm exit can be preempted by a higher priority VM exit, the exit -notifications to userspace can be KVM_EXIT_BUS_LOCK or other reasons. -KVM_RUN_BUS_LOCK flag is used to distinguish between them. +Enabling this capability on a VM provides userspace with a way to select a +policy to handle the bus locks detected in guest. Userspace can obtain the +supported modes from the result of KVM_CHECK_EXTENSION and define it through +the KVM_ENABLE_CAP. The supported modes are mutually-exclusive. + +This capability allows userspace to force VM exits on bus locks detected in the +guest, irrespective whether or not the host has enabled split-lock detection +(which triggers an #AC exception that KVM intercepts). This capability is +intended to mitigate attacks where a malicious/buggy guest can exploit bus +locks to degrade the performance of the whole system. + +If KVM_BUS_LOCK_DETECTION_OFF is set, KVM doesn't force guest bus locks to VM +exit, although the host kernel's split-lock #AC detection still applies, if +enabled. + +If KVM_BUS_LOCK_DETECTION_EXIT is set, KVM enables a CPU feature that ensures +bus locks in the guest trigger a VM exit, and KVM exits to userspace for all +such VM exits, e.g. to allow userspace to throttle the offending guest and/or +apply some other policy-based mitigation. When exiting to userspace, KVM sets +KVM_RUN_X86_BUS_LOCK in vcpu-run->flags, and conditionally sets the exit_reason +to KVM_EXIT_X86_BUS_LOCK. + +Note! Detected bus locks may be coincident with other exits to userspace, i.e. +KVM_RUN_X86_BUS_LOCK should be checked regardless of the primary exit reason if +userspace wants to take action on all detected bus locks. 7.23 KVM_CAP_PPC_DAWR1 ----------------------
Signature · 1 line
2.35.3
Quoted 4 lines · Carlos López
Improve the description for the
KVM_CAP_X86_BUS_LOCK_EXITcapability, fixing a few typos, grammarm and clarifying the purpose of the ioctl.
Applied to kvm-x86 generic, thanks!
[1/1] KVM: X86: improve documentation for KVM_CAP_X86_BUS_LOCK_EXIT
https://github.com/kvm-x86/linux/commit/d3f673c86c5b
Sean Christopherson
reviewerQuoted 10 lines · Sean Christopherson
Quoted 4 lines · Carlos López
Improve the description for the
KVM_CAP_X86_BUS_LOCK_EXITcapability, fixing a few typos, grammarm and clarifying the purpose of the ioctl.Applied to kvm-x86 generic, thanks!
[1/1] KVM: X86: improve documentation for
KVM_CAP_X86_BUS_LOCK_EXIThttps://github.com/kvm-x86/linux/commit/d3f673c86c5b
FYI, I moved this to kvm-x86 misc to avoid a merge conflict down the road.
[1/1] KVM: x86: Improve documentation for KVM_CAP_X86_BUS_LOCK_EXIT
https://github.com/kvm-x86/linux/commit/508f0c7bf6d5