Re: [PATCH v5 10/10] Documentation/virt/kvm/api.rst: Add protvirt dump/info api descriptions

[Claudio Imbrenda <imbrenda@linux.ibm.com>]

On Mon, 16 May 2022 09:08:17 +0000
Janosch Frank <frankja@linux.ibm.com> wrote:

> Time to add the dump API changes to the api documentation file.
> Also some minor cleanup.
> 
> Signed-off-by: Janosch Frank <frankja@linux.ibm.com>
> ---
>  Documentation/virt/kvm/api.rst | 153 ++++++++++++++++++++++++++++++++-
>  1 file changed, 151 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 4a900cdbc62e..c7c964887f5f 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -5061,7 +5061,7 @@ into ESA mode. This reset is a superset of the initial reset.
>  	__u32 reserved[3];
>    };
>  
> -cmd values:
> +**cmd values:**
>  
>  KVM_PV_ENABLE
>    Allocate memory and register the VM with the Ultravisor, thereby
> @@ -5077,7 +5077,6 @@ KVM_PV_ENABLE
>    =====      =============================
>  
>  KVM_PV_DISABLE
> -
>    Deregister the VM from the Ultravisor and reclaim the memory that
>    had been donated to the Ultravisor, making it usable by the kernel
>    again.  All registered VCPUs are converted back to non-protected
> @@ -5094,6 +5093,115 @@ KVM_PV_VM_VERIFY
>    Verify the integrity of the unpacked image. Only if this succeeds,
>    KVM is allowed to start protected VCPUs.
>  
> +KVM_PV_INFO
> +  :Capability: KVM_CAP_S390_PROTECTED_DUMP
> +
> +  Presents an API that provides Ultravisor related data to userspace
> +  via subcommands. len_max is the size of the user space buffer,
> +  len_written is KVM's indication of how much bytes of that buffer
> +  were actually written to. len_written can be used to determine the
> +  valid fields if more response fields are added in the future.
> +
> +  ::
> +
> +     enum pv_cmd_info_id {
> +        KVM_PV_INFO_VM,
> +        KVM_PV_INFO_DUMP,
> +     };
> +
> +     struct kvm_s390_pv_info_header {
> +        __u32 id;
> +        __u32 len_max;
> +        __u32 len_written;
> +        __u32 reserved;
> +     };
> +
> +     struct kvm_s390_pv_info {
> +        struct kvm_s390_pv_info_header header;
> +        struct kvm_s390_pv_info_dump dump;
> +	struct kvm_s390_pv_info_vm vm;
> +     };
> +
> +**subcommands:**
> +
> +  KVM_PV_INFO_VM
> +    This subcommand provides basic Ultravisor information for PV
> +    hosts. These values are likely also exported as files in the sysfs
> +    firmware UV query interface but they are more easily available to
> +    programs in this API.
> +
> +    The installed calls and feature_indication members provide the
> +    installed UV calls and the UV's other feature indications.
> +
> +    The max_* members provide information about the maximum number of PV
> +    vcpus, PV guests and PV guest memory size.
> +
> +    ::
> +
> +      struct kvm_s390_pv_info_vm {
> +        __u64 inst_calls_list[4];
> +        __u64 max_cpus;
> +        __u64 max_guests;
> +        __u64 max_guest_addr;
> +        __u64 feature_indication;
> +      };
> +
> +
> +  KVM_PV_INFO_DUMP
> +    This subcommand provides information related to dumping PV guests.
> +
> +    ::
> +
> +      struct kvm_s390_pv_info_dump {
> +        __u64 dump_cpu_buffer_len;
> +        __u64 dump_config_mem_buffer_per_1m;
> +        __u64 dump_config_finalize_len;
> +      };
> +
> +KVM_PV_DUMP
> +  :Capability: KVM_CAP_S390_PROTECTED_DUMP
> +
> +  Presents an API that provides calls which facilitate dumping a
> +  protected VM.
> +
> +  ::
> +
> +    struct kvm_s390_pv_dmp {
> +      __u64 subcmd;
> +      __u64 buff_addr;
> +      __u64 buff_len;
> +      __u64 gaddr;		/* For dump storage state */
> +    };
> +
> +  **subcommands:**
> +
> +  KVM_PV_DUMP_INIT
> +    Initializes the dump process of a protected VM. If this call does
> +    not succeed all other subcommands will fail with -EINVAL. This
> +    subcommand will return -EINVAL if a dump process has not yet been
> +    completed.
> +
> +    Not all PV vms can be dumped, the owner needs to set `dump
> +    allowed` PCF bit 34 in the SE header to allow dumping.
> +
> +  KVM_PV_DUMP_CONFIG_STOR_STATE
> +    Stores `buff_len` bytes of tweak component values starting with
> +    the 1MB block specified by the absolute guest address
> +    (`gaddr`). `buff_len` needs to be `conf_dump_storage_state_len`
> +    aligned and at least >= the `conf_dump_storage_state_len` value
> +    provided by the dump uv_info data.

