[PR #18] [MERGED] feat: add KVM pre-fault memory API #18

New issue

Closed

opened 2026-10-29 14:30:10 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:30:10 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/firecracker/pull/18
Author: @Hygge-Gezelligheid
Created: 8/12/2026
Status: ✅ Merged
Merged: 8/20/2026
Merged by: @huang-jl

Base: v1.15.1-patch ← Head: agent/kvm-pre-fault-memory

📝 Commits (4)

715f08f feat: add KVM pre-fault memory API
b1d095e refactor: streamline pre-fault memory handling
bde1d09 fix: reject hotpluggable pre-fault ranges
d1319a6 fix: gate pre-fault memory on KVM capability

📊 Changes

13 files changed (+1241 additions, -4 deletions)

View changed files

📝 CHANGELOG.md (+5 -0)
📝 resources/seccomp/aarch64-unknown-linux-musl.json (+31 -0)
📝 resources/seccomp/x86_64-unknown-linux-musl.json (+31 -0)
📝 src/firecracker/src/api_server/parsed_request.rs (+76 -0)
📝 src/firecracker/src/api_server/request/mod.rs (+1 -0)
➕ src/firecracker/src/api_server/request/prefault.rs (+14 -0)
📝 src/firecracker/swagger/firecracker.yaml (+60 -0)
📝 src/vmm/src/lib.rs (+81 -1)
📝 src/vmm/src/rpc_interface.rs (+36 -1)
📝 src/vmm/src/vstate/mod.rs (+2 -0)
➕ src/vmm/src/vstate/prefault.rs (+602 -0)
📝 src/vmm/src/vstate/vcpu.rs (+39 -2)
📝 src/vmm/tests/integration_tests.rs (+263 -0)

📄 Description

Changes

Add a paused-only PUT /vm/pre-fault-memory API accepting guest-physical address and length ranges.
Validate page alignment, checked u64 arithmetic, and full coverage by plugged KVM memory slots.
Balance page-aligned work across available vCPU threads and call KVM_PRE_FAULT_MEMORY concurrently.
Check KVM_CAP_PRE_FAULT_MEMORY on x86_64 and report aarch64 as unsupported.
Add x86_64 seccomp rules, OpenAPI definitions, unit tests, and integration tests.

Reason

This provides the Firecracker-side pre-fault primitive needed by kvcache-ai/AgentENV#125. AgentENV can later use recorded working-set ranges to establish KVM mappings before resuming a snapshot-backed microVM.

The API does not change normal boot, resume, or snapshot behavior unless explicitly called.

Validation

./tools/devtool checkbuild --all: passed for x86_64 and aarch64.
VMM integration tests: 4/4 passed.
Pre-fault unit tests: 13/13 passed.
API parser tests: 6/6 passed in each tested binary.
./tools/devtool build --release: passed; static PIE release binary.
Default-seccomp HTTP tests passed for 1 vCPU and 2 vCPUs, including repeated pre-fault, resume, pause, and snapshot operations.
Both snapshot state files were non-empty.
git diff --check, seccomp JSON parsing, and Swagger YAML parsing passed.

./tools/devtool checkstyle is not fully green because this fork lacks origin/main for gitlint and contains existing whole-repository Rust, Python, and Markdown style failures in unchanged files. The new files and changelog entry were formatted independently; unrelated baseline files were not modified.

License Acceptance

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

PR Checklist

I have read and understand CONTRIBUTING.md.
I have run tools/devtool checkbuild --all.
I have run tools/devtool checkstyle successfully (documented baseline failures above).
I have described the change, motivation, and solution.
I have updated the OpenAPI documentation.
I have mentioned the user-facing change in CHANGELOG.md.
I have tested the new functionality in unit and integration tests.
This functionality cannot be added solely in rust-vmm because it requires Firecracker API, lifecycle, vCPU coordination, and seccomp integration.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/firecracker/pull/18 **Author:** [@Hygge-Gezelligheid](https://github.com/Hygge-Gezelligheid) **Created:** 8/12/2026 **Status:** ✅ Merged **Merged:** 8/20/2026 **Merged by:** [@huang-jl](https://github.com/huang-jl) **Base:** `v1.15.1-patch` ← **Head:** `agent/kvm-pre-fault-memory` --- ### 📝 Commits (4) - [`715f08f`](https://github.com/kvcache-ai/firecracker/commit/715f08f9e9ebc8d003085365bab593df40a27095) feat: add KVM pre-fault memory API - [`b1d095e`](https://github.com/kvcache-ai/firecracker/commit/b1d095ec9406fe0f1a0db5da683d7e430501c359) refactor: streamline pre-fault memory handling - [`bde1d09`](https://github.com/kvcache-ai/firecracker/commit/bde1d0942dead5cdd6497f2d6bd7be60dc0185e7) fix: reject hotpluggable pre-fault ranges - [`d1319a6`](https://github.com/kvcache-ai/firecracker/commit/d1319a66b33018cd43bc381812771e68c17257ba) fix: gate pre-fault memory on KVM capability ### 📊 Changes **13 files changed** (+1241 additions, -4 deletions) <details> <summary>View changed files</summary> 📝 `CHANGELOG.md` (+5 -0) 📝 `resources/seccomp/aarch64-unknown-linux-musl.json` (+31 -0) 📝 `resources/seccomp/x86_64-unknown-linux-musl.json` (+31 -0) 📝 `src/firecracker/src/api_server/parsed_request.rs` (+76 -0) 📝 `src/firecracker/src/api_server/request/mod.rs` (+1 -0) ➕ `src/firecracker/src/api_server/request/prefault.rs` (+14 -0) 📝 `src/firecracker/swagger/firecracker.yaml` (+60 -0) 📝 `src/vmm/src/lib.rs` (+81 -1) 📝 `src/vmm/src/rpc_interface.rs` (+36 -1) 📝 `src/vmm/src/vstate/mod.rs` (+2 -0) ➕ `src/vmm/src/vstate/prefault.rs` (+602 -0) 📝 `src/vmm/src/vstate/vcpu.rs` (+39 -2) 📝 `src/vmm/tests/integration_tests.rs` (+263 -0) </details> ### 📄 Description ## Changes - Add a paused-only `PUT /vm/pre-fault-memory` API accepting guest-physical address and length ranges. - Validate page alignment, checked `u64` arithmetic, and full coverage by plugged KVM memory slots. - Balance page-aligned work across available vCPU threads and call `KVM_PRE_FAULT_MEMORY` concurrently. - Check `KVM_CAP_PRE_FAULT_MEMORY` on x86_64 and report aarch64 as unsupported. - Add x86_64 seccomp rules, OpenAPI definitions, unit tests, and integration tests. ## Reason This provides the Firecracker-side pre-fault primitive needed by [kvcache-ai/AgentENV#125](https://github.com/kvcache-ai/AgentENV/issues/125). AgentENV can later use recorded working-set ranges to establish KVM mappings before resuming a snapshot-backed microVM. The API does not change normal boot, resume, or snapshot behavior unless explicitly called. ## Validation - `./tools/devtool checkbuild --all`: passed for x86_64 and aarch64. - VMM integration tests: 4/4 passed. - Pre-fault unit tests: 13/13 passed. - API parser tests: 6/6 passed in each tested binary. - `./tools/devtool build --release`: passed; static PIE release binary. - Default-seccomp HTTP tests passed for 1 vCPU and 2 vCPUs, including repeated pre-fault, resume, pause, and snapshot operations. - Both snapshot state files were non-empty. - `git diff --check`, seccomp JSON parsing, and Swagger YAML parsing passed. `./tools/devtool checkstyle` is not fully green because this fork lacks `origin/main` for gitlint and contains existing whole-repository Rust, Python, and Markdown style failures in unchanged files. The new files and changelog entry were formatted independently; unrelated baseline files were not modified. ## License Acceptance By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license. ## PR Checklist - [x] I have read and understand `CONTRIBUTING.md`. - [x] I have run `tools/devtool checkbuild --all`. - [ ] I have run `tools/devtool checkstyle` successfully (documented baseline failures above). - [x] I have described the change, motivation, and solution. - [x] I have updated the OpenAPI documentation. - [x] I have mentioned the user-facing change in `CHANGELOG.md`. - [x] I have tested the new functionality in unit and integration tests. - [x] This functionality cannot be added solely in `rust-vmm` because it requires Firecracker API, lifecycle, vCPU coordination, and seccomp integration. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:30:10 +00:00