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