1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ================================= 3 =================================
4 The PPC KVM paravirtual interface 4 The PPC KVM paravirtual interface
5 ================================= 5 =================================
6 6
7 The basic execution principle by which KVM on 7 The basic execution principle by which KVM on PowerPC works is to run all kernel
8 space code in PR=1 which is user space. This w 8 space code in PR=1 which is user space. This way we trap all privileged
9 instructions and can emulate them accordingly. 9 instructions and can emulate them accordingly.
10 10
11 Unfortunately that is also the downfall. There 11 Unfortunately that is also the downfall. There are quite some privileged
12 instructions that needlessly return us to the 12 instructions that needlessly return us to the hypervisor even though they
13 could be handled differently. 13 could be handled differently.
14 14
15 This is what the PPC PV interface helps with. 15 This is what the PPC PV interface helps with. It takes privileged instructions
16 and transforms them into unprivileged ones wit 16 and transforms them into unprivileged ones with some help from the hypervisor.
17 This cuts down virtualization costs by about 5 17 This cuts down virtualization costs by about 50% on some of my benchmarks.
18 18
19 The code for that interface can be found in ar 19 The code for that interface can be found in arch/powerpc/kernel/kvm*
20 20
21 Querying for existence 21 Querying for existence
22 ====================== 22 ======================
23 23
24 To find out if we're running on KVM or not, we 24 To find out if we're running on KVM or not, we leverage the device tree. When
25 Linux is running on KVM, a node /hypervisor ex 25 Linux is running on KVM, a node /hypervisor exists. That node contains a
26 compatible property with the value "linux,kvm" 26 compatible property with the value "linux,kvm".
27 27
28 Once you determined you're running under a PV 28 Once you determined you're running under a PV capable KVM, you can now use
29 hypercalls as described below. 29 hypercalls as described below.
30 30
31 KVM hypercalls 31 KVM hypercalls
32 ============== 32 ==============
33 33
34 Inside the device tree's /hypervisor node ther 34 Inside the device tree's /hypervisor node there's a property called
35 'hypercall-instructions'. This property contai 35 'hypercall-instructions'. This property contains at most 4 opcodes that make
36 up the hypercall. To call a hypercall, just ca 36 up the hypercall. To call a hypercall, just call these instructions.
37 37
38 The parameters are as follows: 38 The parameters are as follows:
39 39
40 ======== ================ 40 ======== ================ ================
41 Register IN 41 Register IN OUT
42 ======== ================ 42 ======== ================ ================
43 r0 - 43 r0 - volatile
44 r3 1st parameter 44 r3 1st parameter Return code
45 r4 2nd parameter 45 r4 2nd parameter 1st output value
46 r5 3rd parameter 46 r5 3rd parameter 2nd output value
47 r6 4th parameter 47 r6 4th parameter 3rd output value
48 r7 5th parameter 48 r7 5th parameter 4th output value
49 r8 6th parameter 49 r8 6th parameter 5th output value
50 r9 7th parameter 50 r9 7th parameter 6th output value
51 r10 8th parameter 51 r10 8th parameter 7th output value
52 r11 hypercall number 52 r11 hypercall number 8th output value
53 r12 - 53 r12 - volatile
54 ======== ================ 54 ======== ================ ================
55 55
56 Hypercall definitions are shared in generic co 56 Hypercall definitions are shared in generic code, so the same hypercall numbers
57 apply for x86 and powerpc alike with the excep 57 apply for x86 and powerpc alike with the exception that each KVM hypercall
58 also needs to be ORed with the KVM vendor code 58 also needs to be ORed with the KVM vendor code which is (42 << 16).
59 59
60 Return codes can be as follows: 60 Return codes can be as follows:
61 61
62 ==== ====================== 62 ==== =========================
63 Code Meaning 63 Code Meaning
64 ==== ====================== 64 ==== =========================
65 0 Success 65 0 Success
66 12 Hypercall not implemen 66 12 Hypercall not implemented
67 <0 Error 67 <0 Error
68 ==== ====================== 68 ==== =========================
69 69
70 The magic page 70 The magic page
71 ============== 71 ==============
72 72
73 To enable communication between the hypervisor 73 To enable communication between the hypervisor and guest there is a new shared
74 page that contains parts of supervisor visible 74 page that contains parts of supervisor visible register state. The guest can
75 map this shared page using the KVM hypercall K 75 map this shared page using the KVM hypercall KVM_HC_PPC_MAP_MAGIC_PAGE.
76 76
77 With this hypercall issued the guest always ge 77 With this hypercall issued the guest always gets the magic page mapped at the
78 desired location. The first parameter indicate 78 desired location. The first parameter indicates the effective address when the
79 MMU is enabled. The second parameter indicates 79 MMU is enabled. The second parameter indicates the address in real mode, if
80 applicable to the target. For now, we always m 80 applicable to the target. For now, we always map the page to -4096. This way we
81 can access it using absolute load and store fu 81 can access it using absolute load and store functions. The following
82 instruction reads the first field of the magic 82 instruction reads the first field of the magic page::
83 83
84 ld rX, -4096(0) 84 ld rX, -4096(0)
85 85
86 The interface is designed to be extensible sho 86 The interface is designed to be extensible should there be need later to add
87 additional registers to the magic page. If you 87 additional registers to the magic page. If you add fields to the magic page,
88 also define a new hypercall feature to indicat 88 also define a new hypercall feature to indicate that the host can give you more
89 registers. Only if the host supports the addit 89 registers. Only if the host supports the additional features, make use of them.
90 90
91 The magic page layout is described by struct k 91 The magic page layout is described by struct kvm_vcpu_arch_shared
92 in arch/powerpc/include/uapi/asm/kvm_para.h. 92 in arch/powerpc/include/uapi/asm/kvm_para.h.
93 93
94 Magic page features 94 Magic page features
95 =================== 95 ===================
96 96
97 When mapping the magic page using the KVM hype 97 When mapping the magic page using the KVM hypercall KVM_HC_PPC_MAP_MAGIC_PAGE,
98 a second return value is passed to the guest. 98 a second return value is passed to the guest. This second return value contains
99 a bitmap of available features inside the magi 99 a bitmap of available features inside the magic page.
100 100
101 The following enhancements to the magic page a 101 The following enhancements to the magic page are currently available:
102 102
103 ============================ ============== 103 ============================ =======================================
104 KVM_MAGIC_FEAT_SR Maps SR regist 104 KVM_MAGIC_FEAT_SR Maps SR registers r/w in the magic page
105 KVM_MAGIC_FEAT_MAS0_TO_SPRG7 Maps MASn, ESR 105 KVM_MAGIC_FEAT_MAS0_TO_SPRG7 Maps MASn, ESR, PIR and high SPRGs
106 ============================ ============== 106 ============================ =======================================
107 107
108 For enhanced features in the magic page, pleas 108 For enhanced features in the magic page, please check for the existence of the
109 feature before using them! 109 feature before using them!
110 110
111 Magic page flags 111 Magic page flags
112 ================ 112 ================
113 113
114 In addition to features that indicate whether 114 In addition to features that indicate whether a host is capable of a particular
115 feature we also have a channel for a guest to 115 feature we also have a channel for a guest to tell the host whether it's capable
116 of something. This is what we call "flags". 116 of something. This is what we call "flags".
117 117
118 Flags are passed to the host in the low 12 bit 118 Flags are passed to the host in the low 12 bits of the Effective Address.
119 119
120 The following flags are currently available fo 120 The following flags are currently available for a guest to expose:
121 121
122 MAGIC_PAGE_FLAG_NOT_MAPPED_NX Guest handles 122 MAGIC_PAGE_FLAG_NOT_MAPPED_NX Guest handles NX bits correctly wrt magic page
123 123
124 MSR bits 124 MSR bits
125 ======== 125 ========
126 126
127 The MSR contains bits that require hypervisor 127 The MSR contains bits that require hypervisor intervention and bits that do
128 not require direct hypervisor intervention bec 128 not require direct hypervisor intervention because they only get interpreted
129 when entering the guest or don't have any impa 129 when entering the guest or don't have any impact on the hypervisor's behavior.
130 130
131 The following bits are safe to be set inside t 131 The following bits are safe to be set inside the guest:
132 132
133 - MSR_EE 133 - MSR_EE
134 - MSR_RI 134 - MSR_RI
135 135
136 If any other bit changes in the MSR, please st 136 If any other bit changes in the MSR, please still use mtmsr(d).
137 137
138 Patched instructions 138 Patched instructions
139 ==================== 139 ====================
140 140
141 The "ld" and "std" instructions are transforme 141 The "ld" and "std" instructions are transformed to "lwz" and "stw" instructions
142 respectively on 32-bit systems with an added o 142 respectively on 32-bit systems with an added offset of 4 to accommodate for big
143 endianness. 143 endianness.
144 144
145 The following is a list of mapping the Linux k 145 The following is a list of mapping the Linux kernel performs when running as
146 guest. Implementing any of those mappings is o 146 guest. Implementing any of those mappings is optional, as the instruction traps
147 also act on the shared page. So calling privil 147 also act on the shared page. So calling privileged instructions still works as
148 before. 148 before.
149 149
150 ======================= ====================== 150 ======================= ================================
151 From To 151 From To
152 ======================= ====================== 152 ======================= ================================
153 mfmsr rX ld rX, magic_page 153 mfmsr rX ld rX, magic_page->msr
154 mfsprg rX, 0 ld rX, magic_page 154 mfsprg rX, 0 ld rX, magic_page->sprg0
155 mfsprg rX, 1 ld rX, magic_page 155 mfsprg rX, 1 ld rX, magic_page->sprg1
156 mfsprg rX, 2 ld rX, magic_page 156 mfsprg rX, 2 ld rX, magic_page->sprg2
157 mfsprg rX, 3 ld rX, magic_page 157 mfsprg rX, 3 ld rX, magic_page->sprg3
158 mfsrr0 rX ld rX, magic_page 158 mfsrr0 rX ld rX, magic_page->srr0
159 mfsrr1 rX ld rX, magic_page 159 mfsrr1 rX ld rX, magic_page->srr1
160 mfdar rX ld rX, magic_page 160 mfdar rX ld rX, magic_page->dar
161 mfdsisr rX lwz rX, magic_page 161 mfdsisr rX lwz rX, magic_page->dsisr
162 162
163 mtmsr rX std rX, magic_page 163 mtmsr rX std rX, magic_page->msr
164 mtsprg 0, rX std rX, magic_page 164 mtsprg 0, rX std rX, magic_page->sprg0
165 mtsprg 1, rX std rX, magic_page 165 mtsprg 1, rX std rX, magic_page->sprg1
166 mtsprg 2, rX std rX, magic_page 166 mtsprg 2, rX std rX, magic_page->sprg2
167 mtsprg 3, rX std rX, magic_page 167 mtsprg 3, rX std rX, magic_page->sprg3
168 mtsrr0 rX std rX, magic_page 168 mtsrr0 rX std rX, magic_page->srr0
169 mtsrr1 rX std rX, magic_page 169 mtsrr1 rX std rX, magic_page->srr1
170 mtdar rX std rX, magic_page 170 mtdar rX std rX, magic_page->dar
171 mtdsisr rX stw rX, magic_page 171 mtdsisr rX stw rX, magic_page->dsisr
172 172
173 tlbsync nop 173 tlbsync nop
174 174
175 mtmsrd rX, 0 b <special mtmsr 175 mtmsrd rX, 0 b <special mtmsr section>
176 mtmsr rX b <special mtmsr 176 mtmsr rX b <special mtmsr section>
177 177
178 mtmsrd rX, 1 b <special mtmsr 178 mtmsrd rX, 1 b <special mtmsrd section>
179 179
180 [Book3S only] 180 [Book3S only]
181 mtsrin rX, rY b <special mtsri 181 mtsrin rX, rY b <special mtsrin section>
182 182
183 [BookE only] 183 [BookE only]
184 wrteei [0|1] b <special wrtee 184 wrteei [0|1] b <special wrteei section>
185 ======================= ====================== 185 ======================= ================================
186 186
187 Some instructions require more logic to determ 187 Some instructions require more logic to determine what's going on than a load
188 or store instruction can deliver. To enable pa 188 or store instruction can deliver. To enable patching of those, we keep some
189 RAM around where we can live translate instruc 189 RAM around where we can live translate instructions to. What happens is the
190 following: 190 following:
191 191
192 1) copy emulation code to memory 192 1) copy emulation code to memory
193 2) patch that code to fit the emulated 193 2) patch that code to fit the emulated instruction
194 3) patch that code to return to the or 194 3) patch that code to return to the original pc + 4
195 4) patch the original instruction to b 195 4) patch the original instruction to branch to the new code
196 196
197 That way we can inject an arbitrary amount of 197 That way we can inject an arbitrary amount of code as replacement for a single
198 instruction. This allows us to check for pendi 198 instruction. This allows us to check for pending interrupts when setting EE=1
199 for example. 199 for example.
200 200
201 Hypercall ABIs in KVM on PowerPC 201 Hypercall ABIs in KVM on PowerPC
202 ================================= 202 =================================
203 203
204 1) KVM hypercalls (ePAPR) 204 1) KVM hypercalls (ePAPR)
205 205
206 These are ePAPR compliant hypercall implementa 206 These are ePAPR compliant hypercall implementation (mentioned above). Even
207 generic hypercalls are implemented here, like 207 generic hypercalls are implemented here, like the ePAPR idle hcall. These are
208 available on all targets. 208 available on all targets.
209 209
210 2) PAPR hypercalls 210 2) PAPR hypercalls
211 211
212 PAPR hypercalls are needed to run server Power 212 PAPR hypercalls are needed to run server PowerPC PAPR guests (-M pseries in QEMU).
213 These are the same hypercalls that pHyp, the P 213 These are the same hypercalls that pHyp, the POWER hypervisor, implements. Some of
214 them are handled in the kernel, some are handl 214 them are handled in the kernel, some are handled in user space. This is only
215 available on book3s_64. 215 available on book3s_64.
216 216
217 3) OSI hypercalls 217 3) OSI hypercalls
218 218
219 Mac-on-Linux is another user of KVM on PowerPC 219 Mac-on-Linux is another user of KVM on PowerPC, which has its own hypercall (long
220 before KVM). This is supported to maintain com 220 before KVM). This is supported to maintain compatibility. All these hypercalls get
221 forwarded to user space. This is only useful o 221 forwarded to user space. This is only useful on book3s_32, but can be used with
222 book3s_64 as well. 222 book3s_64 as well.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.