gup_test.c currently serves two separate purposes: benchmarking
(GUP_FAST_BENCHMARK, PIN_FAST_BENCHMARK and PIN_LONGTERM_BENCHMARK) and
functional testing (GUP_BASIC_TEST, PIN_BASIC_TEST and
DUMP_USER_PAGES_TEST). Keeping both in one program makes the functional
tests harder to run and report individually, while run_vmtests.sh has to
invoke the program repeatedly with different options.

Separate these roles into tools/mm/gup_bench for benchmarking and
tools/testing/selftests/mm/gup for functional testing. Move the shared
file and hugepage helpers to tools/lib/mm/ so both programs can use them
without duplicating the implementation.

Patch 1 makes read_file(), write_file(), read_num(), write_num() and
write_num_ignore_einval() return errors to their callers instead of
exiting. It also makes read_num() reject negative and malformed values
and updates the existing callers to handle failures.

Patch 2 moves these file helpers from vm_util.c to tools/lib/mm/. It keeps
them available to the mm selftests through vm_util.h and adjusts the
selftests build accordingly.

Patch 3 moves hugepage_settings.[ch] from selftests/mm to tools/lib/mm/.
It also removes its kselftest dependency while preserving TAP-compatible
diagnostics for selftest users.

Patch 4 moves the existing gup_test implementation from selftests/mm to
tools/mm as gup_bench. This keeps the code movement separate from the
subsequent changes and makes it easier to review.

Patch 5 removes the functional test modes and kselftest dependency from
gup_bench. When run without arguments, it performs one GUP_FAST benchmark
using the existing defaults instead of running the whole matrix. Other
benchmark configurations can be selected through command-line options.

Patch 6 adds a new harness-based GUP selftest. It covers THP, non-THP and
HugeTLB mappings across private/shared and read/write variants. For each
variant, it tests get_user_pages(), get_user_pages_fast(),
pin_user_pages(), pin_user_pages_fast(), long-term pinning and both dump
modes using four batch sizes. It also preserves the existing sparse dump
coverage for pages 0, 19 and 0x1000. The HugeTLB variants share a one-time
setup of 128 default-sized huge pages.

---
I think Sashiko might complain about some "what if the user inputs this
and that" scenarios in patch 5, but I intentionally am not covering those
now, agreeing with Mike's point that a user will be wise enough to input
sane values to run a benchmark. Those checks increase churn and make the
patch harder to review.

Changes in v7:
- Rebase onto mm-unstable
- Address feedback from Mike and Sashiko
- Make read_file() return 0 on success and tighten read_num() parsing
- Move write_num_ignore_einval() with the shared file helpers
- Keep the existing gup_bench argument parsing and avoid unrelated checks
- Set up 128 HugeTLB pages once for all HugeTLB selftest variants

Changes in v6:
- Rebase onto v7.2-rc5
- Address feedback from David, Mark, John, Dev and Sashiko
- Keep the shared file helpers silent and let callers report errors
- Move the existing gup_test into tools/mm before changing its behaviour
- Report ioctl failures from gup_bench worker threads
- Remove the default benchmark matrix and run one default benchmark instead
- Add the new harness-based functional selftest in a separate final patch
- Drop the unrelated thp_swap_allocator_test .gitignore change

Changes in v5:
- Rebase onto v7.2-rc3
- Address feedback from Mike, John, Dev and Sashiko
- Make file helper diagnostics TAP-compatible
- Validate read_num() input and propagate errors while restoring shared
  memory limits
- Preserve build bisectability for the x86 protection_keys test
- Preserve HugeTLB diagnostics using TAP-compatible printf() output
- Validate the remaining numeric arguments accepted by gup_bench

Changes in v4:
- Address review feedback from Mike and Sashiko
- Add a preparatory patch so shared file helpers return errors instead of exiting
- Reduce include churn by keeping shared helpers exposed through vm_util.h
- Preserve HugeTLB diagnostics and restore HugeTLB state more carefully
- Fix selftests/mm build details after moving helpers to tools/lib/mm
- Tighten gup_bench argument handling and gup_test setup/sparse-dump coverage

Changes in v3:
- Address v2 feedback from Sashiko
- Add shared file_utils helpers under tools/lib/mm
- Move hugepage_settings out of selftests and into tools/lib/mm
- Convert gup_bench to use the shared tools/lib/mm helpers
- Guard against invalid thread counts in gup_bench
- Handle thread-array allocation failure cleanly in gup_bench
- Restore HugeTLB settings on setup failure in gup_test
- Add sparse DUMP_USER_PAGES_TEST coverage for pages 0, 19 and 0x1000

Changes in v2:
- Address v1 feedback from Sashiko
- Add fast and long-term GUP/PUP coverage
- Sweep nr_pages_per_call over 1, 512, 123 and all pages
- Call madvise(MADV_NOHUGEPAGE) in non-THP variants
- Use 256 MB for HugeTLB fixtures
- Restore HugeTLB settings from fixture teardown
- Report nr_pages_per_call for each iteration
- Update the pin_user_pages unit-testing documentation

