Documentation/virt/kvm/msr.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =================
   4 KVM-specific MSRs
   5 =================
   6
   7 :Author: Glauber Costa <glommer@redhat.com>, Red Hat Inc, 2010
   8
   9 KVM makes use of some custom MSRs to service some requests.
  10
  11 Custom MSRs have a range reserved for them, that goes from
  12 0x4b564d00 to 0x4b564dff. There are MSRs outside this area,
  13 but they are deprecated and their use is discouraged.
  14
  15 Custom MSR list
  16 ---------------
  17
  18 The current supported Custom MSR list is:
  19
  20 MSR_KVM_WALL_CLOCK_NEW:
  21         0x4b564d00
  22
  23 data:
  24         4-byte alignment physical address of a memory area which must be
  25         in guest RAM. This memory is expected to hold a copy of the following
  26         structure::
  27
  28          struct pvclock_wall_clock {
  29                 u32   version;
  30                 u32   sec;
  31                 u32   nsec;
  32           } __attribute__((__packed__));
  33
  34         whose data will be filled in by the hypervisor. The hypervisor is only
  35         guaranteed to update this data at the moment of MSR write.
  36         Users that want to reliably query this information more than once have
  37         to write more than once to this MSR. Fields have the following meanings:
  38
  39         version:
  40                 guest has to check version before and after grabbing
  41                 time information and check that they are both equal and even.
  42                 An odd version indicates an in-progress update.
  43
  44         sec:
  45                  number of seconds for wallclock at time of boot.
  46
  47         nsec:
  48                  number of nanoseconds for wallclock at time of boot.
  49
  50         In order to get the current wallclock time, the system_time from
  51         MSR_KVM_SYSTEM_TIME_NEW needs to be added.
  52
  53         Note that although MSRs are per-CPU entities, the effect of this
  54         particular MSR is global.
  55
  56         Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid
  57         leaf prior to usage.
  58
  59 MSR_KVM_SYSTEM_TIME_NEW:
  60         0x4b564d01
  61
  62 data:
  63         4-byte aligned physical address of a memory area which must be in
  64         guest RAM, plus an enable bit in bit 0. This memory is expected to hold
  65         a copy of the following structure::
  66
  67           struct pvclock_vcpu_time_info {
  68                 u32   version;
  69                 u32   pad0;
  70                 u64   tsc_timestamp;
  71                 u64   system_time;
  72                 u32   tsc_to_system_mul;
  73                 s8    tsc_shift;
  74                 u8    flags;
  75                 u8    pad[2];
  76           } __attribute__((__packed__)); /* 32 bytes */
  77
  78         whose data will be filled in by the hypervisor periodically. Only one
  79         write, or registration, is needed for each VCPU. The interval between
  80         updates of this structure is arbitrary and implementation-dependent.
  81         The hypervisor may update this structure at any time it sees fit until
  82         anything with bit0 == 0 is written to it.
  83
  84         Fields have the following meanings:
  85
  86         version:
  87                 guest has to check version before and after grabbing
  88                 time information and check that they are both equal and even.
  89                 An odd version indicates an in-progress update.
  90
  91         tsc_timestamp:
  92                 the tsc value at the current VCPU at the time
  93                 of the update of this structure. Guests can subtract this value
  94                 from current tsc to derive a notion of elapsed time since the
  95                 structure update.
  96
  97         system_time:
  98                 a host notion of monotonic time, including sleep
  99                 time at the time this structure was last updated. Unit is
 100                 nanoseconds.
 101
 102         tsc_to_system_mul:
 103                 multiplier to be used when converting
 104                 tsc-related quantity to nanoseconds
 105
 106         tsc_shift:
 107                 shift to be used when converting tsc-related
 108                 quantity to nanoseconds. This shift will ensure that
 109                 multiplication with tsc_to_system_mul does not overflow.
 110                 A positive value denotes a left shift, a negative value
 111                 a right shift.
 112
 113                 The conversion from tsc to nanoseconds involves an additional
 114                 right shift by 32 bits. With this information, guests can
 115                 derive per-CPU time by doing::
 116
 117                         time = (current_tsc - tsc_timestamp)
 118                         if (tsc_shift >= 0)
 119                                 time <<= tsc_shift;
 120                         else
 121                                 time >>= -tsc_shift;
 122                         time = (time * tsc_to_system_mul) >> 32
 123                         time = time + system_time
 124
 125         flags:
 126                 bits in this field indicate extended capabilities
 127                 coordinated between the guest and the hypervisor. Availability
 128                 of specific flags has to be checked in 0x40000001 cpuid leaf.
 129                 Current flags are:
 130
 131
 132                 +-----------+--------------+----------------------------------+
 133                 | flag bit  | cpuid bit    | meaning                          |
 134                 +-----------+--------------+----------------------------------+
 135                 |           |              | time measures taken across       |
 136                 |    0      |      24      | multiple cpus are guaranteed to  |
 137                 |           |              | be monotonic                     |
 138                 +-----------+--------------+----------------------------------+
 139                 |           |              | guest vcpu has been paused by    |
 140                 |    1      |     N/A      | the host                         |
 141                 |           |              | See 4.70 in api.txt              |
 142                 +-----------+--------------+----------------------------------+
 143
 144         Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid
 145         leaf prior to usage.
 146
 147
 148 MSR_KVM_WALL_CLOCK:
 149         0x11
 150
 151 data and functioning:
 152         same as MSR_KVM_WALL_CLOCK_NEW. Use that instead.
 153
 154         This MSR falls outside the reserved KVM range and may be removed in the
 155         future. Its usage is deprecated.
 156
 157         Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid
 158         leaf prior to usage.
 159
 160 MSR_KVM_SYSTEM_TIME:
 161         0x12
 162
 163 data and functioning:
 164         same as MSR_KVM_SYSTEM_TIME_NEW. Use that instead.
 165
 166         This MSR falls outside the reserved KVM range and may be removed in the
 167         future. Its usage is deprecated.
 168
 169         Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid
 170         leaf prior to usage.
 171
 172         The suggested algorithm for detecting kvmclock presence is then::
 173
 174                 if (!kvm_para_available())    /* refer to cpuid.txt */
 175                         return NON_PRESENT;
 176
 177                 flags = cpuid_eax(0x40000001);
 178                 if (flags & 3) {
 179                         msr_kvm_system_time = MSR_KVM_SYSTEM_TIME_NEW;
 180                         msr_kvm_wall_clock = MSR_KVM_WALL_CLOCK_NEW;
 181                         return PRESENT;
 182                 } else if (flags & 0) {
 183                         msr_kvm_system_time = MSR_KVM_SYSTEM_TIME;
 184                         msr_kvm_wall_clock = MSR_KVM_WALL_CLOCK;
 185                         return PRESENT;
 186                 } else
 187                         return NON_PRESENT;
 188
 189 MSR_KVM_ASYNC_PF_EN:
 190         0x4b564d02
 191
 192 data:
 193         Bits 63-6 hold 64-byte aligned physical address of a
 194         64 byte memory area which must be in guest RAM and must be
 195         zeroed. Bits 5-3 are reserved and should be zero. Bit 0 is 1
 196         when asynchronous page faults are enabled on the vcpu 0 when
 197         disabled. Bit 1 is 1 if asynchronous page faults can be injected
 198         when vcpu is in cpl == 0. Bit 2 is 1 if asynchronous page faults
 199         are delivered to L1 as #PF vmexits.  Bit 2 can be set only if
 200         KVM_FEATURE_ASYNC_PF_VMEXIT is present in CPUID.
 201
 202         First 4 byte of 64 byte memory location will be written to by
 203         the hypervisor at the time of asynchronous page fault (APF)
 204         injection to indicate type of asynchronous page fault. Value
 205         of 1 means that the page referred to by the page fault is not
 206         present. Value 2 means that the page is now available. Disabling
 207         interrupt inhibits APFs. Guest must not enable interrupt
 208         before the reason is read, or it may be overwritten by another
 209         APF. Since APF uses the same exception vector as regular page
 210         fault guest must reset the reason to 0 before it does
 211         something that can generate normal page fault.  If during page
 212         fault APF reason is 0 it means that this is regular page
 213         fault.
 214
 215         During delivery of type 1 APF cr2 contains a token that will
 216         be used to notify a guest when missing page becomes
 217         available. When page becomes available type 2 APF is sent with
 218         cr2 set to the token associated with the page. There is special
 219         kind of token 0xffffffff which tells vcpu that it should wake
 220         up all processes waiting for APFs and no individual type 2 APFs
 221         will be sent.
 222
 223         If APF is disabled while there are outstanding APFs, they will
 224         not be delivered.
 225
 226         Currently type 2 APF will be always delivered on the same vcpu as
 227         type 1 was, but guest should not rely on that.
 228
 229 MSR_KVM_STEAL_TIME:
 230         0x4b564d03
 231
 232 data:
 233         64-byte alignment physical address of a memory area which must be
 234         in guest RAM, plus an enable bit in bit 0. This memory is expected to
 235         hold a copy of the following structure::
 236
 237           struct kvm_steal_time {
 238                 __u64 steal;
 239                 __u32 version;
 240                 __u32 flags;
 241                 __u8  preempted;
 242                 __u8  u8_pad[3];
 243                 __u32 pad[11];
 244           }
 245
 246         whose data will be filled in by the hypervisor periodically. Only one
 247         write, or registration, is needed for each VCPU. The interval between
 248         updates of this structure is arbitrary and implementation-dependent.
 249         The hypervisor may update this structure at any time it sees fit until
 250         anything with bit0 == 0 is written to it. Guest is required to make sure
 251         this structure is initialized to zero.
 252
 253         Fields have the following meanings:
 254
 255         version:
 256                 a sequence counter. In other words, guest has to check
 257                 this field before and after grabbing time information and make
 258                 sure they are both equal and even. An odd version indicates an
 259                 in-progress update.
 260
 261         flags:
 262                 At this point, always zero. May be used to indicate
 263                 changes in this structure in the future.
 264
 265         steal:
 266                 the amount of time in which this vCPU did not run, in
 267                 nanoseconds. Time during which the vcpu is idle, will not be
 268                 reported as steal time.
 269
 270         preempted:
 271                 indicate the vCPU who owns this struct is running or
 272                 not. Non-zero values mean the vCPU has been preempted. Zero
 273                 means the vCPU is not preempted. NOTE, it is always zero if the
 274                 the hypervisor doesn't support this field.
 275
 276 MSR_KVM_EOI_EN:
 277         0x4b564d04
 278
 279 data:
 280         Bit 0 is 1 when PV end of interrupt is enabled on the vcpu; 0
 281         when disabled.  Bit 1 is reserved and must be zero.  When PV end of
 282         interrupt is enabled (bit 0 set), bits 63-2 hold a 4-byte aligned
 283         physical address of a 4 byte memory area which must be in guest RAM and
 284         must be zeroed.
 285
 286         The first, least significant bit of 4 byte memory location will be
 287         written to by the hypervisor, typically at the time of interrupt
 288         injection.  Value of 1 means that guest can skip writing EOI to the apic
 289         (using MSR or MMIO write); instead, it is sufficient to signal
 290         EOI by clearing the bit in guest memory - this location will
 291         later be polled by the hypervisor.
 292         Value of 0 means that the EOI write is required.
 293
 294         It is always safe for the guest to ignore the optimization and perform
 295         the APIC EOI write anyway.
 296
 297         Hypervisor is guaranteed to only modify this least
 298         significant bit while in the current VCPU context, this means that
 299         guest does not need to use either lock prefix or memory ordering
 300         primitives to synchronise with the hypervisor.
 301
 302         However, hypervisor can set and clear this memory bit at any time:
 303         therefore to make sure hypervisor does not interrupt the
 304         guest and clear the least significant bit in the memory area
 305         in the window between guest testing it to detect
 306         whether it can skip EOI apic write and between guest
 307         clearing it to signal EOI to the hypervisor,
 308         guest must both read the least significant bit in the memory area and
 309         clear it using a single CPU instruction, such as test and clear, or
 310         compare and exchange.
 311
 312 MSR_KVM_POLL_CONTROL:
 313         0x4b564d05
 314
 315         Control host-side polling.
 316
 317 data:
 318         Bit 0 enables (1) or disables (0) host-side HLT polling logic.
 319
 320         KVM guests can request the host not to poll on HLT, for example if
 321         they are performing polling themselves.