Improve the description for the KVM_CAP_X86_BUS_LOCK_EXIT capability,
fixing a few typos and improving grammar for overall clarity.
Signed-off-by: Carlos López <[email protected]>
---
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(-)
diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index 7025b3751027..4701370bf46f 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -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
----------------------
--
2.35.3
On Thu, Nov 16, 2023, Carlos López wrote:
> Improve the description for the KVM_CAP_X86_BUS_LOCK_EXIT capability,
> fixing a few typos and improving grammar for overall clarity.
>
> Signed-off-by: Carlos López <[email protected]>
> ---
> 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(-)
>
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 7025b3751027..4701370bf46f 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -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.
Meh, there's a lot of pointless boilerplate in here. These statements hold true
for almost every KVM capability.
> -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.
> -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
I liked the attempt to capture that this is a threat mitigation, although the
typo probably made that hard to see.
> +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.
> +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.
Improve the description for the KVM_CAP_X86_BUS_LOCK_EXIT capability,
fixing a few typos, grammarm and clarifying the purpose of the ioctl.
Signed-off-by: Carlos López <[email protected]>
---
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(-)
diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index 0b5a33ee71ee..a1d78e06a1ad 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -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
----------------------
--
2.35.3