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