Previous versions:
v6: lore.kernel.org/all/20260730140825.238130-1-sarthak.sharma@arm.com/
v5: lore.kernel.org/all/20260716123226.197736-1-sarthak.sharma@arm.com/
v4: lore.kernel.org/all/20260527142432.230127-1-sarthak.sharma@arm.com/
v3: lore.kernel.org/all/20260521111801.173019-1-sarthak.sharma@arm.com/
v2: lore.kernel.org/all/20260519120506.184512-1-sarthak.sharma@arm.com/
v1: lore.kernel.org/all/20260515084840.174652-1-sarthak.sharma@arm.com/

---
Sarthak Sharma (6):
  selftests/mm: make file helpers return errors
  tools/lib/mm: add shared file helpers
  tools/lib/mm: move hugepage_settings out of selftests
  tools/mm: move gup_test from selftests/mm to tools/mm
  tools/mm: make gup_bench a benchmark only tool
  selftests/mm: add a GUP selftest

 Documentation/core-api/pin_user_pages.rst     |  14 +-
 MAINTAINERS                                   |   4 +-
 tools/lib/mm/file_utils.c                     | 104 ++++++
 tools/lib/mm/file_utils.h                     |  13 +
 .../selftests => lib}/mm/hugepage_settings.c  | 109 +++++-
 .../selftests => lib}/mm/hugepage_settings.h  |   0
 tools/mm/.gitignore                           |   1 +
 tools/mm/Makefile                             |  11 +-
 .../mm/gup_test.c => mm/gup_bench.c}          | 194 +++++------
 tools/testing/selftests/mm/Makefile           |  15 +-
 tools/testing/selftests/mm/compaction_test.c  |   2 +-
 tools/testing/selftests/mm/cow.c              |   1 -
 .../selftests/mm/folio_split_race_test.c      |   1 -
 tools/testing/selftests/mm/guard-regions.c    |   1 -
 tools/testing/selftests/mm/gup.c              | 329 ++++++++++++++++++
 tools/testing/selftests/mm/gup_longterm.c     |   1 -
 tools/testing/selftests/mm/hmm-tests.c        |   6 +-
 tools/testing/selftests/mm/hugetlb-madvise.c  |   1 -
 tools/testing/selftests/mm/hugetlb-mmap.c     |   1 -
 tools/testing/selftests/mm/hugetlb-mremap.c   |   1 -
 tools/testing/selftests/mm/hugetlb-shm.c      |   1 -
 .../selftests/mm/hugetlb-soft-offline.c       |   2 +-
 tools/testing/selftests/mm/hugetlb_dio.c      |   1 -
 .../selftests/mm/hugetlb_fault_after_madv.c   |   1 -
 .../selftests/mm/hugetlb_madv_vs_map.c        |   1 -
 tools/testing/selftests/mm/khugepaged.c       |  15 +-
 tools/testing/selftests/mm/ksm_tests.c        |   1 -
 tools/testing/selftests/mm/migration.c        |   2 +-
 tools/testing/selftests/mm/pagemap_ioctl.c    |   1 -
 .../testing/selftests/mm/prctl_thp_disable.c  |   1 -
 tools/testing/selftests/mm/protection_keys.c  |   2 +-
 tools/testing/selftests/mm/run_vmtests.sh     |  37 +-
 tools/testing/selftests/mm/soft-dirty.c       |   1 -
 .../selftests/mm/split_huge_page_test.c       |   6 +-
 tools/testing/selftests/mm/thuge-gen.c        |   1 -
 tools/testing/selftests/mm/transhuge-stress.c |   1 -
 tools/testing/selftests/mm/uffd-common.h      |   1 -
 tools/testing/selftests/mm/uffd-wp-mremap.c   |   2 +-
 .../selftests/mm/va_high_addr_switch.c        |   1 -
 tools/testing/selftests/mm/vm_util.c          | 121 ++-----
 tools/testing/selftests/mm/vm_util.h          |   8 +-
 41 files changed, 710 insertions(+), 306 deletions(-)
 create mode 100644 tools/lib/mm/file_utils.c
 create mode 100644 tools/lib/mm/file_utils.h
 rename tools/{testing/selftests => lib}/mm/hugepage_settings.c (87%)
 rename tools/{testing/selftests => lib}/mm/hugepage_settings.h (100%)
 rename tools/{testing/selftests/mm/gup_test.c => mm/gup_bench.c} (50%)
 create mode 100644 tools/testing/selftests/mm/gup.c


base-commit: f9ca2fa9ef7e9b39ec79a0596929d1a1f8704c5f
-- 
2.39.5

