Synergizing heterogeneous backend devices with reusability-aware page offloading
PagePilot is a Linux kernel research prototype that makes page placement across heterogeneous swap backends aware of page reuse. It targets systems with a small, low-latency swap backend and a larger, slower backend—for example, ZRAM plus an NVMe swap partition.
Linux normally allocates swap space according to static device priorities. Under memory pressure, this can leave cold pages occupying the fast backend while frequently refaulted pages are served by the slow backend. PagePilot instead preserves reuse history across eviction/refault cycles, routes pages using their observed refault distance, and corrects stale placements in the background.
This repository contains the artifact snapshot used by the PagePilot paper. It is based on Linux 6.3.5 with XanMod's -xanmod1 patch level and currently supports two swap-backend tiers.
Warning
PagePilot is a research prototype, not a production kernel. Kernel installation, swap-device setup, and mkswap can make a machine unbootable or destroy data. Use a disposable test machine with a serial console or another recovery path, and never run mkswap on a device containing valuable data.
PagePilot consists of three cooperating components:
- Offloading Tracer preserves per-page eviction timestamps, refault counts, and average refault distance across repeated eviction/refault cycles.
- Offloading Router uses the recorded average refault distance to send pages with evidence of near-term reuse to the fast backend and other pages to the slow backend.
- Backend Migrator scans the fast backend for long-resident pages and asynchronously moves them to the slow backend. An indirect, versioned swap-entry mapping lets migration proceed without scanning and rewriting every page table that references the old entry.
The router changes only the destination of a page already selected for eviction. It does not replace Linux's victim-selection policy and is designed to remain compatible with mechanisms such as MGLRU and DAMON-based reclaim.
The paper evaluates PagePilot with Redis/YCSB, Memcached/YCSB, and HNSW/BIGANN on Ubuntu Server 22.04.5 using ZRAM as the fast backend and NVMe as the slow backend. Across 40 workload/memory configurations, PagePilot reports:
- 15.5% geometric-mean throughput improvement over the unmodified Linux baseline, with a maximum of 68.7%;
- 13.4% geometric-mean reduction in end-to-end completion time;
- 10.8% geometric-mean reduction in refault latency, with a maximum of 45.5%; and
- higher throughput than iSwap in 37 of 40 configurations, with a 23.6% geometric-mean advantage.
These numbers describe the paper's testbed and should not be interpreted as universal performance guarantees.
| Path | Role |
|---|---|
mm/workingset.c |
Refault tracking and persistent shadow-entry history |
mm/swap_slots.c |
Fast/slow swap-slot caches and routing-aware allocation |
mm/swapfile.c |
Backend-priority tracking, versioned slots, and migration mappings |
mm/swap_state.c |
Swap-in path, migration I/O, and PagePilot sysfs controls |
mm/vmscan.c |
Router policy, automatic threshold adjustment, and migrator triggering |
mm/swap_scan_slot.c |
Candidate queue and fast-backend scan control |
include/linux/swap*.h |
PagePilot swap data structures and interfaces |
mm/Kconfig |
Build-time PagePilot feature switches |
The following example builds the broadly compatible x86-64-v1 configuration. Select the v2, v3, or v4 preset only when the target CPU supports that x86-64 microarchitecture level.
On Ubuntu 22.04, install the usual kernel build dependencies:
sudo apt update
sudo apt install build-essential bc bison flex libelf-dev libncurses-dev libssl-dev dwarvesConfigure PagePilot:
cp CONFIGS/xanmod/gcc/config_x86-64-v1 .config
scripts/config --enable CONFIG_SWAP
scripts/config --module CONFIG_ZRAM
scripts/config --module CONFIG_ZSMALLOC
scripts/config --enable CONFIG_CGROUPS
scripts/config --enable CONFIG_MEMCG
scripts/config --enable CONFIG_DEBUG_FS
scripts/config --enable CONFIG_LRU_GEN
scripts/config --enable CONFIG_LRU_GEN_ENABLED
scripts/config --enable CONFIG_LRU_GEN_SHADOW_ENTRY_EXT
scripts/config --enable CONFIG_LRU_GEN_KEEP_REFAULT_HISTORY
scripts/config --enable CONFIG_LRU_GEN_SHADOW_ENTRY_REF_CTRL
scripts/config --enable CONFIG_LRU_GEN_SWAP_ROUTER
scripts/config --enable CONFIG_LRU_GEN_STALE_SWP_ENTRY_SAVIOR
# Keep measurement instrumentation off for normal experiments.
scripts/config --disable CONFIG_PAGEPILOT_OVERHEAD_STAT
make olddefconfig
make -j"$(nproc)"Install the kernel using the procedure appropriate for your distribution. On a conventional Ubuntu test machine this is typically:
sudo make modules_install
sudo make installConfirm that the bootloader has a known-good fallback kernel before rebooting. After boot, verify the kernel release with uname -r; it should identify the 6.3.5 XanMod-based build.
PagePilot identifies the backend with the highest swapon priority as the fast tier and the backend with the lowest priority as the slow tier. The Backend Migrator additionally requires the fast backend to advertise synchronous I/O; ZRAM is the configuration evaluated in the paper.
Create and activate a ZRAM fast tier. Adjust 4G for the experiment:
sudo modprobe zram num_devices=1
sudo zramctl /dev/zram0 --size 4G
sudo mkswap /dev/zram0
sudo swapon --priority 100 /dev/zram0Prepare a dedicated slow swap partition separately, then activate it at a lower priority. Replace the placeholder with the actual dedicated swap device:
sudo swapon --priority 10 /dev/disk/by-id/<dedicated-swap-device>
cat /proc/swaps/proc/swaps should show exactly the intended fast and slow backends with different priorities. For paper-style experiments, size the ZRAM tier to approximately 10% of the application's memory footprint.
Mount debugfs if it is not already mounted:
sudo mount -t debugfs none /sys/kernel/debugThe runtime modes are:
| Mode | Router | Migrator |
|---|---|---|
| Linux-style baseline | 0 | 0 |
| Router only | 1 | 0 |
| Full PagePilot | 1 | 1 |
Enable the full system:
printf '1\n' | sudo tee /sys/kernel/debug/clever_swap_alloc
printf '1\n' | sudo tee /sys/kernel/debug/swap_scan_savior_enabled
printf '1\n' | sudo tee /sys/kernel/mm/swap/swap_scan_enabledDisable both components for a baseline run:
printf '0\n' | sudo tee /sys/kernel/debug/clever_swap_alloc
printf '0\n' | sudo tee /sys/kernel/debug/swap_scan_savior_enabledRouter and migrator thresholds can be inspected or changed through /sys/kernel/mm/swap/:
cat /sys/kernel/mm/swap/router_auto_adjust
cat /sys/kernel/mm/swap/current_router_distance
cat /sys/kernel/mm/swap/current_migrator_distanceThe automatic router adjustment is enabled by default. All utilization watermarks exposed in this directory are expressed in parts per thousand. Keep the settings fixed across systems being compared, clear filesystem caches consistently when appropriate, and repeat each workload enough times to report variance.
Optional sampled overhead instrumentation can be enabled at build time with CONFIG_PAGEPILOT_OVERHEAD_STAT=y. Its counters are then available at /sys/kernel/debug/pagepilot_overhead; the option should remain disabled for normal performance measurements.
This snapshot contains the modified kernel source. The workload harnesses, BIGANN dataset, prebuilt HNSW index, and raw evaluation results are not included. The paper's reference testbed used an Intel Xeon Gold 6442Y CPU, 256 GiB of DDR5 memory, a 4 TB M.2 NVMe SSD, and Ubuntu Server 22.04.5.
If PagePilot is useful in your research, please cite the manuscript:
@misc{liu2026pagepilot,
title = {PagePilot: Synergizing Heterogeneous Backend Devices with
Reusability-Aware Page Offloading},
author = {Liu, Xingze and Dong, Jialin and Liu, Xinyu and Wang, Lizhi and
Li, Haoran and Gong, Xiaoli and Zhang, Jin and Li, Shiyang and
Yew, Pen-Chung},
year = {2026},
note = {Manuscript}
}Replace this entry with the archival venue citation when the paper is published.
This repository is a modified Linux kernel source tree. The kernel is provided under GPL-2.0; individual files may carry compatible SPDX identifiers and additional terms. See COPYING and LICENSES/ for details. Existing copyright and attribution notices are retained.