Re: [PATCH v5 09/10] Documentation: virt: Protected virtual machine dumps

Claudio Imbrenda
2022-05-17T11:42:30Z

On Mon, 16 May 2022 09:08:16 +0000
Janosch Frank <frankja@linux.ibm.com> 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@linux.ibm.com>

Acked-by: Claudio Imbrenda <imbrenda@linux.ibm.com>

> ---
> 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.