ch: hugepages auto-detect poisons snapshots against the mmap restore fast path

[CMGS]

Problem

CH VM creation still auto-enables hugepages whenever the host has them:

// hypervisor/cloudhypervisor/args.go:52
Memory: chMemory{Size: mem, HugePages: utils.DetectHugePages(), Shared: rec.Config.SharedMemory},

Consequence chain:

1. Every snapshot taken from such a VM is stamped hugepages=true in its config.json.
2. validateRestoreMode rejects --restore-mode mmap for hugepages/shared snapshots (CH would otherwise silently downgrade to eager copy), so on a hugepages-configured host the CoW mmap restore path is structurally unavailable for every golden built there.
3. All clones of those goldens are forced into eager-copy restore. Eager copy is already measured ~6x slower than mmap for a single restore (noted in restoreVM), and under a burst it turns into a guest-RAM memcpy per clone that saturates memory bandwidth — the main driver of the known burst-clone latency blowup, since extraction is already cheap (memory-range-* hardlinked, COW reflinked).

The host's hugepages configuration silently deciding guest memory policy is also a policy leak: whether a VM trades hibernate/clone-path speed for TLB benefits should be the caller's explicit choice, not an environment probe.

Precedent: #156 removed hugepages from FC entirely because FC's File restore backend cannot map hugetlbfs-backed snapshots at all. CH tolerates them (via eager copy) but pays the fast-path loss above.

Proposal

1. Drop utils.DetectHugePages() from the CH memory config; add an explicit --hugepages create flag (same shape as the existing --shared-memory, fixed for VM lifetime). Default off.
2. Companion change (separate PR candidate): default CH clones to mmap restore when the snapshot's memory config qualifies (plain private-anon — no hugepages, no shared); cloneAfterExtract already parses config.json, and the hardlinked memory-range files keep the backing inode alive for the mapping's lifetime. Explicit --restore-mode keeps overriding.

Validation plan

Testbed burst64 three-way comparison against one golden rebuilt without hugepages: eager copy vs --restore-mode mmap vs mmap + sqlite meta engine, recording per-step timings and p50/p99 clone latency, plus a hibernate/restore regression pass for hugepages goldens (must keep working via eager copy).

[CMGS]

Measured evidence for the validation plan, plus a consequence the issue undersells: on a hugepages host the cost is not only slower eager copy — it is a hard concurrency ceiling with mass clone failure.

Setup

.79 bare metal, Ryzen 7 9700X (8C/16T), cocoon master-66e4232, cloud-hypervisor v54.0.0 (d77dcf12, official dev release). CH egress-lane golden, 512 MiB guest, rt:24.04. Boundary = cocoon vm clone per op.

The concurrency cap (new — not just a slowdown)

nr_hugepages=3072 = a fixed 6144 MiB hugepage pool. Each hugepage-backed CH VM consumes its full 512 MiB from it, so exactly 6144/512 = 12 VMs fit; the 13th onward fails. 20 concurrent clones from one hugepages golden:

ok=12  fail=8  of 20
HugePages_Free after: 0        # 12 × 256 pages = 3072, pool exhausted

The failure is an opaque EFAULT from the restore, with nothing pointing at hugepages:

Error: clone VM: vm.restore: PUT http://localhost/api/v1/vm.restore → 500:
["Error from API","The VM could not be restored","Memory manager error",
 "Error copying snapshot into region","Guest memory error: Bad address (os error 14)"]

At B64 this is 12–16/64 success, ~48 failures. It stays invisible below the pool size — a 4-connection sustained loop showed 0 failures (4 ≤ 12), which is exactly why this is easy to miss until a real burst.

Burst64 three-way (the validation-plan comparison)

Same golden rebuilt per config; B64 concurrent; per-clone p50; resident = MemAvailable delta / count; exec = liveness sample.

