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
8 space code in PR=1 which is user space. This w
9 instructions and can emulate them accordingly.
10
11 Unfortunately that is also the downfall. There
12 instructions that needlessly return us to the
13 could be handled differently.
14
15 This is what the PPC PV interface helps with.
16 and transforms them into unprivileged ones wit
17 This cuts down virtualization costs by about 5
18
19 The code for that interface can be found in ar
20
21 Querying for existence
22 ======================
23
24 To find out if we're running on KVM or not, we
25 Linux is running on KVM, a node /hypervisor ex
26 compatible property with the value "linux,kvm"
27
28 Once you determined you're running under a PV
29 hypercalls as described below.
30
31 KVM hypercalls
32 ==============
33
34 Inside the device tree's /hypervisor node ther
35 'hypercall-instructions'. This property contai
36 up the hypercall. To call a hypercall, just ca
37
38 The parameters are as follows:
39
40 ======== ================
41 Register IN
42 ======== ================
43 r0 -
44 r3 1st parameter
45 r4 2nd parameter
46 r5 3rd parameter
47 r6 4th parameter
48 r7 5th parameter
49 r8 6th parameter
50 r9 7th parameter
51 r10 8th parameter
52 r11 hypercall number
53 r12 -
54 ======== ================
55
56 Hypercall definitions are shared in generic co
57 apply for x86 and powerpc alike with the excep
58 also needs to be ORed with the KVM vendor code
59
60 Return codes can be as follows:
61
62 ==== ======================
63 Code Meaning
64 ==== ======================
65 0 Success
66 12 Hypercall not implemen
67 <0 Error
68 ==== ======================
69
70 The magic page
71 ==============
72
73 To enable communication between the hypervisor
74 page that contains parts of supervisor visible
75 map this shared page using the KVM hypercall K
76
77 With this hypercall issued the guest always ge
78 desired location. The first parameter indicate
79 MMU is enabled. The second parameter indicates
80 applicable to the target. For now, we always m
81 can access it using absolute load and store fu
82 instruction reads the first field of the magic
83
84 ld rX, -4096(0)
85
86 The interface is designed to be extensible sho
87 additional registers to the magic page. If you
88 also define a new hypercall feature to indicat
89 registers. Only if the host supports the addit
90
91 The magic page layout is described by struct k
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 hype
98 a second return value is passed to the guest.
99 a bitmap of available features inside the magi
100
101 The following enhancements to the magic page a
102
103 ============================ ==============
104 KVM_MAGIC_FEAT_SR Maps SR regist
105 KVM_MAGIC_FEAT_MAS0_TO_SPRG7 Maps MASn, ESR
106 ============================ ==============
107
108 For enhanced features in the magic page, pleas
109 feature before using them!
110
111 Magic page flags
112 ================
113
114 In addition to features that indicate whether
115 feature we also have a channel for a guest to
116 of something. This is what we call "flags".
117
118 Flags are passed to the host in the low 12 bit
119
120 The following flags are currently available fo
121
122 MAGIC_PAGE_FLAG_NOT_MAPPED_NX Guest handles
123
124 MSR bits
125 ========
126
127 The MSR contains bits that require hypervisor
128 not require direct hypervisor intervention bec
129 when entering the guest or don't have any impa
130
131 The following bits are safe to be set inside t
132
133 - MSR_EE
134 - MSR_RI
135
136 If any other bit changes in the MSR, please st
137
138 Patched instructions
139 ====================
140
141 The "ld" and "std" instructions are transforme
142 respectively on 32-bit systems with an added o
143 endianness.
144
145 The following is a list of mapping the Linux k
146 guest. Implementing any of those mappings is o
147 also act on the shared page. So calling privil
148 before.
149
150 ======================= ======================
151 From To
152 ======================= ======================
153 mfmsr rX ld rX, magic_page
154 mfsprg rX, 0 ld rX, magic_page
155 mfsprg rX, 1 ld rX, magic_page
156 mfsprg rX, 2 ld rX, magic_page
157 mfsprg rX, 3 ld rX, magic_page
158 mfsrr0 rX ld rX, magic_page
159 mfsrr1 rX ld rX, magic_page
160 mfdar rX ld rX, magic_page
161 mfdsisr rX lwz rX, magic_page
162
163 mtmsr rX std rX, magic_page
164 mtsprg 0, rX std rX, magic_page
165 mtsprg 1, rX std rX, magic_page
166 mtsprg 2, rX std rX, magic_page
167 mtsprg 3, rX std rX, magic_page
168 mtsrr0 rX std rX, magic_page
169 mtsrr1 rX std rX, magic_page
170 mtdar rX std rX, magic_page
171 mtdsisr rX stw rX, magic_page
172
173 tlbsync nop
174
175 mtmsrd rX, 0 b <special mtmsr
176 mtmsr rX b <special mtmsr
177
178 mtmsrd rX, 1 b <special mtmsr
179
180 [Book3S only]
181 mtsrin rX, rY b <special mtsri
182
183 [BookE only]
184 wrteei [0|1] b <special wrtee
185 ======================= ======================
186
187 Some instructions require more logic to determ
188 or store instruction can deliver. To enable pa
189 RAM around where we can live translate instruc
190 following:
191
192 1) copy emulation code to memory
193 2) patch that code to fit the emulated
194 3) patch that code to return to the or
195 4) patch the original instruction to b
196
197 That way we can inject an arbitrary amount of
198 instruction. This allows us to check for pendi
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 implementa
207 generic hypercalls are implemented here, like
208 available on all targets.
209
210 2) PAPR hypercalls
211
212 PAPR hypercalls are needed to run server Power
213 These are the same hypercalls that pHyp, the P
214 them are handled in the kernel, some are handl
215 available on book3s_64.
216
217 3) OSI hypercalls
218
219 Mac-on-Linux is another user of KVM on PowerPC
220 before KVM). This is supported to maintain com
221 forwarded to user space. This is only useful o
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.