0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =========================================
0004 s390 (IBM Z) Ultravisor and Protected VMs
0005 =========================================
0006
0007 Summary
0008 -------
0009 Protected virtual machines (PVM) are KVM VMs that do not allow KVM to
0010 access VM state like guest memory or guest registers. Instead, the
0011 PVMs are mostly managed by a new entity called Ultravisor (UV). The UV
0012 provides an API that can be used by PVMs and KVM to request management
0013 actions.
0014
0015 Each guest starts in non-protected mode and then may make a request to
0016 transition into protected mode. On transition, KVM registers the guest
0017 and its VCPUs with the Ultravisor and prepares everything for running
0018 it.
0019
0020 The Ultravisor will secure and decrypt the guest's boot memory
0021 (i.e. kernel/initrd). It will safeguard state changes like VCPU
0022 starts/stops and injected interrupts while the guest is running.
0023
0024 As access to the guest's state, such as the SIE state description, is
0025 normally needed to be able to run a VM, some changes have been made in
0026 the behavior of the SIE instruction. A new format 4 state description
0027 has been introduced, where some fields have different meanings for a
0028 PVM. SIE exits are minimized as much as possible to improve speed and
0029 reduce exposed guest state.
0030
0031
0032 Interrupt injection
0033 -------------------
0034 Interrupt injection is safeguarded by the Ultravisor. As KVM doesn't
0035 have access to the VCPUs' lowcores, injection is handled via the
0036 format 4 state description.
0037
0038 Machine check, external, IO and restart interruptions each can be
0039 injected on SIE entry via a bit in the interrupt injection control
0040 field (offset 0x54). If the guest cpu is not enabled for the interrupt
0041 at the time of injection, a validity interception is recognized. The
0042 format 4 state description contains fields in the interception data
0043 block where data associated with the interrupt can be transported.
0044
0045 Program and Service Call exceptions have another layer of
0046 safeguarding; they can only be injected for instructions that have
0047 been intercepted into KVM. The exceptions need to be a valid outcome
0048 of an instruction emulation by KVM, e.g. we can never inject a
0049 addressing exception as they are reported by SIE since KVM has no
0050 access to the guest memory.
0051
0052
0053 Mask notification interceptions
0054 -------------------------------
0055 KVM cannot intercept lctl(g) and lpsw(e) anymore in order to be
0056 notified when a PVM enables a certain class of interrupt. As a
0057 replacement, two new interception codes have been introduced: One
0058 indicating that the contents of CRs 0, 6, or 14 have been changed,
0059 indicating different interruption subclasses; and one indicating that
0060 PSW bit 13 has been changed, indicating that a machine check
0061 intervention was requested and those are now enabled.
0062
0063 Instruction emulation
0064 ---------------------
0065 With the format 4 state description for PVMs, the SIE instruction already
0066 interprets more instructions than it does with format 2. It is not able
0067 to interpret every instruction, but needs to hand some tasks to KVM;
0068 therefore, the SIE and the ultravisor safeguard emulation inputs and outputs.
0069
0070 The control structures associated with SIE provide the Secure
0071 Instruction Data Area (SIDA), the Interception Parameters (IP) and the
0072 Secure Interception General Register Save Area. Guest GRs and most of
0073 the instruction data, such as I/O data structures, are filtered.
0074 Instruction data is copied to and from the SIDA when needed. Guest
0075 GRs are put into / retrieved from the Secure Interception General
0076 Register Save Area.
0077
0078 Only GR values needed to emulate an instruction will be copied into this
0079 save area and the real register numbers will be hidden.
0080
0081 The Interception Parameters state description field still contains
0082 the bytes of the instruction text, but with pre-set register values
0083 instead of the actual ones. I.e. each instruction always uses the same
0084 instruction text, in order not to leak guest instruction text.
0085 This also implies that the register content that a guest had in r<n>
0086 may be in r<m> from the hypervisor's point of view.
0087
0088 The Secure Instruction Data Area contains instruction storage
0089 data. Instruction data, i.e. data being referenced by an instruction
0090 like the SCCB for sclp, is moved via the SIDA. When an instruction is
0091 intercepted, the SIE will only allow data and program interrupts for
0092 this instruction to be moved to the guest via the two data areas
0093 discussed before. Other data is either ignored or results in validity
0094 interceptions.
0095
0096
0097 Instruction emulation interceptions
0098 -----------------------------------
0099 There are two types of SIE secure instruction intercepts: the normal
0100 and the notification type. Normal secure instruction intercepts will
0101 make the guest pending for instruction completion of the intercepted
0102 instruction type, i.e. on SIE entry it is attempted to complete
0103 emulation of the instruction with the data provided by KVM. That might
0104 be a program exception or instruction completion.
0105
0106 The notification type intercepts inform KVM about guest environment
0107 changes due to guest instruction interpretation. Such an interception
0108 is recognized, for example, for the store prefix instruction to provide
0109 the new lowcore location. On SIE reentry, any KVM data in the data areas
0110 is ignored and execution continues as if the guest instruction had
0111 completed. For that reason KVM is not allowed to inject a program
0112 interrupt.
0113
0114 Links
0115 -----
0116 `KVM Forum 2019 presentation <https://static.sched.com/hosted_files/kvmforum2019/3b/ibm_protected_vms_s390x.pdf>`_