On 8/13/26 11:42 PM, Sarthak Sharma wrote:
> gup_test.c currently serves two separate purposes: benchmarking
> (GUP_FAST_BENCHMARK, PIN_FAST_BENCHMARK and PIN_LONGTERM_BENCHMARK) and
> functional testing (GUP_BASIC_TEST, PIN_BASIC_TEST and
> DUMP_USER_PAGES_TEST). Keeping both in one program makes the functional
> tests harder to run and report individually, while run_vmtests.sh has to
> invoke the program repeatedly with different options.
> 
> Separate these roles into tools/mm/gup_bench for benchmarking and
> tools/testing/selftests/mm/gup for functional testing. Move the shared
> file and hugepage helpers to tools/lib/mm/ so both programs can use them
> without duplicating the implementation.
> 

It's been a while since I sent it, so just wanted to follow up and see
if anyone has had a chance to look at the series.

While here, I also wanted to address Sashiko's concern.

> --- Patch [4]: [PATCH v7 4/6] tools/mm: move gup_test from selftests/
> mm to tools/mm ---
> commit 92aa92be01707caef105298876458c303c6513c8
> Author: Sarthak Sharma <sarthak.sharma@arm.com>
> tools/mm: move gup_test from selftests/mm to tools/mm
> This commit moves gup_test.c to gup_bench.c in the tools/mm directory
> to begin separating benchmarking and functional testing components. It
> also updates relevant Makefiles, gitignore, run_vmtests.sh, and
> MAINTAINERS.
>
> tools/mm: move gup_test from selftests/mm to tools/mm
>
> Move tools/testing/selftests/mm/gup_test.c to tools/mm/gup_bench.c.
> This is the first step in separating its benchmarking and
> functional testing components.
> Since the file and binary are being moved and renamed, should we also
> update the references in mm/Kconfig and Documentation/core-api/
> pin_user_pages.rst?
> For example, mm/Kconfig still points to the old path for
> CONFIG_GUP_TEST:
> See tools/testing/selftests/mm/gup_test.c
> And Documentation/core-api/pin_user_pages.rst still references the old
> file and binary name:
> tools/testing/selftests/mm/gup_test.c
> has the following new calls to exercise the new pin*() wrapper
> functions:
>  * PIN_FAST_BENCHMARK (./gup_test -a)
>  * PIN_BASIC_TEST (./gup_test -b)
> Could leaving these unchanged confuse users looking for the test or
> trying to run the benchmark commands?

Documentation/core-api/pin_user_pages.rst has been updated in the last
patch, after the gup.c selftest is added. mm/Kconfig is to be updated,
and I can send a fixup patch for this unless some review comes up that
requires a respin.

On 13/08/2026 7:12 pm, Sarthak Sharma wrote:
> gup_test.c currently serves two separate purposes: benchmarking
> (GUP_FAST_BENCHMARK, PIN_FAST_BENCHMARK and PIN_LONGTERM_BENCHMARK) and
> functional testing (GUP_BASIC_TEST, PIN_BASIC_TEST and
> DUMP_USER_PAGES_TEST). Keeping both in one program makes the functional
> tests harder to run and report individually, while run_vmtests.sh has to
> invoke the program repeatedly with different options.
> 
> Separate these roles into tools/mm/gup_bench for benchmarking and
> tools/testing/selftests/mm/gup for functional testing. Move the shared
> file and hugepage helpers to tools/lib/mm/ so both programs can use them
> without duplicating the implementation.
> 
> Patch 1 makes read_file(), write_file(), read_num(), write_num() and
> write_num_ignore_einval() return errors to their callers instead of
> exiting. It also makes read_num() reject negative and malformed values
> and updates the existing callers to handle failures.
> 
> Patch 2 moves these file helpers from vm_util.c to tools/lib/mm/. It keeps
> them available to the mm selftests through vm_util.h and adjusts the
> selftests build accordingly.
> 
> Patch 3 moves hugepage_settings.[ch] from selftests/mm to tools/lib/mm/.
> It also removes its kselftest dependency while preserving TAP-compatible
> diagnostics for selftest users.
> 
> Patch 4 moves the existing gup_test implementation from selftests/mm to
> tools/mm as gup_bench. This keeps the code movement separate from the
> subsequent changes and makes it easier to review.
> 
> Patch 5 removes the functional test modes and kselftest dependency from
> gup_bench. When run without arguments, it performs one GUP_FAST benchmark
> using the existing defaults instead of running the whole matrix. Other
> benchmark configurations can be selected through command-line options.
> 
> Patch 6 adds a new harness-based GUP selftest. It covers THP, non-THP and
> HugeTLB mappings across private/shared and read/write variants. For each
> variant, it tests get_user_pages(), get_user_pages_fast(),
> pin_user_pages(), pin_user_pages_fast(), long-term pinning and both dump
> modes using four batch sizes. It also preserves the existing sparse dump
> coverage for pages 0, 19 and 0x1000. The HugeTLB variants share a one-time
> setup of 128 default-sized huge pages.

I tested the full MM selftest suite before and after this series and found
no regressions. The new GUP selftest and gup_bench also passed.

Tested-by: Muhammad Usama Anjum <usama.anjum@arm.com>

Thanks,
Usama