[deliverable/linux.git] / Documentation / kvm / msr.txt

KVM-specific MSRs.
Glauber Costa <glommer@redhat.com>, Red Hat Inc, 2010
=====================================================

KVM makes use of some custom MSRs to service some requests.

Custom MSRs have a range reserved for them, that goes from
0x4b564d00 to 0x4b564dff. There are MSRs outside this area,
but they are deprecated and their use is discouraged.

Custom MSR list
--------

The current supported Custom MSR list is:

MSR_KVM_WALL_CLOCK_NEW:   0x4b564d00

	data: 4-byte alignment physical address of a memory area which must be
	in guest RAM. This memory is expected to hold a copy of the following
	structure:

	struct pvclock_wall_clock {
		u32   version;
		u32   sec;
		u32   nsec;
	} __attribute__((__packed__));

	whose data will be filled in by the hypervisor. The hypervisor is only
	guaranteed to update this data at the moment of MSR write.
	Users that want to reliably query this information more than once have
	to write more than once to this MSR. Fields have the following meanings:

		version: guest has to check version before and after grabbing
		time information and check that they are both equal and even.
		An odd version indicates an in-progress update.

		sec: number of seconds for wallclock.

		nsec: number of nanoseconds for wallclock.

	Note that although MSRs are per-CPU entities, the effect of this
	particular MSR is global.

	Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid
	leaf prior to usage.

MSR_KVM_SYSTEM_TIME_NEW:  0x4b564d01

	data: 4-byte aligned physical address of a memory area which must be in
	guest RAM, plus an enable bit in bit 0. This memory is expected to hold
	a copy of the following structure:

	struct pvclock_vcpu_time_info {
		u32   version;
		u32   pad0;
		u64   tsc_timestamp;
		u64   system_time;
		u32   tsc_to_system_mul;
		s8    tsc_shift;
		u8    flags;
		u8    pad[2];
	} __attribute__((__packed__)); /* 32 bytes */

	whose data will be filled in by the hypervisor periodically. Only one
	write, or registration, is needed for each VCPU. The interval between
	updates of this structure is arbitrary and implementation-dependent.
	The hypervisor may update this structure at any time it sees fit until
	anything with bit0 == 0 is written to it.

	Fields have the following meanings:

		version: guest has to check version before and after grabbing
		time information and check that they are both equal and even.
		An odd version indicates an in-progress update.

		tsc_timestamp: the tsc value at the current VCPU at the time
		of the update of this structure. Guests can subtract this value
		from current tsc to derive a notion of elapsed time since the
		structure update.

		system_time: a host notion of monotonic time, including sleep
		time at the time this structure was last updated. Unit is
		nanoseconds.

		tsc_to_system_mul: a function of the tsc frequency. One has
		to multiply any tsc-related quantity by this value to get
		a value in nanoseconds, besides dividing by 2^tsc_shift

		tsc_shift: cycle to nanosecond divider, as a power of two, to
		allow for shift rights. One has to shift right any tsc-related
		quantity by this value to get a value in nanoseconds, besides
		multiplying by tsc_to_system_mul.

		With this information, guests can derive per-CPU time by
		doing:

			time = (current_tsc - tsc_timestamp)
			time = (time * tsc_to_system_mul) >> tsc_shift
			time = time + system_time

		flags: bits in this field indicate extended capabilities
		coordinated between the guest and the hypervisor. Availability
		of specific flags has to be checked in 0x40000001 cpuid leaf.
		Current flags are:

		 flag bit   | cpuid bit    | meaning
		-------------------------------------------------------------
			    |	           | time measures taken across
		     0      |	   24      | multiple cpus are guaranteed to
			    |		   | be monotonic
		-------------------------------------------------------------

	Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid
	leaf prior to usage.


MSR_KVM_WALL_CLOCK:  0x11

	data and functioning: same as MSR_KVM_WALL_CLOCK_NEW. Use that instead.

	This MSR falls outside the reserved KVM range and may be removed in the
	future. Its usage is deprecated.

	Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid
	leaf prior to usage.

