Skip to contentSkip to conversation

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

PATCH Applied Zenghui Yu 5 participants 5 messages Jun 26 – Jun 30

Subsystems (3)
Memory management Documentation MM misc
lore
Share & tools
lore

Zenghui Yu

author
#0 lore raw

PATCH v2 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"). Update 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 included the wrong category in the required mask - PAGE_IS_FILE should be used instead of PAGE_IS_SWAPPED as per the intention.

Fix them all together.

Signed-off-by Zenghui Yu <[email protected]>

---

* From v1 [1]:
- drop PAGE_IS_SWAPPED in .category_mask (David)
- fix typo in commit message (David)
- didn't collect SeongJae's R-b (as the content has changed anyway) but thank you for that!

[1] https://lore.kernel.org/[email protected]

 Documentation/admin-guide/mm/pagemap.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/admin-guide/mm/pagemap.rst +4 -4
index c57e61b5d8aa..20e3fe76f099 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,
    .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
maintainer Acked-by on v2 1/1
#1 lore raw
Quoted 16 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"). Update 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 included the wrong category in the required mask - PAGE_IS_FILE should be used instead of PAGE_IS_SWAPPED as per the intention.

Quoted 3 lines

Fix them all together.

Signed-off-by Zenghui Yu <[email protected]>
Acked-by David Hildenbrand (Arm) <[email protected]>
Signature · 3 lines
Cheers,

David
Reviewed-by on v2 1/1
#2 lore raw
In reply to Zenghui Yu
Quoted 16 lines · On Sat, 27 Jun 2026 00:27:10 +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"). Update 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 included the wrong category in the required mask - PAGE_IS_FILE should be used instead of PAGE_IS_SWAPPED as per the intention.

Quoted 8 lines

Fix them all together.

Signed-off-by Zenghui Yu <[email protected]>

---

* From v1 [1]:
- drop PAGE_IS_SWAPPED in .category_mask (David)
- fix typo in commit message (David)

Good catches!

Quoted 2 lines

- didn't collect SeongJae's R-b (as the content has changed anyway) but thank you for that!

Let me give it again :)

Reviewed-by SeongJae Park <[email protected]>
Quoted 2 lines

[1] https://lore.kernel.org/[email protected]

Thanks,
SJ

[...]

reviewer Reviewed-by on v2 1/1
#3 lore raw
In reply to Zenghui Yu
Quoted 16 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"). Update 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 included the wrong category in the required mask - PAGE_IS_FILE should be used instead of PAGE_IS_SWAPPED as per the intention.

Quoted 3 lines

Fix them all together.

Signed-off-by Zenghui Yu <[email protected]>

LGTM, so:

Reviewed-by Lorenzo Stoakes <[email protected]>
Quoted 56 lines

---

* From v1 [1]:
- drop PAGE_IS_SWAPPED in .category_mask (David)
- fix typo in commit message (David)
- didn't collect SeongJae's R-b (as the content has changed anyway) but thank you for that!

[1] https://lore.kernel.org/[email protected]

 Documentation/admin-guide/mm/pagemap.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/admin-guide/mm/pagemap.rst +4 -5
index c57e61b5d8aa..20e3fe76f099 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,
    .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

maintainer Applied
#4 lore raw
In reply to Zenghui Yu
Quoted 27 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"). Update 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 included the wrong category in the required mask - PAGE_IS_FILE should be used instead of PAGE_IS_SWAPPED as per the intention.

Fix them all together.

Signed-off-by Zenghui Yu <[email protected]>

---

* From v1 [1]:
- drop PAGE_IS_SWAPPED in .category_mask (David)
- fix typo in commit message (David)
- didn't collect SeongJae's R-b (as the content has changed anyway) but thank you for that!

Quoted 4 lines

[1] https://lore.kernel.org/[email protected]

 Documentation/admin-guide/mm/pagemap.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

Applied, thanks.

jon