docs: virt: Convert msr.txt to ReST format
- Use document title markup; - Convert tables; - Add blank lines and adjust indentation. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
This commit is contained in:
parent
2756df60d0
commit
263a19ff21
|
@ -10,6 +10,7 @@ KVM
|
||||||
amd-memory-encryption
|
amd-memory-encryption
|
||||||
cpuid
|
cpuid
|
||||||
halt-polling
|
halt-polling
|
||||||
|
msr
|
||||||
vcpu-requests
|
vcpu-requests
|
||||||
|
|
||||||
arm/index
|
arm/index
|
||||||
|
|
|
@ -1,6 +1,10 @@
|
||||||
KVM-specific MSRs.
|
.. SPDX-License-Identifier: GPL-2.0
|
||||||
Glauber Costa <glommer@redhat.com>, Red Hat Inc, 2010
|
|
||||||
=====================================================
|
=================
|
||||||
|
KVM-specific MSRs
|
||||||
|
=================
|
||||||
|
|
||||||
|
:Author: Glauber Costa <glommer@redhat.com>, Red Hat Inc, 2010
|
||||||
|
|
||||||
KVM makes use of some custom MSRs to service some requests.
|
KVM makes use of some custom MSRs to service some requests.
|
||||||
|
|
||||||
|
@ -9,34 +13,39 @@ Custom MSRs have a range reserved for them, that goes from
|
||||||
but they are deprecated and their use is discouraged.
|
but they are deprecated and their use is discouraged.
|
||||||
|
|
||||||
Custom MSR list
|
Custom MSR list
|
||||||
--------
|
---------------
|
||||||
|
|
||||||
The current supported Custom MSR list is:
|
The current supported Custom MSR list is:
|
||||||
|
|
||||||
MSR_KVM_WALL_CLOCK_NEW: 0x4b564d00
|
MSR_KVM_WALL_CLOCK_NEW:
|
||||||
|
0x4b564d00
|
||||||
|
|
||||||
data: 4-byte alignment physical address of a memory area which must be
|
data:
|
||||||
|
4-byte alignment physical address of a memory area which must be
|
||||||
in guest RAM. This memory is expected to hold a copy of the following
|
in guest RAM. This memory is expected to hold a copy of the following
|
||||||
structure:
|
structure::
|
||||||
|
|
||||||
struct pvclock_wall_clock {
|
struct pvclock_wall_clock {
|
||||||
u32 version;
|
u32 version;
|
||||||
u32 sec;
|
u32 sec;
|
||||||
u32 nsec;
|
u32 nsec;
|
||||||
} __attribute__((__packed__));
|
} __attribute__((__packed__));
|
||||||
|
|
||||||
whose data will be filled in by the hypervisor. The hypervisor is only
|
whose data will be filled in by the hypervisor. The hypervisor is only
|
||||||
guaranteed to update this data at the moment of MSR write.
|
guaranteed to update this data at the moment of MSR write.
|
||||||
Users that want to reliably query this information more than once have
|
Users that want to reliably query this information more than once have
|
||||||
to write more than once to this MSR. Fields have the following meanings:
|
to write more than once to this MSR. Fields have the following meanings:
|
||||||
|
|
||||||
version: guest has to check version before and after grabbing
|
version:
|
||||||
|
guest has to check version before and after grabbing
|
||||||
time information and check that they are both equal and even.
|
time information and check that they are both equal and even.
|
||||||
An odd version indicates an in-progress update.
|
An odd version indicates an in-progress update.
|
||||||
|
|
||||||
sec: number of seconds for wallclock at time of boot.
|
sec:
|
||||||
|
number of seconds for wallclock at time of boot.
|
||||||
|
|
||||||
nsec: number of nanoseconds for wallclock at time of boot.
|
nsec:
|
||||||
|
number of nanoseconds for wallclock at time of boot.
|
||||||
|
|
||||||
In order to get the current wallclock time, the system_time from
|
In order to get the current wallclock time, the system_time from
|
||||||
MSR_KVM_SYSTEM_TIME_NEW needs to be added.
|
MSR_KVM_SYSTEM_TIME_NEW needs to be added.
|
||||||
|
@ -47,13 +56,15 @@ MSR_KVM_WALL_CLOCK_NEW: 0x4b564d00
|
||||||
Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid
|
Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid
|
||||||
leaf prior to usage.
|
leaf prior to usage.
|
||||||
|
|
||||||
MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01
|
MSR_KVM_SYSTEM_TIME_NEW:
|
||||||
|
0x4b564d01
|
||||||
|
|
||||||
data: 4-byte aligned physical address of a memory area which must be in
|
data:
|
||||||
|
4-byte aligned physical address of a memory area which must be in
|
||||||
guest RAM, plus an enable bit in bit 0. This memory is expected to hold
|
guest RAM, plus an enable bit in bit 0. This memory is expected to hold
|
||||||
a copy of the following structure:
|
a copy of the following structure::
|
||||||
|
|
||||||
struct pvclock_vcpu_time_info {
|
struct pvclock_vcpu_time_info {
|
||||||
u32 version;
|
u32 version;
|
||||||
u32 pad0;
|
u32 pad0;
|
||||||
u64 tsc_timestamp;
|
u64 tsc_timestamp;
|
||||||
|
@ -62,7 +73,7 @@ MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01
|
||||||
s8 tsc_shift;
|
s8 tsc_shift;
|
||||||
u8 flags;
|
u8 flags;
|
||||||
u8 pad[2];
|
u8 pad[2];
|
||||||
} __attribute__((__packed__)); /* 32 bytes */
|
} __attribute__((__packed__)); /* 32 bytes */
|
||||||
|
|
||||||
whose data will be filled in by the hypervisor periodically. Only one
|
whose data will be filled in by the hypervisor periodically. Only one
|
||||||
write, or registration, is needed for each VCPU. The interval between
|
write, or registration, is needed for each VCPU. The interval between
|
||||||
|
@ -72,23 +83,28 @@ MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01
|
||||||
|
|
||||||
Fields have the following meanings:
|
Fields have the following meanings:
|
||||||
|
|
||||||
version: guest has to check version before and after grabbing
|
version:
|
||||||
|
guest has to check version before and after grabbing
|
||||||
time information and check that they are both equal and even.
|
time information and check that they are both equal and even.
|
||||||
An odd version indicates an in-progress update.
|
An odd version indicates an in-progress update.
|
||||||
|
|
||||||
tsc_timestamp: the tsc value at the current VCPU at the time
|
tsc_timestamp:
|
||||||
|
the tsc value at the current VCPU at the time
|
||||||
of the update of this structure. Guests can subtract this value
|
of the update of this structure. Guests can subtract this value
|
||||||
from current tsc to derive a notion of elapsed time since the
|
from current tsc to derive a notion of elapsed time since the
|
||||||
structure update.
|
structure update.
|
||||||
|
|
||||||
system_time: a host notion of monotonic time, including sleep
|
system_time:
|
||||||
|
a host notion of monotonic time, including sleep
|
||||||
time at the time this structure was last updated. Unit is
|
time at the time this structure was last updated. Unit is
|
||||||
nanoseconds.
|
nanoseconds.
|
||||||
|
|
||||||
tsc_to_system_mul: multiplier to be used when converting
|
tsc_to_system_mul:
|
||||||
|
multiplier to be used when converting
|
||||||
tsc-related quantity to nanoseconds
|
tsc-related quantity to nanoseconds
|
||||||
|
|
||||||
tsc_shift: shift to be used when converting tsc-related
|
tsc_shift:
|
||||||
|
shift to be used when converting tsc-related
|
||||||
quantity to nanoseconds. This shift will ensure that
|
quantity to nanoseconds. This shift will ensure that
|
||||||
multiplication with tsc_to_system_mul does not overflow.
|
multiplication with tsc_to_system_mul does not overflow.
|
||||||
A positive value denotes a left shift, a negative value
|
A positive value denotes a left shift, a negative value
|
||||||
|
@ -96,7 +112,7 @@ MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01
|
||||||
|
|
||||||
The conversion from tsc to nanoseconds involves an additional
|
The conversion from tsc to nanoseconds involves an additional
|
||||||
right shift by 32 bits. With this information, guests can
|
right shift by 32 bits. With this information, guests can
|
||||||
derive per-CPU time by doing:
|
derive per-CPU time by doing::
|
||||||
|
|
||||||
time = (current_tsc - tsc_timestamp)
|
time = (current_tsc - tsc_timestamp)
|
||||||
if (tsc_shift >= 0)
|
if (tsc_shift >= 0)
|
||||||
|
@ -106,29 +122,34 @@ MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01
|
||||||
time = (time * tsc_to_system_mul) >> 32
|
time = (time * tsc_to_system_mul) >> 32
|
||||||
time = time + system_time
|
time = time + system_time
|
||||||
|
|
||||||
flags: bits in this field indicate extended capabilities
|
flags:
|
||||||
|
bits in this field indicate extended capabilities
|
||||||
coordinated between the guest and the hypervisor. Availability
|
coordinated between the guest and the hypervisor. Availability
|
||||||
of specific flags has to be checked in 0x40000001 cpuid leaf.
|
of specific flags has to be checked in 0x40000001 cpuid leaf.
|
||||||
Current flags are:
|
Current flags are:
|
||||||
|
|
||||||
flag bit | cpuid bit | meaning
|
|
||||||
-------------------------------------------------------------
|
+-----------+--------------+----------------------------------+
|
||||||
| | time measures taken across
|
| flag bit | cpuid bit | meaning |
|
||||||
0 | 24 | multiple cpus are guaranteed to
|
+-----------+--------------+----------------------------------+
|
||||||
| | be monotonic
|
| | | time measures taken across |
|
||||||
-------------------------------------------------------------
|
| 0 | 24 | multiple cpus are guaranteed to |
|
||||||
| | guest vcpu has been paused by
|
| | | be monotonic |
|
||||||
1 | N/A | the host
|
+-----------+--------------+----------------------------------+
|
||||||
| | See 4.70 in api.txt
|
| | | guest vcpu has been paused by |
|
||||||
-------------------------------------------------------------
|
| 1 | N/A | the host |
|
||||||
|
| | | See 4.70 in api.txt |
|
||||||
|
+-----------+--------------+----------------------------------+
|
||||||
|
|
||||||
Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid
|
Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid
|
||||||
leaf prior to usage.
|
leaf prior to usage.
|
||||||
|
|
||||||
|
|
||||||
MSR_KVM_WALL_CLOCK: 0x11
|
MSR_KVM_WALL_CLOCK:
|
||||||
|
0x11
|
||||||
|
|
||||||
data and functioning: same as MSR_KVM_WALL_CLOCK_NEW. Use that instead.
|
data and functioning:
|
||||||
|
same as MSR_KVM_WALL_CLOCK_NEW. Use that instead.
|
||||||
|
|
||||||
This MSR falls outside the reserved KVM range and may be removed in the
|
This MSR falls outside the reserved KVM range and may be removed in the
|
||||||
future. Its usage is deprecated.
|
future. Its usage is deprecated.
|
||||||
|
@ -136,9 +157,11 @@ MSR_KVM_WALL_CLOCK: 0x11
|
||||||
Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid
|
Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid
|
||||||
leaf prior to usage.
|
leaf prior to usage.
|
||||||
|
|
||||||
MSR_KVM_SYSTEM_TIME: 0x12
|
MSR_KVM_SYSTEM_TIME:
|
||||||
|
0x12
|
||||||
|
|
||||||
data and functioning: same as MSR_KVM_SYSTEM_TIME_NEW. Use that instead.
|
data and functioning:
|
||||||
|
same as MSR_KVM_SYSTEM_TIME_NEW. Use that instead.
|
||||||
|
|
||||||
This MSR falls outside the reserved KVM range and may be removed in the
|
This MSR falls outside the reserved KVM range and may be removed in the
|
||||||
future. Its usage is deprecated.
|
future. Its usage is deprecated.
|
||||||
|
@ -146,7 +169,7 @@ MSR_KVM_SYSTEM_TIME: 0x12
|
||||||
Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid
|
Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid
|
||||||
leaf prior to usage.
|
leaf prior to usage.
|
||||||
|
|
||||||
The suggested algorithm for detecting kvmclock presence is then:
|
The suggested algorithm for detecting kvmclock presence is then::
|
||||||
|
|
||||||
if (!kvm_para_available()) /* refer to cpuid.txt */
|
if (!kvm_para_available()) /* refer to cpuid.txt */
|
||||||
return NON_PRESENT;
|
return NON_PRESENT;
|
||||||
|
@ -163,8 +186,11 @@ MSR_KVM_SYSTEM_TIME: 0x12
|
||||||
} else
|
} else
|
||||||
return NON_PRESENT;
|
return NON_PRESENT;
|
||||||
|
|
||||||
MSR_KVM_ASYNC_PF_EN: 0x4b564d02
|
MSR_KVM_ASYNC_PF_EN:
|
||||||
data: Bits 63-6 hold 64-byte aligned physical address of a
|
0x4b564d02
|
||||||
|
|
||||||
|
data:
|
||||||
|
Bits 63-6 hold 64-byte aligned physical address of a
|
||||||
64 byte memory area which must be in guest RAM and must be
|
64 byte memory area which must be in guest RAM and must be
|
||||||
zeroed. Bits 5-3 are reserved and should be zero. Bit 0 is 1
|
zeroed. Bits 5-3 are reserved and should be zero. Bit 0 is 1
|
||||||
when asynchronous page faults are enabled on the vcpu 0 when
|
when asynchronous page faults are enabled on the vcpu 0 when
|
||||||
|
@ -200,20 +226,22 @@ MSR_KVM_ASYNC_PF_EN: 0x4b564d02
|
||||||
Currently type 2 APF will be always delivered on the same vcpu as
|
Currently type 2 APF will be always delivered on the same vcpu as
|
||||||
type 1 was, but guest should not rely on that.
|
type 1 was, but guest should not rely on that.
|
||||||
|
|
||||||
MSR_KVM_STEAL_TIME: 0x4b564d03
|
MSR_KVM_STEAL_TIME:
|
||||||
|
0x4b564d03
|
||||||
|
|
||||||
data: 64-byte alignment physical address of a memory area which must be
|
data:
|
||||||
|
64-byte alignment physical address of a memory area which must be
|
||||||
in guest RAM, plus an enable bit in bit 0. This memory is expected to
|
in guest RAM, plus an enable bit in bit 0. This memory is expected to
|
||||||
hold a copy of the following structure:
|
hold a copy of the following structure::
|
||||||
|
|
||||||
struct kvm_steal_time {
|
struct kvm_steal_time {
|
||||||
__u64 steal;
|
__u64 steal;
|
||||||
__u32 version;
|
__u32 version;
|
||||||
__u32 flags;
|
__u32 flags;
|
||||||
__u8 preempted;
|
__u8 preempted;
|
||||||
__u8 u8_pad[3];
|
__u8 u8_pad[3];
|
||||||
__u32 pad[11];
|
__u32 pad[11];
|
||||||
}
|
}
|
||||||
|
|
||||||
whose data will be filled in by the hypervisor periodically. Only one
|
whose data will be filled in by the hypervisor periodically. Only one
|
||||||
write, or registration, is needed for each VCPU. The interval between
|
write, or registration, is needed for each VCPU. The interval between
|
||||||
|
@ -224,25 +252,32 @@ MSR_KVM_STEAL_TIME: 0x4b564d03
|
||||||
|
|
||||||
Fields have the following meanings:
|
Fields have the following meanings:
|
||||||
|
|
||||||
version: a sequence counter. In other words, guest has to check
|
version:
|
||||||
|
a sequence counter. In other words, guest has to check
|
||||||
this field before and after grabbing time information and make
|
this field before and after grabbing time information and make
|
||||||
sure they are both equal and even. An odd version indicates an
|
sure they are both equal and even. An odd version indicates an
|
||||||
in-progress update.
|
in-progress update.
|
||||||
|
|
||||||
flags: At this point, always zero. May be used to indicate
|
flags:
|
||||||
|
At this point, always zero. May be used to indicate
|
||||||
changes in this structure in the future.
|
changes in this structure in the future.
|
||||||
|
|
||||||
steal: the amount of time in which this vCPU did not run, in
|
steal:
|
||||||
|
the amount of time in which this vCPU did not run, in
|
||||||
nanoseconds. Time during which the vcpu is idle, will not be
|
nanoseconds. Time during which the vcpu is idle, will not be
|
||||||
reported as steal time.
|
reported as steal time.
|
||||||
|
|
||||||
preempted: indicate the vCPU who owns this struct is running or
|
preempted:
|
||||||
|
indicate the vCPU who owns this struct is running or
|
||||||
not. Non-zero values mean the vCPU has been preempted. Zero
|
not. Non-zero values mean the vCPU has been preempted. Zero
|
||||||
means the vCPU is not preempted. NOTE, it is always zero if the
|
means the vCPU is not preempted. NOTE, it is always zero if the
|
||||||
the hypervisor doesn't support this field.
|
the hypervisor doesn't support this field.
|
||||||
|
|
||||||
MSR_KVM_EOI_EN: 0x4b564d04
|
MSR_KVM_EOI_EN:
|
||||||
data: Bit 0 is 1 when PV end of interrupt is enabled on the vcpu; 0
|
0x4b564d04
|
||||||
|
|
||||||
|
data:
|
||||||
|
Bit 0 is 1 when PV end of interrupt is enabled on the vcpu; 0
|
||||||
when disabled. Bit 1 is reserved and must be zero. When PV end of
|
when disabled. Bit 1 is reserved and must be zero. When PV end of
|
||||||
interrupt is enabled (bit 0 set), bits 63-2 hold a 4-byte aligned
|
interrupt is enabled (bit 0 set), bits 63-2 hold a 4-byte aligned
|
||||||
physical address of a 4 byte memory area which must be in guest RAM and
|
physical address of a 4 byte memory area which must be in guest RAM and
|
||||||
|
@ -274,11 +309,13 @@ MSR_KVM_EOI_EN: 0x4b564d04
|
||||||
clear it using a single CPU instruction, such as test and clear, or
|
clear it using a single CPU instruction, such as test and clear, or
|
||||||
compare and exchange.
|
compare and exchange.
|
||||||
|
|
||||||
MSR_KVM_POLL_CONTROL: 0x4b564d05
|
MSR_KVM_POLL_CONTROL:
|
||||||
|
0x4b564d05
|
||||||
|
|
||||||
Control host-side polling.
|
Control host-side polling.
|
||||||
|
|
||||||
data: Bit 0 enables (1) or disables (0) host-side HLT polling logic.
|
data:
|
||||||
|
Bit 0 enables (1) or disables (0) host-side HLT polling logic.
|
||||||
|
|
||||||
KVM guests can request the host not to poll on HLT, for example if
|
KVM guests can request the host not to poll on HLT, for example if
|
||||||
they are performing polling themselves.
|
they are performing polling themselves.
|
||||||
|
|
Loading…
Reference in a new issue