Commit 263a19ff authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Paolo Bonzini
Browse files

docs: virt: Convert msr.txt to ReST format 



- Use document title markup;
- Convert tables;
- Add blank lines and adjust indentation.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarPaolo Bonzini <pbonzini@redhat.com>
parent 2756df60

Documentation/virt/kvm/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -10,6 +10,7 @@ KVM 
   amd-memory-encryption

   cpuid

   halt-polling

   msr

   vcpu-requests



   arm/index

Documentation/virt/kvm/msr.txt→Documentation/virt/kvm/msr.rst

+92 −55
Original line number Diff line number Diff line 
KVM-specific MSRs.

Glauber Costa <glommer@redhat.com>, Red Hat Inc, 2010

=====================================================

.. SPDX-License-Identifier: GPL-2.0



=================

KVM-specific MSRs

=================



:Author: Glauber Costa <glommer@redhat.com>, Red Hat Inc, 2010



KVM makes use of some custom MSRs to service some requests.
@@ -9,15 +13,17 @@ Custom MSRs have a range reserved for them, that goes from 
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

MSR_KVM_WALL_CLOCK_NEW:

	0x4b564d00



	data: 4-byte alignment physical address of a memory area which must be

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:

	structure::



	 struct pvclock_wall_clock {

		u32   version;
@@ -30,13 +36,16 @@ MSR_KVM_WALL_CLOCK_NEW: 0x4b564d00 
	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

	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 at time of boot.

	sec:

		 number of seconds for wallclock at time of boot.



		nsec: number of nanoseconds for wallclock at time of boot.

	nsec:

		 number of nanoseconds for wallclock at time of boot.



	In order to get the current wallclock time, the system_time from

	MSR_KVM_SYSTEM_TIME_NEW needs to be added.
@@ -47,11 +56,13 @@ MSR_KVM_WALL_CLOCK_NEW: 0x4b564d00 
	Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid

	leaf prior to usage.



MSR_KVM_SYSTEM_TIME_NEW:  0x4b564d01

MSR_KVM_SYSTEM_TIME_NEW:

	0x4b564d01



	data: 4-byte aligned physical address of a memory area which must be in

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:

	a copy of the following structure::



	  struct pvclock_vcpu_time_info {

		u32   version;
@@ -72,23 +83,28 @@ MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01 


	Fields have the following meanings:



		version: guest has to check version before and after grabbing

	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

	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

	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: multiplier to be used when converting

	tsc_to_system_mul:

		multiplier to be used when converting

		tsc-related quantity to nanoseconds



		tsc_shift: shift to be used when converting tsc-related

	tsc_shift:

		shift to be used when converting tsc-related

		quantity to nanoseconds. This shift will ensure that

		multiplication with tsc_to_system_mul does not overflow.

		A positive value denotes a left shift, a negative value
@@ -96,7 +112,7 @@ MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01 


		The conversion from tsc to nanoseconds involves an additional

		right shift by 32 bits. With this information, guests can

		derive per-CPU time by doing:

		derive per-CPU time by doing::



			time = (current_tsc - tsc_timestamp)

			if (tsc_shift >= 0)
@@ -106,29 +122,34 @@ MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01 
			time = (time * tsc_to_system_mul) >> 32

			time = time + system_time



		flags: bits in this field indicate extended capabilities

	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

		-------------------------------------------------------------

			    |		   | guest vcpu has been paused by

		     1	    |	  N/A	   | the host

			    |		   | See 4.70 in api.txt

		-------------------------------------------------------------



		+-----------+--------------+----------------------------------+

		| flag bit  | cpuid bit    | meaning			      |

		+-----------+--------------+----------------------------------+

		|	    |		   | time measures taken across       |

		|    0      |	   24      | multiple cpus are guaranteed to  |

		|	    |		   | be monotonic		      |

		+-----------+--------------+----------------------------------+

		|	    |		   | guest vcpu has been paused by    |

		|    1	    |	  N/A	   | the host			      |

		|	    |		   | See 4.70 in api.txt	      |

		+-----------+--------------+----------------------------------+



	Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid

	leaf prior to usage.





MSR_KVM_WALL_CLOCK:  0x11

MSR_KVM_WALL_CLOCK:

	0x11



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

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.
@@ -136,9 +157,11 @@ MSR_KVM_WALL_CLOCK: 0x11 
	Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid

	leaf prior to usage.



MSR_KVM_SYSTEM_TIME: 0x12

MSR_KVM_SYSTEM_TIME:

	0x12



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

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.
@@ -146,7 +169,7 @@ MSR_KVM_SYSTEM_TIME: 0x12 
	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:

	The suggested algorithm for detecting kvmclock presence is then::



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

			return NON_PRESENT;
@@ -163,8 +186,11 @@ MSR_KVM_SYSTEM_TIME: 0x12 
		} else

			return NON_PRESENT;



MSR_KVM_ASYNC_PF_EN: 0x4b564d02

	data: Bits 63-6 hold 64-byte aligned physical address of a

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-3 are reserved and should be zero. Bit 0 is 1

	when asynchronous page faults are enabled on the vcpu 0 when
@@ -200,11 +226,13 @@ MSR_KVM_ASYNC_PF_EN: 0x4b564d02 
	Currently type 2 APF will be always delivered on the same vcpu as

	type 1 was, but guest should not rely on that.



MSR_KVM_STEAL_TIME: 0x4b564d03

MSR_KVM_STEAL_TIME:

	0x4b564d03



	data: 64-byte alignment physical address of a memory area which must be

data:

	64-byte alignment 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:

	hold a copy of the following structure::



	  struct kvm_steal_time {

		__u64 steal;
@@ -224,25 +252,32 @@ MSR_KVM_STEAL_TIME: 0x4b564d03 


	Fields have the following meanings:



		version: a sequence counter. In other words, guest has to check

	version:

		a sequence counter. In other words, guest has to check

		this field before and after grabbing time information and make

		sure they are both equal and even. An odd version indicates an

		in-progress update.



		flags: At this point, always zero. May be used to indicate

	flags:

		At this point, always zero. May be used to indicate

		changes in this structure in the future.



		steal: the amount of time in which this vCPU did not run, in

	steal:

		the amount of time in which this vCPU did not run, in

		nanoseconds. Time during which the vcpu is idle, will not be

		reported as steal time.



		preempted: indicate the vCPU who owns this struct is running or

	preempted:

		indicate the vCPU who owns this struct is running or

		not. Non-zero values mean the vCPU has been preempted. Zero

		means the vCPU is not preempted. NOTE, it is always zero if the

		the hypervisor doesn't support this field.



MSR_KVM_EOI_EN: 0x4b564d04

	data: Bit 0 is 1 when PV end of interrupt is enabled on the vcpu; 0

MSR_KVM_EOI_EN:

	0x4b564d04



data:

	Bit 0 is 1 when PV end of interrupt is enabled on the vcpu; 0

	when disabled.  Bit 1 is reserved and must be zero.  When PV end of

	interrupt is enabled (bit 0 set), bits 63-2 hold a 4-byte aligned

	physical address of a 4 byte memory area which must be in guest RAM and
@@ -274,11 +309,13 @@ MSR_KVM_EOI_EN: 0x4b564d04 
	clear it using a single CPU instruction, such as test and clear, or

	compare and exchange.



MSR_KVM_POLL_CONTROL: 0x4b564d05

MSR_KVM_POLL_CONTROL:

	0x4b564d05



	Control host-side polling.



	data: Bit 0 enables (1) or disables (0) host-side HLT polling logic.

data:

	Bit 0 enables (1) or disables (0) host-side HLT polling logic.



	KVM guests can request the host not to poll on HLT, for example if

	they are performing polling themselves.

CRA Git | Maintained and supported by SUSTech CRA and CCSE