Re: [PATCH v2 02/16] mm: introduce leaf entry type and use to simplify leaf entry logic

[Kairui Song <ryncsn@gmail.com>]

On Sun, Nov 9, 2025 at 1:41 AM Lorenzo Stoakes
<lorenzo.stoakes@oracle.com> wrote:
>
> The kernel maintains leaf page table entries which contain either:
>
> - Nothing ('none' entries)
> - Present entries (that is stuff the hardware can navigate without fault)
> - Everything else that will cause a fault which the kernel handles
>
> In the 'everything else' group we include swap entries, but we also include
> a number of other things such as migration entries, device private entries
> and marker entries.
>
> Unfortunately this 'everything else' group expresses everything through
> a swp_entry_t type, and these entries are referred to swap entries even
> though they may well not contain a... swap entry.
>
> This is compounded by the rather mind-boggling concept of a non-swap swap
> entry (checked via non_swap_entry()) and the means by which we twist and
> turn to satisfy this.
>
> This patch lays the foundation for reducing this confusion.
>
> We refer to 'everything else' as a 'software-define leaf entry' or
> 'softleaf'. for short And in fact we scoop up the 'none' entries into this
> concept also so we are left with:
>
> - Present entries.
> - Softleaf entries (which may be empty).
>
> This allows for radical simplification across the board - one can simply
> convert any leaf page table entry to a leaf entry via softleaf_from_pte().
>
> If the entry is present, we return an empty leaf entry, so it is assumed
> the caller is aware that they must differentiate between the two categories
> of page table entries, checking for the former via pte_present().
>
> As a result, we can eliminate a number of places where we would otherwise
> need to use predicates to see if we can proceed with leaf page table entry
> conversion and instead just go ahead and do it unconditionally.
>
> We do so where we can, adjusting surrounding logic as necessary to
> integrate the new softleaf_t logic as far as seems reasonable at this
> stage.
>
> We typedef swp_entry_t to softleaf_t for the time being until the
> conversion can be complete, meaning everything remains compatible
> regardless of which type is used. We will eventually remove swp_entry_t
> when the conversion is complete.
>
> We introduce a new header file to keep things clear - leafops.h - this
> imports swapops.h so can direct replace swapops imports without issue, and
> we do so in all the files that require it.
>
> Additionally, add new leafops.h file to core mm maintainers entry.
>
> Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
> ---
>  MAINTAINERS                   |   1 +
>  fs/proc/task_mmu.c            |  26 +--
>  fs/userfaultfd.c              |   6 +-
>  include/linux/leafops.h       | 382 ++++++++++++++++++++++++++++++++++
>  include/linux/mm_inline.h     |   6 +-
>  include/linux/mm_types.h      |  25 +++
>  include/linux/swapops.h       |  28 ---
>  include/linux/userfaultfd_k.h |  51 +----
>  mm/hmm.c                      |   2 +-
>  mm/hugetlb.c                  |  37 ++--
>  mm/madvise.c                  |  16 +-
>  mm/memory.c                   |  41 ++--
>  mm/mincore.c                  |   6 +-
>  mm/mprotect.c                 |   6 +-
>  mm/mremap.c                   |   4 +-
>  mm/page_vma_mapped.c          |  11 +-
>  mm/shmem.c                    |   7 +-
>  mm/userfaultfd.c              |   6 +-
>  18 files changed, 497 insertions(+), 164 deletions(-)
>  create mode 100644 include/linux/leafops.h

Hi Lorenzo,

Thanks, overloading swap entry types for things like migration always
looked confusing to me.

There is a problem with this patch as I mentioned here:
https://lore.kernel.org/linux-mm/CAMgjq7AP383YfU3L5ZxJ9U3x-vRPnEkEUtmnPdXD29HiNC8OrA@mail.gmail.com/

