On Tue, 17 May 2022 16:36:28 +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> Acked-by: Claudio Imbrenda <imbrenda@xxxxxxxxxxxxx> > --- > Documentation/virt/kvm/api.rst | 155 ++++++++++++++++++++++++++++++++- > 1 file changed, 153 insertions(+), 2 deletions(-) > > diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst > index 09353e27bdbc..06d1b717b032 100644 > --- a/Documentation/virt/kvm/api.rst > +++ b/Documentation/virt/kvm/api.rst > @@ -5067,7 +5067,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 > @@ -5083,7 +5083,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 > @@ -5100,6 +5099,117 @@ 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. buff_user might be written to > + even if an error rc is returned. For instance if we encounter a > + fault after writing the first page of data. > + > + 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 > ---------------------------- > > @@ -5652,6 +5762,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 > ======================== > > @@ -7729,6 +7865,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 > ========================= >