Re: [PATCH 1/4] tests/xe: Add page reclaim test

["Wang, X" <x.wang@intel.com>]

On 4/6/2026 11:42, Brian Nguyen wrote:
> Page Reclamation is a feature enabled in Xe3p that allows for some
> performance gain by optimizing TLB invalidations. Xe2 and beyond has
> an physical noncoherent L2 cache that requires a full PPC flush
> everytime a TLB invalidation occurs. With page reclamation it will
> only take the corresponding pages associated with the unmap that
> triggers the TLB invalidation.
>
> xe_page_reclaim test cases create pages of a specific size, binds them
> to a VM, and unbinds, observing if the expected pages are added to the
> PRL, through the use of gt stats.
>
> Signed-off-by: Brian Nguyen <brian3.nguyen@intel.com>
> Cc: Xin Wang <x.wang@intel.com>
> ---
>   tests/intel/xe_page_reclaim.c | 441 ++++++++++++++++++++++++++++++++++
>   tests/meson.build             |   1 +
>   2 files changed, 442 insertions(+)
>   create mode 100644 tests/intel/xe_page_reclaim.c
>
> diff --git a/tests/intel/xe_page_reclaim.c b/tests/intel/xe_page_reclaim.c
> new file mode 100644
> index 000000000..acc237d43
> --- /dev/null
> +++ b/tests/intel/xe_page_reclaim.c
> @@ -0,0 +1,441 @@
> +// SPDX-License-Identifier: MIT
> +/*
> + * Copyright © 2026 Intel Corporation
> + */
> +
> +#include <fcntl.h>
> +
> +#include "ioctl_wrappers.h"
> +#include "xe/xe_gt.h"
> +#include "xe/xe_ioctl.h"
> +
> +#define OVERFLOW_PRL_SIZE 512
> +
> +/**
> + * TEST: xe_page_reclaim
> + * Category: Core
> + * Mega feature: General Core features
> + * Sub-category: VM bind
> + * Functionality: Page Reclamation
> + * Test category: functionality test
> + */
> +struct xe_prl_stats {
> +	int prl_4k_entry_count;
> +	int prl_64k_entry_count;
> +	int prl_2m_entry_count;
> +	int prl_issued_count;
> +	int prl_aborted_count;
> +};
> +
> +/*
> + * PRL is only active on the render GT (gt0); media tiles do not participate
> + * in page reclamation. Callers typically pass gt=0.
> + */
> +static struct xe_prl_stats get_prl_stats(int fd, int gt)
> +{
> +	struct xe_prl_stats stats = {0};
> +
> +	stats.prl_4k_entry_count = xe_gt_stats_get_count(fd, gt, "prl_4k_entry_count");
> +	stats.prl_64k_entry_count = xe_gt_stats_get_count(fd, gt, "prl_64k_entry_count");
> +	stats.prl_2m_entry_count = xe_gt_stats_get_count(fd, gt, "prl_2m_entry_count");
> +	stats.prl_issued_count = xe_gt_stats_get_count(fd, gt, "prl_issued_count");
> +	stats.prl_aborted_count = xe_gt_stats_get_count(fd, gt, "prl_aborted_count");
> +
> +	return stats;
> +}
> +
> +static void log_prl_stat_diff(struct xe_prl_stats *stats_before, struct xe_prl_stats *stats_after)
> +{
> +	igt_debug("PRL stats diff: 4K: %d->%d, 64K: %d->%d, 2M: %d -> %d, issued: %d->%d, aborted: %d->%d\n",
> +		  stats_before->prl_4k_entry_count,
> +		  stats_after->prl_4k_entry_count,
> +		  stats_before->prl_64k_entry_count,
> +		  stats_after->prl_64k_entry_count,
> +		  stats_before->prl_2m_entry_count,
> +		  stats_after->prl_2m_entry_count,
> +		  stats_before->prl_issued_count,
> +		  stats_after->prl_issued_count,
> +		  stats_before->prl_aborted_count,
> +		  stats_after->prl_aborted_count);
> +}
> +
> +/* Compare differences between stats and determine if expected */
> +static void compare_prl_stats(struct xe_prl_stats *before, struct xe_prl_stats *after,
> +			      struct xe_prl_stats *expected)
> +{
> +	log_prl_stat_diff(before, after);
> +
> +	igt_assert_eq(after->prl_4k_entry_count - before->prl_4k_entry_count,
> +		      expected->prl_4k_entry_count);
> +	igt_assert_eq(after->prl_64k_entry_count - before->prl_64k_entry_count,
> +		      expected->prl_64k_entry_count);
> +	igt_assert_eq(after->prl_2m_entry_count - before->prl_2m_entry_count,
> +		      expected->prl_2m_entry_count);
> +	igt_assert_eq(after->prl_issued_count - before->prl_issued_count,
> +		      expected->prl_issued_count);
> +	igt_assert_eq(after->prl_aborted_count - before->prl_aborted_count,
> +		      expected->prl_aborted_count);
> +}
> +
> +/* Helper with more flexibility on unbinding and offsets */
> +static void vma_range_list_with_unbind_and_offsets(int fd, const uint64_t *vma_sizes, unsigned int n_vmas,
> +				 uint64_t start_addr, uint64_t unbind_size, const uint64_t *vma_offsets)
> +{
> +	uint32_t vm;
> +	uint32_t *bos;
> +	uint64_t addr;
> +
> +	igt_assert(vma_sizes);
> +	igt_assert(n_vmas);
> +
> +	vm = xe_vm_create(fd, 0, 0);
> +
> +	bos = calloc(n_vmas, sizeof(*bos));
> +	igt_assert(bos);
> +
> +	addr = start_addr;
> +	for (unsigned int i = 0; i < n_vmas; i++) {
> +		igt_assert(vma_sizes[i]);
> +
> +		bos[i] = xe_bo_create(fd, 0, vma_sizes[i], system_memory(fd), 0);
> +		if (vma_offsets)
> +			addr = start_addr + vma_offsets[i];
> +		xe_vm_bind_sync(fd, vm, bos[i], 0, addr, vma_sizes[i]);
> +		addr += vma_sizes[i];
> +	}
> +
> +	/* Unbind the whole contiguous VA span in one operation. */
> +	xe_vm_unbind_sync(fd, vm, 0, start_addr, unbind_size ? unbind_size : addr - start_addr);
> +
> +	for (unsigned int i = 0; i < n_vmas; i++)
> +		gem_close(fd, bos[i]);
> +
> +	free(bos);
> +	xe_vm_destroy(fd, vm);
> +}
> +
> +/*
> + * Takes in an array of vma sizes and allocates/binds individual BOs for each given size,
> + * then unbinds them all at once
> + */
> +static void test_vma_ranges_list(int fd, const uint64_t *vma_sizes,
> +				 unsigned int n_vmas, uint64_t start_addr)
> +{
> +	vma_range_list_with_unbind_and_offsets(fd, vma_sizes, n_vmas, start_addr, 0, NULL);
> +}
> +
> +/**
> + * SUBTEST: basic-mixed
> + * Description: Create multiple different sizes of page (4K, 64K, 2M)
> + *      GPU VMA ranges, bind them into a VM at unique addresses, then
> + *      unbind all to trigger page reclamation on different page sizes
> + *      in one page reclaim list.
> + */
> +static void test_vma_ranges_basic_mixed(int fd)
> +{
> +	struct xe_prl_stats stats_before, stats_after, expected_stats = { 0 };
> +	const uint64_t num_4k_pages = 16;
> +	const uint64_t num_64k_pages = 31;
> +	const uint64_t num_2m_pages = 2;
> +	uint64_t *sizes = calloc(num_4k_pages + num_64k_pages + num_2m_pages, sizeof(uint64_t));
> +	int count = 0;
> +
> +	igt_assert(sizes);
> +	for (int i = 0; i < num_4k_pages; i++)
> +		sizes[count++] = SZ_4K;
> +
> +	for (int i = 0; i < num_64k_pages; i++)
> +		sizes[count++] = SZ_64K;
> +
> +	for (int i = 0; i < num_2m_pages; i++)
> +		sizes[count++] = SZ_2M;
> +
> +	expected_stats.prl_4k_entry_count = num_4k_pages;
> +	expected_stats.prl_64k_entry_count = num_64k_pages;
> +	expected_stats.prl_2m_entry_count = num_2m_pages;
> +	expected_stats.prl_issued_count = 1;
> +	expected_stats.prl_aborted_count = 0;
> +
> +	stats_before = get_prl_stats(fd, 0);
> +	test_vma_ranges_list(fd, sizes, count, 1ull << 30);
> +	stats_after = get_prl_stats(fd, 0);
> +
> +	free(sizes);
> +	compare_prl_stats(&stats_before, &stats_after, &expected_stats);
> +}
> +
> +/**
> + * SUBTEST: prl-invalidate-full
> + * Description: Create 512 4K page entries at the maximum page reclaim list
> + *      size boundary and bind them into a VM.
> + *      Expects to trigger a fallback to full PPC flush due to page reclaim
> + *      list size limitations (512 entries max).
> + *
> + * SUBTEST: prl-max-entries
> + * Description: Create the maximum page reclaim list without overflow
> + *      bind them into a VM.
> + *      Expects no fallback to PPC flush due to page reclaim
> + *      list size limitations (512 entries max).
> + */
> +static void test_vma_ranges_prl_entries(int fd, unsigned int num_entries,
> +					int expected_issued, int expected_aborted)
> +{
> +	struct xe_prl_stats stats_before, stats_after, expected_stats = { 0 };
> +	const uint64_t page_size = SZ_4K;
> +	/* Start address aligned but offset by a page to ensure no large PTE are created */
> +	uint64_t addr = (1ull << 30) + page_size;
> +
> +	/* Capped at OVERFLOW_PRL_SIZE - 1: on overflow the last entry triggers abort */
> +	expected_stats.prl_4k_entry_count = min_t(int, num_entries, OVERFLOW_PRL_SIZE - 1);
> +	expected_stats.prl_64k_entry_count = 0;
> +	expected_stats.prl_2m_entry_count = 0;
> +	expected_stats.prl_issued_count = expected_issued;
> +	expected_stats.prl_aborted_count = expected_aborted;
> +
> +	stats_before = get_prl_stats(fd, 0);
> +	test_vma_ranges_list(fd, &(uint64_t){page_size * num_entries}, 1, addr);
> +	stats_after = get_prl_stats(fd, 0);
> +	compare_prl_stats(&stats_before, &stats_after, &expected_stats);
> +}
> +
> +/*
> + * Bind the BOs to multiple VA ranges and unbind all VA with one range.
> + * BO size is chosen as the maximum of the requested VMA sizes.
> + */
> +static void test_many_ranges_one_bo(int fd,
> +				    const uint64_t vma_size,
> +				    unsigned int n_vmas,
> +				    uint64_t start_addr)
> +{
> +	uint32_t vm;
> +	uint64_t addr;
> +	uint32_t bo;
> +
> +	igt_assert(n_vmas);
> +
> +	vm = xe_vm_create(fd, 0, 0);
> +
> +	igt_assert(vma_size);
> +	bo = xe_bo_create(fd, 0, vma_size, system_memory(fd), 0);
> +
> +	addr = start_addr;
> +	for (unsigned int i = 0; i < n_vmas; i++) {
> +		/* Bind the same BO (offset 0) at a new VA location */
> +		xe_vm_bind_sync(fd, vm, bo, 0, addr, vma_size);
> +		addr += vma_size;
> +	}
> +
> +	/* Unbind all VMAs */
> +	xe_vm_unbind_sync(fd, vm, 0, start_addr, addr - start_addr);
> +
> +	gem_close(fd, bo);
> +	xe_vm_destroy(fd, vm);
> +}
> +
> +/**
> + * SUBTEST: many-vma-same-bo
> + * Description: Create multiple 4K page VMA ranges bound to the same BO,
> + *      bind them into a VM at unique addresses, then unbind all to trigger
> + *      page reclamation handling when the same BO is bound to multiple
> + *      virtual addresses.
> + */
> +static void test_vma_ranges_many_vma_same_bo(int fd, uint64_t vma_size, unsigned int n_vmas)
> +{
> +	struct xe_prl_stats stats_before, stats_after, expected_stats = { 0 };
> +
> +	expected_stats.prl_4k_entry_count = n_vmas;
> +	expected_stats.prl_issued_count = 1;
> +
> +	stats_before = get_prl_stats(fd, 0);
> +	test_many_ranges_one_bo(fd, vma_size, n_vmas, 1ull << 30);
> +	stats_after = get_prl_stats(fd, 0);
> +	compare_prl_stats(&stats_before, &stats_after, &expected_stats);
> +}
> +
> +/**
> + * SUBTEST: invalid-1g
> + * Description: Create a 1G page VMA followed by a 4K page VMA to test
> + *      handling of 1G page mappings during page reclamation.
> + *      Expected is to fallback to invalidation.
> + */
> +static void test_vma_range_invalid_1g(int fd)
> +{
> +	struct xe_prl_stats stats_before, stats_after, expected_stats = { 0 };
> +	static const uint64_t sizes[] = {
> +		SZ_1G,
> +		SZ_4K,
> +	};
> +	int delta_4k, delta_64k, delta_2m, delta_issued, delta_aborted;
> +	bool expected_2m_entries, all_entries_dropped;
> +
> +	/* 1G page broken into 512 2M pages, but it should invalidate the last entry */
> +	expected_stats.prl_2m_entry_count = OVERFLOW_PRL_SIZE - 1;
> +	/* No page size because PRL should be invalidated before the second page */
> +	expected_stats.prl_4k_entry_count = 0;
> +	expected_stats.prl_issued_count = 0;
> +	expected_stats.prl_aborted_count = 1;
> +
> +	stats_before = get_prl_stats(fd, 0);
> +	/* Offset 2G to avoid alignment issues */
> +	test_vma_ranges_list(fd, sizes, ARRAY_SIZE(sizes), SZ_2G);
> +	stats_after = get_prl_stats(fd, 0);
> +	log_prl_stat_diff(&stats_before, &stats_after);
> +
> +	/*
> +	 * Depending on page placement, 1G page directory could be dropped from page walk
> +	 * which would not generate any entries
> +	 */
> +	delta_4k = stats_after.prl_4k_entry_count - stats_before.prl_4k_entry_count;
> +	delta_64k = stats_after.prl_64k_entry_count - stats_before.prl_64k_entry_count;
> +	delta_2m = stats_after.prl_2m_entry_count - stats_before.prl_2m_entry_count;
> +	delta_issued = stats_after.prl_issued_count - stats_before.prl_issued_count;
> +	delta_aborted = stats_after.prl_aborted_count - stats_before.prl_aborted_count;
> +	expected_2m_entries = (delta_2m == expected_stats.prl_2m_entry_count);
> +	all_entries_dropped = (delta_2m == 0 && delta_64k == 0 && delta_4k == 0);
> +
> +	igt_assert_eq(delta_issued, expected_stats.prl_issued_count);
> +	igt_assert_eq(delta_aborted, expected_stats.prl_aborted_count);
> +	igt_assert_eq(delta_4k, expected_stats.prl_4k_entry_count);
> +	igt_assert(expected_2m_entries || all_entries_dropped);
> +}
> +
> +/**
> + * SUBTEST: pde-vs-pd
> + * Description: Test case to trigger invalidation of both PDE (2M pages)
> + *      and PD (page directory filled with 64K pages) to determine correct
> + *      handling of both cases for PRL.
> + */
> +static void test_vma_ranges_pde_vs_pd(int fd)
> +{
> +	struct xe_prl_stats stats_before, stats_after, expected_stats = { 0 };
> +	/* Ensure no alignment issue by using 1G */
> +	uint64_t start_addr = 1ull << 30;
> +	/* 32 pages of 64K to fill one page directory */
> +	static const unsigned int num_pages = SZ_2M / SZ_64K;
> +	static const uint64_t size_pde[] = {
> +		SZ_2M,
> +	};
> +	uint64_t size_pd[num_pages];
> +
> +	for (int i = 0; i < num_pages; i++)
> +		size_pd[i] = SZ_64K;
> +
> +	expected_stats = (struct xe_prl_stats) {
> +		.prl_64k_entry_count = num_pages,
> +		.prl_issued_count = 1,
> +	};
> +	stats_before = get_prl_stats(fd, 0);
> +	test_vma_ranges_list(fd, size_pd, ARRAY_SIZE(size_pd), start_addr);
> +	stats_after = get_prl_stats(fd, 0);
> +	compare_prl_stats(&stats_before, &stats_after, &expected_stats);
> +
> +	expected_stats = (struct xe_prl_stats) {
> +		.prl_2m_entry_count = 1,
> +		.prl_issued_count = 1,
> +	};
> +	stats_before = get_prl_stats(fd, 0);
> +	test_vma_ranges_list(fd, size_pde, ARRAY_SIZE(size_pde), start_addr);
> +	stats_after = get_prl_stats(fd, 0);
> +	compare_prl_stats(&stats_before, &stats_after, &expected_stats);
> +}
> +
> +/**
> + * SUBTEST: boundary-split
> + * Description: Test case to trigger PRL generation beyond a page size alignment
> + *      to ensure correct handling of PRL entries that span page size boundaries.
> + */
> +static void test_boundary_split(int fd)
> +{
> +	struct xe_prl_stats stats_before, stats_after, expected_stats = { 0 };
> +	/* Dangle a page past the boundary with a combination of address offset and size */
> +	uint64_t size_boundary = 64 * SZ_2M + SZ_4K;
> +	uint64_t addr = (1ull << 30) + 64 * SZ_2M;
> +
> +	expected_stats.prl_4k_entry_count = 1;
> +	expected_stats.prl_64k_entry_count = 0;
> +	expected_stats.prl_2m_entry_count = 64;
> +	expected_stats.prl_issued_count = 1;
> +	expected_stats.prl_aborted_count = 0;
> +
> +	stats_before = get_prl_stats(fd, 0);
> +	test_vma_ranges_list(fd, &(uint64_t){size_boundary}, 1, addr);
> +	stats_after = get_prl_stats(fd, 0);
> +	compare_prl_stats(&stats_before, &stats_after, &expected_stats);
> +}
> +
> +/**
> + * SUBTEST: binds-1g-partial
> + * Description: Bind a 1G VMA and a 2M VMA into a VM and unbind only
> + *      the 1G range to verify that decomposing a 1G mapping into its
> + *      constituent 2M PRL entries overflows the PRL capacity limit,
> + *      triggering a full TLB invalidation fallback (aborted PRL) instead
> + *      of a targeted page reclaim list flush.
> + */
> +static void test_binds_1g_partial(int fd)
> +{
> +	struct xe_prl_stats stats_before, stats_after, expected_stats = { 0 };
> +
> +	uint64_t sizes[]   = { SZ_1G, SZ_2M };
> +	uint64_t offsets[] = { 0, SZ_1G };
> +	int count = ARRAY_SIZE(sizes);
> +
> +	expected_stats.prl_4k_entry_count = 0;
> +	expected_stats.prl_64k_entry_count = 0;
> +	expected_stats.prl_2m_entry_count = 0;
> +	expected_stats.prl_issued_count = 0;
> +	expected_stats.prl_aborted_count = 1;
> +
> +	stats_before = get_prl_stats(fd, 0);
> +	vma_range_list_with_unbind_and_offsets(fd, sizes, count, (1ull << 30), SZ_1G + SZ_2M, offsets);
> +	stats_after = get_prl_stats(fd, 0);
> +
> +	compare_prl_stats(&stats_before, &stats_after, &expected_stats);
> +}
> +
> +int igt_main()
> +{
> +	int fd;
> +	/* Buffer to read debugfs entries boolean */
> +	char buf[16] = {0};
> +
> +	igt_fixture() {
> +		fd = drm_open_driver(DRIVER_XE);
> +
> +		igt_require_f(igt_debugfs_exists(fd, "page_reclaim_hw_assist", O_RDONLY),
> +			      "Page Reclamation feature is not supported.\n");
> +
> +		igt_debugfs_read(fd, "page_reclaim_hw_assist", buf);
> +		igt_require_f(buf[0] == '1',
> +			      "Page Reclamation feature is not enabled.\n");
> +
> +		igt_require_f(xe_gt_stats_get_count(fd, 0, "prl_4k_entry_count") >= 0,
> +			      "gt_stats is required for Page Reclamation tests.\n");
> +	}
> +
> +	igt_subtest("basic-mixed")
> +		test_vma_ranges_basic_mixed(fd);
> +
> +	igt_subtest("prl-invalidate-full")
> +		test_vma_ranges_prl_entries(fd, OVERFLOW_PRL_SIZE, 0, 1);
> +
> +	igt_subtest("prl-max-entries")
> +		test_vma_ranges_prl_entries(fd, OVERFLOW_PRL_SIZE - 1, 1, 0);
> +
> +	igt_subtest("many-vma-same-bo")
> +		test_vma_ranges_many_vma_same_bo(fd, SZ_4K, 16);
> +
> +	igt_subtest("pde-vs-pd")
> +		test_vma_ranges_pde_vs_pd(fd);
> +
> +	igt_subtest("invalid-1g")
> +		test_vma_range_invalid_1g(fd);
> +
> +	igt_subtest("boundary-split")
> +		test_boundary_split(fd);
> +
> +	igt_subtest("binds-1g-partial")
> +		test_binds_1g_partial(fd);
> +
> +	igt_fixture()
> +		drm_close_driver(fd);
> +}
> diff --git a/tests/meson.build b/tests/meson.build
> index 26d9345ec..2637033ea 100644
> --- a/tests/meson.build
> +++ b/tests/meson.build
> @@ -321,6 +321,7 @@ intel_xe_progs = [
>   	'xe_noexec_ping_pong',
>           'xe_non_msix',
>   	'xe_oa',
> +	'xe_page_reclaim',
Reviewed-by: Xin Wang <x.wang@intel.com>
>   	'xe_pat',
>   	'xe_peer2peer',
>   	'xe_pm',