Documentation/virt/kvm/ppc-pv.rst

   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.