Re: [RFC PATCH 1/8] KVM: Document KVM_MAP_MEMORY ioctl

[Isaku Yamahata <isaku.yamahata@linux.intel.com>]

On Wed, Mar 06, 2024 at 04:43:51PM -0800,
David Matlack <dmatlack@google.com> wrote:

> On 2024-03-01 09:28 AM, isaku.yamahata@intel.com wrote:
> > From: Isaku Yamahata <isaku.yamahata@intel.com>
> > +
> > +  struct kvm_memory_mapping {
> > +	__u64 base_gfn;
> > +	__u64 nr_pages;
> > +	__u64 flags;
> > +	__u64 source;
> > +  };
> > +
> > +  /* For kvm_memory_mapping:: flags */
> > +  #define KVM_MEMORY_MAPPING_FLAG_WRITE         _BITULL(0)
> > +  #define KVM_MEMORY_MAPPING_FLAG_EXEC          _BITULL(1)
> > +  #define KVM_MEMORY_MAPPING_FLAG_USER          _BITULL(2)
> > +  #define KVM_MEMORY_MAPPING_FLAG_PRIVATE       _BITULL(3)
> > +
> > +KVM_MAP_MEMORY populates guest memory in the underlying mapping. If source is
> > +not zero and it's supported (depending on underlying technology), the guest
> > +memory content is populated with the source.
> 
> What does "populated with the source" mean?

source is user pointer and the memory contents of source is copied into
base_gfn. (and it will encrypted.)


> > The flags field supports three
> > +flags: KVM_MEMORY_MAPPING_FLAG_WRITE, KVM_MEMORY_MAPPING_FLAG_EXEC, and
> > +KVM_MEMORY_MAPPING_FLAG_USER.
> 
> There are 4 flags.

Oops. Let me update it.


KVM_MAP_MEMORY populates guest memory at the specified range (`base_gfn`,
`nr_pages`) in the underlying mapping. `source` is an optional user pointer. If
`source` is not NULL and the underlying technology supports it, the memory
contents of `source` are copied into the guest memory. The backend may encrypt
it.

The `flags` field supports four flags: KVM_MEMORY_MAPPING_FLAG_WRITE,
KVM_MEMORY_MAPPING_FLAG_EXEC, KVM_MEMORY_MAPPING_FLAG_USER, and
KVM_MEMORY_MAPPING_FLAGS_PRIVATE. The first three correspond to the fault code
for the KVM page fault to populate guest memory.  write fault, fetch fault, and
user fault.  KVM_MEMORY_MAPPING_FLAGS_PRIVATE is applicable only for guest
memory with guest_memfd.  It is to populate guest memory with the memory
attribute of KVM_MEMORY_ATTRIBUTE_PRIVATE set.

When the ioctl returns, the input values are updated.  If `nr_pages` is large,
it may return -EAGAIN and update the values (`base_gfn` and `nr_pages`. `source`
if not zero) to point to the remaining range.

-- 
Isaku Yamahata <isaku.yamahata@linux.intel.com>