[linux-2.6-block.git] / Documentation / virtual / kvm / cpuid.rst

.. SPDX-License-Identifier: GPL-2.0

==============
KVM CPUID bits
==============

:Author: Glauber Costa <glommer@gmail.com>

A guest running on a kvm host, can check some of its features using
cpuid. This is not always guaranteed to work, since userspace can
mask-out some, or even all KVM-related cpuid features before launching
a guest.

KVM cpuid functions are:

function: KVM_CPUID_SIGNATURE (0x40000000)

returns::

   eax = 0x40000001
   ebx = 0x4b4d564b
   ecx = 0x564b4d56
   edx = 0x4d

Note that this value in ebx, ecx and edx corresponds to the string "KVMKVMKVM".
The value in eax corresponds to the maximum cpuid function present in this leaf,
and will be updated if more functions are added in the future.
Note also that old hosts set eax value to 0x0. This should
be interpreted as if the value was 0x40000001.
This function queries the presence of KVM cpuid leafs.

function: define KVM_CPUID_FEATURES (0x40000001)

returns::

          ebx, ecx
          eax = an OR'ed group of (1 << flag)

where ``flag`` is defined as below:

================================= =========== ================================
flag                              value       meaning
================================= =========== ================================
KVM_FEATURE_CLOCKSOURCE           0           kvmclock available at msrs
                                              0x11 and 0x12

KVM_FEATURE_NOP_IO_DELAY          1           not necessary to perform delays
                                              on PIO operations

KVM_FEATURE_MMU_OP                2           deprecated

KVM_FEATURE_CLOCKSOURCE2          3           kvmclock available at msrs

                                              0x4b564d00 and 0x4b564d01
KVM_FEATURE_ASYNC_PF              4           async pf can be enabled by
                                              writing to msr 0x4b564d02

KVM_FEATURE_STEAL_TIME            5           steal time can be enabled by
                                              writing to msr 0x4b564d03

KVM_FEATURE_PV_EOI                6           paravirtualized end of interrupt
                                              handler can be enabled by
                                              writing to msr 0x4b564d04

KVM_FEATURE_PV_UNHAULT            7           guest checks this feature bit
                                              before enabling paravirtualized
                                              spinlock support

KVM_FEATURE_PV_TLB_FLUSH          9           guest checks this feature bit
                                              before enabling paravirtualized
                                              tlb flush

KVM_FEATURE_ASYNC_PF_VMEXIT       10          paravirtualized async PF VM EXIT
                                              can be enabled by setting bit 2
                                              when writing to msr 0x4b564d02

KVM_FEATURE_PV_SEND_IPI           11          guest checks this feature bit
                                              before enabling paravirtualized
                                              sebd IPIs

KVM_FEATURE_PV_POLL_CONTROL       12          host-side polling on HLT can
                                              be disabled by writing
                                              to msr 0x4b564d05.

KVM_FEATURE_PV_SCHED_YIELD        13          guest checks this feature bit
                                              before using paravirtualized
                                              sched yield.

KVM_FEATURE_CLOCSOURCE_STABLE_BIT 24          host will warn if no guest-side
                                              per-cpu warps are expeced in
                                              kvmclock
================================= =========== ================================

::

      edx = an OR'ed group of (1 << flag)

Where ``flag`` here is defined as below:

================== ============ =================================
flag               value        meaning
================== ============ =================================
KVM_HINTS_REALTIME 0            guest checks this feature bit to
                                determine that vCPUs are never
                                preempted for an unlimited time
                                allowing optimizations
================== ============ =================================
Commit	Line	Data
e287d6de LNK	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	==============
	4	KVM CPUID bits
	5	==============
	6
	7	:Author: Glauber Costa <glommer@gmail.com>
	8
	9	A guest running on a kvm host, can check some of its features using
	10	cpuid. This is not always guaranteed to work, since userspace can
	11	mask-out some, or even all KVM-related cpuid features before launching
	12	a guest.
	13
	14	KVM cpuid functions are:
	15
	16	function: KVM_CPUID_SIGNATURE (0x40000000)
	17
	18	returns::
	19
	20	eax = 0x40000001
	21	ebx = 0x4b4d564b
	22	ecx = 0x564b4d56
	23	edx = 0x4d
	24
	25	Note that this value in ebx, ecx and edx corresponds to the string "KVMKVMKVM".
	26	The value in eax corresponds to the maximum cpuid function present in this leaf,
	27	and will be updated if more functions are added in the future.
	28	Note also that old hosts set eax value to 0x0. This should
	29	be interpreted as if the value was 0x40000001.
	30	This function queries the presence of KVM cpuid leafs.
	31
	32	function: define KVM_CPUID_FEATURES (0x40000001)
	33
	34	returns::
	35
	36	ebx, ecx
	37	eax = an OR'ed group of (1 << flag)
	38
	39	where ``flag`` is defined as below:
	40
	41	================================= =========== ================================
	42	flag value meaning
	43	================================= =========== ================================
	44	KVM_FEATURE_CLOCKSOURCE 0 kvmclock available at msrs
	45	0x11 and 0x12
	46
	47	KVM_FEATURE_NOP_IO_DELAY 1 not necessary to perform delays
	48	on PIO operations
	49
	50	KVM_FEATURE_MMU_OP 2 deprecated
	51
	52	KVM_FEATURE_CLOCKSOURCE2 3 kvmclock available at msrs
	53
	54	0x4b564d00 and 0x4b564d01
	55	KVM_FEATURE_ASYNC_PF 4 async pf can be enabled by
	56	writing to msr 0x4b564d02
	57
	58	KVM_FEATURE_STEAL_TIME 5 steal time can be enabled by
	59	writing to msr 0x4b564d03
	60
	61	KVM_FEATURE_PV_EOI 6 paravirtualized end of interrupt
	62	handler can be enabled by
	63	writing to msr 0x4b564d04
	64
65	KVM_FEATURE_PV_UNHAULT 7 guest checks this feature bit
66	before enabling paravirtualized
67	spinlock support
68
69	KVM_FEATURE_PV_TLB_FLUSH 9 guest checks this feature bit
70	before enabling paravirtualized
71	tlb flush
72
73	KVM_FEATURE_ASYNC_PF_VMEXIT 10 paravirtualized async PF VM EXIT
74	can be enabled by setting bit 2
75	when writing to msr 0x4b564d02
76
77	KVM_FEATURE_PV_SEND_IPI 11 guest checks this feature bit
78	before enabling paravirtualized
79	sebd IPIs
80
81	KVM_FEATURE_PV_POLL_CONTROL 12 host-side polling on HLT can
82	be disabled by writing
83	to msr 0x4b564d05.
84
85	KVM_FEATURE_PV_SCHED_YIELD 13 guest checks this feature bit
86	before using paravirtualized
87	sched yield.
88
89	KVM_FEATURE_CLOCSOURCE_STABLE_BIT 24 host will warn if no guest-side
90	per-cpu warps are expeced in
91	kvmclock
92	================================= =========== ================================
93
94	::
95
96	edx = an OR'ed group of (1 << flag)
97
98	Where ``flag`` here is defined as below:
99
100	================== ============ =================================
101	flag value meaning
102	================== ============ =================================
103	KVM_HINTS_REALTIME 0 guest checks this feature bit to
104	determine that vCPUs are never
105	preempted for an unlimited time
106	allowing optimizations
107	================== ============ =================================