[net-next-2.6.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.
At present, this facility is only used by kvmclock.

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;
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.
	6	At present, this facility is only used by kvmclock.
	7
	8	Custom MSRs have a range reserved for them, that goes from
	9	0x4b564d00 to 0x4b564dff. There are MSRs outside this area,
	10	but they are deprecated and their use is discouraged.
	11
	12	Custom MSR list
	13	--------
	14
	15	The current supported Custom MSR list is:
	16
	17	MSR_KVM_WALL_CLOCK_NEW: 0x4b564d00
	18
	19	data: 4-byte alignment physical address of a memory area which must be
	20	in guest RAM. This memory is expected to hold a copy of the following
	21	structure:
	22
	23	struct pvclock_wall_clock {
	24	u32 version;
	25	u32 sec;
	26	u32 nsec;
	27	} __attribute__((__packed__));
	28
	29	whose data will be filled in by the hypervisor. The hypervisor is only
	30	guaranteed to update this data at the moment of MSR write.
	31	Users that want to reliably query this information more than once have
	32	to write more than once to this MSR. Fields have the following meanings:
	33
	34	version: guest has to check version before and after grabbing
	35	time information and check that they are both equal and even.
	36	An odd version indicates an in-progress update.
	37
	38	sec: number of seconds for wallclock.
	39
	40	nsec: number of nanoseconds for wallclock.
	41
	42	Note that although MSRs are per-CPU entities, the effect of this
	43	particular MSR is global.
	44
	45	Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid
	46	leaf prior to usage.
	47
	48	MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01
	49
	50	data: 4-byte aligned physical address of a memory area which must be in
	51	guest RAM, plus an enable bit in bit 0. This memory is expected to hold
	52	a copy of the following structure:
	53
	54	struct pvclock_vcpu_time_info {
	55	u32 version;
	56	u32 pad0;
	57	u64 tsc_timestamp;
	58	u64 system_time;
	59	u32 tsc_to_system_mul;
	60	s8 tsc_shift;
	61	u8 flags;
	62	u8 pad[2];
	63	} __attribute__((__packed__)); /* 32 bytes */
	64
65	whose data will be filled in by the hypervisor periodically. Only one
66	write, or registration, is needed for each VCPU. The interval between
67	updates of this structure is arbitrary and implementation-dependent.
68	The hypervisor may update this structure at any time it sees fit until
69	anything with bit0 == 0 is written to it.
70
71	Fields have the following meanings:
72
73	version: guest has to check version before and after grabbing
74	time information and check that they are both equal and even.
75	An odd version indicates an in-progress update.
76
77	tsc_timestamp: the tsc value at the current VCPU at the time
78	of the update of this structure. Guests can subtract this value
79	from current tsc to derive a notion of elapsed time since the
80	structure update.
81
82	system_time: a host notion of monotonic time, including sleep
83	time at the time this structure was last updated. Unit is
84	nanoseconds.
85
86	tsc_to_system_mul: a function of the tsc frequency. One has
87	to multiply any tsc-related quantity by this value to get
88	a value in nanoseconds, besides dividing by 2^tsc_shift
89
90	tsc_shift: cycle to nanosecond divider, as a power of two, to
91	allow for shift rights. One has to shift right any tsc-related
92	quantity by this value to get a value in nanoseconds, besides
93	multiplying by tsc_to_system_mul.
94
95	With this information, guests can derive per-CPU time by
96	doing:
97
98	time = (current_tsc - tsc_timestamp)
99	time = (time * tsc_to_system_mul) >> tsc_shift
100	time = time + system_time
101
102	flags: bits in this field indicate extended capabilities
103	coordinated between the guest and the hypervisor. Availability
104	of specific flags has to be checked in 0x40000001 cpuid leaf.
105	Current flags are:
106
107	flag bit \| cpuid bit \| meaning
108	-------------------------------------------------------------
109	\| \| time measures taken across
110	0 \| 24 \| multiple cpus are guaranteed to
111	\| \| be monotonic
112	-------------------------------------------------------------
113
114	Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid
115	leaf prior to usage.
116
117
118	MSR_KVM_WALL_CLOCK: 0x11
119
120	data and functioning: same as MSR_KVM_WALL_CLOCK_NEW. Use that instead.
121
122	This MSR falls outside the reserved KVM range and may be removed in the
123	future. Its usage is deprecated.
124
125	Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid
126	leaf prior to usage.
127
128	MSR_KVM_SYSTEM_TIME: 0x12
129
130	data and functioning: same as MSR_KVM_SYSTEM_TIME_NEW. Use that instead.
131
132	This MSR falls outside the reserved KVM range and may be removed in the
133	future. Its usage is deprecated.
134
135	Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid
136	leaf prior to usage.
137
138	The suggested algorithm for detecting kvmclock presence is then:
139
140	if (!kvm_para_available()) /* refer to cpuid.txt */
141	return NON_PRESENT;
142
143	flags = cpuid_eax(0x40000001);
144	if (flags & 3) {
145	msr_kvm_system_time = MSR_KVM_SYSTEM_TIME_NEW;
146	msr_kvm_wall_clock = MSR_KVM_WALL_CLOCK_NEW;
147	return PRESENT;
148	} else if (flags & 0) {
149	msr_kvm_system_time = MSR_KVM_SYSTEM_TIME;
150	msr_kvm_wall_clock = MSR_KVM_WALL_CLOCK;
151	return PRESENT;
152	} else
153	return NON_PRESENT;