1 .. SPDX-License-Identifier: GPL-2.0
2
3 ===================
4 Linux KVM Hypercall
5 ===================
6
7 X86:
8 KVM Hypercalls have a three-byte sequence of
9 instruction. The hypervisor can replace it wi
10 guaranteed to be supported.
11
12 Up to four arguments may be passed in rbx, rc
13 The hypercall number should be placed in rax
14 placed in rax. No other registers will be cl
15 by the particular hypercall.
16
17 S390:
18 R2-R7 are used for parameters 1-6. In additi
19 number. The return value is written to R2.
20
21 S390 uses diagnose instruction as hypercall
22 number in R1.
23
24 For further information on the S390 diagnose
25 refer to Documentation/virt/kvm/s390/s390-di
26
27 PowerPC:
28 It uses R3-R10 and hypercall number in R11.
29 Return value is placed in R3.
30
31 KVM hypercalls uses 4 byte opcode, that are
32 property inside the device tree's /hyperviso
33 For more information refer to Documentation/
34
35 MIPS:
36 KVM hypercalls use the HYPCALL instruction w
37 number in $2 (v0). Up to four arguments may
38 the return value is placed in $2 (v0).
39
40 KVM Hypercalls Documentation
41 ============================
42
43 The template for each hypercall is:
44 1. Hypercall name.
45 2. Architecture(s)
46 3. Status (deprecated, obsolete, active)
47 4. Purpose
48
49 1. KVM_HC_VAPIC_POLL_IRQ
50 ------------------------
51
52 :Architecture: x86
53 :Status: active
54 :Purpose: Trigger guest exit so that the host
55 interrupts on reentry.
56
57 2. KVM_HC_MMU_OP
58 ----------------
59
60 :Architecture: x86
61 :Status: deprecated.
62 :Purpose: Support MMU operations such as writi
63 flushing TLB, release PT.
64
65 3. KVM_HC_FEATURES
66 ------------------
67
68 :Architecture: PPC
69 :Status: active
70 :Purpose: Expose hypercall availability to the
71 used to enumerate which hypercalls a
72 device tree based lookup ( which is
73 OR KVM specific enumeration mechanis
74 can be used.
75
76 4. KVM_HC_PPC_MAP_MAGIC_PAGE
77 ----------------------------
78
79 :Architecture: PPC
80 :Status: active
81 :Purpose: To enable communication between the
82 shared page that contains parts of s
83 The guest can map this shared page t
84 through memory using this hypercall.
85
86 5. KVM_HC_KICK_CPU
87 ------------------
88
89 :Architecture: x86
90 :Status: active
91 :Purpose: Hypercall used to wakeup a vcpu from
92 :Usage example:
93 A vcpu of a paravirtualized guest that is bu
94 kernel mode for an event to occur (ex: a spi
95 execute HLT instruction once it has busy-wai
96 time-interval. Execution of HLT instruction
97 the vcpu to sleep until occurrence of an app
98 same guest can wakeup the sleeping vcpu by i
99 specifying APIC ID (a1) of the vcpu to be wo
100 is used in the hypercall for future use.
101
102
103 6. KVM_HC_CLOCK_PAIRING
104 -----------------------
105 :Architecture: x86
106 :Status: active
107 :Purpose: Hypercall used to synchronize host a
108
109 Usage:
110
111 a0: guest physical address where host copies
112 "struct kvm_clock_offset" structure.
113
114 a1: clock_type, ATM only KVM_CLOCK_PAIRING_WAL
115 is supported (corresponding to the host's CLOC
116
117 ::
118
119 struct kvm_clock_pairing {
120 __s64 sec;
121 __s64 nsec;
122 __u64 tsc;
123 __u32 flags;
124 __u32 pad[9];
125 };
126
127 Where:
128 * sec: seconds from clock_type
129 * nsec: nanoseconds from clock_
130 * tsc: guest TSC value used to
131 * flags: flags, unused (0) at t
132
133 The hypercall lets a guest compute a precise t
134 host and guest. The guest can use the returne
135 compute the CLOCK_REALTIME for its clock, at t
136
137 Returns KVM_EOPNOTSUPP if the host does not us
138 or if clock type is different than KVM_CLOCK_P
139
140 6. KVM_HC_SEND_IPI
141 ------------------
142
143 :Architecture: x86
144 :Status: active
145 :Purpose: Send IPIs to multiple vCPUs.
146
147 - a0: lower part of the bitmap of destination
148 - a1: higher part of the bitmap of destination
149 - a2: the lowest APIC ID in bitmap
150 - a3: APIC ICR
151
152 The hypercall lets a guest send multicast IPIs
153 128 destinations per hypercall in 64-bit mode
154 hypercall in 32-bit mode. The destinations ar
155 bitmap contained in the first two arguments (a
156 a0 corresponds to the APIC ID in the third arg
157 corresponds to the APIC ID a2+1, and so on.
158
159 Returns the number of CPUs to which the IPIs w
160
161 7. KVM_HC_SCHED_YIELD
162 ---------------------
163
164 :Architecture: x86
165 :Status: active
166 :Purpose: Hypercall used to yield if the IPI t
167
168 a0: destination APIC ID
169
170 :Usage example: When sending a call-function I
171 any of the IPI target vCPUs wa
172
173 8. KVM_HC_MAP_GPA_RANGE
174 -------------------------
175 :Architecture: x86
176 :Status: active
177 :Purpose: Request KVM to map a GPA range with
178
179 a0: the guest physical address of the start pa
180 a1: the number of (4kb) pages (must be contigu
181 a2: attributes
182
183 Where 'attributes' :
184 * bits 3:0 - preferred page size enco
185 * bit 4 - plaintext = 0, encrypted
186 * bits 63:5 - reserved (must be zero)
187
188 **Implementation note**: this hypercall is imp
189 the KVM_CAP_EXIT_HYPERCALL capability. Userspa
190 before advertising KVM_FEATURE_HC_MAP_GPA_RANG
191 addition, if the guest supports KVM_FEATURE_MI
192 must also set up an MSR filter to process writ
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.