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