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         Asynchronous page fault (APF) control MSR.
 194
 195         Bits 63-6 hold 64-byte aligned physical address of a 64 byte memory area
 196         which must be in guest RAM and must be zeroed. This memory is expected
 197         to hold a copy of the following structure::
 198
 199           struct kvm_vcpu_pv_apf_data {
 200                 /* Used for 'page not present' events delivered via #PF */
 201                 __u32 flags;
 202
 203                 /* Used for 'page ready' events delivered via interrupt notification */
 204                 __u32 token;
 205
 206                 __u8 pad[56];
 207                 __u32 enabled;
 208           };
 209
 210         Bits 5-4 of the MSR are reserved and should be zero. Bit 0 is set to 1
 211         when asynchronous page faults are enabled on the vcpu, 0 when disabled.
 212         Bit 1 is 1 if asynchronous page faults can be injected when vcpu is in
 213         cpl == 0. Bit 2 is 1 if asynchronous page faults are delivered to L1 as
 214         #PF vmexits.  Bit 2 can be set only if KVM_FEATURE_ASYNC_PF_VMEXIT is
 215         present in CPUID. Bit 3 enables interrupt based delivery of 'page ready'
 216         events. Bit 3 can only be set if KVM_FEATURE_ASYNC_PF_INT is present in
 217         CPUID.
 218
 219         'Page not present' events are currently always delivered as synthetic
 220         #PF exception. During delivery of these events APF CR2 register contains
 221         a token that will be used to notify the guest when missing page becomes
 222         available. Also, to make it possible to distinguish between real #PF and
 223         APF, first 4 bytes of 64 byte memory location ('flags') will be written
 224         to by the hypervisor at the time of injection. Only first bit of 'flags'
 225         is currently supported, when set, it indicates that the guest is dealing
 226         with asynchronous 'page not present' event. If during a page fault APF
 227         'flags' is '0' it means that this is regular page fault. Guest is
 228         supposed to clear 'flags' when it is done handling #PF exception so the
 229         next event can be delivered.
 230
 231         Note, since APF 'page not present' events use the same exception vector
 232         as regular page fault, guest must reset 'flags' to '0' before it does
 233         something that can generate normal page fault.
 234
 235         Bytes 5-7 of 64 byte memory location ('token') will be written to by the
 236         hypervisor at the time of APF 'page ready' event injection. The content
 237         of these bytes is a token which was previously delivered as 'page not
 238         present' event. The event indicates the page in now available. Guest is
 239         supposed to write '0' to 'token' when it is done handling 'page ready'
 240         event and to write 1' to MSR_KVM_ASYNC_PF_ACK after clearing the location;
 241         writing to the MSR forces KVM to re-scan its queue and deliver the next
 242         pending notification.
 243
 244         Note, MSR_KVM_ASYNC_PF_INT MSR specifying the interrupt vector for 'page
 245         ready' APF delivery needs to be written to before enabling APF mechanism
 246         in MSR_KVM_ASYNC_PF_EN or interrupt #0 can get injected. The MSR is
 247         available if KVM_FEATURE_ASYNC_PF_INT is present in CPUID.
 248
 249         Note, previously, 'page ready' events were delivered via the same #PF
 250         exception as 'page not present' events but this is now deprecated. If
 251         bit 3 (interrupt based delivery) is not set APF events are not delivered.
 252
 253         If APF is disabled while there are outstanding APFs, they will
 254         not be delivered.
 255
 256         Currently 'page ready' APF events will be always delivered on the
 257         same vcpu as 'page not present' event was, but guest should not rely on
 258         that.
 259
 260 MSR_KVM_STEAL_TIME:
 261         0x4b564d03
 262
 263 data:
 264         64-byte alignment physical address of a memory area which must be
 265         in guest RAM, plus an enable bit in bit 0. This memory is expected to
 266         hold a copy of the following structure::
 267
 268           struct kvm_steal_time {
 269                 __u64 steal;
 270                 __u32 version;
 271                 __u32 flags;
 272                 __u8  preempted;
 273                 __u8  u8_pad[3];
 274                 __u32 pad[11];
 275           }
 276
 277         whose data will be filled in by the hypervisor periodically. Only one
 278         write, or registration, is needed for each VCPU. The interval between
 279         updates of this structure is arbitrary and implementation-dependent.
 280         The hypervisor may update this structure at any time it sees fit until
 281         anything with bit0 == 0 is written to it. Guest is required to make sure
 282         this structure is initialized to zero.
 283
 284         Fields have the following meanings:
 285
 286         version:
 287                 a sequence counter. In other words, guest has to check
 288                 this field before and after grabbing time information and make
 289                 sure they are both equal and even. An odd version indicates an
 290                 in-progress update.
 291
 292         flags:
 293                 At this point, always zero. May be used to indicate
 294                 changes in this structure in the future.
 295
 296         steal:
 297                 the amount of time in which this vCPU did not run, in
 298                 nanoseconds. Time during which the vcpu is idle, will not be
 299                 reported as steal time.
 300
 301         preempted:
 302                 indicate the vCPU who owns this struct is running or
 303                 not. Non-zero values mean the vCPU has been preempted. Zero
 304                 means the vCPU is not preempted. NOTE, it is always zero if the
 305                 the hypervisor doesn't support this field.
 306
 307 MSR_KVM_EOI_EN:
 308         0x4b564d04
 309
 310 data:
 311         Bit 0 is 1 when PV end of interrupt is enabled on the vcpu; 0
 312         when disabled.  Bit 1 is reserved and must be zero.  When PV end of
 313         interrupt is enabled (bit 0 set), bits 63-2 hold a 4-byte aligned
 314         physical address of a 4 byte memory area which must be in guest RAM and
 315         must be zeroed.
 316
 317         The first, least significant bit of 4 byte memory location will be
 318         written to by the hypervisor, typically at the time of interrupt
 319         injection.  Value of 1 means that guest can skip writing EOI to the apic
 320         (using MSR or MMIO write); instead, it is sufficient to signal
 321         EOI by clearing the bit in guest memory - this location will
 322         later be polled by the hypervisor.
 323         Value of 0 means that the EOI write is required.
 324
 325         It is always safe for the guest to ignore the optimization and perform
 326         the APIC EOI write anyway.
 327
 328         Hypervisor is guaranteed to only modify this least
 329         significant bit while in the current VCPU context, this means that
 330         guest does not need to use either lock prefix or memory ordering
 331         primitives to synchronise with the hypervisor.
 332
 333         However, hypervisor can set and clear this memory bit at any time:
 334         therefore to make sure hypervisor does not interrupt the
 335         guest and clear the least significant bit in the memory area
 336         in the window between guest testing it to detect
 337         whether it can skip EOI apic write and between guest
 338         clearing it to signal EOI to the hypervisor,
 339         guest must both read the least significant bit in the memory area and
 340         clear it using a single CPU instruction, such as test and clear, or
 341         compare and exchange.
 342
 343 MSR_KVM_POLL_CONTROL:
 344         0x4b564d05
 345
 346         Control host-side polling.
 347
 348 data:
 349         Bit 0 enables (1) or disables (0) host-side HLT polling logic.
 350
 351         KVM guests can request the host not to poll on HLT, for example if
 352         they are performing polling themselves.
 353
 354 MSR_KVM_ASYNC_PF_INT:
 355         0x4b564d06
 356
 357 data:
 358         Second asynchronous page fault (APF) control MSR.
 359
 360         Bits 0-7: APIC vector for delivery of 'page ready' APF events.
 361         Bits 8-63: Reserved
 362
 363         Interrupt vector for asynchnonous 'page ready' notifications delivery.
 364         The vector has to be set up before asynchronous page fault mechanism
 365         is enabled in MSR_KVM_ASYNC_PF_EN.  The MSR is only available if
 366         KVM_FEATURE_ASYNC_PF_INT is present in CPUID.
 367
 368 MSR_KVM_ASYNC_PF_ACK:
 369         0x4b564d07
 370
 371 data:
 372         Asynchronous page fault (APF) acknowledgment.
 373
 374         When the guest is done processing 'page ready' APF event and 'token'
 375         field in 'struct kvm_vcpu_pv_apf_data' is cleared it is supposed to
 376         write '1' to bit 0 of the MSR, this causes the host to re-scan its queue
 377         and check if there are more notifications pending. The MSR is available
 378         if KVM_FEATURE_ASYNC_PF_INT is present in CPUID.
 379
 380 MSR_KVM_MIGRATION_CONTROL:
 381         0x4b564d08
 382
 383 data:
 384         This MSR is available if KVM_FEATURE_MIGRATION_CONTROL is present in
 385         CPUID.  Bit 0 represents whether live migration of the guest is allowed.
 386
 387         When a guest is started, bit 0 will be 0 if the guest has encrypted
 388         memory and 1 if the guest does not have encrypted memory.  If the
 389         guest is communicating page encryption status to the host using the
 390         ``KVM_HC_MAP_GPA_RANGE`` hypercall, it can set bit 0 in this MSR to
 391         allow live migration of the guest.