This commit refactors __dump_page() into snapshot_page().

snapshot_page() tries to take a faithful snapshot of a page and its
folio representation. The snapshot is returned in the struct
page_snapshot parameter along with additional flags that are best
retrieved at snapshot creation time to reduce race windows.

This function is intended to be used by callers that need a stable
representation of a struct page and struct folio so that pointers
or page information doesn't change while working on a page.

The idea and original implementation of snapshot_page() comes from
Matthew Wilcox with suggestions for improvements from David Hildenbrand.
All bugs and misconceptions are mine.

Signed-off-by: Luiz Capitulino <luizcap@redhat.com>
---
 include/linux/mm.h | 19 +++++++++++
 mm/debug.c         | 42 +++---------------------
 mm/util.c          | 79 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 102 insertions(+), 38 deletions(-)

diff --git a/include/linux/mm.h b/include/linux/mm.h
index 0ef2ba0c667a..929e2330af13 100644
--- a/include/linux/mm.h
+++ b/include/linux/mm.h
@@ -4184,4 +4184,23 @@ static inline bool page_pool_page_is_pp(struct page *page)
 }
 #endif
 
+#define PAGE_SNAPSHOT_FAITHFUL (1 << 0)
+#define PAGE_SNAPSHOT_PG_BUDDY (1 << 1)
+#define PAGE_SNAPSHOT_PG_IDLE  (1 << 2)
+
+struct page_snapshot {
+	struct folio folio_snapshot;
+	struct page page_snapshot;
+	unsigned long pfn;
+	unsigned long idx;
+	unsigned long flags;
+};
+
+static inline bool snapshot_page_is_faithful(const struct page_snapshot *ps)
+{
+	return ps->flags & PAGE_SNAPSHOT_FAITHFUL;
+}
+
+void snapshot_page(struct page_snapshot *ps, const struct page *page);
+
 #endif /* _LINUX_MM_H */
diff --git a/mm/debug.c b/mm/debug.c
index 907382257062..7349330ea506 100644
--- a/mm/debug.c
+++ b/mm/debug.c
@@ -129,47 +129,13 @@ static void __dump_folio(struct folio *folio, struct page *page,
 
 static void __dump_page(const struct page *page)
 {
-	struct folio *foliop, folio;
-	struct page precise;
-	unsigned long head;
-	unsigned long pfn = page_to_pfn(page);
-	unsigned long idx, nr_pages = 1;
-	int loops = 5;
-
-again:
-	memcpy(&precise, page, sizeof(*page));
-	head = precise.compound_head;
-	if ((head & 1) == 0) {
-		foliop = (struct folio *)&precise;
-		idx = 0;
-		if (!folio_test_large(foliop))
-			goto dump;
-		foliop = (struct folio *)page;
-	} else {
-		foliop = (struct folio *)(head - 1);
-		idx = folio_page_idx(foliop, page);
-	}
+	struct page_snapshot ps;
 
-	if (idx < MAX_FOLIO_NR_PAGES) {
-		memcpy(&folio, foliop, 2 * sizeof(struct page));
-		nr_pages = folio_nr_pages(&folio);
-		if (nr_pages > 1)
-			memcpy(&folio.__page_2, &foliop->__page_2,
-			       sizeof(struct page));
-		foliop = &folio;
-	}
-
-	if (idx > nr_pages) {
-		if (loops-- > 0)
-			goto again;
+	snapshot_page(&ps, page);
+	if (!snapshot_page_is_faithful(&ps))
 		pr_warn("page does not match folio\n");
-		precise.compound_head &= ~1UL;
-		foliop = (struct folio *)&precise;
-		idx = 0;
-	}
 
-dump:
-	__dump_folio(foliop, &precise, pfn, idx);
+	__dump_folio(&ps.folio_snapshot, &ps.page_snapshot, ps.pfn, ps.idx);
 }
 
 void dump_page(const struct page *page, const char *reason)
diff --git a/mm/util.c b/mm/util.c
index 0b270c43d7d1..f270bf42465b 100644
--- a/mm/util.c
+++ b/mm/util.c
@@ -25,6 +25,7 @@
 #include <linux/sizes.h>
 #include <linux/compat.h>
 #include <linux/fsnotify.h>
+#include <linux/page_idle.h>
 
 #include <linux/uaccess.h>
 
@@ -1171,3 +1172,81 @@ int compat_vma_mmap_prepare(struct file *file, struct vm_area_struct *vma)
 	return 0;
 }
 EXPORT_SYMBOL(compat_vma_mmap_prepare);
