xen/mm: Host-side integration test environment for page_alloc.c
v2 cover xen/mm: Host-side integration test environment for page_alloc.c
Hi all,
This patch series introduces a host-side integration test environment for Xen's page allocator in xen/common/page_alloc.c, reduced in size by 60% from 2257 to 1411 new lines with v2.
Using this environment, it also introduces integration tests for claims, including NUMA-aware claim sets, complementing the functional system tests submitted as part of the NUMA-aware claims v6 series.
The claim tests verify the page allocator's behaviour with multi-node claim sets in scenarios that are easier to isolate and validate using a synthetic Xen heap and domain state, offering full control and visibility into claim states as claims are made and redeemed during heap allocation.
For these tests, this series depends on the NUMA claims v6 series, which introduced NUMA-aware claim sets:
[PATCH v6 0/7] xen/mm: Introduce NUMA-aware claim sets for domains
https://lists.xen.org/archives/html/xen-devel/2026-04/msg00587.html
https://patchwork.kernel.org/project/xen-devel/list/?series=1081139
Its design is described in this document:
[PATCH v2] docs: Draft Design Document for NUMA-aware claim sets
https://lists.xen.org/archives/html/xen-devel/2026-04/msg00569.html
https://patchwork.kernel.org/project/xen-devel/list/?series=1081047
Patch summary:
1. tools/tests/alloc: Add a test environment for the page allocator
2. tools/tests/alloc: Add integration tests for claims and claim sets
3. tools/tests/alloc: Add tests for offlining with claims present
4. xen/mm: Recall claims when offlining pages if needed
Thanks,
Bernhard Kaindl
---
Changes since v1:
1. Refactored the test environment for minimalism:
- Improved separation of concerns.
- Moved extensions to later patch series.
- Simplified code with targeted assertions and concise comments.
2. Fixed file names to avoid underscores.
3. Updated include guards to comply with CODING_STYLE.
---
PS: The bug fixed in the last commit also affects the global claims in Xen master when offlining pages.
While offlining has known limitations, the bug fixed in this series also affects global claims in Xen master when pages are offlined. I will submit a follow-up series to address offlining itself. In the meantime, this test framework enables targeted testing on a synthetic Xen heap and simplifies validation by letting the tests observe heap-state changes during offlining.
Bernhard Kaindl (4):
tools/tests/alloc: Add Page Allocator Test Environment tools/tests/alloc: Add integration test suite to for NUMA memory
claims
tools/tests/alloc: Add tests for offlining with claims present xen/mm: Recall claims when offlining pages if needed
tools/tests/Makefile | 1 + tools/tests/alloc/.gitignore | 7 + tools/tests/alloc/Makefile | 141 +++++++ tools/tests/alloc/README.rst | 98 +++++ tools/tests/alloc/check-asserts.h | 225 +++++++++++ tools/tests/alloc/harness.h | 57 +++ tools/tests/alloc/hypervisor-macros.h | 95 +++++ tools/tests/alloc/libtest-page-alloc.h | 145 +++++++ tools/tests/alloc/mock-page-list.h | 167 ++++++++ tools/tests/alloc/page-alloc-shim.h | 411 ++++++++++++++++++++ tools/tests/alloc/page-alloc-wrapper.h | 64 +++ tools/tests/alloc/test-claims-basic.c | 108 +++++ tools/tests/alloc/test-claims-numa-redeem.c | 172 ++++++++ tools/tests/alloc/test-offlining-claims.c | 71 ++++ xen/common/page_alloc.c | 42 ++ 15 files changed, 1804 insertions(+) create mode 100644 tools/tests/alloc/.gitignore create mode 100644 tools/tests/alloc/Makefile create mode 100644 tools/tests/alloc/README.rst create mode 100644 tools/tests/alloc/check-asserts.h create mode 100644 tools/tests/alloc/harness.h create mode 100644 tools/tests/alloc/hypervisor-macros.h create mode 100644 tools/tests/alloc/libtest-page-alloc.h create mode 100644 tools/tests/alloc/mock-page-list.h create mode 100644 tools/tests/alloc/page-alloc-shim.h create mode 100644 tools/tests/alloc/page-alloc-wrapper.h create mode 100644 tools/tests/alloc/test-claims-basic.c create mode 100644 tools/tests/alloc/test-claims-numa-redeem.c create mode 100644 tools/tests/alloc/test-offlining-claims.c
Signature · 1 line
2.39.5
PATCH v2 1/4 tools/tests/alloc: Add Page Allocator Test Environment
Provide a small, self-contained test environment for Xen's page allocator.
Instead of reimplementing allocator logic in a model, these tests compile the real allocator code into ordinary host executables and exercise it in a controlled environment with a synthetic Xen heap and domain state. This gives direct visibility into allocator state while keeping the test harness self-contained.
This is intended for scenarios that are difficult to cover with system-level testing alone, such as:
* inspecting NUMA claims in response to allocator operations
* rebuilding buddies after offlining subpages
* reproducing edge cases while inspecting heap state during allocation and free operations
--- tools/tests/Makefile | 1 + tools/tests/alloc/.gitignore | 7 + tools/tests/alloc/Makefile | 141 +++++++++ tools/tests/alloc/README.rst | 98 ++++++ tools/tests/alloc/check-asserts.h | 225 ++++++++++++++ tools/tests/alloc/harness.h | 57 ++++ tools/tests/alloc/hypervisor-macros.h | 95 ++++++ tools/tests/alloc/libtest-page-alloc.h | 145 +++++++++ tools/tests/alloc/mock-page-list.h | 167 ++++++++++ tools/tests/alloc/page-alloc-shim.h | 411 +++++++++++++++++++++++++ tools/tests/alloc/page-alloc-wrapper.h | 64 ++++ 11 files changed, 1411 insertions(+) create mode 100644 tools/tests/alloc/.gitignore create mode 100644 tools/tests/alloc/Makefile create mode 100644 tools/tests/alloc/README.rst create mode 100644 tools/tests/alloc/check-asserts.h create mode 100644 tools/tests/alloc/harness.h create mode 100644 tools/tests/alloc/hypervisor-macros.h create mode 100644 tools/tests/alloc/libtest-page-alloc.h create mode 100644 tools/tests/alloc/mock-page-list.h create mode 100644 tools/tests/alloc/page-alloc-shim.h create mode 100644 tools/tests/alloc/page-alloc-wrapper.h
tools/tests/Makefile +1 -0
@@ -2,6 +2,7 @@ XEN_ROOT = $(CURDIR)/../.. include $(XEN_ROOT)/tools/Rules.mk SUBDIRS-y := +SUBDIRS-y += alloc SUBDIRS-y += domid SUBDIRS-y += mem-claim SUBDIRS-y += paging-mempool
tools/tests/alloc/.gitignore new file +7 -0
@@ -0,0 +1,7 @@ +/test-claims-basic +/test-claims-numa-install +/test-claims-numa-redeem +/test-online-page +/test-offlining-claims +/test-reserve-offline-page +/test-unaligned-buddies
tools/tests/alloc/Makefile new file +141 -0
141 lines not on this page · raw message
tools/tests/alloc/README.rst new file +98 -0
98 lines not on this page · raw message
tools/tests/alloc/check-asserts.h new file +225 -0
225 lines not on this page · raw message
tools/tests/alloc/harness.h new file +57 -0
57 lines not on this page · raw message
tools/tests/alloc/hypervisor-macros.h new file +95 -0
95 lines not on this page · raw message
tools/tests/alloc/libtest-page-alloc.h new file +145 -0
145 lines not on this page · raw message
tools/tests/alloc/mock-page-list.h new file +167 -0
167 lines not on this page · raw message
tools/tests/alloc/page-alloc-shim.h new file +411 -0
411 lines not on this page · raw message
tools/tests/alloc/page-alloc-wrapper.h new file +64 -0
64 lines not on this page · raw message
Signature · 1 line
2.39.5
PATCH v2 2/4 tools/tests/alloc: Add integration test suite to for NUMA memory claims
In reply to Bernhard KaindlTest claims behaviour of the page allocator with global claims using domain_set_outstanding_pages() and the new API and test multi-node claims.
--- tools/tests/alloc/test-claims-basic.c | 108 ++++++++++++ tools/tests/alloc/test-claims-numa-redeem.c | 172 ++++++++++++++++++++ 2 files changed, 280 insertions(+) create mode 100644 tools/tests/alloc/test-claims-basic.c create mode 100644 tools/tests/alloc/test-claims-numa-redeem.c
tools/tests/alloc/test-claims-basic.c new file +108 -0
@@ -0,0 +1,108 @@ +/* SPDX-License-Identifier: GPL-2.0-only */ +/* +* Copyright (C) 2026 Cloud Software Group +*/ +#include "libtest-page-alloc.h" + +int test_set_global_claims (struct domain *d,unsigned long pages) +{ +memory_claim_t claim_set[] = { + {.target =XEN_DOMCTL_CLAIM_MEMORY_GLOBAL , .pages = pages}, + }; + +return domain_install_claim_set (d,ARRAY_SIZE (claim_set), claim_set); +} +typedef int (*set_global_claims )(struct domain *d,unsigned long pages); + +set_global_claims install_global_claims = test_set_global_claims; + +static void test_alloc_domheap_redeems_claims (int start_mfn) +{ +int ret; +struct page_info *pages = test_pages + start_mfn, *pg; + +test_page_list_add_buddy (pages, order2); +ASSERT (!test_set_global_claims (dom1,3 )); +ASSERT (alloc_domheap_pages (dom1, order1,0 ) == pages +2 ); +ASSERT (alloc_domheap_pages (dom1, order0,0 ) == pages +1 ); +CHECK (TOTAL_CLAIMS ==0 ,"Expect all claims consumed after allocations" ); +CHECK (FREE_PAGES ==1 ,"Expect one free page after allocations" ); + +ASSERT (!test_set_global_claims (dom2,FREE_PAGES )); + +/* Claim more than dom1 already has fails with ENOMEM (claimed by dom2) */ + ret =test_set_global_claims (dom1,domain_tot_pages (dom1) +1 ); +CHECK (ret == -ENOMEM ,"dom 1 claim +1 fails due to insufficient pages" ); + +/* Claim more than dom1's d->max_pages fails with EINVAL */ + ret =test_set_global_claims (dom1, dom1->max_pages +1 ); +CHECK (ret == -EINVAL ,"dom 1 claim fails due to exceeding max_pages" ); + +/* Attempt to allocate an order-0 page with a foreign claim present */ + pg =alloc_domheap_pages (dom1, order0,0 ); +CHECK (pg ==NULL ,"dom 1 allocation fails because of domain 2's claim" ); +CHECK (TOTAL_CLAIMS ==1 ,"Expect domain 2's claim to be still present" ); +CHECK (FREE_PAGES ==1 ,"Expect one free page after failed alloc" ); +} + +/* +* Test that memory claims are consumed correctly during allocations. +*/ +static void test_cancel_claims (int start_mfn) +{ +struct page_info *page = test_pages + start_mfn; +unsigned long claims; + +/* Create a buddy of order 2 (4 pages) and add it to the heap. */ +test_page_list_add_buddy (page, order2); + claims =FREE_PAGES /2 ; + +/* Claim half of the free pages for dom1 */ +ASSERT (test_set_global_claims (dom1, claims) ==0 ); +ASSERT (TOTAL_CLAIMS == claims); + +/* Act + Assert 2: Claim all free pages for dom2, should fail */ +ASSERT (test_set_global_claims (dom2,FREE_PAGES ) == -ENOMEM ); +ASSERT (TOTAL_CLAIMS == claims); + +/* Act + Assert 1: Cancel all claims for dom1 */ +ASSERT (test_set_global_claims (dom1,0 ) ==0 ); +ASSERT (TOTAL_CLAIMS ==0 ); + +/* Act + Assert 2: Claim all free pages for dom2, should work */ +ASSERT (test_set_global_claims (dom2,FREE_PAGES ) ==0 ); +ASSERT (TOTAL_CLAIMS ==FREE_PAGES ); +} + +int main (int argc,char *argv[]) +{ +const char *topic ="Test global claims with old and new interfaces" ; +const char *program_name =parse_args (argc, argv, topic); + +if ( !program_name ) +return EXIT_FAILURE ; + +init_page_alloc_tests (); + +RUN_TESTCASE (TCCL , test_cancel_claims,4 ); + +/* Confirm the baseline of using domain_set_outstanding_pages() */ + install_global_claims = domain_set_outstanding_pages; +RUN_TESTCASE (ADCL , test_alloc_domheap_redeems_claims,4 ); + +/* Repeat the same test case using test_set_global_claims() */ + install_global_claims = test_set_global_claims; +RUN_TESTCASE (ADCG , test_alloc_domheap_redeems_claims,4 ); + +testcase_print_summary (program_name); +return 0 ; +} + +/* +* Local variables: +* mode: C +* c-file-style: "BSD" +* c-basic-offset: 4 +* indent-tabs-mode: nil +* End: +*/
tools/tests/alloc/test-claims-numa-redeem.c new file +172 -0
172 lines not on this page · raw message
Signature · 1 line
2.39.5
PATCH v2 3/4 tools/tests/alloc: Add tests for offlining with claims present
In reply to Bernhard KaindlAdd an integration test for offlining pages with outstanding claims. The test offlines two pages, with the second offline operation recalling one claim to prevent over-claiming beyond the available memory. Due to missing checks in the offlining code, there are expected failures which will be fixed in a test-driven manner.
Run this test with both global claims and node-local claims.
--- tools/tests/alloc/test-offlining-claims.c | 75 +++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 tools/tests/alloc/test-offlining-claims.c
tools/tests/alloc/test-offlining-claims.c new file +75 -0
@@ -0,0 +1,75 @@ +/* SPDX-License-Identifier: GPL-2.0-only */ +/* +* Copyright (C) 2026 Cloud Software Group +*/ +#include "libtest-page-alloc.h" + +static void test_offlining_with_global_claims (int mfn) +{ +struct page_info *page = test_pages + mfn; +uint32_t status =0 ; +memory_claim_t claims[1 ] = { + {.pages =3 , .target =XEN_DOMCTL_CLAIM_MEMORY_GLOBAL } + }; + +test_page_list_add_buddy (page, order2);/* Add a buddy with 4 free pages*/ +ASSERT (domain_install_claim_set (dom1,ARRAY_SIZE (claims), claims) ==0 ); + +offline_page (mfn +3 ,0 , &status);/* Offline the 1st page */ +ASSERT (status &PG_OFFLINE_OFFLINED ); +CHECK (TOTAL_CLAIMS ==3 ,"Still 3 claims before offlining the 2nd page" ); + +offline_page (mfn +1 ,0 , &status);/* Offline the 2nd page */ +ASSERT (status &PG_OFFLINE_OFFLINED ); + +CHECK (FREE_PAGES ==2 ,"Expect 2 free pages after offlining two pages" ); +EXPECTED_TO_FAIL_BEGIN (); +CHECK (TOTAL_CLAIMS ==2 ,"Expect 2 claims after offlining two pages" ); +EXPECTED_TO_FAIL_END (1 ); +} + + +/* +* Claim 3 of 4 pages on node0, offline two pages, and the 2nd offline should +* recall one claim to prevent over-claiming beyond the available memory. +* +* As part of offline_page(), reserve_offlined_page() should recall the +* needed claims to not exceed the number of pages that are are remaining. +*/ +static void test_offlining_with_node_claims (int mfn) +{ +struct page_info *page = test_pages + mfn; +uint32_t status =0 ; +memory_claim_t claims[1 ] = { {.pages =3 , .target = node0} }; + +test_page_list_add_buddy (page, order2); +ASSERT (domain_install_claim_set (dom1,ARRAY_SIZE (claims), claims) ==0 ); + +ASSERT (offline_page (mfn +3 ,0 , &status) ==0 ); +ASSERT (status &PG_OFFLINE_OFFLINED ); +CHECK (TOTAL_CLAIMS ==3 ,"Still 3 claims before offlining the 2nd page" ); + +ASSERT (offline_page (mfn +1 ,0 , &status) ==0 ); +ASSERT (status &PG_OFFLINE_OFFLINED ); + +CHECK (FREE_PAGES ==2 ,"Expect 2 free pages after offlining two pages" ); +EXPECTED_TO_FAIL_BEGIN (); +CHECK (TOTAL_CLAIMS ==2 ,"Expect 2 claims after offlining two pages" ); +EXPECTED_TO_FAIL_END (1 ); +} + +int main (int argc,char *argv[]) +{ +const char *topic ="Test offlining with memory claims" ; +const char *program_name =parse_args (argc, argv, topic); + +if ( !program_name ) +return EXIT_FAILURE ; + +init_page_alloc_tests (); + +RUN_TESTCASE (OWGC , test_offlining_with_global_claims,4 ); +RUN_TESTCASE (OWNC , test_offlining_with_node_claims,4 ); + +return testcase_print_summary (program_name); +}
Signature · 1 line
2.39.5
PATCH v2 4/4 xen/mm: Recall claims when offlining pages if needed
In reply to Bernhard KaindlFix a bug where offlining pages could cause an unsigned underflow in total_avail_pages - outstanding_claims, leading to incorrect claim behavior.
This issue arises when outstanding claims are close to the total available pages. It occurse when domain_set_outstanding_claims() and domain_install_claim_set effectively do this:
unsigned long avail_pages = total_avail_pages - outstanding_claims;
When this unsigned subtraction underflows, staking claims can succeed even when there is insufficient unclaimed memory for the new claim. This leads to a state where claims always succeed, regardless of actual memory availability.
To prevent this, recall claims when offlining pages if needed to maintain equilibrium between total_avail_pages and outstanding claims for global and for per-NUMA-node claims.
--- tools/tests/alloc/test-offlining-claims.c | 4 --- xen/common/page_alloc.c | 42 +++++++++++++++++++++++ 2 files changed, 42 insertions(+), 4 deletions(-)
tools/tests/alloc/test-offlining-claims.c +0 -4
@@ -23,9 +23,7 @@ static void test_offlining_with_global_claims(int mfn)ASSERT (status &PG_OFFLINE_OFFLINED );CHECK (FREE_PAGES ==2 ,"Expect 2 free pages after offlining two pages" ); -EXPECTED_TO_FAIL_BEGIN ();CHECK (TOTAL_CLAIMS ==2 ,"Expect 2 claims after offlining two pages" ); -EXPECTED_TO_FAIL_END (1 ); }
@@ -53,9 +51,7 @@ static void test_offlining_with_node_claims(int mfn)ASSERT (status &PG_OFFLINE_OFFLINED );CHECK (FREE_PAGES ==2 ,"Expect 2 free pages after offlining two pages" ); -EXPECTED_TO_FAIL_BEGIN ();CHECK (TOTAL_CLAIMS ==2 ,"Expect 2 claims after offlining two pages" ); -EXPECTED_TO_FAIL_END (1 ); }int main (int argc,char *argv[])
xen/common/page_alloc.c +42 -0
48 lines not on this page · raw message
Signature · 1 line
2.39.5
Re: [PATCH v2 4/4] xen/mm: Recall claims when offlining pages if needed
Quoted 15 lines · Bernhard Kaindl
Fix a bug where offlining pages could cause an unsigned underflow in
total_avail_pages-outstanding_claims, leading to incorrect claim behavior.This issue arises when outstanding claims are close to the total available pages. It occurse when
domain_set_outstanding_claims()anddomain_install_claim_seteffectively do this:unsigned long
avail_pages=total_avail_pages-outstanding_claims;When this unsigned subtraction underflows, staking claims can succeed even when there is insufficient unclaimed memory for the new claim. This leads to a state where claims always succeed, regardless of actual memory availability.
Quoted 5 lines
To prevent this, recall claims when offlining pages if needed to maintain equilibrium between
total_avail_pagesand outstanding claims for global and for per-NUMA-node claims.Signed-off-by Bernhard Kaindl <[email protected]>
First: This patch being a bug fix (which, btw, lacks a Fixes: tag), it wants to move ahead of the NUMA claims series, to facilitate backporting.
xen/common/page_alloc.c static int reserve_offlined_page(struct page_info *head) · line 1578
Quoted 7 lines
xen/common/page_alloc.c +1
-0@@ -1575,6 +1575,48 @@ static int reserve_offlined_page(struct page_info *head) count++; } +if ( count )
Why did you decide to put this in reserve_offlined_page()? The function has two callers, yet in one case the extra checking is entirely unneeded afaict. While in the other case we further know that it's exactly one page which is being offlined.
xen/common/page_alloc.c static int reserve_offlined_page(struct page_info *head) · line 1591
Quoted 13 lines
xen/common/page_alloc.c +13
-0+ { +long recall_pages; +struct domain *d; + +/* Ensure that claims on the node are in line with its free memory. */ + recall_pages = node_outstanding_claims[node] - node_avail_pages[node]; +if ( recall_pages >0 ) +/* +* node_avail_pages slipped below node_outstanding_claims. +* We need to recall claimed pages until the amount of claimed +* memory is in line with the amount of available memory again. +*/ +for_each_domain ( d )
Such loops need serializing against domain list modifications. Also we really don't want to loop over all domains twice.
xen/common/page_alloc.c static int reserve_offlined_page(struct page_info *head) · line 1599
Quoted 8 lines
xen/common/page_alloc.c +8
-0+ { +if ( d->claims[node] ) + { + recall_pages -=deduct_node_claims (d, node, recall_pages); +if ( recall_pages <=0 ) +break ; + } + }
So domains early on the list are penalized over ones later on the list? The only truly fair approach I can think of right away looks to be to discard all claims, requiring the toolstack to re-establish them. With the observation above the next best approach might be to cycle through domains, removing one page from their claim and recording where we left off (the per-node part would be slightly more involved). However, any reduction of a claim is likely to render that claim useless altogether. Hence requiring admin action (to re-establish claims) may still be the least bad option.
Jan
Quoted 22 lines
xen/common/page_alloc.c +19
-0+/* Ensure that outstanding claims are in line with available memory. */ + recall_pages = outstanding_claims - total_avail_pages; +if ( recall_pages >0 ) +/* +* total_avail_pages slipped below outstanding_claims. +* We need to recall claimed pages until the amount of claimed +* memory is in line with the amount of available memory again. +*/ + for_each_domain ( d ) + { +if ( d->global_claims ) + { + recall_pages -=deduct_global_claims (d, recall_pages); +if ( recall_pages <=0 ) +break ; + } + } + } +return count; }