Skip to content

Add --free-page-reporting to give freed guest memory back to the host - #122

Draft
JartX wants to merge 1 commit into
libkrun:mainfrom
JartX:free-page-reporting
Draft

JartX wants to merge 1 commit into
libkrun:mainfrom
JartX:free-page-reporting

Conversation

@JartX

@JartX JartX commented Oct 25, 2026 •

Copy link
Copy Markdown

Adds --free-page-reporting default|replace, which calls libkrun's krun_set_balloon_free_page_reporting_mode().

On macOS, libkrun's balloon madvise()s the pages the guest reports as free, which doesn't release the pages the guest has written to. A VM's footprint only grows, up to the RAM it was given, even after the guest frees the memory. libkrun can give those pages back by replacing them with fresh memory (#931 on main). This option lets krunkit, and through it Colima and Podman, turn that on.

Without the option krunkit doesn't call the function, so nothing changes. The function is newer than the rest of the libkrun API krunkit uses, so it's looked up with dlsym() only when the option is given. krunkit still starts with a libkrun that doesn't have it, and the option fails with an error that says what's missing.

Draft: this depends on libkrun/libkrun#941, which adds the function to stable-1.19.x. It can't be merged until a libkrun with it is released.

Testing: cargo test (39 passed, including two new tests), cargo clippy and cargo fmt --check are clean. With libkrun#941 (f3fec24e) built from source, I booted a 3 GiB guest through Colima with this krunkit, wrote 1.5 GiB to tmpfs and freed it:

given back to the host
--free-page-reporting replace 1364 MiB
no option 0
replace with a libkrun without the function krunkit exits: --free-page-reporting needs a libkrun with krun_set_balloon_free_page_reporting_mode()

On macOS, libkrun's balloon madvise()s the pages the guest reports as
free, which doesn't release the pages the guest has written to: a VM's
phys_footprint only grows, up to the RAM it was given, even after the
guest frees the memory. libkrun can give them back by replacing them
with fresh memory, and krun_set_balloon_free_page_reporting_mode()
selects that (KRUN_FREE_PAGE_REPORTING_MODE_REPLACE).

Add --free-page-reporting default|replace to call it. Without the
option krunkit doesn't call it, so nothing changes. The function is
newer than the rest of the libkrun API krunkit uses, so it's looked up
with dlsym() when the option is used: krunkit still starts with a
libkrun that doesn't have it, and the option fails with an error that
says so.

On a 3 GiB guest booted through Colima, writing and freeing 1.5 GiB of
tmpfs gave 1364 MiB back to the host with --free-page-reporting replace,
and 0 without it.

Assisted-by: Claude Code / claude-opus-5.5
Signed-off-by: JartX <[email protected]>
@jongwan56

Copy link
Copy Markdown

Tested this branch (9010731) with libkrun 1.19.8 from Homebrew on an M5 Max, macOS 27.2, under
Colima 0.10.3 / Lima 2.2.1 (8 GiB VM, Ubuntu 24.04 guest, kernel 6.8). The balloon negotiates
STATS_VQ, FREE_PAGE_HINT and REPORTING.

Writing 4 GiB of /dev/urandom to a guest tmpfs and deleting it, krunkit's phys_footprint
(top -stats mem):

--free-page-reporting replace official 1.3.2
before 1,376 MB 1,347 MB
after writing 5,466 MB 5,443 MB
5 s after deleting 1,990 MB 5,443 MB
30 s after deleting 1,382 MB 5,444 MB

Page cache is not returned while the guest keeps it: a 3 GiB file written to disk kept the footprint
at 7.5 GB until the file was deleted or the guest ran drop_caches.

Assisted-by: Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants