s390-pv.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3=========================================
  4s390 (IBM Z) Ultravisor and Protected VMs
  5=========================================
  6
  7Summary
  8-------
  9Protected virtual machines (PVM) are KVM VMs that do not allow KVM to
 10access VM state like guest memory or guest registers. Instead, the
 11PVMs are mostly managed by a new entity called Ultravisor (UV). The UV
 12provides an API that can be used by PVMs and KVM to request management
 13actions.
 14
 15Each guest starts in non-protected mode and then may make a request to
 16transition into protected mode. On transition, KVM registers the guest
 17and its VCPUs with the Ultravisor and prepares everything for running
 18it.
 19
 20The Ultravisor will secure and decrypt the guest's boot memory
 21(i.e. kernel/initrd). It will safeguard state changes like VCPU
 22starts/stops and injected interrupts while the guest is running.
 23
 24As access to the guest's state, such as the SIE state description, is
 25normally needed to be able to run a VM, some changes have been made in
 26the behavior of the SIE instruction. A new format 4 state description
 27has been introduced, where some fields have different meanings for a
 28PVM. SIE exits are minimized as much as possible to improve speed and
 29reduce exposed guest state.
 30
 31
 32Interrupt injection
 33-------------------
 34Interrupt injection is safeguarded by the Ultravisor. As KVM doesn't
 35have access to the VCPUs' lowcores, injection is handled via the
 36format 4 state description.
 37
 38Machine check, external, IO and restart interruptions each can be
 39injected on SIE entry via a bit in the interrupt injection control
 40field (offset 0x54). If the guest cpu is not enabled for the interrupt
 41at the time of injection, a validity interception is recognized. The
 42format 4 state description contains fields in the interception data
 43block where data associated with the interrupt can be transported.
 44
 45Program and Service Call exceptions have another layer of
 46safeguarding; they can only be injected for instructions that have
 47been intercepted into KVM. The exceptions need to be a valid outcome
 48of an instruction emulation by KVM, e.g. we can never inject a
 49addressing exception as they are reported by SIE since KVM has no
 50access to the guest memory.
 51
 52
 53Mask notification interceptions
 54-------------------------------
 55KVM cannot intercept lctl(g) and lpsw(e) anymore in order to be
 56notified when a PVM enables a certain class of interrupt.  As a
 57replacement, two new interception codes have been introduced: One
 58indicating that the contents of CRs 0, 6, or 14 have been changed,
 59indicating different interruption subclasses; and one indicating that
 60PSW bit 13 has been changed, indicating that a machine check
 61intervention was requested and those are now enabled.
 62
 63Instruction emulation
 64---------------------
 65With the format 4 state description for PVMs, the SIE instruction already
 66interprets more instructions than it does with format 2. It is not able
 67to interpret every instruction, but needs to hand some tasks to KVM;
 68therefore, the SIE and the ultravisor safeguard emulation inputs and outputs.
 69
 70The control structures associated with SIE provide the Secure
 71Instruction Data Area (SIDA), the Interception Parameters (IP) and the
 72Secure Interception General Register Save Area.  Guest GRs and most of
 73the instruction data, such as I/O data structures, are filtered.
 74Instruction data is copied to and from the SIDA when needed.  Guest
 75GRs are put into / retrieved from the Secure Interception General
 76Register Save Area.
 77
 78Only GR values needed to emulate an instruction will be copied into this
 79save area and the real register numbers will be hidden.
 80
 81The Interception Parameters state description field still contains
 82the bytes of the instruction text, but with pre-set register values
 83instead of the actual ones. I.e. each instruction always uses the same
 84instruction text, in order not to leak guest instruction text.
 85This also implies that the register content that a guest had in r<n>
 86may be in r<m> from the hypervisor's point of view.
 87
 88The Secure Instruction Data Area contains instruction storage
 89data. Instruction data, i.e. data being referenced by an instruction
 90like the SCCB for sclp, is moved via the SIDA. When an instruction is
 91intercepted, the SIE will only allow data and program interrupts for
 92this instruction to be moved to the guest via the two data areas
 93discussed before. Other data is either ignored or results in validity
 94interceptions.
 95
 96
 97Instruction emulation interceptions
 98-----------------------------------
 99There are two types of SIE secure instruction intercepts: the normal
100and the notification type. Normal secure instruction intercepts will
101make the guest pending for instruction completion of the intercepted
102instruction type, i.e. on SIE entry it is attempted to complete
103emulation of the instruction with the data provided by KVM. That might
104be a program exception or instruction completion.
105
106The notification type intercepts inform KVM about guest environment
107changes due to guest instruction interpretation. Such an interception
108is recognized, for example, for the store prefix instruction to provide
109the new lowcore location. On SIE reentry, any KVM data in the data areas
110is ignored and execution continues as if the guest instruction had
111completed. For that reason KVM is not allowed to inject a program
112interrupt.
113
114Links
115-----
116`KVM Forum 2019 presentation <https://static.sched.com/hosted_files/kvmforum2019/3b/ibm_protected_vms_s390x.pdf>`_