On Mon, Sep 28, 2026 at 08:03:42AM +0200, Markus Armbruster wrote:
> Michael Roth <[email protected]> writes:
>
> > From: Peter Xu <[email protected]>
> >
> > Host backends supports guest-memfd now by detecting whether it's a
> > confidential VM. There's no way to choose it yet from the memory level to
> > use it fully shared. If we use guest-memfd, it so far always implies we
> > need two layers of memory backends, while the guest-memfd only provides the
> > private set of pages.
> >
> > This patch introduces a way so that QEMU can consume guest memfd as the
> > only source of memory to back the object (aka, fully shared).
> >
> > To use the fully shared guest-memfd, one can add a memfd object with:
> >
> > -object memory-backend-memfd,x-guest-memfd=on,share=on
> >
> > Note that share=on is required with fully shared guest_memfd.
> >
> > Since guest-memfd is not yet a drop-in replacement for memfd (e.g. lack
> > of hugepage support), the option is tagged as experimental for now so
> > that it can be made available for early enablement/testing without
> > causing any surprises for other users.
> >
> > PS: there's a trivial touch-up on fd<0 check, because the stub to create
> > guest-memfd may return negative but not -1.
> >
> > Reviewed-by: Xiaoyao Li <[email protected]>
> > Reviewed-by: Fabiano Rosas <[email protected]>
> > Reviewed-by: David Hildenbrand <[email protected]>
> > Signed-off-by: Peter Xu <[email protected]>
> > [mdr: add accompanying guest-memfd doc, mark as experimental]
> > Co-developed-by: Michael Roth <[email protected]>
> > Signed-off-by: Michael Roth <[email protected]>
>
> [...]
>
> > diff --git a/docs/system/guest-memfd.rst b/docs/system/guest-memfd.rst
> > new file mode 100644
> > index 0000000000..f7cef19283
> > --- /dev/null
> > +++ b/docs/system/guest-memfd.rst
> > @@ -0,0 +1,60 @@
> > +.. _guest-memfd:
> > +
> > +guest-memfd support
> > +===================
> > +
> > +Recent kernels allow for the creation of a guest-memfd file
> > +descriptor, which can be used to back VMs in a similar manner as a
> > +memfd file descriptor, but is intended specifically for this purpose
> > +and allows for closer coordination between KVM and the management of
> > +this memory to enable more advanced/VM-specific use-cases.
> > +
> > +Initially this additional functionality centered around providing a
> > +common/centralized place for managing kernel-side memory handing
> > +requirements for various Confidential Guest architectures. (For more
> > +on Confidential Guests, see :ref:`confidential-guest-support`).
> > +
> > +guest_memfd has since evolved to become a more general-purpose way to
> > +allocate/manage guest memory and potentially allow for things like
> > +providing additional memory isolation within the kernel[1] and support
> > +for persisting a guest's state across kexec to allow for live-updating
> > +the host kernel with minimal guest downtime[2].
> > +
> > +Usage
> > +-----
> > +
> > +For Confidential Guests, guest-memfd is currently utilized internally
> > +by QEMU to handle private guest memory, independently of whatever
> > +memory backend the user has configured for normal/non-private/shared
> > +guest memory. To avoid doubling memory, QEMU discards memory in
> > +response to the guest converting GPA ranges between shared/private.
> > +(e.g. if GPA X is converted from private to shared, the guest-memfd FD
> > +offset corresponding to GPA x will be truncated since the memory will
> > +be provided by the memory backend the user configured for shared
> > +memory, and vice-versa). This is handled automatically/internally for
> > +Confidential Guests that rely on this handling and is not directly
> > +exposed by QEMU command-line options.
> > +
> > +For non-Confidential guests, guest-memfd can be used in a manner that
> > +is somewhat interchangeable with a normal memfd. Currently, this is
> > +handled by using the same memory-backend implementation as memfd, but
> > +with an additional 'x-guest-memfd=on' option. E.g.::
> > +
> > + qemu ... \
> > + -object
> > memory-backend-memfd,id=ID,size=SIZE,share=on,x-guest-memfd=on
> > +
> > +Note that the share=on option is required for guest-memfd, since it
> > +does not support anonymous memory allocations or COW-like semantics.
> > +
> > +Also note that there are a couple of limitations in using guest_memfd
> > +in this way compared to a normal memfd, which is why the option is
> > +exposed as an experimental for the time being:
> > +
> > + * guest_memfd does not currently support the hugetlb=on option
> > + * guest_memfd does not currently support Transparent Huge Pages
> > +
> > +References
> > +----------
> > +
> > +- `[1] directmap removal
> > <https://lore.kernel.org/kvm/[email protected]/>`__
> > +- `[2] LUO
> > <https://lore.kernel.org/kvm/[email protected]/>`__
>
> This is helpful, thanks.
>
> > diff --git a/docs/system/index.rst b/docs/system/index.rst
> > index 4509630fa4..060850a739 100644
> > --- a/docs/system/index.rst
> > +++ b/docs/system/index.rst
> > @@ -44,3 +44,4 @@ or Hypervisor.Framework.
> > vm-templating
> > sriov
> > qemu-colo
> > + guest-memfd
> > diff --git a/qapi/qom.json b/qapi/qom.json
> > index 5895c97750..602b17ad83 100644
> > --- a/qapi/qom.json
> > +++ b/qapi/qom.json
> > @@ -780,13 +780,18 @@
> > # @seal: if true, create a sealed-file, which will block further
> > # resizing of the memory (default: true)
> > #
> > +# @x-guest-memfd: if 'on', use guest-memfd to back the memory region.
> > +# See the "guest-memfd" QEMU documentation for more details.
>
> Can you make this a link? Try :doc:`/system/guest-memfd`.
That works, thanks.
>
> > +# (default: auto, since: 11.2)
>
> What does 'auto' mean?
I've added some documentation for this in v7.
>
> > +#
> > # Since: 2.12
> > ##
> > { 'struct': 'MemoryBackendMemfdProperties',
> > 'base': 'MemoryBackendProperties',
> > 'data': { '*hugetlb': 'bool',
> > '*hugetlbsize': 'size',
> > - '*seal': 'bool' },
> > + '*seal': 'bool',
> > + '*x-guest-memfd': 'OnOffAuto' },
>
> You forgot to mark the member unstable. Use
>
> { 'name': 'x-guest-memfd', 'features': [ 'unstable' ] }
>
> This will make the generator demand documentation. Add this
>
> # Features:
> #
> # @unstable: Member @x-guest-memfd is experimental.
>
> between the member descriptions and "Since:".
>
> The 'x-' name prefix is fine, but not required; the feature is the sole
> source of truth. The prefix can serve as an additional signal to human
> users. Drawback: you have to rename when the member becomes stable. Up
> to you.
Thanks, I'd somehow missed that 'unstable' features deprecated the old school
"x-" stuff. Hopefully I got it right in v7 :) Based on Peter's recommendation
I went with 'guest-memfd'.
Thanks,
Mike
>
> > 'if': 'CONFIG_LINUX' }
> >
> > ##
>
