[PATCH] docs: pagemap: fix flags location, member name and sample code

[PATCH] docs: pagemap: fix flags location, member name and sample code

[Zenghui Yu]

The userland visible page flags (KPF_*) were initially moved to
include/linux/kernel-page-flags.h in commit 1a9b5b7fe0c5 ("mm: export
stable page flags"), and later moved to
include/uapi/linux/kernel-page-flags.h in commit 607ca46e97a1 ("UAPI:
(Scripted) Disintegrate include/linux"). Upadte the doc to reflect the
current location of these flags.

The member @walk_end of struct pm_scan_arg {} was wrongly written as
"end_walk".

The first sample code of the PAGEMAP_SCAN ioctl wrongly used the
PM_SCAN_CHECK_WPASYNC flag twice, instead of the PM_SCAN_WP_MATCHING flag.
The second one missed PAGE_IS_FILE in the required mask.

Fix them all together.

Signed-off-by: Zenghui Yu <zenghui.yu@linux.dev>
---
 Documentation/admin-guide/mm/pagemap.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/admin-guide/mm/pagemap.rst b/Documentation/admin-guide/mm/pagemap.rst
index c57e61b5d8aa..12ac97d9d277 100644
--- a/Documentation/admin-guide/mm/pagemap.rst
+++ b/Documentation/admin-guide/mm/pagemap.rst
@@ -67,7 +67,7 @@ number of times a page is mapped.
  * ``/proc/kpageflags``.  This file contains a 64-bit set of flags for each
    page, indexed by PFN.
 
-   The flags are (from ``fs/proc/page.c``, above kpageflags_read):
+   The flags are (from ``include/uapi/linux/kernel-page-flags.h``):
 
     0. LOCKED
     1. ERROR
@@ -264,7 +264,7 @@ The ``struct pm_scan_arg`` is used as the argument of the IOCTL.
     provided or not.
  3. The range is specified through ``start`` and ``end``.
  4. The walk can abort before visiting the complete range such as the user buffer
-    can get full etc. The walk ending address is specified in``end_walk``.
+    can get full etc. The walk ending address is specified in ``walk_end``.
  5. The output buffer of ``struct page_region`` array and size is specified in
     ``vec`` and ``vec_len``.
  6. The optional maximum requested pages are specified in the ``max_pages``.
@@ -275,7 +275,7 @@ Find pages which have been written and WP them as well::
 
    struct pm_scan_arg arg = {
    .size = sizeof(arg),
-   .flags = PM_SCAN_CHECK_WPASYNC | PM_SCAN_CHECK_WPASYNC,
+   .flags = PM_SCAN_WP_MATCHING | PM_SCAN_CHECK_WPASYNC,
    ..
    .category_mask = PAGE_IS_WRITTEN,
    .return_mask = PAGE_IS_WRITTEN,
@@ -288,7 +288,7 @@ present or huge::
    .size = sizeof(arg),
    .flags = 0,
    ..
-   .category_mask = PAGE_IS_WRITTEN | PAGE_IS_SWAPPED,
+   .category_mask = PAGE_IS_WRITTEN | PAGE_IS_FILE | PAGE_IS_SWAPPED,
    .category_inverted = PAGE_IS_SWAPPED,
    .category_anyof_mask = PAGE_IS_PRESENT | PAGE_IS_HUGE,
    .return_mask = PAGE_IS_WRITTEN | PAGE_IS_SWAPPED |
-- 
2.53.0

Re: [PATCH] docs: pagemap: fix flags location, member name and sample code

[SeongJae Park]

On Fri, 26 Jun 2026 01:44:47 +0800 Zenghui Yu <zenghui.yu@linux.dev> wrote:

> The userland visible page flags (KPF_*) were initially moved to
> include/linux/kernel-page-flags.h in commit 1a9b5b7fe0c5 ("mm: export
> stable page flags"), and later moved to
> include/uapi/linux/kernel-page-flags.h in commit 607ca46e97a1 ("UAPI:
> (Scripted) Disintegrate include/linux"). Upadte the doc to reflect the
> current location of these flags.
> 
> The member @walk_end of struct pm_scan_arg {} was wrongly written as
> "end_walk".
> 
> The first sample code of the PAGEMAP_SCAN ioctl wrongly used the
> PM_SCAN_CHECK_WPASYNC flag twice, instead of the PM_SCAN_WP_MATCHING flag.
> The second one missed PAGE_IS_FILE in the required mask.
> 
> Fix them all together.

Looks good to me, thank you!

> 
> Signed-off-by: Zenghui Yu <zenghui.yu@linux.dev>

Reviewed-by: SeongJae Park <sj@kernel.org>


Thanks,
SJ

[...]

Re: [PATCH] docs: pagemap: fix flags location, member name and sample code

[David Hildenbrand (Arm)]

On 6/25/26 19:44, Zenghui Yu wrote:
> The userland visible page flags (KPF_*) were initially moved to
> include/linux/kernel-page-flags.h in commit 1a9b5b7fe0c5 ("mm: export
> stable page flags"), and later moved to
> include/uapi/linux/kernel-page-flags.h in commit 607ca46e97a1 ("UAPI:
> (Scripted) Disintegrate include/linux"). Upadte the doc to reflect the

s/Upadte/Update/

> current location of these flags.

Ack

> 
> The member @walk_end of struct pm_scan_arg {} was wrongly written as
> "end_walk".

Ack

> 
> The first sample code of the PAGEMAP_SCAN ioctl wrongly used the
> PM_SCAN_CHECK_WPASYNC flag twice, instead of the PM_SCAN_WP_MATCHING flag.

That makes sense.

> The second one missed PAGE_IS_FILE in the required mask.

Hm. The description says: "Find pages which have been written, are file backed,
not swapped and either present or huge".

But doesn't that mean that

it should actually be

	.category_mask = PAGE_IS_WRITTEN | PAGE_IS_FILE,

Because

	.category_inverted = PAGE_IS_SWAPPED,

-- 
Cheers,

David

Re: [PATCH] docs: pagemap: fix flags location, member name and sample code

[Zenghui Yu]

On 6/26/26 10:47 PM, David Hildenbrand (Arm) wrote:
> On 6/25/26 19:44, Zenghui Yu wrote:
> > The userland visible page flags (KPF_*) were initially moved to
> > include/linux/kernel-page-flags.h in commit 1a9b5b7fe0c5 ("mm: export
> > stable page flags"), and later moved to
> > include/uapi/linux/kernel-page-flags.h in commit 607ca46e97a1 ("UAPI:
> > (Scripted) Disintegrate include/linux"). Upadte the doc to reflect the
> 
> s/Upadte/Update/
> 
> > current location of these flags.
> 
> Ack
> 
> >
> > The member @walk_end of struct pm_scan_arg {} was wrongly written as
> > "end_walk".
> 
> Ack
> 
> >
> > The first sample code of the PAGEMAP_SCAN ioctl wrongly used the
> > PM_SCAN_CHECK_WPASYNC flag twice, instead of the PM_SCAN_WP_MATCHING flag.
> 
> That makes sense.
> 
> > The second one missed PAGE_IS_FILE in the required mask.
> 
> Hm. The description says: "Find pages which have been written, are file backed,
> not swapped and either present or huge".
> 
> But doesn't that mean that
> 
> it should actually be
> 
> 	.category_mask = PAGE_IS_WRITTEN | PAGE_IS_FILE,
> 
> Because
> 
> 	.category_inverted = PAGE_IS_SWAPPED,

Ah! Thanks for pointing it out. I'll fix it soon.

Thanks,
Zenghui