0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===========================================
0004 s390 (IBM Z) Protected Virtualization dumps
0005 ===========================================
0006
0007 Summary
0008 -------
0009
0010 Dumping a VM is an essential tool for debugging problems inside
0011 it. This is especially true when a protected VM runs into trouble as
0012 there's no way to access its memory and registers from the outside
0013 while it's running.
0014
0015 However when dumping a protected VM we need to maintain its
0016 confidentiality until the dump is in the hands of the VM owner who
0017 should be the only one capable of analysing it.
0018
0019 The confidentiality of the VM dump is ensured by the Ultravisor who
0020 provides an interface to KVM over which encrypted CPU and memory data
0021 can be requested. The encryption is based on the Customer
0022 Communication Key which is the key that's used to encrypt VM data in a
0023 way that the customer is able to decrypt.
0024
0025
0026 Dump process
0027 ------------
0028
0029 A dump is done in 3 steps:
0030
0031 **Initiation**
0032
0033 This step initializes the dump process, generates cryptographic seeds
0034 and extracts dump keys with which the VM dump data will be encrypted.
0035
0036 **Data gathering**
0037
0038 Currently there are two types of data that can be gathered from a VM:
0039 the memory and the vcpu state.
0040
0041 The vcpu state contains all the important registers, general, floating
0042 point, vector, control and tod/timers of a vcpu. The vcpu dump can
0043 contain incomplete data if a vcpu is dumped while an instruction is
0044 emulated with help of the hypervisor. This is indicated by a flag bit
0045 in the dump data. For the same reason it is very important to not only
0046 write out the encrypted vcpu state, but also the unencrypted state
0047 from the hypervisor.
0048
0049 The memory state is further divided into the encrypted memory and its
0050 metadata comprised of the encryption tweaks and status flags. The
0051 encrypted memory can simply be read once it has been exported. The
0052 time of the export does not matter as no re-encryption is
0053 needed. Memory that has been swapped out and hence was exported can be
0054 read from the swap and written to the dump target without need for any
0055 special actions.
0056
0057 The tweaks / status flags for the exported pages need to be requested
0058 from the Ultravisor.
0059
0060 **Finalization**
0061
0062 The finalization step will provide the data needed to be able to
0063 decrypt the vcpu and memory data and end the dump process. When this
0064 step completes successfully a new dump initiation can be started.
