[PATCH v2 2/2] KVM: x86: update documentation for MSR filtering

[Aaron Lewis <aaronlewis@google.com>]

Update the documentation to ensure best practices are used by VMM
developers when using KVM_X86_SET_MSR_FILTER and
KVM_CAP_X86_USER_SPACE_MSR.

Signed-off-by: Aaron Lewis <aaronlewis@google.com>
---
 Documentation/virt/kvm/api.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index 5c651a4e4e2c..bd7d081e960f 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -4178,7 +4178,14 @@ KVM does guarantee that vCPUs will see either the previous filter or the new
 filter, e.g. MSRs with identical settings in both the old and new filter will
 have deterministic behavior.
 
+When using filtering for the purpose of deflecting MSR accesses to userspace,
+exiting[1] **must** be enabled for the lifetime of filtering.  That is to say,
+exiting needs to be enabled before filtering is enabled, and exiting needs to
+remain enabled until after filtering has been disabled.  Doing so avoids the
+case where when an MSR access is filtered, instead of deflecting it to
+userspace as intended a #GP is injected in the guest.
 
+[1] KVM_CAP_X86_USER_SPACE_MSR set with exit reason KVM_MSR_EXIT_REASON_FILTER.
 
 4.98 KVM_CREATE_SPAPR_TCE_64
 ----------------------------
@@ -7191,6 +7198,16 @@ KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR exit notifications which user space
 can then handle to implement model specific MSR handling and/or user notifications
 to inform a user that an MSR was not handled.
 
+When using filtering[1] for the purpose of deflecting MSR accesses to
+userspace, exiting[2] **must** be enabled for the lifetime of filtering.  That
+is to say, exiting needs to be enabled before filtering is enabled, and exiting
+needs to remain enabled until after filtering has been disabled.  Doing so
+avoids the case where when an MSR access is filtered, instead of deflecting it
+to userspace as intended a #GP is injected in the guest.
+
+[1] Using KVM_X86_SET_MSR_FILTER
+[2] KVM_CAP_X86_USER_SPACE_MSR set with exit reason KVM_MSR_EXIT_REASON_FILTER.
+
 7.22 KVM_CAP_X86_BUS_LOCK_EXIT
 -------------------------------
 
-- 
2.37.0.144.g8ac04bfd2-goog