MSR_KVM_SYSTEM_TIME: 0x12

	data and functioning: same as MSR_KVM_SYSTEM_TIME_NEW. Use that instead.

	This MSR falls outside the reserved KVM range and may be removed in the
	future. Its usage is deprecated.

	Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid
	leaf prior to usage.

	The suggested algorithm for detecting kvmclock presence is then:

		if (!kvm_para_available())    /* refer to cpuid.txt */
			return NON_PRESENT;

		flags = cpuid_eax(0x40000001);
		if (flags & 3) {
			msr_kvm_system_time = MSR_KVM_SYSTEM_TIME_NEW;
			msr_kvm_wall_clock = MSR_KVM_WALL_CLOCK_NEW;
			return PRESENT;
		} else if (flags & 0) {
			msr_kvm_system_time = MSR_KVM_SYSTEM_TIME;
			msr_kvm_wall_clock = MSR_KVM_WALL_CLOCK;
			return PRESENT;
		} else
			return NON_PRESENT;

MSR_KVM_ASYNC_PF_EN: 0x4b564d02
	data: Bits 63-6 hold 64-byte aligned physical address of a
	64 byte memory area which must be in guest RAM and must be
	zeroed. Bits 5-2 are reserved and should be zero. Bit 0 is 1
	when asynchronous page faults are enabled on the vcpu 0 when
	disabled. Bit 2 is 1 if asynchronous page faults can be injected
	when vcpu is in cpl == 0.

	First 4 byte of 64 byte memory location will be written to by
	the hypervisor at the time of asynchronous page fault (APF)
	injection to indicate type of asynchronous page fault. Value
	of 1 means that the page referred to by the page fault is not
	present. Value 2 means that the page is now available. Disabling
	interrupt inhibits APFs. Guest must not enable interrupt
	before the reason is read, or it may be overwritten by another
	APF. Since APF uses the same exception vector as regular page
	fault guest must reset the reason to 0 before it does
	something that can generate normal page fault.  If during page
	fault APF reason is 0 it means that this is regular page
	fault.

	During delivery of type 1 APF cr2 contains a token that will
	be used to notify a guest when missing page becomes
	available. When page becomes available type 2 APF is sent with
	cr2 set to the token associated with the page. There is special
	kind of token 0xffffffff which tells vcpu that it should wake
	up all processes waiting for APFs and no individual type 2 APFs
	will be sent.

	If APF is disabled while there are outstanding APFs, they will
	not be delivered.

	Currently type 2 APF will be always delivered on the same vcpu as
	type 1 was, but guest should not rely on that.
Commit	Line	Data
d2d7a611 GC	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.
d2d7a611 GC	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.
	38
	39	nsec: number of nanoseconds for wallclock.
	40
	41	Note that although MSRs are per-CPU entities, the effect of this
	42	particular MSR is global.
	43
	44	Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid
	45	leaf prior to usage.
	46
	47	MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01
	48
	49	data: 4-byte aligned physical address of a memory area which must be in
	50	guest RAM, plus an enable bit in bit 0. This memory is expected to hold
	51	a copy of the following structure:
	52
	53	struct pvclock_vcpu_time_info {
	54	u32 version;
	55	u32 pad0;
	56	u64 tsc_timestamp;
	57	u64 system_time;
	58	u32 tsc_to_system_mul;
	59	s8 tsc_shift;
	60	u8 flags;
	61	u8 pad[2];
	62	} __attribute__((__packed__)); /* 32 bytes */
	63
	64	whose data will be filled in by the hypervisor periodically. Only one
	65	write, or registration, is needed for each VCPU. The interval between
	66	updates of this structure is arbitrary and implementation-dependent.
	67	The hypervisor may update this structure at any time it sees fit until
	68	anything with bit0 == 0 is written to it.
	69
