Commit 1f158147 authored by Sean Christopherson's avatar Sean Christopherson
Browse files

KVM: x86: Clean up KVM_CAP_X86_USER_SPACE_MSR documentation 



Clean up the KVM_CAP_X86_USER_SPACE_MSR documentation to eliminate
misleading and/or inconsistent verbiage, and to actually document what
accesses are intercepted by which flags.

  - s/will/may since not all #GPs are guaranteed to be intercepted
  - s/deflect/intercept to align with common KVM terminology
  - s/user space/userspace to align with the majority of KVM docs
  - Avoid using "trap" terminology, as KVM exits to userspace _before_
    stepping, i.e. doesn't exhibit trap-like behavior
  - Actually document the flags

Signed-off-by: default avatarSean Christopherson <seanjc@google.com>
Link: https://lore.kernel.org/r/20220831001706.4075399-4-seanjc@google.com
parent b93d2ec3

Documentation/virt/kvm/api.rst

+24 −16
Original line number Diff line number Diff line
@@ -6473,11 +6473,11 @@ if it decides to decode and emulate the instruction. 


Used on x86 systems. When the VM capability KVM_CAP_X86_USER_SPACE_MSR is

enabled, MSR accesses to registers that would invoke a #GP by KVM kernel code

will instead trigger a KVM_EXIT_X86_RDMSR exit for reads and KVM_EXIT_X86_WRMSR

may instead trigger a KVM_EXIT_X86_RDMSR exit for reads and KVM_EXIT_X86_WRMSR

exit for writes.



The "reason" field specifies why the MSR trap occurred. User space will only

receive MSR exit traps when a particular reason was requested during through

The "reason" field specifies why the MSR interception occurred. Userspace will

only receive MSR exits when a particular reason was requested during through

ENABLE_CAP. Currently valid exit reasons are:



	KVM_MSR_EXIT_REASON_UNKNOWN - access to MSR that is unknown to KVM
@@ -7265,8 +7265,8 @@ the module parameter for the target VM. 
:Parameters: args[0] contains the mask of KVM_MSR_EXIT_REASON_* events to report

:Returns: 0 on success; -1 on error



This capability enables trapping of #GP invoking RDMSR and WRMSR instructions

into user space.

This capability allows userspace to intercept RDMSR and WRMSR instructions if

access to an MSR is denied.  By default, KVM injects #GP on denied accesses.



When a guest requests to read or write an MSR, KVM may not implement all MSRs

that are relevant to a respective system. It also does not differentiate by
@@ -7274,10 +7274,18 @@ CPU type. 


To allow more fine grained control over MSR handling, userspace may enable

this capability. With it enabled, MSR accesses that match the mask specified in

args[0] and trigger a #GP event inside the guest by KVM will instead trigger

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.

args[0] and would trigger a #GP inside the guest will instead trigger

KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR exit notifications.  Userspace

can then implement model specific MSR handling and/or user notifications

to inform a user that an MSR was not emulated/virtualized by KVM.



The valid mask flags are:



	KVM_MSR_EXIT_REASON_UNKNOWN - intercept accesses to unknown (to KVM) MSRs

	KVM_MSR_EXIT_REASON_INVAL   - intercept accesses that are architecturally

                                invalid according to the vCPU model and/or mode

	KVM_MSR_EXIT_REASON_FILTER  - intercept accesses that are denied by userspace

                                via KVM_X86_SET_MSR_FILTER



7.22 KVM_CAP_X86_BUS_LOCK_EXIT

-------------------------------