Re: [PATCH v13 2/6] KVM: s390: pv: api documentation for asynchronous destroy

[Janosch Frank]

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 <imbrenda@xxxxxxxxxxxxx>
> Reviewed-by: Nico Boehr <nrb@xxxxxxxxxxxxx>
> ---
>   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
>   ----------------------------