iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

KVM: x86: Clean up KVM_CAP_X86_USER_SPACE_MSR documentation

Browse Source 
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: Sean Christopherson <seanjc@google.com>
Link: https://lore.kernel.org/r/20220831001706.4075399-4-seanjc@google.com
This commit is contained in:
Sean Christopherson 2022-08-31 00:17:06 +00:00
parent b93d2ec34e
commit 1f15814718
1 changed files with 24 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
Documentation/virt/kvm/api.rst
View File

@ -6473,29 +6473,29 @@ if it decides to decode and emulate the instruction.
Used on x86 systems. When the VM capability KVM_CAP_X86_USER_SPACE_MSR is 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 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. exit for writes.
The "reason" field specifies why the MSR trap occurred. User space will only The "reason" field specifies why the MSR interception occurred. Userspace will
receive MSR exit traps when a particular reason was requested during through only receive MSR exits when a particular reason was requested during through
ENABLE_CAP. Currently valid exit reasons are: ENABLE_CAP. Currently valid exit reasons are:
KVM_MSR_EXIT_REASON_UNKNOWN - access to MSR that is unknown to KVM KVM_MSR_EXIT_REASON_UNKNOWN - access to MSR that is unknown to KVM
KVM_MSR_EXIT_REASON_INVAL - access to invalid MSRs or reserved bits KVM_MSR_EXIT_REASON_INVAL - access to invalid MSRs or reserved bits
KVM_MSR_EXIT_REASON_FILTER - access blocked by KVM_X86_SET_MSR_FILTER KVM_MSR_EXIT_REASON_FILTER - access blocked by KVM_X86_SET_MSR_FILTER
For KVM_EXIT_X86_RDMSR, the "index" field tells user space which MSR the guest For KVM_EXIT_X86_RDMSR, the "index" field tells userspace which MSR the guest
wants to read. To respond to this request with a successful read, user space wants to read. To respond to this request with a successful read, userspace
writes the respective data into the "data" field and must continue guest writes the respective data into the "data" field and must continue guest
execution to ensure the read data is transferred into guest register state. execution to ensure the read data is transferred into guest register state.
If the RDMSR request was unsuccessful, user space indicates that with a "1" in If the RDMSR request was unsuccessful, userspace indicates that with a "1" in
the "error" field. This will inject a #GP into the guest when the VCPU is the "error" field. This will inject a #GP into the guest when the VCPU is
executed again. executed again.
For KVM_EXIT_X86_WRMSR, the "index" field tells user space which MSR the guest For KVM_EXIT_X86_WRMSR, the "index" field tells userspace which MSR the guest
wants to write. Once finished processing the event, user space must continue wants to write. Once finished processing the event, userspace must continue
vCPU execution. If the MSR write was unsuccessful, user space also sets the vCPU execution. If the MSR write was unsuccessful, userspace also sets the
"error" field to "1". "error" field to "1".
See KVM_X86_SET_MSR_FILTER for details on the interaction with MSR filtering. See KVM_X86_SET_MSR_FILTER for details on the interaction with MSR filtering.
@ -7265,19 +7265,27 @@ the module parameter for the target VM.
:Parameters: args[0] contains the mask of KVM_MSR_EXIT_REASON_* events to report :Parameters: args[0] contains the mask of KVM_MSR_EXIT_REASON_* events to report
:Returns: 0 on success; -1 on error :Returns: 0 on success; -1 on error
This capability enables trapping of #GP invoking RDMSR and WRMSR instructions This capability allows userspace to intercept RDMSR and WRMSR instructions if
into user space. 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 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 that are relevant to a respective system. It also does not differentiate by
CPU type. CPU type.
To allow more fine grained control over MSR handling, user space may enable 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 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 args[0] and would trigger a #GP inside the guest will instead trigger
KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR exit notifications which user space KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR exit notifications. Userspace
can then handle to implement model specific MSR handling and/or user notifications can then implement model specific MSR handling and/or user notifications
to inform a user that an MSR was not handled. 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 7.22 KVM_CAP_X86_BUS_LOCK_EXIT
------------------------------- -------------------------------