+
+static void set_ps_flags(struct page_snapshot *ps, const struct folio *folio,
+			 const struct page *page)
+{
+	/*
+	 * Only the first page of a high-order buddy page has PageBuddy() set.
+	 * So we have to check manually whether this page is part of a high-
+	 * order buddy page.
+	 */
+	if (PageBuddy(page))
+		ps->flags |= PAGE_SNAPSHOT_PG_BUDDY;
+	else if (page_count(page) == 0 && is_free_buddy_page(page))
+		ps->flags |= PAGE_SNAPSHOT_PG_BUDDY;
+
+	if (folio_test_idle(folio))
+		ps->flags |= PAGE_SNAPSHOT_PG_IDLE;
+}
+
+/**
+ * snapshot_page() - Create a snapshot of a struct page
+ * @ps: Pointer to a struct page_snapshot to store the page snapshot
+ * @page: The page to snapshot
+ *
+ * Create a snapshot of the page and store both its struct page and struct
+ * folio representations in @ps.
+ *
+ * Note that creating a faithful snapshot may fail if the compound
+ * state of the page keeps changing (e.g., due to a folio split). In
+ * this case, ps->faithful is set to false, and the snapshot assumes
+ * that @page refers to a single page.
+ */
+void snapshot_page(struct page_snapshot *ps, const struct page *page)
+{
+	unsigned long head, nr_pages = 1;
+	struct folio *foliop;
+	int loops = 5;
+
+	ps->pfn = page_to_pfn(page);
+	ps->flags = PAGE_SNAPSHOT_FAITHFUL;
+
+again:
+	memset(&ps->folio_snapshot, 0, sizeof(struct folio));
+	memcpy(&ps->page_snapshot, page, sizeof(*page));
+	head = ps->page_snapshot.compound_head;
+	if ((head & 1) == 0) {
+		ps->idx = 0;
+		foliop = (struct folio *)&ps->page_snapshot;
+		if (!folio_test_large(foliop)) {
+			set_ps_flags(ps, page_folio(page), page);
+			memcpy(&ps->folio_snapshot, foliop,
+			       sizeof(struct page));
+			return;
+		}
+		foliop = (struct folio *)page;
+	} else {
+		foliop = (struct folio *)(head - 1);
+		ps->idx = folio_page_idx(foliop, page);
+	}
+
+	if (ps->idx < MAX_FOLIO_NR_PAGES) {
+		memcpy(&ps->folio_snapshot, foliop, 2 * sizeof(struct page));
+		nr_pages = folio_nr_pages(&ps->folio_snapshot);
+		if (nr_pages > 1)
+			memcpy(&ps->folio_snapshot.__page_2, &foliop->__page_2,
+			       sizeof(struct page));
+		set_ps_flags(ps, foliop, page);
+	}
+
+	if (ps->idx > nr_pages) {
+		if (loops-- > 0)
+			goto again;
+		clear_compound_head(&ps->page_snapshot);
+		foliop = (struct folio *)&ps->page_snapshot;
+		memcpy(&ps->folio_snapshot, foliop, sizeof(struct page));
+		ps->flags = 0;
+		ps->idx = 0;
+	}
+}
-- 
2.50.0

[...]

>   
> -dump:
> -	__dump_folio(foliop, &precise, pfn, idx);
> +	__dump_folio(&ps.folio_snapshot, &ps.page_snapshot, ps.pfn, ps.idx);

