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