Commit | Line | Data |
---|---|---|
250c6c31 | 1 | .. SPDX-License-Identifier: GPL-2.0 |
ad9b48c5 | 2 | .. _ultravisor: |
250c6c31 SB |
3 | |
4 | ============================ | |
5 | Protected Execution Facility | |
6 | ============================ | |
7 | ||
8 | .. contents:: | |
9 | :depth: 3 | |
10 | ||
c44166fe MCC |
11 | Introduction |
12 | ############ | |
250c6c31 SB |
13 | |
14 | Protected Execution Facility (PEF) is an architectural change for | |
15 | POWER 9 that enables Secure Virtual Machines (SVMs). DD2.3 chips | |
16 | (PVR=0x004e1203) or greater will be PEF-capable. A new ISA release | |
17 | will include the PEF RFC02487 changes. | |
18 | ||
19 | When enabled, PEF adds a new higher privileged mode, called Ultravisor | |
20 | mode, to POWER architecture. Along with the new mode there is new | |
21 | firmware called the Protected Execution Ultravisor (or Ultravisor | |
22 | for short). Ultravisor mode is the highest privileged mode in POWER | |
23 | architecture. | |
24 | ||
25 | +------------------+ | |
26 | | Privilege States | | |
27 | +==================+ | |
28 | | Problem | | |
29 | +------------------+ | |
30 | | Supervisor | | |
31 | +------------------+ | |
32 | | Hypervisor | | |
33 | +------------------+ | |
34 | | Ultravisor | | |
35 | +------------------+ | |
36 | ||
37 | PEF protects SVMs from the hypervisor, privileged users, and other | |
38 | VMs in the system. SVMs are protected while at rest and can only be | |
39 | executed by an authorized machine. All virtual machines utilize | |
40 | hypervisor services. The Ultravisor filters calls between the SVMs | |
41 | and the hypervisor to assure that information does not accidentally | |
42 | leak. All hypercalls except H_RANDOM are reflected to the hypervisor. | |
43 | H_RANDOM is not reflected to prevent the hypervisor from influencing | |
44 | random values in the SVM. | |
45 | ||
46 | To support this there is a refactoring of the ownership of resources | |
47 | in the CPU. Some of the resources which were previously hypervisor | |
48 | privileged are now ultravisor privileged. | |
49 | ||
50 | Hardware | |
51 | ======== | |
52 | ||
53 | The hardware changes include the following: | |
54 | ||
55 | * There is a new bit in the MSR that determines whether the current | |
56 | process is running in secure mode, MSR(S) bit 41. MSR(S)=1, process | |
57 | is in secure mode, MSR(s)=0 process is in normal mode. | |
58 | ||
59 | * The MSR(S) bit can only be set by the Ultravisor. | |
60 | ||
61 | * HRFID cannot be used to set the MSR(S) bit. If the hypervisor needs | |
62 | to return to a SVM it must use an ultracall. It can determine if | |
63 | the VM it is returning to is secure. | |
64 | ||
65 | * There is a new Ultravisor privileged register, SMFCTRL, which has an | |
66 | enable/disable bit SMFCTRL(E). | |
67 | ||
68 | * The privilege of a process is now determined by three MSR bits, | |
69 | MSR(S, HV, PR). In each of the tables below the modes are listed | |
70 | from least privilege to highest privilege. The higher privilege | |
71 | modes can access all the resources of the lower privilege modes. | |
72 | ||
73 | **Secure Mode MSR Settings** | |
74 | ||
75 | +---+---+---+---------------+ | |
76 | | S | HV| PR|Privilege | | |
77 | +===+===+===+===============+ | |
78 | | 1 | 0 | 1 | Problem | | |
79 | +---+---+---+---------------+ | |
80 | | 1 | 0 | 0 | Privileged(OS)| | |
81 | +---+---+---+---------------+ | |
82 | | 1 | 1 | 0 | Ultravisor | | |
83 | +---+---+---+---------------+ | |
84 | | 1 | 1 | 1 | Reserved | | |
85 | +---+---+---+---------------+ | |
86 | ||
87 | **Normal Mode MSR Settings** | |
88 | ||
89 | +---+---+---+---------------+ | |
90 | | S | HV| PR|Privilege | | |
91 | +===+===+===+===============+ | |
92 | | 0 | 0 | 1 | Problem | | |
93 | +---+---+---+---------------+ | |
94 | | 0 | 0 | 0 | Privileged(OS)| | |
95 | +---+---+---+---------------+ | |
96 | | 0 | 1 | 0 | Hypervisor | | |
97 | +---+---+---+---------------+ | |
98 | | 0 | 1 | 1 | Problem (Host)| | |
99 | +---+---+---+---------------+ | |
100 | ||
101 | * Memory is partitioned into secure and normal memory. Only processes | |
102 | that are running in secure mode can access secure memory. | |
103 | ||
104 | * The hardware does not allow anything that is not running secure to | |
105 | access secure memory. This means that the Hypervisor cannot access | |
106 | the memory of the SVM without using an ultracall (asking the | |
107 | Ultravisor). The Ultravisor will only allow the hypervisor to see | |
108 | the SVM memory encrypted. | |
109 | ||
110 | * I/O systems are not allowed to directly address secure memory. This | |
111 | limits the SVMs to virtual I/O only. | |
112 | ||
113 | * The architecture allows the SVM to share pages of memory with the | |
114 | hypervisor that are not protected with encryption. However, this | |
115 | sharing must be initiated by the SVM. | |
116 | ||
117 | * When a process is running in secure mode all hypercalls | |
118 | (syscall lev=1) go to the Ultravisor. | |
119 | ||
120 | * When a process is in secure mode all interrupts go to the | |
121 | Ultravisor. | |
122 | ||
123 | * The following resources have become Ultravisor privileged and | |
124 | require an Ultravisor interface to manipulate: | |
125 | ||
126 | * Processor configurations registers (SCOMs). | |
127 | ||
128 | * Stop state information. | |
129 | ||
130 | * The debug registers CIABR, DAWR, and DAWRX when SMFCTRL(D) is set. | |
131 | If SMFCTRL(D) is not set they do not work in secure mode. When set, | |
132 | reading and writing requires an Ultravisor call, otherwise that | |
133 | will cause a Hypervisor Emulation Assistance interrupt. | |
134 | ||
135 | * PTCR and partition table entries (partition table is in secure | |
136 | memory). An attempt to write to PTCR will cause a Hypervisor | |
137 | Emulation Assitance interrupt. | |
138 | ||
139 | * LDBAR (LD Base Address Register) and IMC (In-Memory Collection) | |
140 | non-architected registers. An attempt to write to them will cause a | |
141 | Hypervisor Emulation Assistance interrupt. | |
142 | ||
143 | * Paging for an SVM, sharing of memory with Hypervisor for an SVM. | |
144 | (Including Virtual Processor Area (VPA) and virtual I/O). | |
145 | ||
146 | ||
147 | Software/Microcode | |
148 | ================== | |
149 | ||
150 | The software changes include: | |
151 | ||
152 | * SVMs are created from normal VM using (open source) tooling supplied | |
153 | by IBM. | |
154 | ||
155 | * All SVMs start as normal VMs and utilize an ultracall, UV_ESM | |
156 | (Enter Secure Mode), to make the transition. | |
157 | ||
158 | * When the UV_ESM ultracall is made the Ultravisor copies the VM into | |
159 | secure memory, decrypts the verification information, and checks the | |
160 | integrity of the SVM. If the integrity check passes the Ultravisor | |
161 | passes control in secure mode. | |
162 | ||
163 | * The verification information includes the pass phrase for the | |
164 | encrypted disk associated with the SVM. This pass phrase is given | |
165 | to the SVM when requested. | |
166 | ||
167 | * The Ultravisor is not involved in protecting the encrypted disk of | |
168 | the SVM while at rest. | |
169 | ||
170 | * For external interrupts the Ultravisor saves the state of the SVM, | |
171 | and reflects the interrupt to the hypervisor for processing. | |
172 | For hypercalls, the Ultravisor inserts neutral state into all | |
173 | registers not needed for the hypercall then reflects the call to | |
174 | the hypervisor for processing. The H_RANDOM hypercall is performed | |
175 | by the Ultravisor and not reflected. | |
176 | ||
177 | * For virtual I/O to work bounce buffering must be done. | |
178 | ||
179 | * The Ultravisor uses AES (IAPM) for protection of SVM memory. IAPM | |
180 | is a mode of AES that provides integrity and secrecy concurrently. | |
181 | ||
182 | * The movement of data between normal and secure pages is coordinated | |
183 | with the Ultravisor by a new HMM plug-in in the Hypervisor. | |
184 | ||
185 | The Ultravisor offers new services to the hypervisor and SVMs. These | |
186 | are accessed through ultracalls. | |
187 | ||
188 | Terminology | |
189 | =========== | |
190 | ||
191 | * Hypercalls: special system calls used to request services from | |
192 | Hypervisor. | |
193 | ||
194 | * Normal memory: Memory that is accessible to Hypervisor. | |
195 | ||
196 | * Normal page: Page backed by normal memory and available to | |
197 | Hypervisor. | |
198 | ||
199 | * Shared page: A page backed by normal memory and available to both | |
200 | the Hypervisor/QEMU and the SVM (i.e page has mappings in SVM and | |
201 | Hypervisor/QEMU). | |
202 | ||
203 | * Secure memory: Memory that is accessible only to Ultravisor and | |
204 | SVMs. | |
205 | ||
206 | * Secure page: Page backed by secure memory and only available to | |
207 | Ultravisor and SVM. | |
208 | ||
209 | * SVM: Secure Virtual Machine. | |
210 | ||
211 | * Ultracalls: special system calls used to request services from | |
212 | Ultravisor. | |
213 | ||
214 | ||
215 | Ultravisor calls API | |
216 | #################### | |
217 | ||
218 | This section describes Ultravisor calls (ultracalls) needed to | |
219 | support Secure Virtual Machines (SVM)s and Paravirtualized KVM. The | |
220 | ultracalls allow the SVMs and Hypervisor to request services from the | |
221 | Ultravisor such as accessing a register or memory region that can only | |
222 | be accessed when running in Ultravisor-privileged mode. | |
223 | ||
224 | The specific service needed from an ultracall is specified in register | |
225 | R3 (the first parameter to the ultracall). Other parameters to the | |
226 | ultracall, if any, are specified in registers R4 through R12. | |
227 | ||
228 | Return value of all ultracalls is in register R3. Other output values | |
229 | from the ultracall, if any, are returned in registers R4 through R12. | |
230 | The only exception to this register usage is the ``UV_RETURN`` | |
231 | ultracall described below. | |
232 | ||
233 | Each ultracall returns specific error codes, applicable in the context | |
234 | of the ultracall. However, like with the PowerPC Architecture Platform | |
235 | Reference (PAPR), if no specific error code is defined for a | |
236 | particular situation, then the ultracall will fallback to an erroneous | |
237 | parameter-position based code. i.e U_PARAMETER, U_P2, U_P3 etc | |
238 | depending on the ultracall parameter that may have caused the error. | |
239 | ||
240 | Some ultracalls involve transferring a page of data between Ultravisor | |
241 | and Hypervisor. Secure pages that are transferred from secure memory | |
242 | to normal memory may be encrypted using dynamically generated keys. | |
243 | When the secure pages are transferred back to secure memory, they may | |
244 | be decrypted using the same dynamically generated keys. Generation and | |
245 | management of these keys will be covered in a separate document. | |
246 | ||
247 | For now this only covers ultracalls currently implemented and being | |
248 | used by Hypervisor and SVMs but others can be added here when it | |
249 | makes sense. | |
250 | ||
251 | The full specification for all hypercalls/ultracalls will eventually | |
252 | be made available in the public/OpenPower version of the PAPR | |
253 | specification. | |
254 | ||
ad9b48c5 | 255 | .. note:: |
250c6c31 | 256 | |
ad9b48c5 AZ |
257 | If PEF is not enabled, the ultracalls will be redirected to the |
258 | Hypervisor which must handle/fail the calls. | |
250c6c31 SB |
259 | |
260 | Ultracalls used by Hypervisor | |
261 | ============================= | |
262 | ||
263 | This section describes the virtual memory management ultracalls used | |
264 | by the Hypervisor to manage SVMs. | |
265 | ||
266 | UV_PAGE_OUT | |
267 | ----------- | |
268 | ||
269 | Encrypt and move the contents of a page from secure memory to normal | |
270 | memory. | |
271 | ||
272 | Syntax | |
273 | ~~~~~~ | |
274 | ||
275 | .. code-block:: c | |
276 | ||
277 | uint64_t ultracall(const uint64_t UV_PAGE_OUT, | |
278 | uint16_t lpid, /* LPAR ID */ | |
279 | uint64_t dest_ra, /* real address of destination page */ | |
280 | uint64_t src_gpa, /* source guest-physical-address */ | |
281 | uint8_t flags, /* flags */ | |
282 | uint64_t order) /* page size order */ | |
283 | ||
284 | Return values | |
285 | ~~~~~~~~~~~~~ | |
286 | ||
287 | One of the following values: | |
288 | ||
289 | * U_SUCCESS on success. | |
290 | * U_PARAMETER if ``lpid`` is invalid. | |
291 | * U_P2 if ``dest_ra`` is invalid. | |
292 | * U_P3 if the ``src_gpa`` address is invalid. | |
293 | * U_P4 if any bit in the ``flags`` is unrecognized | |
294 | * U_P5 if the ``order`` parameter is unsupported. | |
295 | * U_FUNCTION if functionality is not supported. | |
296 | * U_BUSY if page cannot be currently paged-out. | |
297 | ||
298 | Description | |
299 | ~~~~~~~~~~~ | |
300 | ||
301 | Encrypt the contents of a secure-page and make it available to | |
302 | Hypervisor in a normal page. | |
303 | ||
304 | By default, the source page is unmapped from the SVM's partition- | |
305 | scoped page table. But the Hypervisor can provide a hint to the | |
306 | Ultravisor to retain the page mapping by setting the ``UV_SNAPSHOT`` | |
307 | flag in ``flags`` parameter. | |
308 | ||
309 | If the source page is already a shared page the call returns | |
310 | U_SUCCESS, without doing anything. | |
311 | ||
312 | Use cases | |
313 | ~~~~~~~~~ | |
314 | ||
315 | #. QEMU attempts to access an address belonging to the SVM but the | |
316 | page frame for that address is not mapped into QEMU's address | |
317 | space. In this case, the Hypervisor will allocate a page frame, | |
318 | map it into QEMU's address space and issue the ``UV_PAGE_OUT`` | |
319 | call to retrieve the encrypted contents of the page. | |
320 | ||
321 | #. When Ultravisor runs low on secure memory and it needs to page-out | |
322 | an LRU page. In this case, Ultravisor will issue the | |
323 | ``H_SVM_PAGE_OUT`` hypercall to the Hypervisor. The Hypervisor will | |
324 | then allocate a normal page and issue the ``UV_PAGE_OUT`` ultracall | |
325 | and the Ultravisor will encrypt and move the contents of the secure | |
326 | page into the normal page. | |
327 | ||
328 | #. When Hypervisor accesses SVM data, the Hypervisor requests the | |
329 | Ultravisor to transfer the corresponding page into a insecure page, | |
330 | which the Hypervisor can access. The data in the normal page will | |
331 | be encrypted though. | |
332 | ||
333 | UV_PAGE_IN | |
334 | ---------- | |
335 | ||
336 | Move the contents of a page from normal memory to secure memory. | |
337 | ||
338 | Syntax | |
339 | ~~~~~~ | |
340 | ||
341 | .. code-block:: c | |
342 | ||
343 | uint64_t ultracall(const uint64_t UV_PAGE_IN, | |
344 | uint16_t lpid, /* the LPAR ID */ | |
345 | uint64_t src_ra, /* source real address of page */ | |
346 | uint64_t dest_gpa, /* destination guest physical address */ | |
347 | uint64_t flags, /* flags */ | |
348 | uint64_t order) /* page size order */ | |
349 | ||
350 | Return values | |
351 | ~~~~~~~~~~~~~ | |
352 | ||
353 | One of the following values: | |
354 | ||
355 | * U_SUCCESS on success. | |
356 | * U_BUSY if page cannot be currently paged-in. | |
357 | * U_FUNCTION if functionality is not supported | |
358 | * U_PARAMETER if ``lpid`` is invalid. | |
359 | * U_P2 if ``src_ra`` is invalid. | |
360 | * U_P3 if the ``dest_gpa`` address is invalid. | |
361 | * U_P4 if any bit in the ``flags`` is unrecognized | |
362 | * U_P5 if the ``order`` parameter is unsupported. | |
363 | ||
364 | Description | |
365 | ~~~~~~~~~~~ | |
366 | ||
367 | Move the contents of the page identified by ``src_ra`` from normal | |
368 | memory to secure memory and map it to the guest physical address | |
369 | ``dest_gpa``. | |
370 | ||
371 | If `dest_gpa` refers to a shared address, map the page into the | |
372 | partition-scoped page-table of the SVM. If `dest_gpa` is not shared, | |
373 | copy the contents of the page into the corresponding secure page. | |
374 | Depending on the context, decrypt the page before being copied. | |
375 | ||
376 | The caller provides the attributes of the page through the ``flags`` | |
377 | parameter. Valid values for ``flags`` are: | |
378 | ||
379 | * CACHE_INHIBITED | |
380 | * CACHE_ENABLED | |
381 | * WRITE_PROTECTION | |
382 | ||
383 | The Hypervisor must pin the page in memory before making | |
384 | ``UV_PAGE_IN`` ultracall. | |
385 | ||
386 | Use cases | |
387 | ~~~~~~~~~ | |
388 | ||
389 | #. When a normal VM switches to secure mode, all its pages residing | |
390 | in normal memory, are moved into secure memory. | |
391 | ||
392 | #. When an SVM requests to share a page with Hypervisor the Hypervisor | |
393 | allocates a page and informs the Ultravisor. | |
394 | ||
395 | #. When an SVM accesses a secure page that has been paged-out, | |
396 | Ultravisor invokes the Hypervisor to locate the page. After | |
397 | locating the page, the Hypervisor uses UV_PAGE_IN to make the | |
398 | page available to Ultravisor. | |
399 | ||
400 | UV_PAGE_INVAL | |
401 | ------------- | |
402 | ||
403 | Invalidate the Ultravisor mapping of a page. | |
404 | ||
405 | Syntax | |
406 | ~~~~~~ | |
407 | ||
408 | .. code-block:: c | |
409 | ||
410 | uint64_t ultracall(const uint64_t UV_PAGE_INVAL, | |
411 | uint16_t lpid, /* the LPAR ID */ | |
412 | uint64_t guest_pa, /* destination guest-physical-address */ | |
413 | uint64_t order) /* page size order */ | |
414 | ||
415 | Return values | |
416 | ~~~~~~~~~~~~~ | |
417 | ||
418 | One of the following values: | |
419 | ||
420 | * U_SUCCESS on success. | |
421 | * U_PARAMETER if ``lpid`` is invalid. | |
422 | * U_P2 if ``guest_pa`` is invalid (or corresponds to a secure | |
423 | page mapping). | |
424 | * U_P3 if the ``order`` is invalid. | |
425 | * U_FUNCTION if functionality is not supported. | |
426 | * U_BUSY if page cannot be currently invalidated. | |
427 | ||
428 | Description | |
429 | ~~~~~~~~~~~ | |
430 | ||
431 | This ultracall informs Ultravisor that the page mapping in Hypervisor | |
432 | corresponding to the given guest physical address has been invalidated | |
433 | and that the Ultravisor should not access the page. If the specified | |
434 | ``guest_pa`` corresponds to a secure page, Ultravisor will ignore the | |
435 | attempt to invalidate the page and return U_P2. | |
436 | ||
437 | Use cases | |
438 | ~~~~~~~~~ | |
439 | ||
440 | #. When a shared page is unmapped from the QEMU's page table, possibly | |
441 | because it is paged-out to disk, Ultravisor needs to know that the | |
442 | page should not be accessed from its side too. | |
443 | ||
444 | ||
445 | UV_WRITE_PATE | |
446 | ------------- | |
447 | ||
448 | Validate and write the partition table entry (PATE) for a given | |
449 | partition. | |
450 | ||
451 | Syntax | |
452 | ~~~~~~ | |
453 | ||
454 | .. code-block:: c | |
455 | ||
456 | uint64_t ultracall(const uint64_t UV_WRITE_PATE, | |
457 | uint32_t lpid, /* the LPAR ID */ | |
458 | uint64_t dw0 /* the first double word to write */ | |
459 | uint64_t dw1) /* the second double word to write */ | |
460 | ||
461 | Return values | |
462 | ~~~~~~~~~~~~~ | |
463 | ||
464 | One of the following values: | |
465 | ||
466 | * U_SUCCESS on success. | |
467 | * U_BUSY if PATE cannot be currently written to. | |
468 | * U_FUNCTION if functionality is not supported. | |
469 | * U_PARAMETER if ``lpid`` is invalid. | |
470 | * U_P2 if ``dw0`` is invalid. | |
471 | * U_P3 if the ``dw1`` address is invalid. | |
472 | * U_PERMISSION if the Hypervisor is attempting to change the PATE | |
473 | of a secure virtual machine or if called from a | |
474 | context other than Hypervisor. | |
475 | ||
476 | Description | |
477 | ~~~~~~~~~~~ | |
478 | ||
479 | Validate and write a LPID and its partition-table-entry for the given | |
480 | LPID. If the LPID is already allocated and initialized, this call | |
481 | results in changing the partition table entry. | |
482 | ||
483 | Use cases | |
484 | ~~~~~~~~~ | |
485 | ||
486 | #. The Partition table resides in Secure memory and its entries, | |
487 | called PATE (Partition Table Entries), point to the partition- | |
488 | scoped page tables for the Hypervisor as well as each of the | |
489 | virtual machines (both secure and normal). The Hypervisor | |
490 | operates in partition 0 and its partition-scoped page tables | |
491 | reside in normal memory. | |
492 | ||
493 | #. This ultracall allows the Hypervisor to register the partition- | |
494 | scoped and process-scoped page table entries for the Hypervisor | |
495 | and other partitions (virtual machines) with the Ultravisor. | |
496 | ||
497 | #. If the value of the PATE for an existing partition (VM) changes, | |
498 | the TLB cache for the partition is flushed. | |
499 | ||
500 | #. The Hypervisor is responsible for allocating LPID. The LPID and | |
501 | its PATE entry are registered together. The Hypervisor manages | |
502 | the PATE entries for a normal VM and can change the PATE entry | |
503 | anytime. Ultravisor manages the PATE entries for an SVM and | |
504 | Hypervisor is not allowed to modify them. | |
505 | ||
506 | UV_RETURN | |
507 | --------- | |
508 | ||
509 | Return control from the Hypervisor back to the Ultravisor after | |
510 | processing an hypercall or interrupt that was forwarded (aka | |
511 | *reflected*) to the Hypervisor. | |
512 | ||
513 | Syntax | |
514 | ~~~~~~ | |
515 | ||
516 | .. code-block:: c | |
517 | ||
518 | uint64_t ultracall(const uint64_t UV_RETURN) | |
519 | ||
520 | Return values | |
521 | ~~~~~~~~~~~~~ | |
522 | ||
523 | This call never returns to Hypervisor on success. It returns | |
524 | U_INVALID if ultracall is not made from a Hypervisor context. | |
525 | ||
526 | Description | |
527 | ~~~~~~~~~~~ | |
528 | ||
529 | When an SVM makes an hypercall or incurs some other exception, the | |
530 | Ultravisor usually forwards (aka *reflects*) the exceptions to the | |
531 | Hypervisor. After processing the exception, Hypervisor uses the | |
532 | ``UV_RETURN`` ultracall to return control back to the SVM. | |
533 | ||
534 | The expected register state on entry to this ultracall is: | |
535 | ||
536 | * Non-volatile registers are restored to their original values. | |
537 | * If returning from an hypercall, register R0 contains the return | |
538 | value (**unlike other ultracalls**) and, registers R4 through R12 | |
539 | contain any output values of the hypercall. | |
540 | * R3 contains the ultracall number, i.e UV_RETURN. | |
541 | * If returning with a synthesized interrupt, R2 contains the | |
542 | synthesized interrupt number. | |
543 | ||
544 | Use cases | |
545 | ~~~~~~~~~ | |
546 | ||
547 | #. Ultravisor relies on the Hypervisor to provide several services to | |
548 | the SVM such as processing hypercall and other exceptions. After | |
549 | processing the exception, Hypervisor uses UV_RETURN to return | |
550 | control back to the Ultravisor. | |
551 | ||
552 | #. Hypervisor has to use this ultracall to return control to the SVM. | |
553 | ||
554 | ||
555 | UV_REGISTER_MEM_SLOT | |
556 | -------------------- | |
557 | ||
558 | Register an SVM address-range with specified properties. | |
559 | ||
560 | Syntax | |
561 | ~~~~~~ | |
562 | ||
563 | .. code-block:: c | |
564 | ||
565 | uint64_t ultracall(const uint64_t UV_REGISTER_MEM_SLOT, | |
566 | uint64_t lpid, /* LPAR ID of the SVM */ | |
567 | uint64_t start_gpa, /* start guest physical address */ | |
568 | uint64_t size, /* size of address range in bytes */ | |
569 | uint64_t flags /* reserved for future expansion */ | |
570 | uint16_t slotid) /* slot identifier */ | |
571 | ||
572 | Return values | |
573 | ~~~~~~~~~~~~~ | |
574 | ||
575 | One of the following values: | |
576 | ||
577 | * U_SUCCESS on success. | |
578 | * U_PARAMETER if ``lpid`` is invalid. | |
579 | * U_P2 if ``start_gpa`` is invalid. | |
580 | * U_P3 if ``size`` is invalid. | |
581 | * U_P4 if any bit in the ``flags`` is unrecognized. | |
582 | * U_P5 if the ``slotid`` parameter is unsupported. | |
583 | * U_PERMISSION if called from context other than Hypervisor. | |
584 | * U_FUNCTION if functionality is not supported. | |
585 | ||
586 | ||
587 | Description | |
588 | ~~~~~~~~~~~ | |
589 | ||
590 | Register a memory range for an SVM. The memory range starts at the | |
591 | guest physical address ``start_gpa`` and is ``size`` bytes long. | |
592 | ||
593 | Use cases | |
594 | ~~~~~~~~~ | |
595 | ||
596 | ||
597 | #. When a virtual machine goes secure, all the memory slots managed by | |
598 | the Hypervisor move into secure memory. The Hypervisor iterates | |
599 | through each of memory slots, and registers the slot with | |
600 | Ultravisor. Hypervisor may discard some slots such as those used | |
601 | for firmware (SLOF). | |
602 | ||
603 | #. When new memory is hot-plugged, a new memory slot gets registered. | |
604 | ||
605 | ||
606 | UV_UNREGISTER_MEM_SLOT | |
607 | ---------------------- | |
608 | ||
609 | Unregister an SVM address-range that was previously registered using | |
610 | UV_REGISTER_MEM_SLOT. | |
611 | ||
612 | Syntax | |
613 | ~~~~~~ | |
614 | ||
615 | .. code-block:: c | |
616 | ||
617 | uint64_t ultracall(const uint64_t UV_UNREGISTER_MEM_SLOT, | |
618 | uint64_t lpid, /* LPAR ID of the SVM */ | |
619 | uint64_t slotid) /* reservation slotid */ | |
620 | ||
621 | Return values | |
622 | ~~~~~~~~~~~~~ | |
623 | ||
624 | One of the following values: | |
625 | ||
626 | * U_SUCCESS on success. | |
627 | * U_FUNCTION if functionality is not supported. | |
628 | * U_PARAMETER if ``lpid`` is invalid. | |
629 | * U_P2 if ``slotid`` is invalid. | |
630 | * U_PERMISSION if called from context other than Hypervisor. | |
631 | ||
632 | Description | |
633 | ~~~~~~~~~~~ | |
634 | ||
635 | Release the memory slot identified by ``slotid`` and free any | |
636 | resources allocated towards the reservation. | |
637 | ||
638 | Use cases | |
639 | ~~~~~~~~~ | |
640 | ||
641 | #. Memory hot-remove. | |
642 | ||
643 | ||
644 | UV_SVM_TERMINATE | |
645 | ---------------- | |
646 | ||
647 | Terminate an SVM and release its resources. | |
648 | ||
649 | Syntax | |
650 | ~~~~~~ | |
651 | ||
652 | .. code-block:: c | |
653 | ||
654 | uint64_t ultracall(const uint64_t UV_SVM_TERMINATE, | |
655 | uint64_t lpid, /* LPAR ID of the SVM */) | |
656 | ||
657 | Return values | |
658 | ~~~~~~~~~~~~~ | |
659 | ||
660 | One of the following values: | |
661 | ||
662 | * U_SUCCESS on success. | |
663 | * U_FUNCTION if functionality is not supported. | |
664 | * U_PARAMETER if ``lpid`` is invalid. | |
665 | * U_INVALID if VM is not secure. | |
666 | * U_PERMISSION if not called from a Hypervisor context. | |
667 | ||
668 | Description | |
669 | ~~~~~~~~~~~ | |
670 | ||
671 | Terminate an SVM and release all its resources. | |
672 | ||
673 | Use cases | |
674 | ~~~~~~~~~ | |
675 | ||
676 | #. Called by Hypervisor when terminating an SVM. | |
677 | ||
678 | ||
679 | Ultracalls used by SVM | |
680 | ====================== | |
681 | ||
682 | UV_SHARE_PAGE | |
683 | ------------- | |
684 | ||
685 | Share a set of guest physical pages with the Hypervisor. | |
686 | ||
687 | Syntax | |
688 | ~~~~~~ | |
689 | ||
690 | .. code-block:: c | |
691 | ||
692 | uint64_t ultracall(const uint64_t UV_SHARE_PAGE, | |
693 | uint64_t gfn, /* guest page frame number */ | |
694 | uint64_t num) /* number of pages of size PAGE_SIZE */ | |
695 | ||
696 | Return values | |
697 | ~~~~~~~~~~~~~ | |
698 | ||
699 | One of the following values: | |
700 | ||
701 | * U_SUCCESS on success. | |
702 | * U_FUNCTION if functionality is not supported. | |
703 | * U_INVALID if the VM is not secure. | |
704 | * U_PARAMETER if ``gfn`` is invalid. | |
705 | * U_P2 if ``num`` is invalid. | |
706 | ||
707 | Description | |
708 | ~~~~~~~~~~~ | |
709 | ||
710 | Share the ``num`` pages starting at guest physical frame number ``gfn`` | |
711 | with the Hypervisor. Assume page size is PAGE_SIZE bytes. Zero the | |
712 | pages before returning. | |
713 | ||
714 | If the address is already backed by a secure page, unmap the page and | |
715 | back it with an insecure page, with the help of the Hypervisor. If it | |
716 | is not backed by any page yet, mark the PTE as insecure and back it | |
717 | with an insecure page when the address is accessed. If it is already | |
718 | backed by an insecure page, zero the page and return. | |
719 | ||
720 | Use cases | |
721 | ~~~~~~~~~ | |
722 | ||
723 | #. The Hypervisor cannot access the SVM pages since they are backed by | |
724 | secure pages. Hence an SVM must explicitly request Ultravisor for | |
725 | pages it can share with Hypervisor. | |
726 | ||
727 | #. Shared pages are needed to support virtio and Virtual Processor Area | |
728 | (VPA) in SVMs. | |
729 | ||
730 | ||
731 | UV_UNSHARE_PAGE | |
732 | --------------- | |
733 | ||
734 | Restore a shared SVM page to its initial state. | |
735 | ||
736 | Syntax | |
737 | ~~~~~~ | |
738 | ||
739 | .. code-block:: c | |
740 | ||
741 | uint64_t ultracall(const uint64_t UV_UNSHARE_PAGE, | |
742 | uint64_t gfn, /* guest page frame number */ | |
743 | uint73 num) /* number of pages of size PAGE_SIZE*/ | |
744 | ||
745 | Return values | |
746 | ~~~~~~~~~~~~~ | |
747 | ||
748 | One of the following values: | |
749 | ||
750 | * U_SUCCESS on success. | |
751 | * U_FUNCTION if functionality is not supported. | |
752 | * U_INVALID if VM is not secure. | |
753 | * U_PARAMETER if ``gfn`` is invalid. | |
754 | * U_P2 if ``num`` is invalid. | |
755 | ||
756 | Description | |
757 | ~~~~~~~~~~~ | |
758 | ||
759 | Stop sharing ``num`` pages starting at ``gfn`` with the Hypervisor. | |
760 | Assume that the page size is PAGE_SIZE. Zero the pages before | |
761 | returning. | |
762 | ||
763 | If the address is already backed by an insecure page, unmap the page | |
764 | and back it with a secure page. Inform the Hypervisor to release | |
765 | reference to its shared page. If the address is not backed by a page | |
766 | yet, mark the PTE as secure and back it with a secure page when that | |
767 | address is accessed. If it is already backed by an secure page zero | |
768 | the page and return. | |
769 | ||
770 | Use cases | |
771 | ~~~~~~~~~ | |
772 | ||
773 | #. The SVM may decide to unshare a page from the Hypervisor. | |
774 | ||
775 | ||
776 | UV_UNSHARE_ALL_PAGES | |
777 | -------------------- | |
778 | ||
779 | Unshare all pages the SVM has shared with Hypervisor. | |
780 | ||
781 | Syntax | |
782 | ~~~~~~ | |
783 | ||
784 | .. code-block:: c | |
785 | ||
786 | uint64_t ultracall(const uint64_t UV_UNSHARE_ALL_PAGES) | |
787 | ||
788 | Return values | |
789 | ~~~~~~~~~~~~~ | |
790 | ||
791 | One of the following values: | |
792 | ||
793 | * U_SUCCESS on success. | |
794 | * U_FUNCTION if functionality is not supported. | |
795 | * U_INVAL if VM is not secure. | |
796 | ||
797 | Description | |
798 | ~~~~~~~~~~~ | |
799 | ||
800 | Unshare all shared pages from the Hypervisor. All unshared pages are | |
801 | zeroed on return. Only pages explicitly shared by the SVM with the | |
802 | Hypervisor (using UV_SHARE_PAGE ultracall) are unshared. Ultravisor | |
803 | may internally share some pages with the Hypervisor without explicit | |
804 | request from the SVM. These pages will not be unshared by this | |
805 | ultracall. | |
806 | ||
807 | Use cases | |
808 | ~~~~~~~~~ | |
809 | ||
810 | #. This call is needed when ``kexec`` is used to boot a different | |
811 | kernel. It may also be needed during SVM reset. | |
812 | ||
813 | UV_ESM | |
814 | ------ | |
815 | ||
816 | Secure the virtual machine (*enter secure mode*). | |
817 | ||
818 | Syntax | |
819 | ~~~~~~ | |
820 | ||
821 | .. code-block:: c | |
822 | ||
823 | uint64_t ultracall(const uint64_t UV_ESM, | |
824 | uint64_t esm_blob_addr, /* location of the ESM blob */ | |
825 | unint64_t fdt) /* Flattened device tree */ | |
826 | ||
827 | Return values | |
828 | ~~~~~~~~~~~~~ | |
829 | ||
830 | One of the following values: | |
831 | ||
832 | * U_SUCCESS on success (including if VM is already secure). | |
833 | * U_FUNCTION if functionality is not supported. | |
834 | * U_INVALID if VM is not secure. | |
835 | * U_PARAMETER if ``esm_blob_addr`` is invalid. | |
836 | * U_P2 if ``fdt`` is invalid. | |
837 | * U_PERMISSION if any integrity checks fail. | |
838 | * U_RETRY insufficient memory to create SVM. | |
839 | * U_NO_KEY symmetric key unavailable. | |
840 | ||
841 | Description | |
842 | ~~~~~~~~~~~ | |
843 | ||
844 | Secure the virtual machine. On successful completion, return | |
845 | control to the virtual machine at the address specified in the | |
846 | ESM blob. | |
847 | ||
848 | Use cases | |
849 | ~~~~~~~~~ | |
850 | ||
851 | #. A normal virtual machine can choose to switch to a secure mode. | |
852 | ||
853 | Hypervisor Calls API | |
854 | #################### | |
855 | ||
856 | This document describes the Hypervisor calls (hypercalls) that are | |
857 | needed to support the Ultravisor. Hypercalls are services provided by | |
858 | the Hypervisor to virtual machines and Ultravisor. | |
859 | ||
860 | Register usage for these hypercalls is identical to that of the other | |
861 | hypercalls defined in the Power Architecture Platform Reference (PAPR) | |
862 | document. i.e on input, register R3 identifies the specific service | |
863 | that is being requested and registers R4 through R11 contain | |
864 | additional parameters to the hypercall, if any. On output, register | |
865 | R3 contains the return value and registers R4 through R9 contain any | |
866 | other output values from the hypercall. | |
867 | ||
868 | This document only covers hypercalls currently implemented/planned | |
869 | for Ultravisor usage but others can be added here when it makes sense. | |
870 | ||
871 | The full specification for all hypercalls/ultracalls will eventually | |
872 | be made available in the public/OpenPower version of the PAPR | |
873 | specification. | |
874 | ||
875 | Hypervisor calls to support Ultravisor | |
876 | ====================================== | |
877 | ||
878 | Following are the set of hypercalls needed to support Ultravisor. | |
879 | ||
880 | H_SVM_INIT_START | |
881 | ---------------- | |
882 | ||
883 | Begin the process of converting a normal virtual machine into an SVM. | |
884 | ||
885 | Syntax | |
886 | ~~~~~~ | |
887 | ||
888 | .. code-block:: c | |
889 | ||
890 | uint64_t hypercall(const uint64_t H_SVM_INIT_START) | |
891 | ||
892 | Return values | |
893 | ~~~~~~~~~~~~~ | |
894 | ||
895 | One of the following values: | |
896 | ||
897 | * H_SUCCESS on success. | |
2027a24a | 898 | * H_STATE if the VM is not in a position to switch to secure. |
250c6c31 SB |
899 | |
900 | Description | |
901 | ~~~~~~~~~~~ | |
902 | ||
903 | Initiate the process of securing a virtual machine. This involves | |
904 | coordinating with the Ultravisor, using ultracalls, to allocate | |
905 | resources in the Ultravisor for the new SVM, transferring the VM's | |
906 | pages from normal to secure memory etc. When the process is | |
907 | completed, Ultravisor issues the H_SVM_INIT_DONE hypercall. | |
908 | ||
909 | Use cases | |
910 | ~~~~~~~~~ | |
911 | ||
912 | #. Ultravisor uses this hypercall to inform Hypervisor that a VM | |
913 | has initiated the process of switching to secure mode. | |
914 | ||
915 | ||
916 | H_SVM_INIT_DONE | |
917 | --------------- | |
918 | ||
919 | Complete the process of securing an SVM. | |
920 | ||
921 | Syntax | |
922 | ~~~~~~ | |
923 | ||
924 | .. code-block:: c | |
925 | ||
926 | uint64_t hypercall(const uint64_t H_SVM_INIT_DONE) | |
927 | ||
928 | Return values | |
929 | ~~~~~~~~~~~~~ | |
930 | ||
931 | One of the following values: | |
932 | ||
933 | * H_SUCCESS on success. | |
934 | * H_UNSUPPORTED if called from the wrong context (e.g. | |
935 | from an SVM or before an H_SVM_INIT_START | |
936 | hypercall). | |
dfaa973a RP |
937 | * H_STATE if the hypervisor could not successfully |
938 | transition the VM to Secure VM. | |
250c6c31 SB |
939 | |
940 | Description | |
941 | ~~~~~~~~~~~ | |
942 | ||
943 | Complete the process of securing a virtual machine. This call must | |
944 | be made after a prior call to ``H_SVM_INIT_START`` hypercall. | |
945 | ||
946 | Use cases | |
947 | ~~~~~~~~~ | |
948 | ||
949 | On successfully securing a virtual machine, the Ultravisor informs | |
950 | Hypervisor about it. Hypervisor can use this call to finish setting | |
951 | up its internal state for this virtual machine. | |
952 | ||
953 | ||
3a43970d SB |
954 | H_SVM_INIT_ABORT |
955 | ---------------- | |
956 | ||
957 | Abort the process of securing an SVM. | |
958 | ||
959 | Syntax | |
960 | ~~~~~~ | |
961 | ||
962 | .. code-block:: c | |
963 | ||
964 | uint64_t hypercall(const uint64_t H_SVM_INIT_ABORT) | |
965 | ||
966 | Return values | |
967 | ~~~~~~~~~~~~~ | |
968 | ||
969 | One of the following values: | |
970 | ||
971 | * H_PARAMETER on successfully cleaning up the state, | |
972 | Hypervisor will return this value to the | |
973 | **guest**, to indicate that the underlying | |
974 | UV_ESM ultracall failed. | |
975 | ||
976 | * H_STATE if called after a VM has gone secure (i.e | |
977 | H_SVM_INIT_DONE hypercall was successful). | |
978 | ||
979 | * H_UNSUPPORTED if called from a wrong context (e.g. from a | |
980 | normal VM). | |
981 | ||
982 | Description | |
983 | ~~~~~~~~~~~ | |
984 | ||
985 | Abort the process of securing a virtual machine. This call must | |
986 | be made after a prior call to ``H_SVM_INIT_START`` hypercall and | |
987 | before a call to ``H_SVM_INIT_DONE``. | |
988 | ||
989 | On entry into this hypercall the non-volatile GPRs and FPRs are | |
990 | expected to contain the values they had at the time the VM issued | |
991 | the UV_ESM ultracall. Further ``SRR0`` is expected to contain the | |
992 | address of the instruction after the ``UV_ESM`` ultracall and ``SRR1`` | |
993 | the MSR value with which to return to the VM. | |
994 | ||
995 | This hypercall will cleanup any partial state that was established for | |
996 | the VM since the prior ``H_SVM_INIT_START`` hypercall, including paging | |
997 | out pages that were paged-into secure memory, and issue the | |
998 | ``UV_SVM_TERMINATE`` ultracall to terminate the VM. | |
999 | ||
1000 | After the partial state is cleaned up, control returns to the VM | |
1001 | (**not Ultravisor**), at the address specified in ``SRR0`` with the | |
1002 | MSR values set to the value in ``SRR1``. | |
1003 | ||
1004 | Use cases | |
1005 | ~~~~~~~~~ | |
1006 | ||
1007 | If after a successful call to ``H_SVM_INIT_START``, the Ultravisor | |
1008 | encounters an error while securing a virtual machine, either due | |
1009 | to lack of resources or because the VM's security information could | |
1010 | not be validated, Ultravisor informs the Hypervisor about it. | |
1011 | Hypervisor should use this call to clean up any internal state for | |
1012 | this virtual machine and return to the VM. | |
1013 | ||
250c6c31 SB |
1014 | H_SVM_PAGE_IN |
1015 | ------------- | |
1016 | ||
1017 | Move the contents of a page from normal memory to secure memory. | |
1018 | ||
1019 | Syntax | |
1020 | ~~~~~~ | |
1021 | ||
1022 | .. code-block:: c | |
1023 | ||
1024 | uint64_t hypercall(const uint64_t H_SVM_PAGE_IN, | |
1025 | uint64_t guest_pa, /* guest-physical-address */ | |
1026 | uint64_t flags, /* flags */ | |
1027 | uint64_t order) /* page size order */ | |
1028 | ||
1029 | Return values | |
1030 | ~~~~~~~~~~~~~ | |
1031 | ||
1032 | One of the following values: | |
1033 | ||
1034 | * H_SUCCESS on success. | |
1035 | * H_PARAMETER if ``guest_pa`` is invalid. | |
1036 | * H_P2 if ``flags`` is invalid. | |
1037 | * H_P3 if ``order`` of page is invalid. | |
1038 | ||
1039 | Description | |
1040 | ~~~~~~~~~~~ | |
1041 | ||
1042 | Retrieve the content of the page, belonging to the VM at the specified | |
1043 | guest physical address. | |
1044 | ||
1045 | Only valid value(s) in ``flags`` are: | |
1046 | ||
1047 | * H_PAGE_IN_SHARED which indicates that the page is to be shared | |
1048 | with the Ultravisor. | |
1049 | ||
1050 | * H_PAGE_IN_NONSHARED indicates that the UV is not anymore | |
1051 | interested in the page. Applicable if the page is a shared page. | |
1052 | ||
1053 | The ``order`` parameter must correspond to the configured page size. | |
1054 | ||
1055 | Use cases | |
1056 | ~~~~~~~~~ | |
1057 | ||
1058 | #. When a normal VM becomes a secure VM (using the UV_ESM ultracall), | |
1059 | the Ultravisor uses this hypercall to move contents of each page of | |
1060 | the VM from normal memory to secure memory. | |
1061 | ||
1062 | #. Ultravisor uses this hypercall to ask Hypervisor to provide a page | |
1063 | in normal memory that can be shared between the SVM and Hypervisor. | |
1064 | ||
1065 | #. Ultravisor uses this hypercall to page-in a paged-out page. This | |
1066 | can happen when the SVM touches a paged-out page. | |
1067 | ||
1068 | #. If SVM wants to disable sharing of pages with Hypervisor, it can | |
1069 | inform Ultravisor to do so. Ultravisor will then use this hypercall | |
1070 | and inform Hypervisor that it has released access to the normal | |
1071 | page. | |
1072 | ||
1073 | H_SVM_PAGE_OUT | |
1074 | --------------- | |
1075 | ||
1076 | Move the contents of the page to normal memory. | |
1077 | ||
1078 | Syntax | |
1079 | ~~~~~~ | |
1080 | ||
1081 | .. code-block:: c | |
1082 | ||
1083 | uint64_t hypercall(const uint64_t H_SVM_PAGE_OUT, | |
1084 | uint64_t guest_pa, /* guest-physical-address */ | |
1085 | uint64_t flags, /* flags (currently none) */ | |
1086 | uint64_t order) /* page size order */ | |
1087 | ||
1088 | Return values | |
1089 | ~~~~~~~~~~~~~ | |
1090 | ||
1091 | One of the following values: | |
1092 | ||
1093 | * H_SUCCESS on success. | |
1094 | * H_PARAMETER if ``guest_pa`` is invalid. | |
1095 | * H_P2 if ``flags`` is invalid. | |
1096 | * H_P3 if ``order`` is invalid. | |
1097 | ||
1098 | Description | |
1099 | ~~~~~~~~~~~ | |
1100 | ||
1101 | Move the contents of the page identified by ``guest_pa`` to normal | |
1102 | memory. | |
1103 | ||
1104 | Currently ``flags`` is unused and must be set to 0. The ``order`` | |
1105 | parameter must correspond to the configured page size. | |
1106 | ||
1107 | Use cases | |
1108 | ~~~~~~~~~ | |
1109 | ||
1110 | #. If Ultravisor is running low on secure pages, it can move the | |
1111 | contents of some secure pages, into normal pages using this | |
1112 | hypercall. The content will be encrypted. | |
1113 | ||
1114 | References | |
1115 | ########## | |
1116 | ||
ad9b48c5 | 1117 | - `Supporting Protected Computing on IBM Power Architecture <https://developer.ibm.com/articles/l-support-protected-computing/>`_ |