0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. _ultravisor:
0003
0004 ============================
0005 Protected Execution Facility
0006 ============================
0007
0008 .. contents::
0009 :depth: 3
0010
0011 Introduction
0012 ############
0013
0014 Protected Execution Facility (PEF) is an architectural change for
0015 POWER 9 that enables Secure Virtual Machines (SVMs). DD2.3 chips
0016 (PVR=0x004e1203) or greater will be PEF-capable. A new ISA release
0017 will include the PEF RFC02487 changes.
0018
0019 When enabled, PEF adds a new higher privileged mode, called Ultravisor
0020 mode, to POWER architecture. Along with the new mode there is new
0021 firmware called the Protected Execution Ultravisor (or Ultravisor
0022 for short). Ultravisor mode is the highest privileged mode in POWER
0023 architecture.
0024
0025 +------------------+
0026 | Privilege States |
0027 +==================+
0028 | Problem |
0029 +------------------+
0030 | Supervisor |
0031 +------------------+
0032 | Hypervisor |
0033 +------------------+
0034 | Ultravisor |
0035 +------------------+
0036
0037 PEF protects SVMs from the hypervisor, privileged users, and other
0038 VMs in the system. SVMs are protected while at rest and can only be
0039 executed by an authorized machine. All virtual machines utilize
0040 hypervisor services. The Ultravisor filters calls between the SVMs
0041 and the hypervisor to assure that information does not accidentally
0042 leak. All hypercalls except H_RANDOM are reflected to the hypervisor.
0043 H_RANDOM is not reflected to prevent the hypervisor from influencing
0044 random values in the SVM.
0045
0046 To support this there is a refactoring of the ownership of resources
0047 in the CPU. Some of the resources which were previously hypervisor
0048 privileged are now ultravisor privileged.
0049
0050 Hardware
0051 ========
0052
0053 The hardware changes include the following:
0054
0055 * There is a new bit in the MSR that determines whether the current
0056 process is running in secure mode, MSR(S) bit 41. MSR(S)=1, process
0057 is in secure mode, MSR(s)=0 process is in normal mode.
0058
0059 * The MSR(S) bit can only be set by the Ultravisor.
0060
0061 * HRFID cannot be used to set the MSR(S) bit. If the hypervisor needs
0062 to return to a SVM it must use an ultracall. It can determine if
0063 the VM it is returning to is secure.
0064
0065 * There is a new Ultravisor privileged register, SMFCTRL, which has an
0066 enable/disable bit SMFCTRL(E).
0067
0068 * The privilege of a process is now determined by three MSR bits,
0069 MSR(S, HV, PR). In each of the tables below the modes are listed
0070 from least privilege to highest privilege. The higher privilege
0071 modes can access all the resources of the lower privilege modes.
0072
0073 **Secure Mode MSR Settings**
0074
0075 +---+---+---+---------------+
0076 | S | HV| PR|Privilege |
0077 +===+===+===+===============+
0078 | 1 | 0 | 1 | Problem |
0079 +---+---+---+---------------+
0080 | 1 | 0 | 0 | Privileged(OS)|
0081 +---+---+---+---------------+
0082 | 1 | 1 | 0 | Ultravisor |
0083 +---+---+---+---------------+
0084 | 1 | 1 | 1 | Reserved |
0085 +---+---+---+---------------+
0086
0087 **Normal Mode MSR Settings**
0088
0089 +---+---+---+---------------+
0090 | S | HV| PR|Privilege |
0091 +===+===+===+===============+
0092 | 0 | 0 | 1 | Problem |
0093 +---+---+---+---------------+
0094 | 0 | 0 | 0 | Privileged(OS)|
0095 +---+---+---+---------------+
0096 | 0 | 1 | 0 | Hypervisor |
0097 +---+---+---+---------------+
0098 | 0 | 1 | 1 | Problem (Host)|
0099 +---+---+---+---------------+
0100
0101 * Memory is partitioned into secure and normal memory. Only processes
0102 that are running in secure mode can access secure memory.
0103
0104 * The hardware does not allow anything that is not running secure to
0105 access secure memory. This means that the Hypervisor cannot access
0106 the memory of the SVM without using an ultracall (asking the
0107 Ultravisor). The Ultravisor will only allow the hypervisor to see
0108 the SVM memory encrypted.
0109
0110 * I/O systems are not allowed to directly address secure memory. This
0111 limits the SVMs to virtual I/O only.
0112
0113 * The architecture allows the SVM to share pages of memory with the
0114 hypervisor that are not protected with encryption. However, this
0115 sharing must be initiated by the SVM.
0116
0117 * When a process is running in secure mode all hypercalls
0118 (syscall lev=1) go to the Ultravisor.
0119
0120 * When a process is in secure mode all interrupts go to the
0121 Ultravisor.
0122
0123 * The following resources have become Ultravisor privileged and
0124 require an Ultravisor interface to manipulate:
0125
0126 * Processor configurations registers (SCOMs).
0127
0128 * Stop state information.
0129
0130 * The debug registers CIABR, DAWR, and DAWRX when SMFCTRL(D) is set.
0131 If SMFCTRL(D) is not set they do not work in secure mode. When set,
0132 reading and writing requires an Ultravisor call, otherwise that
0133 will cause a Hypervisor Emulation Assistance interrupt.
0134
0135 * PTCR and partition table entries (partition table is in secure
0136 memory). An attempt to write to PTCR will cause a Hypervisor
0137 Emulation Assitance interrupt.
0138
0139 * LDBAR (LD Base Address Register) and IMC (In-Memory Collection)
0140 non-architected registers. An attempt to write to them will cause a
0141 Hypervisor Emulation Assistance interrupt.
0142
0143 * Paging for an SVM, sharing of memory with Hypervisor for an SVM.
0144 (Including Virtual Processor Area (VPA) and virtual I/O).
0145
0146
0147 Software/Microcode
0148 ==================
0149
0150 The software changes include:
0151
0152 * SVMs are created from normal VM using (open source) tooling supplied
0153 by IBM.
0154
0155 * All SVMs start as normal VMs and utilize an ultracall, UV_ESM
0156 (Enter Secure Mode), to make the transition.
0157
0158 * When the UV_ESM ultracall is made the Ultravisor copies the VM into
0159 secure memory, decrypts the verification information, and checks the
0160 integrity of the SVM. If the integrity check passes the Ultravisor
0161 passes control in secure mode.
0162
0163 * The verification information includes the pass phrase for the
0164 encrypted disk associated with the SVM. This pass phrase is given
0165 to the SVM when requested.
0166
0167 * The Ultravisor is not involved in protecting the encrypted disk of
0168 the SVM while at rest.
0169
0170 * For external interrupts the Ultravisor saves the state of the SVM,
0171 and reflects the interrupt to the hypervisor for processing.
0172 For hypercalls, the Ultravisor inserts neutral state into all
0173 registers not needed for the hypercall then reflects the call to
0174 the hypervisor for processing. The H_RANDOM hypercall is performed
0175 by the Ultravisor and not reflected.
0176
0177 * For virtual I/O to work bounce buffering must be done.
0178
0179 * The Ultravisor uses AES (IAPM) for protection of SVM memory. IAPM
0180 is a mode of AES that provides integrity and secrecy concurrently.
0181
0182 * The movement of data between normal and secure pages is coordinated
0183 with the Ultravisor by a new HMM plug-in in the Hypervisor.
0184
0185 The Ultravisor offers new services to the hypervisor and SVMs. These
0186 are accessed through ultracalls.
0187
0188 Terminology
0189 ===========
0190
0191 * Hypercalls: special system calls used to request services from
0192 Hypervisor.
0193
0194 * Normal memory: Memory that is accessible to Hypervisor.
0195
0196 * Normal page: Page backed by normal memory and available to
0197 Hypervisor.
0198
0199 * Shared page: A page backed by normal memory and available to both
0200 the Hypervisor/QEMU and the SVM (i.e page has mappings in SVM and
0201 Hypervisor/QEMU).
0202
0203 * Secure memory: Memory that is accessible only to Ultravisor and
0204 SVMs.
0205
0206 * Secure page: Page backed by secure memory and only available to
0207 Ultravisor and SVM.
0208
0209 * SVM: Secure Virtual Machine.
0210
0211 * Ultracalls: special system calls used to request services from
0212 Ultravisor.
0213
0214
0215 Ultravisor calls API
0216 ####################
0217
0218 This section describes Ultravisor calls (ultracalls) needed to
0219 support Secure Virtual Machines (SVM)s and Paravirtualized KVM. The
0220 ultracalls allow the SVMs and Hypervisor to request services from the
0221 Ultravisor such as accessing a register or memory region that can only
0222 be accessed when running in Ultravisor-privileged mode.
0223
0224 The specific service needed from an ultracall is specified in register
0225 R3 (the first parameter to the ultracall). Other parameters to the
0226 ultracall, if any, are specified in registers R4 through R12.
0227
0228 Return value of all ultracalls is in register R3. Other output values
0229 from the ultracall, if any, are returned in registers R4 through R12.
0230 The only exception to this register usage is the ``UV_RETURN``
0231 ultracall described below.
0232
0233 Each ultracall returns specific error codes, applicable in the context
0234 of the ultracall. However, like with the PowerPC Architecture Platform
0235 Reference (PAPR), if no specific error code is defined for a
0236 particular situation, then the ultracall will fallback to an erroneous
0237 parameter-position based code. i.e U_PARAMETER, U_P2, U_P3 etc
0238 depending on the ultracall parameter that may have caused the error.
0239
0240 Some ultracalls involve transferring a page of data between Ultravisor
0241 and Hypervisor. Secure pages that are transferred from secure memory
0242 to normal memory may be encrypted using dynamically generated keys.
0243 When the secure pages are transferred back to secure memory, they may
0244 be decrypted using the same dynamically generated keys. Generation and
0245 management of these keys will be covered in a separate document.
0246
0247 For now this only covers ultracalls currently implemented and being
0248 used by Hypervisor and SVMs but others can be added here when it
0249 makes sense.
0250
0251 The full specification for all hypercalls/ultracalls will eventually
0252 be made available in the public/OpenPower version of the PAPR
0253 specification.
0254
0255 .. note::
0256
0257 If PEF is not enabled, the ultracalls will be redirected to the
0258 Hypervisor which must handle/fail the calls.
0259
0260 Ultracalls used by Hypervisor
0261 =============================
0262
0263 This section describes the virtual memory management ultracalls used
0264 by the Hypervisor to manage SVMs.
0265
0266 UV_PAGE_OUT
0267 -----------
0268
0269 Encrypt and move the contents of a page from secure memory to normal
0270 memory.
0271
0272 Syntax
0273 ~~~~~~
0274
0275 .. code-block:: c
0276
0277 uint64_t ultracall(const uint64_t UV_PAGE_OUT,
0278 uint16_t lpid, /* LPAR ID */
0279 uint64_t dest_ra, /* real address of destination page */
0280 uint64_t src_gpa, /* source guest-physical-address */
0281 uint8_t flags, /* flags */
0282 uint64_t order) /* page size order */
0283
0284 Return values
0285 ~~~~~~~~~~~~~
0286
0287 One of the following values:
0288
0289 * U_SUCCESS on success.
0290 * U_PARAMETER if ``lpid`` is invalid.
0291 * U_P2 if ``dest_ra`` is invalid.
0292 * U_P3 if the ``src_gpa`` address is invalid.
0293 * U_P4 if any bit in the ``flags`` is unrecognized
0294 * U_P5 if the ``order`` parameter is unsupported.
0295 * U_FUNCTION if functionality is not supported.
0296 * U_BUSY if page cannot be currently paged-out.
0297
0298 Description
0299 ~~~~~~~~~~~
0300
0301 Encrypt the contents of a secure-page and make it available to
0302 Hypervisor in a normal page.
0303
0304 By default, the source page is unmapped from the SVM's partition-
0305 scoped page table. But the Hypervisor can provide a hint to the
0306 Ultravisor to retain the page mapping by setting the ``UV_SNAPSHOT``
0307 flag in ``flags`` parameter.
0308
0309 If the source page is already a shared page the call returns
0310 U_SUCCESS, without doing anything.
0311
0312 Use cases
0313 ~~~~~~~~~
0314
0315 #. QEMU attempts to access an address belonging to the SVM but the
0316 page frame for that address is not mapped into QEMU's address
0317 space. In this case, the Hypervisor will allocate a page frame,
0318 map it into QEMU's address space and issue the ``UV_PAGE_OUT``
0319 call to retrieve the encrypted contents of the page.
0320
0321 #. When Ultravisor runs low on secure memory and it needs to page-out
0322 an LRU page. In this case, Ultravisor will issue the
0323 ``H_SVM_PAGE_OUT`` hypercall to the Hypervisor. The Hypervisor will
0324 then allocate a normal page and issue the ``UV_PAGE_OUT`` ultracall
0325 and the Ultravisor will encrypt and move the contents of the secure
0326 page into the normal page.
0327
0328 #. When Hypervisor accesses SVM data, the Hypervisor requests the
0329 Ultravisor to transfer the corresponding page into a insecure page,
0330 which the Hypervisor can access. The data in the normal page will
0331 be encrypted though.
0332
0333 UV_PAGE_IN
0334 ----------
0335
0336 Move the contents of a page from normal memory to secure memory.
0337
0338 Syntax
0339 ~~~~~~
0340
0341 .. code-block:: c
0342
0343 uint64_t ultracall(const uint64_t UV_PAGE_IN,
0344 uint16_t lpid, /* the LPAR ID */
0345 uint64_t src_ra, /* source real address of page */
0346 uint64_t dest_gpa, /* destination guest physical address */
0347 uint64_t flags, /* flags */
0348 uint64_t order) /* page size order */
0349
0350 Return values
0351 ~~~~~~~~~~~~~
0352
0353 One of the following values:
0354
0355 * U_SUCCESS on success.
0356 * U_BUSY if page cannot be currently paged-in.
0357 * U_FUNCTION if functionality is not supported
0358 * U_PARAMETER if ``lpid`` is invalid.
0359 * U_P2 if ``src_ra`` is invalid.
0360 * U_P3 if the ``dest_gpa`` address is invalid.
0361 * U_P4 if any bit in the ``flags`` is unrecognized
0362 * U_P5 if the ``order`` parameter is unsupported.
0363
0364 Description
0365 ~~~~~~~~~~~
0366
0367 Move the contents of the page identified by ``src_ra`` from normal
0368 memory to secure memory and map it to the guest physical address
0369 ``dest_gpa``.
0370
0371 If `dest_gpa` refers to a shared address, map the page into the
0372 partition-scoped page-table of the SVM. If `dest_gpa` is not shared,
0373 copy the contents of the page into the corresponding secure page.
0374 Depending on the context, decrypt the page before being copied.
0375
0376 The caller provides the attributes of the page through the ``flags``
0377 parameter. Valid values for ``flags`` are:
0378
0379 * CACHE_INHIBITED
0380 * CACHE_ENABLED
0381 * WRITE_PROTECTION
0382
0383 The Hypervisor must pin the page in memory before making
0384 ``UV_PAGE_IN`` ultracall.
0385
0386 Use cases
0387 ~~~~~~~~~
0388
0389 #. When a normal VM switches to secure mode, all its pages residing
0390 in normal memory, are moved into secure memory.
0391
0392 #. When an SVM requests to share a page with Hypervisor the Hypervisor
0393 allocates a page and informs the Ultravisor.
0394
0395 #. When an SVM accesses a secure page that has been paged-out,
0396 Ultravisor invokes the Hypervisor to locate the page. After
0397 locating the page, the Hypervisor uses UV_PAGE_IN to make the
0398 page available to Ultravisor.
0399
0400 UV_PAGE_INVAL
0401 -------------
0402
0403 Invalidate the Ultravisor mapping of a page.
0404
0405 Syntax
0406 ~~~~~~
0407
0408 .. code-block:: c
0409
0410 uint64_t ultracall(const uint64_t UV_PAGE_INVAL,
0411 uint16_t lpid, /* the LPAR ID */
0412 uint64_t guest_pa, /* destination guest-physical-address */
0413 uint64_t order) /* page size order */
0414
0415 Return values
0416 ~~~~~~~~~~~~~
0417
0418 One of the following values:
0419
0420 * U_SUCCESS on success.
0421 * U_PARAMETER if ``lpid`` is invalid.
0422 * U_P2 if ``guest_pa`` is invalid (or corresponds to a secure
0423 page mapping).
0424 * U_P3 if the ``order`` is invalid.
0425 * U_FUNCTION if functionality is not supported.
0426 * U_BUSY if page cannot be currently invalidated.
0427
0428 Description
0429 ~~~~~~~~~~~
0430
0431 This ultracall informs Ultravisor that the page mapping in Hypervisor
0432 corresponding to the given guest physical address has been invalidated
0433 and that the Ultravisor should not access the page. If the specified
0434 ``guest_pa`` corresponds to a secure page, Ultravisor will ignore the
0435 attempt to invalidate the page and return U_P2.
0436
0437 Use cases
0438 ~~~~~~~~~
0439
0440 #. When a shared page is unmapped from the QEMU's page table, possibly
0441 because it is paged-out to disk, Ultravisor needs to know that the
0442 page should not be accessed from its side too.
0443
0444
0445 UV_WRITE_PATE
0446 -------------
0447
0448 Validate and write the partition table entry (PATE) for a given
0449 partition.
0450
0451 Syntax
0452 ~~~~~~
0453
0454 .. code-block:: c
0455
0456 uint64_t ultracall(const uint64_t UV_WRITE_PATE,
0457 uint32_t lpid, /* the LPAR ID */
0458 uint64_t dw0 /* the first double word to write */
0459 uint64_t dw1) /* the second double word to write */
0460
0461 Return values
0462 ~~~~~~~~~~~~~
0463
0464 One of the following values:
0465
0466 * U_SUCCESS on success.
0467 * U_BUSY if PATE cannot be currently written to.
0468 * U_FUNCTION if functionality is not supported.
0469 * U_PARAMETER if ``lpid`` is invalid.
0470 * U_P2 if ``dw0`` is invalid.
0471 * U_P3 if the ``dw1`` address is invalid.
0472 * U_PERMISSION if the Hypervisor is attempting to change the PATE
0473 of a secure virtual machine or if called from a
0474 context other than Hypervisor.
0475
0476 Description
0477 ~~~~~~~~~~~
0478
0479 Validate and write a LPID and its partition-table-entry for the given
0480 LPID. If the LPID is already allocated and initialized, this call
0481 results in changing the partition table entry.
0482
0483 Use cases
0484 ~~~~~~~~~
0485
0486 #. The Partition table resides in Secure memory and its entries,
0487 called PATE (Partition Table Entries), point to the partition-
0488 scoped page tables for the Hypervisor as well as each of the
0489 virtual machines (both secure and normal). The Hypervisor
0490 operates in partition 0 and its partition-scoped page tables
0491 reside in normal memory.
0492
0493 #. This ultracall allows the Hypervisor to register the partition-
0494 scoped and process-scoped page table entries for the Hypervisor
0495 and other partitions (virtual machines) with the Ultravisor.
0496
0497 #. If the value of the PATE for an existing partition (VM) changes,
0498 the TLB cache for the partition is flushed.
0499
0500 #. The Hypervisor is responsible for allocating LPID. The LPID and
0501 its PATE entry are registered together. The Hypervisor manages
0502 the PATE entries for a normal VM and can change the PATE entry
0503 anytime. Ultravisor manages the PATE entries for an SVM and
0504 Hypervisor is not allowed to modify them.
0505
0506 UV_RETURN
0507 ---------
0508
0509 Return control from the Hypervisor back to the Ultravisor after
0510 processing an hypercall or interrupt that was forwarded (aka
0511 *reflected*) to the Hypervisor.
0512
0513 Syntax
0514 ~~~~~~
0515
0516 .. code-block:: c
0517
0518 uint64_t ultracall(const uint64_t UV_RETURN)
0519
0520 Return values
0521 ~~~~~~~~~~~~~
0522
0523 This call never returns to Hypervisor on success. It returns
0524 U_INVALID if ultracall is not made from a Hypervisor context.
0525
0526 Description
0527 ~~~~~~~~~~~
0528
0529 When an SVM makes an hypercall or incurs some other exception, the
0530 Ultravisor usually forwards (aka *reflects*) the exceptions to the
0531 Hypervisor. After processing the exception, Hypervisor uses the
0532 ``UV_RETURN`` ultracall to return control back to the SVM.
0533
0534 The expected register state on entry to this ultracall is:
0535
0536 * Non-volatile registers are restored to their original values.
0537 * If returning from an hypercall, register R0 contains the return
0538 value (**unlike other ultracalls**) and, registers R4 through R12
0539 contain any output values of the hypercall.
0540 * R3 contains the ultracall number, i.e UV_RETURN.
0541 * If returning with a synthesized interrupt, R2 contains the
0542 synthesized interrupt number.
0543
0544 Use cases
0545 ~~~~~~~~~
0546
0547 #. Ultravisor relies on the Hypervisor to provide several services to
0548 the SVM such as processing hypercall and other exceptions. After
0549 processing the exception, Hypervisor uses UV_RETURN to return
0550 control back to the Ultravisor.
0551
0552 #. Hypervisor has to use this ultracall to return control to the SVM.
0553
0554
0555 UV_REGISTER_MEM_SLOT
0556 --------------------
0557
0558 Register an SVM address-range with specified properties.
0559
0560 Syntax
0561 ~~~~~~
0562
0563 .. code-block:: c
0564
0565 uint64_t ultracall(const uint64_t UV_REGISTER_MEM_SLOT,
0566 uint64_t lpid, /* LPAR ID of the SVM */
0567 uint64_t start_gpa, /* start guest physical address */
0568 uint64_t size, /* size of address range in bytes */
0569 uint64_t flags /* reserved for future expansion */
0570 uint16_t slotid) /* slot identifier */
0571
0572 Return values
0573 ~~~~~~~~~~~~~
0574
0575 One of the following values:
0576
0577 * U_SUCCESS on success.
0578 * U_PARAMETER if ``lpid`` is invalid.
0579 * U_P2 if ``start_gpa`` is invalid.
0580 * U_P3 if ``size`` is invalid.
0581 * U_P4 if any bit in the ``flags`` is unrecognized.
0582 * U_P5 if the ``slotid`` parameter is unsupported.
0583 * U_PERMISSION if called from context other than Hypervisor.
0584 * U_FUNCTION if functionality is not supported.
0585
0586
0587 Description
0588 ~~~~~~~~~~~
0589
0590 Register a memory range for an SVM. The memory range starts at the
0591 guest physical address ``start_gpa`` and is ``size`` bytes long.
0592
0593 Use cases
0594 ~~~~~~~~~
0595
0596
0597 #. When a virtual machine goes secure, all the memory slots managed by
0598 the Hypervisor move into secure memory. The Hypervisor iterates
0599 through each of memory slots, and registers the slot with
0600 Ultravisor. Hypervisor may discard some slots such as those used
0601 for firmware (SLOF).
0602
0603 #. When new memory is hot-plugged, a new memory slot gets registered.
0604
0605
0606 UV_UNREGISTER_MEM_SLOT
0607 ----------------------
0608
0609 Unregister an SVM address-range that was previously registered using
0610 UV_REGISTER_MEM_SLOT.
0611
0612 Syntax
0613 ~~~~~~
0614
0615 .. code-block:: c
0616
0617 uint64_t ultracall(const uint64_t UV_UNREGISTER_MEM_SLOT,
0618 uint64_t lpid, /* LPAR ID of the SVM */
0619 uint64_t slotid) /* reservation slotid */
0620
0621 Return values
0622 ~~~~~~~~~~~~~
0623
0624 One of the following values:
0625
0626 * U_SUCCESS on success.
0627 * U_FUNCTION if functionality is not supported.
0628 * U_PARAMETER if ``lpid`` is invalid.
0629 * U_P2 if ``slotid`` is invalid.
0630 * U_PERMISSION if called from context other than Hypervisor.
0631
0632 Description
0633 ~~~~~~~~~~~
0634
0635 Release the memory slot identified by ``slotid`` and free any
0636 resources allocated towards the reservation.
0637
0638 Use cases
0639 ~~~~~~~~~
0640
0641 #. Memory hot-remove.
0642
0643
0644 UV_SVM_TERMINATE
0645 ----------------
0646
0647 Terminate an SVM and release its resources.
0648
0649 Syntax
0650 ~~~~~~
0651
0652 .. code-block:: c
0653
0654 uint64_t ultracall(const uint64_t UV_SVM_TERMINATE,
0655 uint64_t lpid, /* LPAR ID of the SVM */)
0656
0657 Return values
0658 ~~~~~~~~~~~~~
0659
0660 One of the following values:
0661
0662 * U_SUCCESS on success.
0663 * U_FUNCTION if functionality is not supported.
0664 * U_PARAMETER if ``lpid`` is invalid.
0665 * U_INVALID if VM is not secure.
0666 * U_PERMISSION if not called from a Hypervisor context.
0667
0668 Description
0669 ~~~~~~~~~~~
0670
0671 Terminate an SVM and release all its resources.
0672
0673 Use cases
0674 ~~~~~~~~~
0675
0676 #. Called by Hypervisor when terminating an SVM.
0677
0678
0679 Ultracalls used by SVM
0680 ======================
0681
0682 UV_SHARE_PAGE
0683 -------------
0684
0685 Share a set of guest physical pages with the Hypervisor.
0686
0687 Syntax
0688 ~~~~~~
0689
0690 .. code-block:: c
0691
0692 uint64_t ultracall(const uint64_t UV_SHARE_PAGE,
0693 uint64_t gfn, /* guest page frame number */
0694 uint64_t num) /* number of pages of size PAGE_SIZE */
0695
0696 Return values
0697 ~~~~~~~~~~~~~
0698
0699 One of the following values:
0700
0701 * U_SUCCESS on success.
0702 * U_FUNCTION if functionality is not supported.
0703 * U_INVALID if the VM is not secure.
0704 * U_PARAMETER if ``gfn`` is invalid.
0705 * U_P2 if ``num`` is invalid.
0706
0707 Description
0708 ~~~~~~~~~~~
0709
0710 Share the ``num`` pages starting at guest physical frame number ``gfn``
0711 with the Hypervisor. Assume page size is PAGE_SIZE bytes. Zero the
0712 pages before returning.
0713
0714 If the address is already backed by a secure page, unmap the page and
0715 back it with an insecure page, with the help of the Hypervisor. If it
0716 is not backed by any page yet, mark the PTE as insecure and back it
0717 with an insecure page when the address is accessed. If it is already
0718 backed by an insecure page, zero the page and return.
0719
0720 Use cases
0721 ~~~~~~~~~
0722
0723 #. The Hypervisor cannot access the SVM pages since they are backed by
0724 secure pages. Hence an SVM must explicitly request Ultravisor for
0725 pages it can share with Hypervisor.
0726
0727 #. Shared pages are needed to support virtio and Virtual Processor Area
0728 (VPA) in SVMs.
0729
0730
0731 UV_UNSHARE_PAGE
0732 ---------------
0733
0734 Restore a shared SVM page to its initial state.
0735
0736 Syntax
0737 ~~~~~~
0738
0739 .. code-block:: c
0740
0741 uint64_t ultracall(const uint64_t UV_UNSHARE_PAGE,
0742 uint64_t gfn, /* guest page frame number */
0743 uint73 num) /* number of pages of size PAGE_SIZE*/
0744
0745 Return values
0746 ~~~~~~~~~~~~~
0747
0748 One of the following values:
0749
0750 * U_SUCCESS on success.
0751 * U_FUNCTION if functionality is not supported.
0752 * U_INVALID if VM is not secure.
0753 * U_PARAMETER if ``gfn`` is invalid.
0754 * U_P2 if ``num`` is invalid.
0755
0756 Description
0757 ~~~~~~~~~~~
0758
0759 Stop sharing ``num`` pages starting at ``gfn`` with the Hypervisor.
0760 Assume that the page size is PAGE_SIZE. Zero the pages before
0761 returning.
0762
0763 If the address is already backed by an insecure page, unmap the page
0764 and back it with a secure page. Inform the Hypervisor to release
0765 reference to its shared page. If the address is not backed by a page
0766 yet, mark the PTE as secure and back it with a secure page when that
0767 address is accessed. If it is already backed by an secure page zero
0768 the page and return.
0769
0770 Use cases
0771 ~~~~~~~~~
0772
0773 #. The SVM may decide to unshare a page from the Hypervisor.
0774
0775
0776 UV_UNSHARE_ALL_PAGES
0777 --------------------
0778
0779 Unshare all pages the SVM has shared with Hypervisor.
0780
0781 Syntax
0782 ~~~~~~
0783
0784 .. code-block:: c
0785
0786 uint64_t ultracall(const uint64_t UV_UNSHARE_ALL_PAGES)
0787
0788 Return values
0789 ~~~~~~~~~~~~~
0790
0791 One of the following values:
0792
0793 * U_SUCCESS on success.
0794 * U_FUNCTION if functionality is not supported.
0795 * U_INVAL if VM is not secure.
0796
0797 Description
0798 ~~~~~~~~~~~
0799
0800 Unshare all shared pages from the Hypervisor. All unshared pages are
0801 zeroed on return. Only pages explicitly shared by the SVM with the
0802 Hypervisor (using UV_SHARE_PAGE ultracall) are unshared. Ultravisor
0803 may internally share some pages with the Hypervisor without explicit
0804 request from the SVM. These pages will not be unshared by this
0805 ultracall.
0806
0807 Use cases
0808 ~~~~~~~~~
0809
0810 #. This call is needed when ``kexec`` is used to boot a different
0811 kernel. It may also be needed during SVM reset.
0812
0813 UV_ESM
0814 ------
0815
0816 Secure the virtual machine (*enter secure mode*).
0817
0818 Syntax
0819 ~~~~~~
0820
0821 .. code-block:: c
0822
0823 uint64_t ultracall(const uint64_t UV_ESM,
0824 uint64_t esm_blob_addr, /* location of the ESM blob */
0825 unint64_t fdt) /* Flattened device tree */
0826
0827 Return values
0828 ~~~~~~~~~~~~~
0829
0830 One of the following values:
0831
0832 * U_SUCCESS on success (including if VM is already secure).
0833 * U_FUNCTION if functionality is not supported.
0834 * U_INVALID if VM is not secure.
0835 * U_PARAMETER if ``esm_blob_addr`` is invalid.
0836 * U_P2 if ``fdt`` is invalid.
0837 * U_PERMISSION if any integrity checks fail.
0838 * U_RETRY insufficient memory to create SVM.
0839 * U_NO_KEY symmetric key unavailable.
0840
0841 Description
0842 ~~~~~~~~~~~
0843
0844 Secure the virtual machine. On successful completion, return
0845 control to the virtual machine at the address specified in the
0846 ESM blob.
0847
0848 Use cases
0849 ~~~~~~~~~
0850
0851 #. A normal virtual machine can choose to switch to a secure mode.
0852
0853 Hypervisor Calls API
0854 ####################
0855
0856 This document describes the Hypervisor calls (hypercalls) that are
0857 needed to support the Ultravisor. Hypercalls are services provided by
0858 the Hypervisor to virtual machines and Ultravisor.
0859
0860 Register usage for these hypercalls is identical to that of the other
0861 hypercalls defined in the Power Architecture Platform Reference (PAPR)
0862 document. i.e on input, register R3 identifies the specific service
0863 that is being requested and registers R4 through R11 contain
0864 additional parameters to the hypercall, if any. On output, register
0865 R3 contains the return value and registers R4 through R9 contain any
0866 other output values from the hypercall.
0867
0868 This document only covers hypercalls currently implemented/planned
0869 for Ultravisor usage but others can be added here when it makes sense.
0870
0871 The full specification for all hypercalls/ultracalls will eventually
0872 be made available in the public/OpenPower version of the PAPR
0873 specification.
0874
0875 Hypervisor calls to support Ultravisor
0876 ======================================
0877
0878 Following are the set of hypercalls needed to support Ultravisor.
0879
0880 H_SVM_INIT_START
0881 ----------------
0882
0883 Begin the process of converting a normal virtual machine into an SVM.
0884
0885 Syntax
0886 ~~~~~~
0887
0888 .. code-block:: c
0889
0890 uint64_t hypercall(const uint64_t H_SVM_INIT_START)
0891
0892 Return values
0893 ~~~~~~~~~~~~~
0894
0895 One of the following values:
0896
0897 * H_SUCCESS on success.
0898 * H_STATE if the VM is not in a position to switch to secure.
0899
0900 Description
0901 ~~~~~~~~~~~
0902
0903 Initiate the process of securing a virtual machine. This involves
0904 coordinating with the Ultravisor, using ultracalls, to allocate
0905 resources in the Ultravisor for the new SVM, transferring the VM's
0906 pages from normal to secure memory etc. When the process is
0907 completed, Ultravisor issues the H_SVM_INIT_DONE hypercall.
0908
0909 Use cases
0910 ~~~~~~~~~
0911
0912 #. Ultravisor uses this hypercall to inform Hypervisor that a VM
0913 has initiated the process of switching to secure mode.
0914
0915
0916 H_SVM_INIT_DONE
0917 ---------------
0918
0919 Complete the process of securing an SVM.
0920
0921 Syntax
0922 ~~~~~~
0923
0924 .. code-block:: c
0925
0926 uint64_t hypercall(const uint64_t H_SVM_INIT_DONE)
0927
0928 Return values
0929 ~~~~~~~~~~~~~
0930
0931 One of the following values:
0932
0933 * H_SUCCESS on success.
0934 * H_UNSUPPORTED if called from the wrong context (e.g.
0935 from an SVM or before an H_SVM_INIT_START
0936 hypercall).
0937 * H_STATE if the hypervisor could not successfully
0938 transition the VM to Secure VM.
0939
0940 Description
0941 ~~~~~~~~~~~
0942
0943 Complete the process of securing a virtual machine. This call must
0944 be made after a prior call to ``H_SVM_INIT_START`` hypercall.
0945
0946 Use cases
0947 ~~~~~~~~~
0948
0949 On successfully securing a virtual machine, the Ultravisor informs
0950 Hypervisor about it. Hypervisor can use this call to finish setting
0951 up its internal state for this virtual machine.
0952
0953
0954 H_SVM_INIT_ABORT
0955 ----------------
0956
0957 Abort the process of securing an SVM.
0958
0959 Syntax
0960 ~~~~~~
0961
0962 .. code-block:: c
0963
0964 uint64_t hypercall(const uint64_t H_SVM_INIT_ABORT)
0965
0966 Return values
0967 ~~~~~~~~~~~~~
0968
0969 One of the following values:
0970
0971 * H_PARAMETER on successfully cleaning up the state,
0972 Hypervisor will return this value to the
0973 **guest**, to indicate that the underlying
0974 UV_ESM ultracall failed.
0975
0976 * H_STATE if called after a VM has gone secure (i.e
0977 H_SVM_INIT_DONE hypercall was successful).
0978
0979 * H_UNSUPPORTED if called from a wrong context (e.g. from a
0980 normal VM).
0981
0982 Description
0983 ~~~~~~~~~~~
0984
0985 Abort the process of securing a virtual machine. This call must
0986 be made after a prior call to ``H_SVM_INIT_START`` hypercall and
0987 before a call to ``H_SVM_INIT_DONE``.
0988
0989 On entry into this hypercall the non-volatile GPRs and FPRs are
0990 expected to contain the values they had at the time the VM issued
0991 the UV_ESM ultracall. Further ``SRR0`` is expected to contain the
0992 address of the instruction after the ``UV_ESM`` ultracall and ``SRR1``
0993 the MSR value with which to return to the VM.
0994
0995 This hypercall will cleanup any partial state that was established for
0996 the VM since the prior ``H_SVM_INIT_START`` hypercall, including paging
0997 out pages that were paged-into secure memory, and issue the
0998 ``UV_SVM_TERMINATE`` ultracall to terminate the VM.
0999
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
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
1117 - `Supporting Protected Computing on IBM Power Architecture <https://developer.ibm.com/articles/l-support-protected-computing/>`_