Nit that can be cleaned up later on top:

We should probably call this

__dump_page_snapshot() and then just pass ... the page_snapshot.

>   }
>   
>   void dump_page(const struct page *page, const char *reason)
> diff --git a/mm/util.c b/mm/util.c
> index 0b270c43d7d1..f270bf42465b 100644
> --- a/mm/util.c
> +++ b/mm/util.c
> @@ -25,6 +25,7 @@
>   #include <linux/sizes.h>
>   #include <linux/compat.h>
>   #include <linux/fsnotify.h>
> +#include <linux/page_idle.h>
>   
>   #include <linux/uaccess.h>
>   
> @@ -1171,3 +1172,81 @@ int compat_vma_mmap_prepare(struct file *file, struct vm_area_struct *vma)
>   	return 0;
>   }
>   EXPORT_SYMBOL(compat_vma_mmap_prepare);
> +
> +static void set_ps_flags(struct page_snapshot *ps, const struct folio *folio,
> +			 const struct page *page)
> +{
> +	/*
> +	 * Only the first page of a high-order buddy page has PageBuddy() set.
> +	 * So we have to check manually whether this page is part of a high-
> +	 * order buddy page.
> +	 */
> +	if (PageBuddy(page))
> +		ps->flags |= PAGE_SNAPSHOT_PG_BUDDY;
> +	else if (page_count(page) == 0 && is_free_buddy_page(page))
> +		ps->flags |= PAGE_SNAPSHOT_PG_BUDDY;
> +
> +	if (folio_test_idle(folio))
> +		ps->flags |= PAGE_SNAPSHOT_PG_IDLE;
> +}
> +
> +/**
> + * snapshot_page() - Create a snapshot of a struct page
> + * @ps: Pointer to a struct page_snapshot to store the page snapshot
> + * @page: The page to snapshot
> + *
> + * Create a snapshot of the page and store both its struct page and struct
> + * folio representations in @ps.
> + *
> + * Note that creating a faithful snapshot may fail if the compound

Maybe highlight that this is not really expected to happen, ever.

> + * state of the page keeps changing (e.g., due to a folio split). In
> + * this case, ps->faithful is set to false, and the snapshot assumes

There is no ps->faithful.

> + * that @page refers to a single page.
> + */
> +void snapshot_page(struct page_snapshot *ps, const struct page *page)
> +{
> +	unsigned long head, nr_pages = 1;
> +	struct folio *foliop;
> +	int loops = 5;
> +
> +	ps->pfn = page_to_pfn(page);
> +	ps->flags = PAGE_SNAPSHOT_FAITHFUL;
> +
> +again:
> +	memset(&ps->folio_snapshot, 0, sizeof(struct folio));
> +	memcpy(&ps->page_snapshot, page, sizeof(*page));
> +	head = ps->page_snapshot.compound_head;
> +	if ((head & 1) == 0) {
> +		ps->idx = 0;
> +		foliop = (struct folio *)&ps->page_snapshot;
> +		if (!folio_test_large(foliop)) {
> +			set_ps_flags(ps, page_folio(page), page);
> +			memcpy(&ps->folio_snapshot, foliop,
> +			       sizeof(struct page));
> +			return;
> +		}
> +		foliop = (struct folio *)page;
> +	} else {
> +		foliop = (struct folio *)(head - 1);
> +		ps->idx = folio_page_idx(foliop, page);
> +	}

Condition could be cleaned up by reversing both things

if (head & 1) {
	/* Tail page, lookup the actual head. */
	foliop = (struct folio *)(head - 1);
	ps->idx = folio_page_idx(foliop, page);
} else
	...
}

But you're just moving that code, so no need to do that now.


I think we could improve some of that in the future a bit to
make it even more faithful.

But for now this should be just fine.

Acked-by: David Hildenbrand <david@redhat.com>

-- 
Cheers,

David / dhildenb

