From c4d189a1c5b59816c5144a96f990b4d553829e15 Mon Sep 17 00:00:00 2001 From: JartX Date: Mon, 26 Oct 2026 14:00:26 +0100 Subject: [PATCH] docs: explain why krunkit's footprint overstates its memory use on macOS Activity Monitor shows krunkit's physical footprint, and macOS counts a page of guest memory there twice when krunkit writes it and the guest then uses it: disk reads, received packets, virtio-fs reads, and the kernel and initramfs at boot. After a guest reads a 600 MiB file, the footprint grows by about 1.2 GiB. Add a section to docs/usage.md that explains this and points to the system-wide numbers, which show what a VM really costs the host. Assisted-by: Claude Code / claude-opus-5.5 Signed-off-by: JartX --- docs/usage.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/usage.md b/docs/usage.md index a2835c3..a8ad7fa 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -279,3 +279,24 @@ The table below provides some data on how offloading effects the gvproxy and vmn | gvproxy | krunkit | false | 1.47 Gbits/s | 2.58 Gbits/s | | gvproxy | vfkit | false | 1.43 Gbits/s | 2.84 Gbits/s | + +## Measuring Memory Use on macOS + +Activity Monitor's "Memory" column, `top` and `footprint` show a process's physical footprint. For +krunkit, that number can be much larger than the memory the virtual machine really takes from the +host. + +macOS charges a page of guest memory to krunkit twice when krunkit writes it and the guest then +uses it. krunkit writes guest memory on the guest's behalf for disk reads, received network +packets, virtio-fs reads, and the kernel and initramfs at boot. The page exists only once; only the +per-process accounting counts it twice. For example, after a guest reads a 600 MiB file from its +disk, krunkit's footprint grows by about 1.2 GiB, while the guest's page cache grew by 600 MiB. When +the guest drops its page cache, both go away. + +This comes from how Hypervisor.framework's memory is accounted, not from krunkit or libkrun: a +minimal program that maps memory into a VM with `hv_vm_map()`, writes it, and has a vCPU read it +shows the same doubling (libkrun/libkrun#947). + +To see what a virtual machine really costs the host, compare system-wide numbers before and after +starting it: "Memory Used" and "Memory Pressure" in Activity Monitor's Memory tab, or `vm_stat` +(the active, inactive, wired and compressor pages).