On Mon, 16 May 2022 09:08:16 +0000 Janosch Frank <frankja@xxxxxxxxxxxxx> wrote: > Let's add a documentation file which describes the dump process. Since > we only copy the UV dump data from the UV to userspace we'll not go > into detail here and let the party which processes the data describe > its structure. > > Signed-off-by: Janosch Frank <frankja@xxxxxxxxxxxxx> Acked-by: Claudio Imbrenda <imbrenda@xxxxxxxxxxxxx> > --- > Documentation/virt/kvm/s390/index.rst | 1 + > Documentation/virt/kvm/s390/s390-pv-dump.rst | 64 ++++++++++++++++++++ > 2 files changed, 65 insertions(+) > create mode 100644 Documentation/virt/kvm/s390/s390-pv-dump.rst > > diff --git a/Documentation/virt/kvm/s390/index.rst b/Documentation/virt/kvm/s390/index.rst > index 605f488f0cc5..44ec9ab14b59 100644 > --- a/Documentation/virt/kvm/s390/index.rst > +++ b/Documentation/virt/kvm/s390/index.rst > @@ -10,3 +10,4 @@ KVM for s390 systems > s390-diag > s390-pv > s390-pv-boot > + s390-pv-dump > diff --git a/Documentation/virt/kvm/s390/s390-pv-dump.rst b/Documentation/virt/kvm/s390/s390-pv-dump.rst > new file mode 100644 > index 000000000000..e542f06048f3 > --- /dev/null > +++ b/Documentation/virt/kvm/s390/s390-pv-dump.rst > @@ -0,0 +1,64 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +=========================================== > +s390 (IBM Z) Protected Virtualization dumps > +=========================================== > + > +Summary > +------- > + > +Dumping a VM is an essential tool for debugging problems inside > +it. This is especially true when a protected VM runs into trouble as > +there's no way to access its memory and registers from the outside > +while it's running. > + > +However when dumping a protected VM we need to maintain its > +confidentiality until the dump is in the hands of the VM owner who > +should be the only one capable of analysing it. > + > +The confidentiality of the VM dump is ensured by the Ultravisor who > +provides an interface to KVM over which encrypted CPU and memory data > +can be requested. The encryption is based on the Customer > +Communication Key which is the key that's used to encrypt VM data in a > +way that the customer is able to decrypt. > + > + > +Dump process > +------------ > + > +A dump is done in 3 steps: > + > +**Initiation** > + > +This step initializes the dump process, generates cryptographic seeds > +and extracts dump keys with which the VM dump data will be encrypted. > + > +**Data gathering** > + > +Currently there are two types of data that can be gathered from a VM: > +the memory and the vcpu state. > + > +The vcpu state contains all the important registers, general, floating > +point, vector, control and tod/timers of a vcpu. The vcpu dump can > +contain incomplete data if a vcpu is dumped while an instruction is > +emulated with help of the hypervisor. This is indicated by a flag bit > +in the dump data. For the same reason it is very important to not only > +write out the encrypted vcpu state, but also the unencrypted state > +from the hypervisor. > + > +The memory state is further divided into the encrypted memory and its > +metadata comprised of the encryption tweaks and status flags. The > +encrypted memory can simply be read once it has been exported. The > +time of the export does not matter as no re-encryption is > +needed. Memory that has been swapped out and hence was exported can be > +read from the swap and written to the dump target without need for any > +special actions. > + > +The tweaks / status flags for the exported pages need to be requested > +from the Ultravisor. > + > +**Finalization** > + > +The finalization step will provide the data needed to be able to > +decrypt the vcpu and memory data and end the dump process. When this > +step completes successfully a new dump initiation can be started.
