Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
41 changes: 41 additions & 0 deletions src/cmdline.rs
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,20 @@ pub struct Args {
/// Vsock port for timesync
#[arg(long = "timesync", value_parser = parse_timesync)]
pub timesync: Option<u32>,

/// 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<u32>,
}

/// The KRUN_FREE_PAGE_REPORTING_MODE_* value for a --free-page-reporting argument.
pub fn parse_free_page_reporting(s: &str) -> Result<u32, String> {
match s {
"default" => Ok(0),
"replace" => Ok(1),
_ => Err("expected 'default' or 'replace'".to_string()),
}
}

fn parse_timesync(s: &str) -> Result<u32, String> {
Expand Down Expand Up @@ -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 =
Expand Down
29 changes: 29 additions & 0 deletions src/context.rs
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,10 @@ impl TryFrom<Args> 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,
Expand Down Expand Up @@ -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<Vec<String>>,
Expand Down