feat(uffd,fc): wire balloon free-page-reporting by ValentaTomas · Pull Request #2541 · e2b-dev/infra

ValentaTomas · 2026-05-03T01:22:55Z

Wires Firecracker balloon free-page-reporting through the template build into pkg/sandbox/fc. In the orchestrator path FPR turns on only when fcInfo.HasFreePageReporting() (FC v1.14+) AND the free-page-reporting LaunchDarkly flag are both true; cmd/create-build defaults to the FC-version-derived value and accepts an explicit --free-page-reporting override.

Depends on #2545 → #2520 — without the REMOVE-event handling from #2520, FC's madvise(MADV_DONTNEED) on balloon deflate would race in-flight pagefault workers.

cursor · 2026-05-03T01:23:01Z

PR Summary

Medium Risk
Touches Firecracker boot/device configuration and snapshot dirty/empty page accounting; regressions could cause VM start failures or incorrect memory diffs during snapshotting.

Overview
Free-page-reporting is enabled via Firecracker’s balloon device and wired from template creation/build config into sandbox/FC process startup, gated by Firecracker version (>=1.14) and the free-page-reporting feature flag.

Potential issues: enableFreePageReporting always configures a balloon (amount=0) and will hard-fail VM creation if the API/balloon device is unsupported or misbehaves; ExportPageStates returns bitmap pointers whose ownership/lifetime isn’t obvious (risk of sharing/mutation after locks are released); the updated UFFD diff logic now merges UFFD “empty” pages with Firecracker DirtyMemory, so any mismatch in how “zero-installed then written” is tracked could lead to incorrect snapshot metadata.

^{Reviewed by Cursor Bugbot for commit eedb533. Bugbot is set up for automated code reviews on this repo. Configure here.}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6faaefab87

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Read the Removed bitmap from PageTracker and emit it as DiffMetadata.Empty so REMOVE'd pages become uuid.Nil mappings in the snapshot header (read as zero on resume). Defensively AndNot the empty set out of dirty: settle drains make these disjoint in practice (Removed pages have no PTE, WP-async only sees present pages with WP cleared), but if the invariant ever breaks the guest's last intent for a Removed page is "free, read zero on restore" — so empty must win, not stale dirty content.

…e comments Receiver derives freePageReporting from FC version + LD flag and never reads cfg.GetFreePageReporting(), so the proto field was dead. Removing it also kills the noisy generated pb.go diff.

A REMOVE'd page that gets a read fault before snapshot installs zero+WP+wake. The unconditional Zero->Dirty promotion stripped it from the empty bitmap while WP-async dirty scan still excludes it (WP set, no write yet), so the page fell back to the parent layer's stale content. Keep the tracker entry as Zero for that case and let WP-async surface any later write; flip the AndNot so dirty wins over empty for written pages.

…e-reporting-integration

- DiffMetadata: settle UFFD workers before sampling FC WP-async pagemap so a Zero->Write install in flight can't escape both Dirty and Empty bitmaps. - TemplateCreate: gate freePageReporting on !hugePages. Firecracker rejects balloon device + hugepages combinations, and the v1.14 rollout would otherwise auto-enable both and abort VM creation.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a092da952a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

claude

⚠️ Code review skipped — your organization's overage spend limit has been reached.

Code review is billed via overage credits. To resume reviews, an organization admin can raise the monthly limit at claude.ai/admin-settings/claude-code.

Once credits are available, push a new commit or reopen this pull request to trigger a review.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ff748eafd3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

linear-code · 2026-05-06T10:18:35Z

ENG-3652 Add free page reporting

Remove the !hugePages guard — hugepages and balloon FPR are not mutually exclusive in Firecracker.

claude

⚠️ Code review skipped — your organization has reached its monthly code review spending cap.

An organization admin can view or raise the cap at claude.ai/admin-settings/claude-code. The cap resets at the start of the next billing period.

Once the cap resets or is raised, push a new commit or reopen this pull request to trigger a review.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is ON. A cloud agent has been kicked off to fix the reported issue. You can view the agent here.}

^{Reviewed by Cursor Bugbot for commit 14f995f. Configure here.}

Requested review again.

e2b-request-same-site-reviewers Bot assigned tvi May 3, 2026

cursor Bot reviewed May 3, 2026

View reviewed changes

Comment thread packages/shared/pkg/fcversion/sandbox_features.go

ValentaTomas mentioned this pull request May 3, 2026

uffd: add support for UFFD_EVENT_REMOVE events #1896

Closed

ValentaTomas unassigned tvi May 3, 2026

ValentaTomas force-pushed the feat/uffd-fc-free-page-reporting-integration branch from 0a2570e to 99eec35 Compare May 3, 2026 02:21

ValentaTomas mentioned this pull request May 3, 2026

feat(uffd): handle UFFD_EVENT_REMOVE; track per-page state; race-safe COPY #2520

Merged

ValentaTomas force-pushed the feat/uffd-fc-free-page-reporting-integration branch from 0fd4caf to d30e0ef Compare May 3, 2026 04:52

ValentaTomas changed the title ~~feat(uffd): wire free-page-reporting through template build to FC balloon~~ feat(uffd,fc): wire balloon free-page-reporting (auto for FC v1.14+) May 3, 2026

ValentaTomas force-pushed the feat/uffd-fc-free-page-reporting-integration branch 3 times, most recently from bf23242 to 6d4b734 Compare May 3, 2026 05:28

ValentaTomas mentioned this pull request May 3, 2026

