diff --git a/docs/usage.md b/docs/usage.md index a2835c3..1b00177 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -56,6 +56,27 @@ Enable Nested Virtualization. Note: this requires an M3 or newer CPU and macOS 15+. +- `--free-page-reporting` + +What the balloon device does with the pages the guest reports as free, `default` or `replace`. + +`default`, which is what krunkit does without the option, has libkrun `madvise()` them. On macOS +this doesn't give back the pages the guest has written to, so the VM's memory footprint only grows +up to the RAM it was given, even after the guest frees it. `replace` has libkrun replace the +reported pages with fresh memory, which gives them back to the host, at the cost of a few system +calls per report. + +The guest only reports free pages if its kernel has `CONFIG_PAGE_REPORTING` and the virtio-balloon +driver, and it reports them in blocks of 2 MiB, so free memory fragmented into smaller blocks stays +in use. This requires a libkrun with `krun_set_balloon_free_page_reporting_mode()`; krunkit exits +with an error if the option is used with an older one. + +#### Example + +``` +--free-page-reporting replace +``` + #### Example This configures a virtual machine to use two vCPUs and 2048 MiB of RAM: diff --git a/src/cmdline.rs b/src/cmdline.rs index a08f3f1..0e00c7f 100644 --- a/src/cmdline.rs +++ b/src/cmdline.rs @@ -68,6 +68,20 @@ pub struct Args { /// Vsock port for timesync #[arg(long = "timesync", value_parser = parse_timesync)] pub timesync: Option, + + /// What the balloon does with the guest's free page reports: "default" madvise()s them, + /// which on macOS doesn't give back the pages the guest has written to; "replace" does. + #[arg(long = "free-page-reporting", value_parser = parse_free_page_reporting)] + pub free_page_reporting: Option, +} + +/// The KRUN_FREE_PAGE_REPORTING_MODE_* value for a --free-page-reporting argument. +pub fn parse_free_page_reporting(s: &str) -> Result { + match s { + "default" => Ok(0), + "replace" => Ok(1), + _ => Err("expected 'default' or 'replace'".to_string()), + } } fn parse_timesync(s: &str) -> Result { @@ -315,6 +329,33 @@ mod tests { assert!(super::parse_memory("").is_err()); } + #[test] + fn free_page_reporting_parse() { + assert_eq!(super::parse_free_page_reporting("default"), Ok(0)); + assert_eq!(super::parse_free_page_reporting("replace"), Ok(1)); + assert!(super::parse_free_page_reporting("Replace").is_err()); + assert!(super::parse_free_page_reporting("on").is_err()); + assert!(super::parse_free_page_reporting("").is_err()); + } + + #[test] + fn free_page_reporting_flag() { + use clap::Parser; + + let args = |extra: &[&str]| { + let mut argv = vec!["krunkit", "--cpus", "1", "--memory", "512"]; + argv.extend_from_slice(extra); + super::Args::try_parse_from(argv).map(|a| a.free_page_reporting) + }; + + assert_eq!(args(&[]).unwrap(), None); + assert_eq!( + args(&["--free-page-reporting", "replace"]).unwrap(), + Some(1) + ); + assert!(args(&["--free-page-reporting", "lazy"]).is_err()); + } + #[test] fn virtio_blk_argument_ordering() { let in_order = diff --git a/src/context.rs b/src/context.rs index eed1a6e..bba92a8 100644 --- a/src/context.rs +++ b/src/context.rs @@ -199,6 +199,10 @@ impl TryFrom for KrunContext { } } + if let Some(mode) = args.free_page_reporting { + set_balloon_free_page_reporting_mode(id, mode)?; + } + if let Some(timesync_port) = args.timesync { let vsock_config = VsockConfig { port: timesync_port, @@ -251,6 +255,31 @@ impl KrunContext { } } +/// Calls krun_set_balloon_free_page_reporting_mode(), which is newer than the rest of the libkrun +/// API that krunkit uses. It's looked up when the option is used rather than linked, so that +/// krunkit still starts with a libkrun that doesn't have it. +fn set_balloon_free_page_reporting_mode(ctx_id: u32, mode: u32) -> Result<(), anyhow::Error> { + type SetMode = unsafe extern "C" fn(u32, u32) -> i32; + extern "C" { + fn dlsym(handle: *mut std::ffi::c_void, symbol: *const c_char) -> *mut std::ffi::c_void; + } + // RTLD_DEFAULT on macOS: search every image loaded in the process. + const RTLD_DEFAULT: *mut std::ffi::c_void = -2isize as *mut std::ffi::c_void; + + let symbol = c"krun_set_balloon_free_page_reporting_mode"; + let f = unsafe { dlsym(RTLD_DEFAULT, symbol.as_ptr()) }; + if f.is_null() { + return Err(anyhow!( + "--free-page-reporting needs a libkrun with krun_set_balloon_free_page_reporting_mode()" + )); + } + let set_mode: SetMode = unsafe { std::mem::transmute(f) }; + match unsafe { set_mode(ctx_id, mode) } { + 0 => Ok(()), + e => Err(anyhow!("unable to set the free page reporting mode: {e}")), + } +} + fn set_smbios_oem_strings( ctx_id: u32, oem_strings: &Option>,