Documentation/virt/kvm/s390-pv.rst - linux - Git at Google

 .. SPDX-License-Identifier: GPL-2.0

 =========================================
 s390 (IBM Z) Ultravisor and Protected VMs
 =========================================

 Summary
 -------
 Protected virtual machines (PVM) are KVM VMs that do not allow KVM to
 access VM state like guest memory or guest registers. Instead, the
 PVMs are mostly managed by a new entity called Ultravisor (UV). The UV
 provides an API that can be used by PVMs and KVM to request management
 actions.

 Each guest starts in non-protected mode and then may make a request to
 transition into protected mode. On transition, KVM registers the guest
 and its VCPUs with the Ultravisor and prepares everything for running
 it.

 The Ultravisor will secure and decrypt the guest's boot memory
 (i.e. kernel/initrd). It will safeguard state changes like VCPU
 starts/stops and injected interrupts while the guest is running.

 As access to the guest's state, such as the SIE state description, is
 normally needed to be able to run a VM, some changes have been made in
 the behavior of the SIE instruction. A new format 4 state description
 has been introduced, where some fields have different meanings for a
 PVM. SIE exits are minimized as much as possible to improve speed and
 reduce exposed guest state.


 Interrupt injection
 -------------------
 Interrupt injection is safeguarded by the Ultravisor. As KVM doesn't
 have access to the VCPUs' lowcores, injection is handled via the
 format 4 state description.

 Machine check, external, IO and restart interruptions each can be
 injected on SIE entry via a bit in the interrupt injection control
 field (offset 0x54). If the guest cpu is not enabled for the interrupt
 at the time of injection, a validity interception is recognized. The
 format 4 state description contains fields in the interception data
 block where data associated with the interrupt can be transported.

 Program and Service Call exceptions have another layer of
 safeguarding; they can only be injected for instructions that have
 been intercepted into KVM. The exceptions need to be a valid outcome
 of an instruction emulation by KVM, e.g. we can never inject a
 addressing exception as they are reported by SIE since KVM has no
 access to the guest memory.


 Mask notification interceptions
 -------------------------------
 KVM cannot intercept lctl(g) and lpsw(e) anymore in order to be
 notified when a PVM enables a certain class of interrupt.  As a
 replacement, two new interception codes have been introduced: One
 indicating that the contents of CRs 0, 6, or 14 have been changed,
 indicating different interruption subclasses; and one indicating that
 PSW bit 13 has been changed, indicating that a machine check
 intervention was requested and those are now enabled.

 Instruction emulation
 ---------------------
 With the format 4 state description for PVMs, the SIE instruction already
 interprets more instructions than it does with format 2. It is not able
 to interpret every instruction, but needs to hand some tasks to KVM;
 therefore, the SIE and the ultravisor safeguard emulation inputs and outputs.

 The control structures associated with SIE provide the Secure
 Instruction Data Area (SIDA), the Interception Parameters (IP) and the
 Secure Interception General Register Save Area.  Guest GRs and most of
 the instruction data, such as I/O data structures, are filtered.
 Instruction data is copied to and from the SIDA when needed.  Guest
 GRs are put into / retrieved from the Secure Interception General
 Register Save Area.

 Only GR values needed to emulate an instruction will be copied into this
 save area and the real register numbers will be hidden.

 The Interception Parameters state description field still contains the
 the bytes of the instruction text, but with pre-set register values
 instead of the actual ones. I.e. each instruction always uses the same
 instruction text, in order not to leak guest instruction text.
 This also implies that the register content that a guest had in r<n>
 may be in r<m> from the hypervisor's point of view.

 The Secure Instruction Data Area contains instruction storage
 data. Instruction data, i.e. data being referenced by an instruction
 like the SCCB for sclp, is moved via the SIDA. When an instruction is
 intercepted, the SIE will only allow data and program interrupts for
 this instruction to be moved to the guest via the two data areas
 discussed before. Other data is either ignored or results in validity
 interceptions.


 Instruction emulation interceptions
 -----------------------------------
 There are two types of SIE secure instruction intercepts: the normal
 and the notification type. Normal secure instruction intercepts will
 make the guest pending for instruction completion of the intercepted
 instruction type, i.e. on SIE entry it is attempted to complete
 emulation of the instruction with the data provided by KVM. That might
 be a program exception or instruction completion.

 The notification type intercepts inform KVM about guest environment
 changes due to guest instruction interpretation. Such an interception
 is recognized, for example, for the store prefix instruction to provide
 the new lowcore location. On SIE reentry, any KVM data in the data areas
 is ignored and execution continues as if the guest instruction had
 completed. For that reason KVM is not allowed to inject a program
 interrupt.

 Links
 -----
 `KVM Forum 2019 presentation <https://static.sched.com/hosted_files/kvmforum2019/3b/ibm_protected_vms_s390x.pdf>`_
	.. SPDX-License-Identifier: GPL-2.0

	=========================================
	s390 (IBM Z) Ultravisor and Protected VMs
	=========================================

	Summary
	-------
	Protected virtual machines (PVM) are KVM VMs that do not allow KVM to
	access VM state like guest memory or guest registers. Instead, the
	PVMs are mostly managed by a new entity called Ultravisor (UV). The UV
	provides an API that can be used by PVMs and KVM to request management
	actions.

	Each guest starts in non-protected mode and then may make a request to
	transition into protected mode. On transition, KVM registers the guest
	and its VCPUs with the Ultravisor and prepares everything for running
	it.

	The Ultravisor will secure and decrypt the guest's boot memory
	(i.e. kernel/initrd). It will safeguard state changes like VCPU
	starts/stops and injected interrupts while the guest is running.

	As access to the guest's state, such as the SIE state description, is
	normally needed to be able to run a VM, some changes have been made in
	the behavior of the SIE instruction. A new format 4 state description
	has been introduced, where some fields have different meanings for a
	PVM. SIE exits are minimized as much as possible to improve speed and
	reduce exposed guest state.


	Interrupt injection
	-------------------
	Interrupt injection is safeguarded by the Ultravisor. As KVM doesn't
	have access to the VCPUs' lowcores, injection is handled via the
	format 4 state description.

	Machine check, external, IO and restart interruptions each can be
	injected on SIE entry via a bit in the interrupt injection control
	field (offset 0x54). If the guest cpu is not enabled for the interrupt
	at the time of injection, a validity interception is recognized. The
	format 4 state description contains fields in the interception data
	block where data associated with the interrupt can be transported.

	Program and Service Call exceptions have another layer of
	safeguarding; they can only be injected for instructions that have
	been intercepted into KVM. The exceptions need to be a valid outcome
	of an instruction emulation by KVM, e.g. we can never inject a
	addressing exception as they are reported by SIE since KVM has no
	access to the guest memory.


	Mask notification interceptions
	-------------------------------
	KVM cannot intercept lctl(g) and lpsw(e) anymore in order to be
	notified when a PVM enables a certain class of interrupt. As a
	replacement, two new interception codes have been introduced: One
	indicating that the contents of CRs 0, 6, or 14 have been changed,
	indicating different interruption subclasses; and one indicating that
	PSW bit 13 has been changed, indicating that a machine check
	intervention was requested and those are now enabled.

	Instruction emulation
	---------------------
	With the format 4 state description for PVMs, the SIE instruction already
	interprets more instructions than it does with format 2. It is not able
	to interpret every instruction, but needs to hand some tasks to KVM;
	therefore, the SIE and the ultravisor safeguard emulation inputs and outputs.

	The control structures associated with SIE provide the Secure
	Instruction Data Area (SIDA), the Interception Parameters (IP) and the
	Secure Interception General Register Save Area. Guest GRs and most of
	the instruction data, such as I/O data structures, are filtered.
	Instruction data is copied to and from the SIDA when needed. Guest
	GRs are put into / retrieved from the Secure Interception General
	Register Save Area.

	Only GR values needed to emulate an instruction will be copied into this
	save area and the real register numbers will be hidden.

	The Interception Parameters state description field still contains the
	the bytes of the instruction text, but with pre-set register values
	instead of the actual ones. I.e. each instruction always uses the same
	instruction text, in order not to leak guest instruction text.
	This also implies that the register content that a guest had in r<n>
	may be in r<m> from the hypervisor's point of view.

	The Secure Instruction Data Area contains instruction storage
	data. Instruction data, i.e. data being referenced by an instruction
	like the SCCB for sclp, is moved via the SIDA. When an instruction is
	intercepted, the SIE will only allow data and program interrupts for
	this instruction to be moved to the guest via the two data areas
	discussed before. Other data is either ignored or results in validity
	interceptions.


	Instruction emulation interceptions
	-----------------------------------
	There are two types of SIE secure instruction intercepts: the normal
	and the notification type. Normal secure instruction intercepts will
	make the guest pending for instruction completion of the intercepted
	instruction type, i.e. on SIE entry it is attempted to complete
	emulation of the instruction with the data provided by KVM. That might
	be a program exception or instruction completion.

	The notification type intercepts inform KVM about guest environment
	changes due to guest instruction interpretation. Such an interception
	is recognized, for example, for the store prefix instruction to provide
	the new lowcore location. On SIE reentry, any KVM data in the data areas
	is ignored and execution continues as if the guest instruction had
	completed. For that reason KVM is not allowed to inject a program
	interrupt.

	Links
	-----
	`KVM Forum 2019 presentation <https://static.sched.com/hosted_files/kvmforum2019/3b/ibm_protected_vms_s390x.pdf>`_