Skip to contentSkip to conversation

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

PATCH Superseded Zenghui Yu 3 participants 4 messages Jun 25 – Jun 26

Subsystems (3)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

Zenghui Yu

author
#0 lore raw

PATCH 1/1 docs: pagemap: fix flags location, member name and sample code

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.

---
 Documentation/admin-guide/mm/pagemap.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/admin-guide/mm/pagemap.rst +4 -4
index c57e61b5d8aa..12ac97d9d277 100644
@@ -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 |
Signature · 1 line
2.53.0
Reviewed-by on v1 1/1
#1 lore raw
Quoted 7 lines · On Fri, 26 Jun 2026 01:44:47 +0800 Zenghui Yu <[email protected]> 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.

Quoted 8 lines

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!

Quoted 2 lines

Thanks,
SJ

[...]

#2 lore raw
In reply to Zenghui Yu
Quoted 5 lines · 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

s/Upadte/Update/

Quoted 1 line

current location of these flags.

Ack

Quoted 3 lines

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

Ack

Quoted 3 lines

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.

Quoted 1 line

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,

Signature · 3 lines
Cheers,

David
author
#3 lore raw
Quoted 32 lines · David Hildenbrand (Arm)
Quoted 5 lines · 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

s/Upadte/Update/

Quoted 1 line

current location of these flags.

Ack

Quoted 3 lines

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

Ack

Quoted 3 lines

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.

Quoted 1 line

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

Quoted 7 lines

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