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

[Claudio Imbrenda]

On Mon, 7 Feb 2022 15:52:37 +0100
Janosch Frank <frankja@xxxxxxxxxxxxx> wrote:

> 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.

I'm not sure we should give out implementation details, which might
change with newer kernel and/or hardware versions

> 
> 
> 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
> >   ----------------------------
> >   
> >   
>