config	ok/64	p50 clone	resident	note
hp=3072, forced eager	12–16/64	1049–1085ms*	—	*only the ~12 that fit; rest EFAULT
hp=0, --restore-mode mmap (CoW)	64/64	1151–1322ms	31 MB/VM
hp=0, default copy	64/64	2177ms	346 MB/VM

So on a hugepages host you don't get "slower clones" — above ~12 concurrent CH VMs you get clone failures. Dropping hugepages (this issue's proposal) restores 64/64, and mmap adds the 11× density win (31 vs 346 MB/VM) and ~1.8× latency win (1151 vs 2177 ms) over eager at the same concurrency.

Single-restore footnote for the "~6x slower" line: at N=1 the eager-vs-mmap gap does not reproduce as a latency win (cold cocoon vm clone→exec: copy 121ms / mmap 153ms / ondemand 135ms) — the eager copy of a page-cache-hot 512 MiB is cheap and CoW's setup has no sharing to amortize at N=1. The eager penalty is a burst / density effect (bandwidth saturation + the pool cap above), not a single-restore one. Worth keeping the proposal framed around burst + density rather than single-restore latency.

[CMGS]

Implementation plan

Design decisions (locked): explicit beats implicit everywhere — --hugepages is an explicit create-time choice, FC rejects it outright, and CH surfaces every degradation as a warning instead of deciding silently (whether the silent decider is cocoon's auto-detect or CH's internal mmap→copy fallback).

PR A — explicit flag + loud constraints

1. --hugepages create/run flag (CH only, default off), persisted on the VM config for its lifetime — same shape as --shared-memory. hypervisor/cloudhypervisor/args.go uses rec.Config.HugePages; utils.DetectHugePages() loses its last caller and is deleted.
2. FC rejects --hugepages at create with a typed error: FC's File restore backend cannot map hugetlbfs-backed snapshots, so hibernate/clone would break later (fc: never enable hugepages, they break hibernate/clone #156) — fail at the moment the user asks, not when the snapshot dies.
3. CH restore/clone warnings for hugepages/shared snapshots:
   • restoring such a snapshot warns that the mmap fast path is unavailable and memory loads via eager copy;
   • explicit --restore-mode mmap against such a snapshot becomes warn + proceed as copy (replacing today's hard reject in validateRestoreMode): the user is told CH will silently fall back to eager copy (~6x slower memory load) and how to fix it (rebuild the golden without hugepages/shared). The mode string validation (unknown mode = error) stays.
4. Docs: flag help + README note; the warning text carries the rebuild-the-golden remedy so operators can self-serve.

Behavior change to call out: on hugepages-configured hosts, newly created CH VMs no longer pick up hugepages implicitly. That is the point — opt back in with the flag.

PR B — auto-mmap for clones

Default CH clones to mmap restore when the snapshot's memory config is plain private-anon (no hugepages, no shared); explicit --restore-mode always wins. cloneAfterExtract already parses config.json, so selection is free.

Safety invariant: auto-mmap applies only where the backing memory-range files provably live in the clone's own runDir via hardlink (inode stays alive regardless of snapshot GC). The vm restore / hibernate-wake path is NOT auto-switched in PR B — it follows only after verifying its extraction gives the same runDir-owned lifetime; until then it keeps eager copy by default with --restore-mode mmap available.

Tests

• FC create with --hugepages → typed reject.
• CH args build from the persisted flag, no host probe.
• Restore-mode matrix: plain snapshot → auto mmap (clone), hugepages snapshot → copy + warn, shared → copy + warn, explicit mmap + hugepages → warn + copy, explicit copy → copy, unknown mode → error.
• Existing hugepages goldens: hibernate + restore regression must keep passing via eager copy.

Hardware validation (testbed)

burst64 three-way against one golden rebuilt without hugepages — eager copy vs auto-mmap vs auto-mmap + sqlite meta engine — recording per-step timings and p50/p99 clone latency, plus RSS per clone (mmap should share clean pages across the fleet). Numbers gate flipping anything beyond clones.