Add documentation for the new commands added to the KVM_S390_PV_COMMAND
ioctl.
Signed-off-by: Claudio Imbrenda <[email protected]>
Reviewed-by: Nico Boehr <[email protected]>
---
Documentation/virt/kvm/api.rst | 30 ++++++++++++++++++++++++++++--
1 file changed, 28 insertions(+), 2 deletions(-)
diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index 9788b19f9ff7..5bd151b601b4 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -5163,8 +5163,11 @@ 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
- ones.
+ again. All registered VCPUs are converted back to non-protected
+ ones. If a previous VM had been set aside for asynchonous teardown
+ with KVM_PV_ASYNC_CLEANUP_PREPARE and not actually torn down with
+ KVM_PV_ASYNC_CLEANUP_PERFORM, it will be torn down in this call
+ together with the current VM.
KVM_PV_VM_SET_SEC_PARMS
Pass the image header from VM memory to the Ultravisor in
@@ -5287,6 +5290,29 @@ KVM_PV_DUMP
authentication tag all of which are needed to decrypt the dump at a
later time.
+KVM_PV_ASYNC_CLEANUP_PREPARE
+ Prepare the current protected VM for asynchronous teardown. Most
+ resources used by the current protected VM will be set aside for a
+ subsequent asynchronous teardown. The current protected VM will then
+ resume execution immediately as non-protected. There can be at most
+ one protected VM set aside at any time. If a protected VM had
+ already been set aside without starting the asynchronous teardown
+ process, this call will fail. In that case, the userspace process
+ should issue a normal KVM_PV_DISABLE. The resources set aside with
+ this call will need to be cleaned up with a subsequent call to
+ KVM_PV_ASYNC_CLEANUP_PERFORM or KVM_PV_DISABLE, otherwise they will
+ be cleaned up when KVM terminates.
+
+KVM_PV_ASYNC_CLEANUP_PERFORM
+ Tear down the protected VM previously set aside with
+ KVM_PV_ASYNC_CLEANUP_PREPARE. The resources that had been set aside
+ will be freed during the execution of this command. This PV command
+ should ideally be issued by userspace from a separate thread. If a
+ fatal signal is received (or the process terminates naturally), the
+ command will terminate immediately without completing, and the normal
+ KVM shutdown procedure will take care of cleaning up all remaining
+ protected VMs.
+
4.126 KVM_X86_SET_MSR_FILTER
----------------------------
--
2.37.1
On 8/10/22 14:56, Claudio Imbrenda wrote:
> Add documentation for the new commands added to the KVM_S390_PV_COMMAND
> ioctl.
>
> Signed-off-by: Claudio Imbrenda <[email protected]>
> Reviewed-by: Nico Boehr <[email protected]>
> ---
> Documentation/virt/kvm/api.rst | 30 ++++++++++++++++++++++++++++--
> 1 file changed, 28 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 9788b19f9ff7..5bd151b601b4 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -5163,8 +5163,11 @@ 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
> - ones.
> + again. All registered VCPUs are converted back to non-protected
> + ones. If a previous VM had been set aside for asynchonous teardown
> + with KVM_PV_ASYNC_CLEANUP_PREPARE and not actually torn down with
...and hasn't yet been torn down with...
> + KVM_PV_ASYNC_CLEANUP_PERFORM, it will be torn down in this call
> + together with the current VM.
current PV VM? or protected VM
I know it's missing in the unchanged paragraph above too but such is life.
>
> KVM_PV_VM_SET_SEC_PARMS
> Pass the image header from VM memory to the Ultravisor in
> @@ -5287,6 +5290,29 @@ KVM_PV_DUMP
> authentication tag all of which are needed to decrypt the dump at a
> later time.
>
> +KVM_PV_ASYNC_CLEANUP_PREPARE
> + Prepare the current protected VM for asynchronous teardown. Most
> + resources used by the current protected VM will be set aside for a
> + subsequent asynchronous teardown. The current protected VM will then
> + resume execution immediately as non-protected. There can be at most
> + one protected VM set aside at any time. If a protected VM had
> + already been set aside without starting the asynchronous teardown
> + process, this call will fail. In that case, the userspace process
If KVM_PV_ASYNC_CLEANUP_PREPARE has already been called without a
successful KVM_PV_ASYNC_CLEANUP_PERFORM this call will fail. I.e. only
be one PV VM can be set aside.
Do we need to finish the cleanup or is it enough to start the cleanup
like you describe here?
> + should issue a normal KVM_PV_DISABLE. The resources set aside with
> + this call will need to be cleaned up with a subsequent call to
> + KVM_PV_ASYNC_CLEANUP_PERFORM or KVM_PV_DISABLE, otherwise they will
> + be cleaned up when KVM terminates.
> +
> +KVM_PV_ASYNC_CLEANUP_PERFORM
> + Tear down the protected VM previously set aside with
> + KVM_PV_ASYNC_CLEANUP_PREPARE. The resources that had been set aside
> + will be freed during the execution of this command. This PV command
> + should ideally be issued by userspace from a separate thread. If a
> + fatal signal is received (or the process terminates naturally), the
> + command will terminate immediately without completing, and the normal
> + KVM shutdown procedure will take care of cleaning up all remaining
> + protected VMs.
> +
>
> 4.126 KVM_X86_SET_MSR_FILTER
> ----------------------------