Re: [PATCH v10 11/41] KVM: guest_memfd: Ensure pages are not in use before conversion

[Sean Christopherson <seanjc@google.com>]

On Mon, Aug 10, 2026, Ackerley Tng wrote:
> "David Hildenbrand (Arm)" <david@kernel.org> writes:
> 
> > On 8/7/26 23:52, Ackerley Tng via B4 Relay wrote:
> >> From: Ackerley Tng <ackerleytng@google.com>
> >>
> >> When converting memory to private in guest_memfd, it is necessary to ensure
> >> that the pages are not currently being accessed by any other part of the
> >> kernel or userspace to avoid any current user writing to guest private
> >> memory.
> >>
> >> guest_memfd checks for unexpected refcounts to determine whether a page is
> >> still in use. The only expected refcounts after unmapping the range
> >> requested for conversion are those that are held by guest_memfd itself.
> >>
> >> Update the kvm_memory_attributes2 structure to include an error_offset
> >> field. This allows KVM to report the exact offset where a conversion
> >> failed to userspace. If the safety check fails, return -EAGAIN and copy
> >> the error_offset back to userspace so that it can potentially retry the
> >> operation or handle the failure gracefully.
> >>
> >> Update documentation to document the error_offset field and the possible
> >> -EAGAIN error.
> >>
> >> Suggested-by: David Hildenbrand <david@kernel.org>
> >> Co-developed-by: Vishal Annapurve <vannapurve@google.com>
> >> Signed-off-by: Vishal Annapurve <vannapurve@google.com>
> >> Reviewed-by: Fuad Tabba <tabba@google.com>
> >> Tested-by: Shivank Garg <shivankg@amd.com>
> >> Signed-off-by: Ackerley Tng <ackerleytng@google.com>
> >> ---
> >
> > [...]
> >
> >>  #define KVM_MEMORY_ATTRIBUTE_PRIVATE           (1ULL << 3)
> >> diff --git a/virt/kvm/guest_memfd.c b/virt/kvm/guest_memfd.c
> >> index 3783e63476569..13c3989136f67 100644
> >> --- a/virt/kvm/guest_memfd.c
> >> +++ b/virt/kvm/guest_memfd.c
> >> @@ -524,8 +524,42 @@ static int kvm_gmem_mas_preallocate(struct ma_state *mas, u64 attributes,
> >>  	return mas_preallocate(mas, xa_mk_value(attributes), GFP_KERNEL);
> >>  }
> >>
> >> +static bool kvm_gmem_is_safe_for_conversion(struct inode *inode, pgoff_t start,
> >> +					    size_t nr_pages, pgoff_t *err_index)
> >
> > I would focus on the "to_private" aspect or abstract it to
> > "kvm_gmem_mem_has_unexpected_refs" or sth like that.

+1.  Maybe "kvm_gmem_page_has_outstanding_references"?

> Do you mean something like kvm_gmem_is_safe_for_to_private_conversion,
> as in that you want to emphasise that "safe" here refers to a to_private
> and not a to_shared conversion?

I'm obviously not David, but for me, the problem with names like
kvm_gmem_is_safe_for_conversion() is that (a) it conflates what the function is
literally doing with how the function is being used, which often makes the code
harder to understand as it obfuscates things, and (b) can become stale or even
outright broken far too easily.  E.g. if KVM adds more checks on whether
or not a conversion is "safe", then the name of the function is a lie because it
doesn't actually check that the target data is safe for conversion, only that
its "safe" for a specific aspect of conversion.

And there is real risk to hiding what a function does.  E.g. looking at this code
without diving into the details:

        if (to_private) {
                unmap_mapping_pages(mapping, start, nr_pages, false);

                if (!kvm_gmem_is_safe_for_conversion(inode, start, nr_pages,
                                                     err_index)) {
                        mas_destroy(&mas);
                        r = -EAGAIN;
                        goto out;
                }
        }

and one might thing that it's perfectly find to check for "safety" before
unmapping pages.   In fact, looking at the code without a priori knowledge of
the rules, and the above flat out looks wrong.  E.g. I could definitely see
someone "fixing" the code to:

        if (to_private) {
                if (!kvm_gmem_is_safe_for_conversion(inode, start, nr_pages,
                                                     err_index)) {
                        mas_destroy(&mas);
                        r = -EAGAIN;
                        goto out;
                }

                unmap_mapping_pages(mapping, start, nr_pages, false);
	}

