mirror of
https://github.com/torvalds/linux.git
synced 2024-11-22 12:11:40 +00:00
Documentation/virt/kvm/api.rst: Add protvirt dump/info api descriptions
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> Acked-by: Claudio Imbrenda <imbrenda@linux.ibm.com> Link: https://lore.kernel.org/r/20220517163629.3443-11-frankja@linux.ibm.com Message-Id: <20220517163629.3443-11-frankja@linux.ibm.com> Signed-off-by: Christian Borntraeger <borntraeger@linux.ibm.com>
This commit is contained in:
Janosch Frank
Christian Borntraeger
parent
660a28653d
commit
437cfd714d
@ -5127,7 +5127,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
|
||||
@ -5143,7 +5143,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
|
||||
@ -5160,6 +5159,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
|
||||
----------------------------
|
||||
|
||||
@ -5802,6 +5912,32 @@ of CPUID leaf 0xD on the host.
|
||||
|
||||
This ioctl injects an event channel interrupt directly to the guest vCPU.
|
||||
|
||||
4.136 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
|
||||
========================
|
||||
|
||||
@ -7954,6 +8090,20 @@ should adjust CPUID leaf 0xA to reflect that the PMU is disabled.
|
||||
When enabled, KVM will exit to userspace with KVM_EXIT_SYSTEM_EVENT of
|
||||
type KVM_SYSTEM_EVENT_SUSPEND to process the guest suspend request.
|
||||
|
||||
8.37 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
|
||||
=========================
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user