>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 2628431dcdfe..314910a70bbf 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -16257,6 +16257,7 @@ T:      git git://git.kernel.org/pub/scm/linux/kernel/git/akpm/mm
>  F:     include/linux/gfp.h
>  F:     include/linux/gfp_types.h
>  F:     include/linux/highmem.h
> +F:     include/linux/leafops.h
>  F:     include/linux/memory.h
>  F:     include/linux/mm.h
>  F:     include/linux/mm_*.h
> diff --git a/fs/proc/task_mmu.c b/fs/proc/task_mmu.c
> index fc35a0543f01..24d26b49d870 100644
> --- a/fs/proc/task_mmu.c
> +++ b/fs/proc/task_mmu.c
> @@ -14,7 +14,7 @@
>  #include <linux/rmap.h>
>  #include <linux/swap.h>
>  #include <linux/sched/mm.h>
> -#include <linux/swapops.h>
> +#include <linux/leafops.h>
>  #include <linux/mmu_notifier.h>
>  #include <linux/page_idle.h>
>  #include <linux/shmem_fs.h>
> @@ -1230,11 +1230,11 @@ static int smaps_hugetlb_range(pte_t *pte, unsigned long hmask,
>         if (pte_present(ptent)) {
>                 folio = page_folio(pte_page(ptent));
>                 present = true;
> -       } else if (is_swap_pte(ptent)) {
> -               swp_entry_t swpent = pte_to_swp_entry(ptent);
> +       } else {
> +               const softleaf_t entry = softleaf_from_pte(ptent);
>
> -               if (is_pfn_swap_entry(swpent))
> -                       folio = pfn_swap_entry_folio(swpent);
> +               if (softleaf_has_pfn(entry))
> +                       folio = softleaf_to_folio(entry);
>         }
>
>         if (folio) {
> @@ -1955,9 +1955,9 @@ static pagemap_entry_t pte_to_pagemap_entry(struct pagemapread *pm,
>                 flags |= PM_SWAP;
>                 if (is_pfn_swap_entry(entry))
>                         page = pfn_swap_entry_to_page(entry);
> -               if (pte_marker_entry_uffd_wp(entry))
> +               if (softleaf_is_uffd_wp_marker(entry))
>                         flags |= PM_UFFD_WP;
> -               if (is_guard_swp_entry(entry))
> +               if (softleaf_is_guard_marker(entry))
>                         flags |=  PM_GUARD_REGION;
>         }
>
> @@ -2330,18 +2330,18 @@ static unsigned long pagemap_page_category(struct pagemap_scan_private *p,
>                 if (pte_soft_dirty(pte))
>                         categories |= PAGE_IS_SOFT_DIRTY;
>         } else if (is_swap_pte(pte)) {
> -               swp_entry_t swp;
> +               softleaf_t entry;
>
>                 categories |= PAGE_IS_SWAPPED;
>                 if (!pte_swp_uffd_wp_any(pte))
>                         categories |= PAGE_IS_WRITTEN;
>
> -               swp = pte_to_swp_entry(pte);
> -               if (is_guard_swp_entry(swp))
> +               entry = softleaf_from_pte(pte);
> +               if (softleaf_is_guard_marker(entry))
>                         categories |= PAGE_IS_GUARD;
>                 else if ((p->masks_of_interest & PAGE_IS_FILE) &&
> -                        is_pfn_swap_entry(swp) &&
> -                        !folio_test_anon(pfn_swap_entry_folio(swp)))
> +                        softleaf_has_pfn(entry) &&
> +                        !folio_test_anon(softleaf_to_folio(entry)))
>                         categories |= PAGE_IS_FILE;
>
>                 if (pte_swp_soft_dirty(pte))
> @@ -2466,7 +2466,7 @@ static void make_uffd_wp_huge_pte(struct vm_area_struct *vma,
>  {
>         unsigned long psize;
>
> -       if (is_hugetlb_entry_hwpoisoned(ptent) || is_pte_marker(ptent))
> +       if (is_hugetlb_entry_hwpoisoned(ptent) || pte_is_marker(ptent))
>                 return;
>
>         psize = huge_page_size(hstate_vma(vma));
> diff --git a/fs/userfaultfd.c b/fs/userfaultfd.c
> index 04c66b5001d5..e33e7df36927 100644
> --- a/fs/userfaultfd.c
> +++ b/fs/userfaultfd.c
> @@ -29,7 +29,7 @@
>  #include <linux/ioctl.h>
>  #include <linux/security.h>
>  #include <linux/hugetlb.h>
> -#include <linux/swapops.h>
> +#include <linux/leafops.h>
>  #include <linux/miscdevice.h>
>  #include <linux/uio.h>
>
> @@ -251,7 +251,7 @@ static inline bool userfaultfd_huge_must_wait(struct userfaultfd_ctx *ctx,
>         if (huge_pte_none(pte))
>                 return true;
>         /* UFFD PTE markers require handling. */
> -       if (is_uffd_pte_marker(pte))
> +       if (pte_is_uffd_marker(pte))
>                 return true;
>         /* If VMA has UFFD WP faults enabled and WP fault, wait for handler. */
>         if (!huge_pte_write(pte) && (reason & VM_UFFD_WP))
> @@ -330,7 +330,7 @@ static inline bool userfaultfd_must_wait(struct userfaultfd_ctx *ctx,
>         if (pte_none(ptent))
>                 goto out;
>         /* UFFD PTE markers require handling. */
> -       if (is_uffd_pte_marker(ptent))
> +       if (pte_is_uffd_marker(ptent))
>                 goto out;
>         /* If VMA has UFFD WP faults enabled and WP fault, wait for handler. */
>         if (!pte_write(ptent) && (reason & VM_UFFD_WP))
> diff --git a/include/linux/leafops.h b/include/linux/leafops.h
> new file mode 100644
> index 000000000000..1376589d94b0
> --- /dev/null
> +++ b/include/linux/leafops.h
> @@ -0,0 +1,382 @@
> +/* SPDX-License-Identifier: GPL-2.0 */
> +/*
> + * Describes operations that can be performed on software-defined page table
> + * leaf entries. These are abstracted from the hardware page table entries
> + * themselves by the softleaf_t type, see mm_types.h.
> + */
> +#ifndef _LINUX_LEAFOPS_H
> +#define _LINUX_LEAFOPS_H
> +
> +#include <linux/mm_types.h>
> +#include <linux/swapops.h>
> +#include <linux/swap.h>
> +
> +#ifdef CONFIG_MMU
> +
> +/* Temporary until swp_entry_t eliminated. */
> +#define LEAF_TYPE_SHIFT SWP_TYPE_SHIFT
> +
> +enum softleaf_type {
> +       /* Fundamental types. */
> +       SOFTLEAF_NONE,
> +       SOFTLEAF_SWAP,
> +       /* Migration types. */
> +       SOFTLEAF_MIGRATION_READ,
> +       SOFTLEAF_MIGRATION_READ_EXCLUSIVE,
> +       SOFTLEAF_MIGRATION_WRITE,
> +       /* Device types. */
> +       SOFTLEAF_DEVICE_PRIVATE_READ,
> +       SOFTLEAF_DEVICE_PRIVATE_WRITE,
> +       SOFTLEAF_DEVICE_EXCLUSIVE,
> +       /* H/W posion types. */
> +       SOFTLEAF_HWPOISON,
> +       /* Marker types. */
> +       SOFTLEAF_MARKER,
> +};
> +
> +/**
> + * softleaf_mk_none() - Create an empty ('none') leaf entry.
> + * Returns: empty leaf entry.
> + */
> +static inline softleaf_t softleaf_mk_none(void)
> +{
> +       return ((softleaf_t) { 0 });
> +}
> +
> +/**
> + * softleaf_from_pte() - Obtain a leaf entry from a PTE entry.
> + * @pte: PTE entry.
> + *
> + * If @pte is present (therefore not a leaf entry) the function returns an empty
> + * leaf entry. Otherwise, it returns a leaf entry.
> + *
> + * Returns: Leaf entry.
> + */
> +static inline softleaf_t softleaf_from_pte(pte_t pte)
> +{
> +       if (pte_present(pte))
> +               return softleaf_mk_none();
> +
> +       /* Temporary until swp_entry_t eliminated. */
> +       return pte_to_swp_entry(pte);
> +}
> +
> +/**
> + * softleaf_is_none() - Is the leaf entry empty?
> + * @entry: Leaf entry.
> + *
> + * Empty entries are typically the result of a 'none' page table leaf entry
> + * being converted to a leaf entry.
> + *
> + * Returns: true if the entry is empty, false otherwise.
> + */
> +static inline bool softleaf_is_none(softleaf_t entry)
> +{
> +       return entry.val == 0;
> +}
> +
> +/**
> + * softleaf_type() - Identify the type of leaf entry.
> + * @enntry: Leaf entry.
> + *
> + * Returns: the leaf entry type associated with @entry.
> + */
> +static inline enum softleaf_type softleaf_type(softleaf_t entry)
> +{
> +       unsigned int type_num;
> +
> +       if (softleaf_is_none(entry))
> +               return SOFTLEAF_NONE;
> +
> +       type_num = entry.val >> LEAF_TYPE_SHIFT;
> +
> +       if (type_num < MAX_SWAPFILES)
> +               return SOFTLEAF_SWAP;
> +
> +       switch (type_num) {
> +#ifdef CONFIG_MIGRATION
> +       case SWP_MIGRATION_READ:
> +               return SOFTLEAF_MIGRATION_READ;
> +       case SWP_MIGRATION_READ_EXCLUSIVE:
> +               return SOFTLEAF_MIGRATION_READ_EXCLUSIVE;
> +       case SWP_MIGRATION_WRITE:
> +               return SOFTLEAF_MIGRATION_WRITE;
> +#endif
> +#ifdef CONFIG_DEVICE_PRIVATE
> +       case SWP_DEVICE_WRITE:
> +               return SOFTLEAF_DEVICE_PRIVATE_WRITE;
> +       case SWP_DEVICE_READ:
> +               return SOFTLEAF_DEVICE_PRIVATE_READ;
> +       case SWP_DEVICE_EXCLUSIVE:
> +               return SOFTLEAF_DEVICE_EXCLUSIVE;
> +#endif
> +#ifdef CONFIG_MEMORY_FAILURE
> +       case SWP_HWPOISON:
> +               return SOFTLEAF_HWPOISON;
> +#endif
> +       case SWP_PTE_MARKER:
> +               return SOFTLEAF_MARKER;
> +       }
> +
> +       /* Unknown entry type. */
> +       VM_WARN_ON_ONCE(1);
> +       return SOFTLEAF_NONE;
> +}
> +
> +/**
> + * softleaf_is_swap() - Is this leaf entry a swap entry?
> + * @entry: Leaf entry.
> + *
> + * Returns: true if the leaf entry is a swap entry, otherwise false.
> + */
> +static inline bool softleaf_is_swap(softleaf_t entry)
> +{
> +       return softleaf_type(entry) == SOFTLEAF_SWAP;
> +}
> +
> +/**
> + * softleaf_is_swap() - Is this leaf entry a migration entry?
> + * @entry: Leaf entry.
> + *
> + * Returns: true if the leaf entry is a migration entry, otherwise false.
> + */
> +static inline bool softleaf_is_migration(softleaf_t entry)

And a nitpick here, the kerneldoc above doesn't match the function name here.

And now swap functions (swap_cache_*) that expects a swp_entry_t is
getting a softleaf_t instead, they are the same thing right now, so
that's fine. Will we need something like a softleaf_to_swap?