please explain that the output buffer might be written to (even
partially) even when the IOCTL fails

> +
> +  KVM_PV_DUMP_COMPLETE
> +    If the subcommand succeeds it completes the dump process and lets
> +    KVM_PV_DUMP_INIT be called again.
> +
> +    On success `conf_dump_finalize_len` bytes of completion data will be
> +    stored to the `buff_addr`. The completion data contains a key
> +    derivation seed, IV, tweak nonce and encryption keys as well as an
> +    authentication tag all of which are needed to decrypt the dump at a
> +    later time.
> +
> +
>  4.126 KVM_X86_SET_MSR_FILTER
>  ----------------------------
>  
> @@ -5646,6 +5754,32 @@ The offsets of the state save areas in struct kvm_xsave follow the contents
>  of CPUID leaf 0xD on the host.
>  
>  
> +4.135 KVM_S390_PV_CPU_COMMAND
> +-----------------------------
> +
> +:Capability: KVM_CAP_S390_PROTECTED_DUMP
> +:Architectures: s390
> +:Type: vcpu ioctl
> +:Parameters: none
> +:Returns: 0 on success, < 0 on error
> +
> +This ioctl closely mirrors `KVM_S390_PV_COMMAND` but handles requests
> +for vcpus. It re-uses the kvm_s390_pv_dmp struct and hence also shares
> +the command ids.
> +
> +**command:**
> +
> +KVM_PV_DUMP
> +  Presents an API that provides calls which facilitate dumping a vcpu
> +  of a protected VM.
> +
> +**subcommand:**
> +
> +KVM_PV_DUMP_CPU
> +  Provides encrypted dump data like register values.
> +  The length of the returned data is provided by uv_info.guest_cpu_stor_len.
> +
> +
>  5. The kvm_run structure
>  ========================
>  
> @@ -7734,6 +7868,21 @@ At this time, KVM_PMU_CAP_DISABLE is the only capability.  Setting
>  this capability will disable PMU virtualization for that VM.  Usermode
>  should adjust CPUID leaf 0xA to reflect that the PMU is disabled.
>  
> +
> +8.36 KVM_CAP_S390_PROTECTED_DUMP
> +--------------------------------
> +
> +:Capability: KVM_CAP_S390_PROTECTED_DUMP
> +:Architectures: s390
> +:Type: vm
> +
> +This capability indicates that KVM and the Ultravisor support dumping
> +PV guests. The `KVM_PV_DUMP` command is available for the
> +`KVM_S390_PV_COMMAND` ioctl and the `KVM_PV_INFO` command provides
> +dump related UV data. Also the vcpu ioctl `KVM_S390_PV_CPU_COMMAND` is
> +available and supports the `KVM_PV_DUMP_CPU` subcommand.
> +
> +
>  9. Known KVM API problems
>  =========================
>