About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / virtual / kvm / msr.txt




Custom Search

Based on kernel version 4.13.3. Page generated on 2017-09-23 13:56 EST.

1	KVM-specific MSRs.
2	Glauber Costa <glommer@redhat.com>, Red Hat Inc, 2010
3	=====================================================
4	
5	KVM makes use of some custom MSRs to service some requests.
6	
7	Custom MSRs have a range reserved for them, that goes from
8	0x4b564d00 to 0x4b564dff. There are MSRs outside this area,
9	but they are deprecated and their use is discouraged.
10	
11	Custom MSR list
12	--------
13	
14	The current supported Custom MSR list is:
15	
16	MSR_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	
50	MSR_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	
129	MSR_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	
139	MSR_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	
166	MSR_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.
174	
175		First 4 byte of 64 byte memory location will be written to by
176		the hypervisor at the time of asynchronous page fault (APF)
177		injection to indicate type of asynchronous page fault. Value
178		of 1 means that the page referred to by the page fault is not
179		present. Value 2 means that the page is now available. Disabling
180		interrupt inhibits APFs. Guest must not enable interrupt
181		before the reason is read, or it may be overwritten by another
182		APF. Since APF uses the same exception vector as regular page
183		fault guest must reset the reason to 0 before it does
184		something that can generate normal page fault.  If during page
185		fault APF reason is 0 it means that this is regular page
186		fault.
187	
188		During delivery of type 1 APF cr2 contains a token that will
189		be used to notify a guest when missing page becomes
190		available. When page becomes available type 2 APF is sent with
191		cr2 set to the token associated with the page. There is special
192		kind of token 0xffffffff which tells vcpu that it should wake
193		up all processes waiting for APFs and no individual type 2 APFs
194		will be sent.
195	
196		If APF is disabled while there are outstanding APFs, they will
197		not be delivered.
198	
199		Currently type 2 APF will be always delivered on the same vcpu as
200		type 1 was, but guest should not rely on that.
201	
202	MSR_KVM_STEAL_TIME: 0x4b564d03
203	
204		data: 64-byte alignment physical address of a memory area which must be
205		in guest RAM, plus an enable bit in bit 0. This memory is expected to
206		hold a copy of the following structure:
207	
208		struct kvm_steal_time {
209			__u64 steal;
210			__u32 version;
211			__u32 flags;
212			__u8  preempted;
213			__u8  u8_pad[3];
214			__u32 pad[11];
215		}
216	
217		whose data will be filled in by the hypervisor periodically. Only one
218		write, or registration, is needed for each VCPU. The interval between
219		updates of this structure is arbitrary and implementation-dependent.
220		The hypervisor may update this structure at any time it sees fit until
221		anything with bit0 == 0 is written to it. Guest is required to make sure
222		this structure is initialized to zero.
223	
224		Fields have the following meanings:
225	
226			version: a sequence counter. In other words, guest has to check
227			this field before and after grabbing time information and make
228			sure they are both equal and even. An odd version indicates an
229			in-progress update.
230	
231			flags: At this point, always zero. May be used to indicate
232			changes in this structure in the future.
233	
234			steal: the amount of time in which this vCPU did not run, in
235			nanoseconds. Time during which the vcpu is idle, will not be
236			reported as steal time.
237	
238			preempted: indicate the vCPU who owns this struct is running or
239			not. Non-zero values mean the vCPU has been preempted. Zero
240			means the vCPU is not preempted. NOTE, it is always zero if the
241			the hypervisor doesn't support this field.
242	
243	MSR_KVM_EOI_EN: 0x4b564d04
244		data: Bit 0 is 1 when PV end of interrupt is enabled on the vcpu; 0
245		when disabled.  Bit 1 is reserved and must be zero.  When PV end of
246		interrupt is enabled (bit 0 set), bits 63-2 hold a 4-byte aligned
247		physical address of a 4 byte memory area which must be in guest RAM and
248		must be zeroed.
249	
250		The first, least significant bit of 4 byte memory location will be
251		written to by the hypervisor, typically at the time of interrupt
252		injection.  Value of 1 means that guest can skip writing EOI to the apic
253		(using MSR or MMIO write); instead, it is sufficient to signal
254		EOI by clearing the bit in guest memory - this location will
255		later be polled by the hypervisor.
256		Value of 0 means that the EOI write is required.
257	
258		It is always safe for the guest to ignore the optimization and perform
259		the APIC EOI write anyway.
260	
261		Hypervisor is guaranteed to only modify this least
262		significant bit while in the current VCPU context, this means that
263		guest does not need to use either lock prefix or memory ordering
264		primitives to synchronise with the hypervisor.
265	
266		However, hypervisor can set and clear this memory bit at any time:
267		therefore to make sure hypervisor does not interrupt the
268		guest and clear the least significant bit in the memory area
269		in the window between guest testing it to detect
270		whether it can skip EOI apic write and between guest
271		clearing it to signal EOI to the hypervisor,
272		guest must both read the least significant bit in the memory area and
273		clear it using a single CPU instruction, such as test and clear, or
274		compare and exchange.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.