On Mon, 16 May 2022 09:08:17 +0000
Janosch Frank <frankja@xxxxxxxxxxxxx> wrote:
> Time to add the dump API changes to the api documentation file.
> Also some minor cleanup.
>
> Signed-off-by: Janosch Frank <frankja@xxxxxxxxxxxxx>
> ---
> 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
> =========================
>
