1.. SPDX-License-Identifier: GPL-2.0 2 3=========================================== 4s390 (IBM Z) Protected Virtualization dumps 5=========================================== 6 7Summary 8------- 9 10Dumping a VM is an essential tool for debugging problems inside 11it. This is especially true when a protected VM runs into trouble as 12there's no way to access its memory and registers from the outside 13while it's running. 14 15However when dumping a protected VM we need to maintain its 16confidentiality until the dump is in the hands of the VM owner who 17should be the only one capable of analysing it. 18 19The confidentiality of the VM dump is ensured by the Ultravisor who 20provides an interface to KVM over which encrypted CPU and memory data 21can be requested. The encryption is based on the Customer 22Communication Key which is the key that's used to encrypt VM data in a 23way that the customer is able to decrypt. 24 25 26Dump process 27------------ 28 29A dump is done in 3 steps: 30 31**Initiation** 32 33This step initializes the dump process, generates cryptographic seeds 34and extracts dump keys with which the VM dump data will be encrypted. 35 36**Data gathering** 37 38Currently there are two types of data that can be gathered from a VM: 39the memory and the vcpu state. 40 41The vcpu state contains all the important registers, general, floating 42point, vector, control and tod/timers of a vcpu. The vcpu dump can 43contain incomplete data if a vcpu is dumped while an instruction is 44emulated with help of the hypervisor. This is indicated by a flag bit 45in the dump data. For the same reason it is very important to not only 46write out the encrypted vcpu state, but also the unencrypted state 47from the hypervisor. 48 49The memory state is further divided into the encrypted memory and its 50metadata comprised of the encryption tweaks and status flags. The 51encrypted memory can simply be read once it has been exported. The 52time of the export does not matter as no re-encryption is 53needed. Memory that has been swapped out and hence was exported can be 54read from the swap and written to the dump target without need for any 55special actions. 56 57The tweaks / status flags for the exported pages need to be requested 58from the Ultravisor. 59 60**Finalization** 61 62The finalization step will provide the data needed to be able to 63decrypt the vcpu and memory data and end the dump process. When this 64step completes successfully a new dump initiation can be started. 65