Whereas this:

        if (to_private) {
                unmap_mapping_pages(mapping, start, nr_pages, false);

                if (kvm_gmem_has_outstanding_references(inode, start, nr_pages,
							err_index)) {
                        mas_destroy(&mas);
                        r = -EAGAIN;
                        goto out;
                }
        }

helps the reader understand what's being checked without having to look at the
details, and also helps communicate the ordering dependency without needing a
comment.

There are definitely times where the usage of a function bleeds into its name,
but usually that's because the name and the usage are on and the same.  E.g.
get_user() describes both the usage and the "what".  And it's easy/possible to
go too far in the opposite direction, e.g. by giving a play-by-play of what a
function is doing, but that's why we have bikshedding sessions :-)

> Perhaps a little ahead of its time,

Ya.

> but later with restructuring for huge pages, we also need no additional
> refcounts other than gmem's own so that restructuring is safe, hence this
> function name was meant to extend there as well.

Given that I've read that at least five times and still don't understand the
nuance, I think it's safe (ha!) to say we'll need to revisit and review those
changes no matter what. :-)

 
> In this case "unexpected" (especially since the next patch adds checks
> for maybe dma pinned and unmapping), begs the question "unexpected in
> what way"?

Ya, that's why I like "outstanding", it succinctly captures that one or more
references have been "loaned" but not yet "repaid".

> >> +	struct address_space *mapping = inode->i_mapping;
> >> +	const int filemap_get_folios_refcount = 1;
> >> +	pgoff_t last = start + nr_pages - 1;
> >> +	struct folio_batch fbatch;
> >> +	bool safe = true;
> >> +	pgoff_t next;
> >> +	int i;
> >> +
> >> +	folio_batch_init(&fbatch);
> >> +
> >> +	next = start;
> >> +	while (safe && filemap_get_folios(mapping, &next, last, &fbatch)) {
> >> +		for (i = 0; i < folio_batch_count(&fbatch); ++i) {
> >> +			struct folio *folio = fbatch.folios[i];
> >> +
> >> +			if (folio_ref_count(folio) !=
> >> +			    folio_nr_pages(folio) + filemap_get_folios_refcount) {
> >
> > I'd rather add a comment than have this filemap_get_folios_refcount.

+1, the local variable just made me scratch my head.

> >
> > /*
> >  * We expect one reference per folio-page in the pagecache and one
> >  * reference from filemap_get_folios().

Nit, please no pronouns in KVM code.

> >  */
> > if (folio_ref_count(folio) != folio_nr_pages(folio) + 1)
> >
> 
> This comment explains what's "unexpected". I can do this and switch it
> to kvm_gmem_mem_has_unexpected_refs() unless people have other
> suggestions.
> 
> I wish there was a folio_pagecache_refs(folio) that
> folio_expected_ref_count() can share with this, and also
> folio_swapcache_refs(), to solidify the definition of refcounts taken by
> the pagecache.

...

> >> @@ -542,8 +576,21 @@ static int __kvm_gmem_set_attributes(struct inode *inode, pgoff_t start,
> >>
> >>  	mas_init(&mas, mt, start);
> >>  	r = kvm_gmem_mas_preallocate(&mas, attrs, start, nr_pages);
> >> -	if (r)
> >> +	if (r) {
> >> +		*err_index = start;
> >>  		goto out;
> >> +	}
> >> +
> >> +	if (to_private) {
> >
> > I'd add a comment here for the "why are we unmapping".
> >
> 
> Does this sound right:
> 
> Unmap here to ensure that userspace page tables have no mappings, which
> also ensures refcounts from those mappings are dropped.

How about:

		/*
		 * Forcefully unmap the pages from all userspace page tables,
		 * and then verify there are no outstanding references, e.g.
		 * acquired via GUP or similar.  Tell userspace to try again if
		 * there are oustanding references and hope that whatever has
		 * pinned the page will put its reference "soon".
		 */
		unmap_mapping_pages(mapping, start, nr_pages, false);

                if (!kvm_gmem_is_safe_for_conversion(inode, start, nr_pages,
                                                     err_index)) {
                        mas_destroy(&mas);
                        r = -EAGAIN;
                        goto out;
                }


> 
> > --
> > Cheers,
> >
> > David