On 2025-07-16 06:16, David Hildenbrand wrote:
> [...]
> 
>> -dump:
>> -    __dump_folio(foliop, &precise, pfn, idx);
>> +    __dump_folio(&ps.folio_snapshot, &ps.page_snapshot, ps.pfn, ps.idx);
> 
> Nit that can be cleaned up later on top:
> 
> We should probably call this
> 
> __dump_page_snapshot() and then just pass ... the page_snapshot.
> 
>>   }
>>   void dump_page(const struct page *page, const char *reason)
>> diff --git a/mm/util.c b/mm/util.c
>> index 0b270c43d7d1..f270bf42465b 100644
>> --- a/mm/util.c
>> +++ b/mm/util.c
>> @@ -25,6 +25,7 @@
>>   #include <linux/sizes.h>
>>   #include <linux/compat.h>
>>   #include <linux/fsnotify.h>
>> +#include <linux/page_idle.h>
>>   #include <linux/uaccess.h>
>> @@ -1171,3 +1172,81 @@ int compat_vma_mmap_prepare(struct file *file, struct vm_area_struct *vma)
>>       return 0;
>>   }
>>   EXPORT_SYMBOL(compat_vma_mmap_prepare);
>> +
>> +static void set_ps_flags(struct page_snapshot *ps, const struct folio *folio,
>> +             const struct page *page)
>> +{
>> +    /*
>> +     * Only the first page of a high-order buddy page has PageBuddy() set.
>> +     * So we have to check manually whether this page is part of a high-
>> +     * order buddy page.
>> +     */
>> +    if (PageBuddy(page))
>> +        ps->flags |= PAGE_SNAPSHOT_PG_BUDDY;
>> +    else if (page_count(page) == 0 && is_free_buddy_page(page))
>> +        ps->flags |= PAGE_SNAPSHOT_PG_BUDDY;
>> +
>> +    if (folio_test_idle(folio))
>> +        ps->flags |= PAGE_SNAPSHOT_PG_IDLE;
>> +}
>> +
>> +/**
>> + * snapshot_page() - Create a snapshot of a struct page
>> + * @ps: Pointer to a struct page_snapshot to store the page snapshot
>> + * @page: The page to snapshot
>> + *
>> + * Create a snapshot of the page and store both its struct page and struct
>> + * folio representations in @ps.
>> + *
>> + * Note that creating a faithful snapshot may fail if the compound
> 
> Maybe highlight that this is not really expected to happen, ever.
> 
>> + * state of the page keeps changing (e.g., due to a folio split). In
>> + * this case, ps->faithful is set to false, and the snapshot assumes
> 
> There is no ps->faithful.

Yes, good catch. This was from an earlier version.

Is it fine if I fix only this with a follow up patch for Andrew in this
thread or would you prefer that I post v4 with all the other changes as
well?

> 
>> + * that @page refers to a single page.
>> + */
>> +void snapshot_page(struct page_snapshot *ps, const struct page *page)
>> +{
>> +    unsigned long head, nr_pages = 1;
>> +    struct folio *foliop;
>> +    int loops = 5;
>> +
>> +    ps->pfn = page_to_pfn(page);
>> +    ps->flags = PAGE_SNAPSHOT_FAITHFUL;
>> +
>> +again:
>> +    memset(&ps->folio_snapshot, 0, sizeof(struct folio));
>> +    memcpy(&ps->page_snapshot, page, sizeof(*page));
>> +    head = ps->page_snapshot.compound_head;
>> +    if ((head & 1) == 0) {
>> +        ps->idx = 0;
>> +        foliop = (struct folio *)&ps->page_snapshot;
>> +        if (!folio_test_large(foliop)) {
>> +            set_ps_flags(ps, page_folio(page), page);
>> +            memcpy(&ps->folio_snapshot, foliop,
>> +                   sizeof(struct page));
>> +            return;
>> +        }
>> +        foliop = (struct folio *)page;
>> +    } else {
>> +        foliop = (struct folio *)(head - 1);
>> +        ps->idx = folio_page_idx(foliop, page);
>> +    }
> 
> Condition could be cleaned up by reversing both things
> 
> if (head & 1) {
>      /* Tail page, lookup the actual head. */
>      foliop = (struct folio *)(head - 1);
>      ps->idx = folio_page_idx(foliop, page);
> } else
>      ...
> }
> 
> But you're just moving that code, so no need to do that now.
> 
> 
> I think we could improve some of that in the future a bit to
> make it even more faithful.
> 
> But for now this should be just fine.
> 
> Acked-by: David Hildenbrand <david@redhat.com>
>

