Received-SPF: pass (google.com: domain of linux-kernel+bounces-148439-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.80.249 as permitted sender) client-ip=147.75.80.249;
Precedence: bulk
MIME-Version: 1.0
References: <cover.1712785629.git.isaku.yamahata@intel.com>
 <9a060293c9ad9a78f1d8994cfe1311e818e99257.1712785629.git.isaku.yamahata@intel.com>
 <28923ef142d588836201a1533b73fe4d89ce4696.camel@intel.com>
In-Reply-To: <28923ef142d588836201a1533b73fe4d89ce4696.camel@intel.com>
From: Paolo Bonzini <pbonzini@redhat.com>
Date: Wed, 17 Apr 2024 13:56:20 +0200
Message-ID: <CABgObfaOkP+ECAxFz6AUBo-HTiZng3HOZDQ9kxeewpxc1yNNJg@mail.gmail.com>
Subject: Re: [PATCH v2 01/10] KVM: Document KVM_MAP_MEMORY ioctl
To: "Edgecombe, Rick P" <rick.p.edgecombe@intel.com>
Cc: "kvm@vger.kernel.org" <kvm@vger.kernel.org>, "Yamahata, Isaku" <isaku.yamahata@intel.com>, 
	"seanjc@google.com" <seanjc@google.com>, "Huang, Kai" <kai.huang@intel.com>, 
	"federico.parola@polito.it" <federico.parola@polito.it>, 
	"linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>, 
	"isaku.yamahata@gmail.com" <isaku.yamahata@gmail.com>, "dmatlack@google.com" <dmatlack@google.com>, 
	"michael.roth@amd.com" <michael.roth@amd.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Tue, Apr 16, 2024 at 1:27=E2=80=AFAM Edgecombe, Rick P
<rick.p.edgecombe@intel.com> wrote:
> > +  EAGAIN     The region is only processed partially.  The caller shoul=
d
> > +             issue the ioctl with the updated parameters when `size` >=
 0.
> > +  EINTR      An unmasked signal is pending.  The region may be process=
ed
> > +             partially.

The common convention is to only return errno if no page was processed.

> > +KVM_MAP_MEMORY populates guest memory with the range, `base_address` i=
n (L1)
> > +guest physical address(GPA) and `size` in bytes.  `flags` must be zero=
  It's
> > +reserved for future use.  When the ioctl returns, the input values are
> > updated
> > +to point to the remaining range.  If `size` > 0 on return, the caller =
should
> > +issue the ioctl with the updated parameters.
> > +
> > +Multiple vcpus are allowed to call this ioctl simultaneously.  It's no=
t
> > +mandatory for all vcpus to issue this ioctl.  A single vcpu can suffic=
e.
> > +Multiple vcpus invocations are utilized for scalability to process the
> > +population in parallel.  If multiple vcpus call this ioctl in parallel=
, it
> > may
> > +result in the error of EAGAIN due to race conditions.
> > +
> > +This population is restricted to the "pure" population without trigger=
ing
> > +underlying technology-specific initialization.  For example, CoCo-rela=
ted
> > +operations won't perform.  In the case of TDX, this API won't invoke
> > +TDH.MEM.PAGE.ADD() or TDH.MR.EXTEND().  Vendor-specific uAPIs are requ=
ired
> > for
> > +such operations.
>
> Probably don't want to have TDX bits in here yet. Since it's talking abou=
t what
> KVM_MAP_MEMORY is *not* doing, it can just be dropped.

Let's rewrite everything to be more generic:

+KVM_MAP_MEMORY populates guest memory in the page tables of a vCPU.
+When the ioctl returns, the input values are updated to point to the
+remaining range.  If `size` > 0 on return, the caller should
+issue the ioctl again with updated parameters.
+
+In some cases, multiple vCPUs might share the page tables.  In this
+case, if this ioctl is called in parallel for multiple vCPUs the
+ioctl might return with `size > 0`.
+
+The ioctl may not be supported for all VMs.  You may use
+`KVM_CHECK_EXTENSION` on the VM file descriptor to check if it is
+supported.
+
+`flags` must currently be zero.


Paolo