Messages in this thread | | | From | Paolo Bonzini <> | Date | Wed, 17 Apr 2024 13:56:20 +0200 | Subject | Re: [PATCH v2 01/10] KVM: Document KVM_MAP_MEMORY ioctl |
| |
On Tue, Apr 16, 2024 at 1:27 AM Edgecombe, Rick P <rick.p.edgecombe@intel.com> wrote: > > + EAGAIN The region is only processed partially. The caller should > > + issue the ioctl with the updated parameters when `size` > 0. > > + EINTR An unmasked signal is pending. The region may be processed > > + 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` in (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 not > > +mandatory for all vcpus to issue this ioctl. A single vcpu can suffice. > > +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 triggering > > +underlying technology-specific initialization. For example, CoCo-related > > +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 required > > for > > +such operations. > > Probably don't want to have TDX bits in here yet. Since it's talking about 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
| |