Re: [PATCH v7 15/17] KVM: s390: pv: api documentation for asynchronous destroy

[Janosch Frank]

On 2/4/22 16:53, Claudio Imbrenda wrote:
> Add documentation for the new commands added to the KVM_S390_PV_COMMAND
> ioctl.
>
> Signed-off-by: Claudio Imbrenda <imbrenda@xxxxxxxxxxxxx>
> ---
>   Documentation/virt/kvm/api.rst | 21 ++++++++++++++++++---
>   1 file changed, 18 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index a4267104db50..3b9068aceead 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -5010,11 +5010,13 @@ 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 prepared for asynchonous teardown
> +  with KVM_PV_ASYNC_DISABLE_PREPARE and not actually torn down with
> +  KVM_PV_ASYNC_DISABLE, 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
> @@ -5027,6 +5029,19 @@ KVM_PV_VM_VERIFY
>     Verify the integrity of the unpacked image. Only if this succeeds,
>     KVM is allowed to start protected VCPUs.
>   
> +KVM_PV_ASYNC_DISABLE_PREPARE
> +  Prepare the current protected VM for asynchronous teardown. The current

I think the first sentence needs a few more examples of what we do so 
the second sentence makes more sense.

...by setting aside the pointers to the donated storage, replacing the 
top most page table, destroying the first 2GB of memory and zeroing the 
KVM PV structs.


Or something which sounds a bit nicer.

> +  VM will then continue immediately as non-protected. If a protected VM had
> +  already been set aside without starting the teardown process, this call
> +  will fail. In this case the userspace process should issue a normal
> +  KVM_PV_DISABLE.
> +
> +KVM_PV_ASYNC_DISABLE
> +  Tear down the protected VM previously set aside for asynchronous teardown.
> +  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.
> +
>   4.126 KVM_X86_SET_MSR_FILTER
>   ----------------------------
>