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