Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Mon, 7 Feb 2022 16:17:19 +0100
From:   Claudio Imbrenda <imbrenda@linux.ibm.com>
To:     Janosch Frank <frankja@linux.ibm.com>
Cc:     kvm@vger.kernel.org, borntraeger@de.ibm.com, thuth@redhat.com,
        pasic@linux.ibm.com, david@redhat.com, linux-s390@vger.kernel.org,
        linux-kernel@vger.kernel.org, scgl@linux.ibm.com
Subject: Re: [PATCH v7 15/17] KVM: s390: pv: api documentation for
 asynchronous destroy
Message-ID: <20220207161719.5147058a@p-imbrenda>
In-Reply-To: <99296cad-5f74-d9ab-544c-b2d1a557b226@linux.ibm.com>
References: <20220204155349.63238-1-imbrenda@linux.ibm.com>
        <20220204155349.63238-16-imbrenda@linux.ibm.com>
        <99296cad-5f74-d9ab-544c-b2d1a557b226@linux.ibm.com>
Organization: IBM
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk

On Mon, 7 Feb 2022 15:52:37 +0100
Janosch Frank <frankja@linux.ibm.com> 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@linux.ibm.com>
> > ---
> >   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
> >   ----------------------------
> >   
> >   
>