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