kvcache-ai/firecracker

Fork 0

mirror of https://github.com/kvcache-ai/firecracker.git synced 2026-11-05 01:17:43 +00:00

[PR #20] [MERGED] release: prepare v1.15.1-patch-v2 #20

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/20
Author: @Hygge-Gezelligheid
Created: 8/25/2026
Status: ✅ Merged
Merged: 8/26/2026
Merged by: @huang-jl

Base: v1.15.1-patch ← Head: agent/v1.15.1-patch-v2

📝 Commits (4)

96ea95f release: prepare v1.15.1-patch-v2
91d2509 feat: expose guest physical addresses for memory regions
1881cbd chore: add aarch64 v2 candidate
9f50bed chore: remove aarch64 candidate artifact

📊 Changes

11 files changed (+61 additions, -24 deletions)

View changed files

📝 CHANGELOG.md (+10 -0)
📝 Cargo.lock (+6 -6)
📝 src/cpu-template-helper/Cargo.toml (+1 -1)
📝 src/firecracker/Cargo.toml (+1 -1)
📝 src/firecracker/src/api_server/parsed_request.rs (+1 -0)
📝 src/firecracker/swagger/firecracker.yaml (+12 -4)
📝 src/jailer/Cargo.toml (+1 -1)
📝 src/rebase-snap/Cargo.toml (+1 -1)
📝 src/seccompiler/Cargo.toml (+1 -1)
📝 src/snapshot-editor/Cargo.toml (+1 -1)
📝 src/vmm/src/persist.rs (+26 -8)

📄 Description

Summary

Prepare the 1.15.1-patch-v2 release candidate on the AgentENV-compatible Firecracker 1.15.1 line. This PR adds the minimal guest-physical-address region API required to translate Firecracker mincore/snapshot-image offsets to GPAs without assuming a contiguous x86 memory layout. It does not change snapshot serialization or snapshot data format.

Why 1.15.1, not 1.16.1

The withdrawn v1.16.1-patch-v1 line is not suitable for AgentENV: Firecracker 1.16 changed snapshot data format semantics relative to AgentENV's current 1.15.1 snapshot chain. This PR deliberately remains on the downstream 1.15.1 line and contains no 1.16-only adaptation commits.

Base, commits, and scope

Base: origin/v1.15.1-patch at dcb1186cf03649783ffafc75fdeb93ffa3f21dbb
Release-version commit: 96ea95f0cb2d8973e0286e6736dbfbc1d2c611a8
GPA implementation head: 91d2509ad2718914254d950c002cd929a90a3a3b
Final PR head: 1881cbda056fe9641310b326e06b03c8e02ca934 (chore: add aarch64 v2 candidate)
Compared with immutable aenv-deps@90288c397d6d3fa576f9d367d997bdeebf835f10, the base adds only merged PR #18: paused-only PUT /vm/pre-fault-memory, VMM/vCPU KVM pre-fault handling, Swagger definitions/parser coverage, x86_64/aarch64 seccomp allowlist entries, and VMM/integration tests.
The older aenv-deps asset already contains direct drive (O_DIRECT), dirty guest-memory ranges, optional snapshot memory-file handling, and the initial guest-memory-regions API.
This PR keeps the six workspace versions, Cargo.lock, Swagger info.version, and CHANGELOG at 1.15.1-patch-v2; additionally, GET /vm/guest-memory-regions now returns required guest_phys_addr.

GPA API

GuestRegionUffdMapping now exposes guest_phys_addr, populated from each guest memory region's actual start address. offset remains the contiguous snapshot-image layout offset; GPA preserves physical gaps such as the x86 MMIO hole. The mapping unit test explicitly models a region at 4 GiB while its image offset follows a first, low-memory region. Swagger marks the field required and documents the distinct semantics.

The UFFD handshake is JSON with no deny_unknown_fields on the existing receiver model, so older receivers ignore this additive field. No UFFD protocol behavior was otherwise changed.

Snapshot compatibility evidence

SNAPSHOT_VERSION remains 9.0.0.
GPA is an API/UFFD-handshake response field; it is not part of MicrovmState snapshot serialization.
src/vmm/src/persist.rs persistence/snapshot logic and src/vmm/src/snapshot/mod.rs data format logic are unchanged from aenv-deps except for the additive runtime mapping metadata.
Built x86_64 binaries confirm aenv-deps reports v1.15.1-patch-v1 / --snapshot-version v9.0.0, while this PR reports v1.15.1-patch-v2 / --snapshot-version v9.0.0.

Validation

Re-run on final GPA head:

git diff --check
cargo check --workspace
official ./tools/devtool -y checkbuild --all for x86_64 and aarch64
GPA mapping test (including 4 GiB/MMIO-hole layout): 1 passed
UFFD handshake serialization test: 1 passed
API parser tests: 39 passed
Swagger/OpenAPI validator: passed
pre-fault VMM unit tests: 9 passed
snapshot unit tests: 12 passed; matching snapshot integration tests: 4 passed
seccomp filter behavior validation: 1 passed
x86_64 musl release build: both required binaries are static-PIE, firecracker --version is Firecracker v1.15.1-patch-v2, --snapshot-version is v9.0.0, and the archive contains only firecracker and cpu-template-helper

Supplemental pre-GPA validation retained from the release-only commit:

Firecracker lib tests: 79 passed
PR #18 pre-fault integration cases all passed

Candidate artifact

firecracker-1.15.1-patch-v2-x86_64.tgz
SHA-256: 86888330747b6c200883dc8bd2d44204d42a3a5dc24da85a1861abf331f5ea2a
firecracker-1.15.1-patch-v2-aarch64.tgz
SHA-256: 9d4a0d1582272745d9482ee05cb7753803896da548b4a5692101a919d8bc4cf6

The aarch64 artifact was built from GPA implementation head 91d2509ad2718914254d950c002cd929a90a3a3b in public.ecr.aws/firecracker/fcuvm:v88 with the documented musl-dev:arm64 cross layer. The image supplied the installed Rust aarch64-unknown-linux-musl target, aarch64-linux-musl-gcc, and aarch64-linux-gnu-ar; the build explicitly set its linker, CC, AR, and arm64 C include flags. file and aarch64-linux-gnu-readelf confirm both archive binaries are ELF64/AArch64, statically linked, with no INTERP program header and no dynamic section. The archive contains exactly firecracker and cpu-template-helper.

Per explicit review direction, this statically verified aarch64 .tgz and its checksum are committed in candidates/91d2509ad/ by final PR head 1881cbda056fe9641310b326e06b03c8e02ca934, so reviewers can inspect the exact candidate bytes. It is a PR review candidate only: no tag or GitHub Release asset has been created.

Known limitations / release gates

cargo fmt --check reports six pre-existing formatting differences outside this PR; they were deliberately not reformatted.
Full VMM lib suite has pre-existing shared-metric, nested-KVM/TSC, and TAP-contention failures; targeted GPA, snapshot, and pre-fault tests above passed.
The temporary test source is an archive, not a Git checkout. Git-dependent checkstyle portions cannot run there; the standalone Swagger validator passed.
No real persisted AgentENV/aenv-deps snapshot file was available for an old-file restore; source/data-version evidence and snapshot tests are recorded above.
The aarch64 musl artifact is built and statically inspected. The server has no ARM64 binfmt/QEMU, so direct ARM --version execution and native ARM64/KVM runtime validation were not executed. Per review direction, they are outside this PR's required candidate validation scope; cross-compilation is not represented as native runtime evidence.

Release status

No tag or Release has been created, moved, modified, or published. The existing aenv-deps tag is untouched. This remains a Draft PR pending review and explicit authorization.

_{🔄 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/20 **Author:** [@Hygge-Gezelligheid](https://github.com/Hygge-Gezelligheid) **Created:** 8/25/2026 **Status:** ✅ Merged **Merged:** 8/26/2026 **Merged by:** [@huang-jl](https://github.com/huang-jl) **Base:** `v1.15.1-patch` ← **Head:** `agent/v1.15.1-patch-v2` --- ### 📝 Commits (4) - [`96ea95f`](https://github.com/kvcache-ai/firecracker/commit/96ea95f0cb2d8973e0286e6736dbfbc1d2c611a8) release: prepare v1.15.1-patch-v2 - [`91d2509`](https://github.com/kvcache-ai/firecracker/commit/91d2509ad2718914254d950c002cd929a90a3a3b) feat: expose guest physical addresses for memory regions - [`1881cbd`](https://github.com/kvcache-ai/firecracker/commit/1881cbda056fe9641310b326e06b03c8e02ca934) chore: add aarch64 v2 candidate - [`9f50bed`](https://github.com/kvcache-ai/firecracker/commit/9f50bedd7286b5db8c17b67a6e12cffe9444dee7) chore: remove aarch64 candidate artifact ### 📊 Changes **11 files changed** (+61 additions, -24 deletions) <details> <summary>View changed files</summary> 📝 `CHANGELOG.md` (+10 -0) 📝 `Cargo.lock` (+6 -6) 📝 `src/cpu-template-helper/Cargo.toml` (+1 -1) 📝 `src/firecracker/Cargo.toml` (+1 -1) 📝 `src/firecracker/src/api_server/parsed_request.rs` (+1 -0) 📝 `src/firecracker/swagger/firecracker.yaml` (+12 -4) 📝 `src/jailer/Cargo.toml` (+1 -1) 📝 `src/rebase-snap/Cargo.toml` (+1 -1) 📝 `src/seccompiler/Cargo.toml` (+1 -1) 📝 `src/snapshot-editor/Cargo.toml` (+1 -1) 📝 `src/vmm/src/persist.rs` (+26 -8) </details> ### 📄 Description ## Summary Prepare the 1.15.1-patch-v2 release candidate on the AgentENV-compatible Firecracker 1.15.1 line. This PR adds the minimal guest-physical-address region API required to translate Firecracker mincore/snapshot-image offsets to GPAs without assuming a contiguous x86 memory layout. It does not change snapshot serialization or snapshot data format. ## Why 1.15.1, not 1.16.1 The withdrawn v1.16.1-patch-v1 line is not suitable for AgentENV: Firecracker 1.16 changed snapshot data format semantics relative to AgentENV's current 1.15.1 snapshot chain. This PR deliberately remains on the downstream 1.15.1 line and contains no 1.16-only adaptation commits. ## Base, commits, and scope - Base: `origin/v1.15.1-patch` at `dcb1186cf03649783ffafc75fdeb93ffa3f21dbb` - Release-version commit: `96ea95f0cb2d8973e0286e6736dbfbc1d2c611a8` - GPA implementation head: `91d2509ad2718914254d950c002cd929a90a3a3b` - Final PR head: `1881cbda056fe9641310b326e06b03c8e02ca934` (`chore: add aarch64 v2 candidate`) - Compared with immutable `aenv-deps@90288c397d6d3fa576f9d367d997bdeebf835f10`, the base adds only merged PR #18: paused-only `PUT /vm/pre-fault-memory`, VMM/vCPU KVM pre-fault handling, Swagger definitions/parser coverage, x86_64/aarch64 seccomp allowlist entries, and VMM/integration tests. - The older aenv-deps asset already contains direct drive (`O_DIRECT`), dirty guest-memory ranges, optional snapshot memory-file handling, and the initial guest-memory-regions API. - This PR keeps the six workspace versions, Cargo.lock, Swagger `info.version`, and CHANGELOG at `1.15.1-patch-v2`; additionally, `GET /vm/guest-memory-regions` now returns required `guest_phys_addr`. ## GPA API `GuestRegionUffdMapping` now exposes `guest_phys_addr`, populated from each guest memory region's actual start address. `offset` remains the contiguous snapshot-image layout offset; GPA preserves physical gaps such as the x86 MMIO hole. The mapping unit test explicitly models a region at 4 GiB while its image offset follows a first, low-memory region. Swagger marks the field required and documents the distinct semantics. The UFFD handshake is JSON with no `deny_unknown_fields` on the existing receiver model, so older receivers ignore this additive field. No UFFD protocol behavior was otherwise changed. ## Snapshot compatibility evidence - `SNAPSHOT_VERSION` remains `9.0.0`. - GPA is an API/UFFD-handshake response field; it is not part of `MicrovmState` snapshot serialization. - `src/vmm/src/persist.rs` persistence/snapshot logic and `src/vmm/src/snapshot/mod.rs` data format logic are unchanged from aenv-deps except for the additive runtime mapping metadata. - Built x86_64 binaries confirm `aenv-deps` reports `v1.15.1-patch-v1` / `--snapshot-version v9.0.0`, while this PR reports `v1.15.1-patch-v2` / `--snapshot-version v9.0.0`. ## Validation Re-run on final GPA head: - `git diff --check` - `cargo check --workspace` - official `./tools/devtool -y checkbuild --all` for x86_64 and aarch64 - GPA mapping test (including 4 GiB/MMIO-hole layout): 1 passed - UFFD handshake serialization test: 1 passed - API parser tests: 39 passed - Swagger/OpenAPI validator: passed - pre-fault VMM unit tests: 9 passed - snapshot unit tests: 12 passed; matching snapshot integration tests: 4 passed - seccomp filter behavior validation: 1 passed - x86_64 musl release build: both required binaries are static-PIE, `firecracker --version` is `Firecracker v1.15.1-patch-v2`, `--snapshot-version` is `v9.0.0`, and the archive contains only `firecracker` and `cpu-template-helper` Supplemental pre-GPA validation retained from the release-only commit: - Firecracker lib tests: 79 passed - PR #18 pre-fault integration cases all passed ## Candidate artifact - `firecracker-1.15.1-patch-v2-x86_64.tgz` - SHA-256: `86888330747b6c200883dc8bd2d44204d42a3a5dc24da85a1861abf331f5ea2a` - `firecracker-1.15.1-patch-v2-aarch64.tgz` - SHA-256: `9d4a0d1582272745d9482ee05cb7753803896da548b4a5692101a919d8bc4cf6` The aarch64 artifact was built from GPA implementation head `91d2509ad2718914254d950c002cd929a90a3a3b` in `public.ecr.aws/firecracker/fcuvm:v88` with the documented `musl-dev:arm64` cross layer. The image supplied the installed Rust `aarch64-unknown-linux-musl` target, `aarch64-linux-musl-gcc`, and `aarch64-linux-gnu-ar`; the build explicitly set its linker, CC, AR, and arm64 C include flags. `file` and `aarch64-linux-gnu-readelf` confirm both archive binaries are ELF64/AArch64, statically linked, with no `INTERP` program header and no dynamic section. The archive contains exactly `firecracker` and `cpu-template-helper`. Per explicit review direction, this statically verified aarch64 `.tgz` and its checksum are committed in `candidates/91d2509ad/` by final PR head `1881cbda056fe9641310b326e06b03c8e02ca934`, so reviewers can inspect the exact candidate bytes. It is a PR review candidate only: no tag or GitHub Release asset has been created. ## Known limitations / release gates - `cargo fmt --check` reports six pre-existing formatting differences outside this PR; they were deliberately not reformatted. - Full VMM lib suite has pre-existing shared-metric, nested-KVM/TSC, and TAP-contention failures; targeted GPA, snapshot, and pre-fault tests above passed. - The temporary test source is an archive, not a Git checkout. Git-dependent checkstyle portions cannot run there; the standalone Swagger validator passed. - No real persisted AgentENV/aenv-deps snapshot file was available for an old-file restore; source/data-version evidence and snapshot tests are recorded above. - The aarch64 musl artifact is built and statically inspected. The server has no ARM64 binfmt/QEMU, so direct ARM `--version` execution and native ARM64/KVM runtime validation were not executed. Per review direction, they are outside this PR's required candidate validation scope; cross-compilation is not represented as native runtime evidence. ## Release status No tag or Release has been created, moved, modified, or published. The existing `aenv-deps` tag is untouched. This remains a Draft PR pending review and explicit authorization. --- <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

closed this issue
added the
pull-request
label

No labels

pull-request

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

kvcache-ai/firecracker#20

No description provided.

Rows
Columns