On 16.07.25 19:36, Luiz Capitulino wrote:
> On 2025-07-16 06:16, David Hildenbrand wrote:
>> [...]
>>
>>> -dump:
>>> -    __dump_folio(foliop, &precise, pfn, idx);
>>> +    __dump_folio(&ps.folio_snapshot, &ps.page_snapshot, ps.pfn, ps.idx);
>>
>> Nit that can be cleaned up later on top:
>>
>> We should probably call this
>>
>> __dump_page_snapshot() and then just pass ... the page_snapshot.
>>
>>>    }
>>>    void dump_page(const struct page *page, const char *reason)
>>> diff --git a/mm/util.c b/mm/util.c
>>> index 0b270c43d7d1..f270bf42465b 100644
>>> --- a/mm/util.c
>>> +++ b/mm/util.c
>>> @@ -25,6 +25,7 @@
>>>    #include <linux/sizes.h>
>>>    #include <linux/compat.h>
>>>    #include <linux/fsnotify.h>
>>> +#include <linux/page_idle.h>
>>>    #include <linux/uaccess.h>
>>> @@ -1171,3 +1172,81 @@ int compat_vma_mmap_prepare(struct file *file, struct vm_area_struct *vma)
>>>        return 0;
>>>    }
>>>    EXPORT_SYMBOL(compat_vma_mmap_prepare);
>>> +
>>> +static void set_ps_flags(struct page_snapshot *ps, const struct folio *folio,
>>> +             const struct page *page)
>>> +{
>>> +    /*
>>> +     * Only the first page of a high-order buddy page has PageBuddy() set.
>>> +     * So we have to check manually whether this page is part of a high-
>>> +     * order buddy page.
>>> +     */
>>> +    if (PageBuddy(page))
>>> +        ps->flags |= PAGE_SNAPSHOT_PG_BUDDY;
>>> +    else if (page_count(page) == 0 && is_free_buddy_page(page))
>>> +        ps->flags |= PAGE_SNAPSHOT_PG_BUDDY;
>>> +
>>> +    if (folio_test_idle(folio))
>>> +        ps->flags |= PAGE_SNAPSHOT_PG_IDLE;
>>> +}
>>> +
>>> +/**
>>> + * snapshot_page() - Create a snapshot of a struct page
>>> + * @ps: Pointer to a struct page_snapshot to store the page snapshot
>>> + * @page: The page to snapshot
>>> + *
>>> + * Create a snapshot of the page and store both its struct page and struct
>>> + * folio representations in @ps.
>>> + *
>>> + * Note that creating a faithful snapshot may fail if the compound
>>
>> Maybe highlight that this is not really expected to happen, ever.
>>
>>> + * state of the page keeps changing (e.g., due to a folio split). In
>>> + * this case, ps->faithful is set to false, and the snapshot assumes
>>
>> There is no ps->faithful.
> 
> Yes, good catch. This was from an earlier version.
> 
> Is it fine if I fix only this with a follow up patch for Andrew in this
> thread or would you prefer that I post v4 with all the other changes as
> well?

I think the series was part of mm-new, but now I only spot it in 
mm-everything, weird. Maybe because of a conflict with the other 
stable_page_flags() change?

So whatever Andrew prefers, really :)

-- 
Cheers,

David / dhildenb

On Wed, 16 Jul 2025 20:18:00 +0200 David Hildenbrand <david@redhat.com> wrote:

> On 16.07.25 19:36, Luiz Capitulino wrote:
> > Yes, good catch. This was from an earlier version.
> > 
> > Is it fine if I fix only this with a follow up patch for Andrew in this
> > thread or would you prefer that I post v4 with all the other changes as
> > well?
> 
> I think the series was part of mm-new, but now I only spot it in 
> mm-everything, weird. Maybe because of a conflict with the other 
> stable_page_flags() change?

I think I removed v2 from mm-unstable and added v3 to mm-new.  Maybe.

> So whatever Andrew prefers, really :)

Either is OK at this stage.  I do prefer little fixes so that I and
others can see what changed - it depends how tricky and large they are.

On 2025-07-16 18:19, Andrew Morton wrote:
> On Wed, 16 Jul 2025 20:18:00 +0200 David Hildenbrand <david@redhat.com> wrote:
> 
>> On 16.07.25 19:36, Luiz Capitulino wrote:
>>> Yes, good catch. This was from an earlier version.
>>>
>>> Is it fine if I fix only this with a follow up patch for Andrew in this
>>> thread or would you prefer that I post v4 with all the other changes as
>>> well?
>>
>> I think the series was part of mm-new, but now I only spot it in
>> mm-everything, weird. Maybe because of a conflict with the other
>> stable_page_flags() change?
> 
> I think I removed v2 from mm-unstable and added v3 to mm-new.  Maybe.
> 
>> So whatever Andrew prefers, really :)
> 
> Either is OK at this stage.  I do prefer little fixes so that I and
> others can see what changed - it depends how tricky and large they are.

I liked some of the other suggestions from David so I'll send v4.

On 2025-07-16 21:52, Luiz Capitulino wrote:
> On 2025-07-16 18:19, Andrew Morton wrote:
>> On Wed, 16 Jul 2025 20:18:00 +0200 David Hildenbrand <david@redhat.com> wrote:
>>
>>> On 16.07.25 19:36, Luiz Capitulino wrote:
>>>> Yes, good catch. This was from an earlier version.
>>>>
>>>> Is it fine if I fix only this with a follow up patch for Andrew in this
>>>> thread or would you prefer that I post v4 with all the other changes as
>>>> well?
>>>
>>> I think the series was part of mm-new, but now I only spot it in
>>> mm-everything, weird. Maybe because of a conflict with the other
>>> stable_page_flags() change?
>>
>> I think I removed v2 from mm-unstable and added v3 to mm-new.  Maybe.
>>
>>> So whatever Andrew prefers, really :)
>>
>> Either is OK at this stage.  I do prefer little fixes so that I and
>> others can see what changed - it depends how tricky and large they are.
> 
> I liked some of the other suggestions from David so I'll send v4.

I changed my mind again (sorry). I think the current version should be
good as is except for the doc bug, so here's a patch to fix it on top:

diff --git a/mm/util.c b/mm/util.c
index f270bf42465b..6e5b6ff1c90d 100644
--- a/mm/util.c
+++ b/mm/util.c
@@ -1198,10 +1198,12 @@ static void set_ps_flags(struct page_snapshot *ps, const struct folio *folio,
   * Create a snapshot of the page and store both its struct page and struct
   * folio representations in @ps.
   *
- * Note that creating a faithful snapshot may fail if the compound
- * state of the page keeps changing (e.g., due to a folio split). In
- * this case, ps->faithful is set to false, and the snapshot assumes
- * that @page refers to a single page.
+ * A snapshot is marked as "faithful" if the compound state of @page was
+ * stable and allowed safe reconstruction of the folio representation. In
+ * rare cases where this is not possible (e.g. due to folio splitting),
+ * snapshot_page() falls back to treating @page as a single page and the
+ * snapshot is marked as "unfaithful". The snapshot_page_is_faithful()
+ * helper can be used to check for this condition.
   */
  void snapshot_page(struct page_snapshot *ps, const struct page *page)
  {