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