70	Fields have the following meanings:
71
72	version: guest has to check version before and after grabbing
73	time information and check that they are both equal and even.
74	An odd version indicates an in-progress update.
75
76	tsc_timestamp: the tsc value at the current VCPU at the time
77	of the update of this structure. Guests can subtract this value
78	from current tsc to derive a notion of elapsed time since the
79	structure update.
80
81	system_time: a host notion of monotonic time, including sleep
82	time at the time this structure was last updated. Unit is
83	nanoseconds.
84
85	tsc_to_system_mul: a function of the tsc frequency. One has
86	to multiply any tsc-related quantity by this value to get
87	a value in nanoseconds, besides dividing by 2^tsc_shift
88
89	tsc_shift: cycle to nanosecond divider, as a power of two, to
90	allow for shift rights. One has to shift right any tsc-related
91	quantity by this value to get a value in nanoseconds, besides
92	multiplying by tsc_to_system_mul.
93
94	With this information, guests can derive per-CPU time by
95	doing:
96
97	time = (current_tsc - tsc_timestamp)
98	time = (time * tsc_to_system_mul) >> tsc_shift
99	time = time + system_time
100
101	flags: bits in this field indicate extended capabilities
102	coordinated between the guest and the hypervisor. Availability
103	of specific flags has to be checked in 0x40000001 cpuid leaf.
104	Current flags are:
105
106	flag bit \| cpuid bit \| meaning
107	-------------------------------------------------------------
108	\| \| time measures taken across
109	0 \| 24 \| multiple cpus are guaranteed to
110	\| \| be monotonic
111	-------------------------------------------------------------
112
113	Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid
114	leaf prior to usage.
115
116
117	MSR_KVM_WALL_CLOCK: 0x11
118
119	data and functioning: same as MSR_KVM_WALL_CLOCK_NEW. Use that instead.
120
121	This MSR falls outside the reserved KVM range and may be removed in the
122	future. Its usage is deprecated.
123
124	Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid
125	leaf prior to usage.
126
127	MSR_KVM_SYSTEM_TIME: 0x12
128
129	data and functioning: same as MSR_KVM_SYSTEM_TIME_NEW. Use that instead.
130
131	This MSR falls outside the reserved KVM range and may be removed in the
132	future. Its usage is deprecated.
133
134	Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid
135	leaf prior to usage.
136
137	The suggested algorithm for detecting kvmclock presence is then:
138
139	if (!kvm_para_available()) /* refer to cpuid.txt */
140	return NON_PRESENT;
141
142	flags = cpuid_eax(0x40000001);
143	if (flags & 3) {
144	msr_kvm_system_time = MSR_KVM_SYSTEM_TIME_NEW;
145	msr_kvm_wall_clock = MSR_KVM_WALL_CLOCK_NEW;
146	return PRESENT;
147	} else if (flags & 0) {
148	msr_kvm_system_time = MSR_KVM_SYSTEM_TIME;
149	msr_kvm_wall_clock = MSR_KVM_WALL_CLOCK;
150	return PRESENT;
151	} else
152	return NON_PRESENT;
344d9588 GN	153
	154	MSR_KVM_ASYNC_PF_EN: 0x4b564d02
	155	data: Bits 63-6 hold 64-byte aligned physical address of a
	156	64 byte memory area which must be in guest RAM and must be
6adba527	157	zeroed. Bits 5-2 are reserved and should be zero. Bit 0 is 1
344d9588	158	when asynchronous page faults are enabled on the vcpu 0 when
6adba527 GN	159	disabled. Bit 2 is 1 if asynchronous page faults can be injected
6adba527 GN	160	when vcpu is in cpl == 0.
344d9588 GN	161
	162	First 4 byte of 64 byte memory location will be written to by
	163	the hypervisor at the time of asynchronous page fault (APF)
	164	injection to indicate type of asynchronous page fault. Value
	165	of 1 means that the page referred to by the page fault is not
	166	present. Value 2 means that the page is now available. Disabling
	167	interrupt inhibits APFs. Guest must not enable interrupt
	168	before the reason is read, or it may be overwritten by another
	169	APF. Since APF uses the same exception vector as regular page
	170	fault guest must reset the reason to 0 before it does
	171	something that can generate normal page fault. If during page
	172	fault APF reason is 0 it means that this is regular page
	173	fault.
	174
	175	During delivery of type 1 APF cr2 contains a token that will
	176	be used to notify a guest when missing page becomes
	177	available. When page becomes available type 2 APF is sent with
	178	cr2 set to the token associated with the page. There is special
	179	kind of token 0xffffffff which tells vcpu that it should wake
	180	up all processes waiting for APFs and no individual type 2 APFs
	181	will be sent.
	182
	183	If APF is disabled while there are outstanding APFs, they will
	184	not be delivered.
	185
	186	Currently type 2 APF will be always delivered on the same vcpu as
	187	type 1 was, but guest should not rely on that.