feat(block): add Tracker with NotPresent/Dirty/Zero states #2545

Merged

ValentaTomas force-pushed the feat/uffd-remove-events-matrix branch from 68037d2 to ceec7d6 Compare May 3, 2026 07:10

ValentaTomas force-pushed the feat/uffd-fc-free-page-reporting-integration branch from d38614d to c777e5c Compare May 3, 2026 07:18

ValentaTomas force-pushed the feat/uffd-remove-events-matrix branch from ceec7d6 to 9ce0941 Compare May 3, 2026 07:36

ValentaTomas force-pushed the feat/uffd-fc-free-page-reporting-integration branch from c777e5c to 6faaefa Compare May 3, 2026 07:39

ValentaTomas marked this pull request as ready for review May 3, 2026 08:04

ValentaTomas requested review from dobrac and jakubno as code owners May 3, 2026 08:04

e2b-request-same-site-reviewers Bot assigned tvi May 3, 2026

ValentaTomas unassigned tvi May 3, 2026

chatgpt-codex-connector Bot reviewed May 3, 2026

View reviewed changes

Comment thread packages/orchestrator/pkg/sandbox/uffd/uffd.go Outdated

claude Bot reviewed May 3, 2026

View reviewed changes

Comment thread packages/orchestrator/pkg/sandbox/uffd/uffd.go Outdated

ValentaTomas force-pushed the feat/uffd-remove-events-matrix branch from 9ce0941 to 5896b7b Compare May 3, 2026 08:43

ValentaTomas force-pushed the feat/uffd-fc-free-page-reporting-integration branch from 6faaefa to 4bb8be8 Compare May 3, 2026 08:43

ValentaTomas changed the title ~~feat(uffd,fc): wire balloon free-page-reporting (auto for FC v1.14+)~~ feat(uffd,fc): wire balloon free-page-reporting May 3, 2026

ValentaTomas force-pushed the feat/uffd-fc-free-page-reporting-integration branch 2 times, most recently from 07ab37d to 4951164 Compare May 3, 2026 09:39

ValentaTomas force-pushed the feat/uffd-remove-events-matrix branch from 345f7e9 to db978d4 Compare May 3, 2026 10:22

ValentaTomas added 3 commits May 5, 2026 01:18

chore(uffd): trim comments for review

a194833

chore(template-build): trim narrating comments

8652309

ValentaTomas force-pushed the feat/uffd-fc-free-page-reporting-integration branch from 920e8ec to 7f22709 Compare May 5, 2026 08:19

claude Bot reviewed May 5, 2026

View reviewed changes

Comment thread packages/orchestrator/pkg/template/server/create_template.go

bchalios approved these changes May 5, 2026

View reviewed changes

fix(template): drop unused freePageReporting proto field, trim verbos…

9f57128

…e comments Receiver derives freePageReporting from FC version + LD flag and never reads cfg.GetFreePageReporting(), so the proto field was dead. Removing it also kills the noisy generated pb.go diff.

claude Bot reviewed May 5, 2026

View reviewed changes

Comment thread packages/orchestrator/pkg/sandbox/uffd/uffd.go Outdated

claude Bot reviewed May 5, 2026

View reviewed changes

Comment thread packages/orchestrator/pkg/sandbox/uffd/uffd.go

Comment thread packages/orchestrator/pkg/template/server/create_template.go

bchalios approved these changes May 5, 2026

View reviewed changes

bchalios reviewed May 5, 2026

View reviewed changes

Comment thread packages/orchestrator/pkg/sandbox/uffd/userfaultfd/userfaultfd.go

ValentaTomas added 2 commits May 5, 2026 13:15

Merge remote-tracking branch 'origin/main' into feat/uffd-fc-free-pag…

81f86c1

…e-reporting-integration

cla-bot Bot added the cla-signed label May 5, 2026

chatgpt-codex-connector Bot reviewed May 5, 2026

View reviewed changes

Comment thread packages/orchestrator/pkg/template/server/create_template.go Outdated

claude Bot reviewed May 5, 2026

View reviewed changes

Comment thread packages/orchestrator/pkg/sandbox/uffd/userfaultfd/userfaultfd.go

Merge branch 'main' into feat/uffd-fc-free-page-reporting-integration

ff748ea

claude Bot reviewed May 6, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed May 6, 2026

View reviewed changes

Comment thread packages/orchestrator/pkg/template/server/create_template.go Outdated

bchalios previously requested changes May 6, 2026

View reviewed changes

Comment thread packages/orchestrator/pkg/template/server/create_template.go Outdated

fix(template): allow FPR with hugepages per FC 1.14 support

14f995f

Remove the !hugePages guard — hugepages and balloon FPR are not mutually exclusive in Firecracker.

claude Bot reviewed May 6, 2026

View reviewed changes

cursor Bot reviewed May 6, 2026

View reviewed changes

Comment thread packages/orchestrator/pkg/template/server/create_template.go

ValentaTomas requested a review from bchalios May 7, 2026 06:25

Merge branch 'main' into feat/uffd-fc-free-page-reporting-integration

eedb533

ValentaTomas mentioned this pull request May 7, 2026

feat(fc): drain virtio-balloon free-page-hinting before pause #2552

Open

bchalios approved these changes May 7, 2026

View reviewed changes

Conversation

ValentaTomas commented May 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot commented May 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

linear-code Bot commented May 6, 2026

Uh oh!

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ValentaTomas commented May 3, 2026 •

edited

Loading

cursor Bot commented May 3, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading