firecracker-microvm/firecracker

This system is Firecracker, a lightweight virtual machine monitor (VMM) designed to create and manage secure, ephemeral microVMs. It provides a Rust-based API for configuring and controlling virtualized environments, supporting features such as CPU and memory hotplug, snapshot persistence, and various VirtIO device backends including block, network, and memory devices. The platform includes a jailer for host isolation, seccomp-based syscall filtering for security, and a metadata service for guest configuration, all underpinned by a modular architecture for x86\_64 and aarch64 architectures.

24 changes.

This period focused on overhauling the project's testing infrastructure by migrating to a comprehensive pytest-based integration suite covering functional, performance, and security domains. Concurrently, the core codebase underwent significant architectural restructuring, including modularizing the VMM device manager, refactoring the Firecracker binary into a library, and upgrading the seccompiler to use libseccomp. These changes were supported by modernizing the development environment, updating dependencies to Rust 2024, and rewriting the CI pipeline for improved automation and analysis.

46 changes.

This period focused on restructuring the Virtual Machine Manager into a modular architecture with centralized handling for x86\_64 and aarch64 platforms. Significant work included implementing comprehensive CPU template management, rewriting VirtIO device drivers with snapshot support, and introducing a custom TCP stack for metadata services. The effort also expanded tooling for snapshot inspection, CPU configuration, and CI infrastructure to support newer kernel versions.

26 changes.

This period focused on expanding platform support by introducing a new ACPI crate for x86\_64 guests, adding VMGenID and vmclock devices for better guest awareness. It also implemented VirtIO PCI and MMIO transport layers, enabled vhost-user block support, and added dynamic memory hotplug via the virtio-mem device. Underlying these features were significant architectural refactors of the API server, PCI subsystem, and block devices to improve modularity and observability.

Users can now define custom ARM64 CPU configurations via JSON templates that explicitly declare required KVM capabilities, modify vCPU feature bitmaps, and apply bitwise filters to 32, 64, and 128-bit registers. The new \CustomCpuTemplate\ structure validates these inputs against supported register sizes and ensures that only valid KVM capabilities are requested before applying the configuration to vCPUs.

_src/vmm/src/cpu\config/aarch64 · high confidence

The VMM now generates standard ACPI tables (RSDP, XSDT, FADT, MADT, MCFG, and DSDT) for x86\_64 microVMs, allowing the guest OS to discover hardware configuration such as interrupt controllers, PCI configuration spaces, and VirtIO devices. This change introduces the \src/vmm/src/acpi\ module, which constructs these tables using the \acpi\_tables\ crate and writes them into guest memory, enabling proper hardware enumeration and power management support in the guest.

src/vmm/src/acpi · high confidence

Introduces a new \AmdCpuid\ module that implements AMD-specific CPUID normalization logic. This change adds support for handling AMD extended function entries, including topology, cache, and feature leaf updates, ensuring that virtual CPUs expose the correct CPUID data to guests running on AMD hardware.

_src/vmm/src/cpu\_config/x86\64/cpuid/amd · high confidence

The API server now exposes endpoints to manage memory and device hotplug operations. Users can configure a virtio-mem device via a new PUT request, query its status via GET, and dynamically resize it via PATCH, with all size parameters strictly bounded to u32 limits to prevent overflow. Additionally, a new endpoint allows for the hot-unplug of virtio devices by specifying their type and ID.

_src/firecracker/src/api\server/request/hotplug · high confidence

The VMM now supports both GICv2 and GICv3 interrupt controllers on ARM64, including full state serialization and restoration for VM snapshots. GICv3 includes support for the Interrupt Translation Service (ITS), allowing MSI-X interrupts to be properly saved and restored. The implementation handles distributor, CPU interface, redistributor, and ITS registers, ensuring that interrupt state is preserved across snapshots and restores.

src/vmm/src/arch/aarch64/gic · high confidence

A new static CPU template, V1N1, is now available for aarch64 virtual machines. This template masks the Neoverse-V1 CPU profile to appear as a Neoverse-N1 by disabling specific CPU features (such as SVE, SHA3, and SM3) via register modifiers. The implementation includes a hardcoded Rust definition that is verified against the corresponding JSON template to ensure consistency.

_src/vmm/src/cpu\_config/aarch64/static\_cpu\templates · high confidence

New ACPI devices VMGenID and VMclock are now available to expose virtual machine generation and clock information to the guest. VMGenID provides a 128-bit cryptographically random generation ID that changes on every new microVM creation or snapshot restore, allowing the guest to detect configuration changes. VMclock exposes host CPU-to-clock relationships and disruption markers (such as live migration events) to the guest. Both devices allocate guest memory and GSI interrupts, implement ACPI AML tables for discovery, and support state persistence via snapshot save/restore to ensure correct notification behavior after resumption.

src/vmm/src/devices/acpi · high confidence

New benchmark files have been added to the VMM benches directory to measure performance of key subsystems. The block request benchmark measures the latency of parsing block requests from descriptor chains. The CPU template benchmark measures the serialization and deserialization speed of JSON CPU configuration templates. The memory access benchmark measures page fault latency for both standard 4K pages and 2M huge pages. The queue benchmark measures the performance of virtio queue operations, including popping descriptors, iterating descriptor chains, and adding used buffers.

src/vmm/benches · high confidence

A new pseudo-device, BootTimer, has been added to the VMM's device layer to measure and log the time it takes for the guest OS to boot. This device implements a MMIO bus interface that, upon receiving a specific magic value (123) at offset 0, calculates the elapsed user and CPU time since the VMM started and logs the result in microseconds and milliseconds. This allows users to monitor boot performance metrics directly from the VMM logs.

src/vmm/src/devices/pseudo · high confidence

Introduces a new vhost-user block device implementation, allowing the virtual machine to connect to block storage via an external vhost-user process through a Unix socket. This change adds the device driver, event handling, and configuration structures for vhost-user block devices, while explicitly noting that snapshotting for this device type is not yet supported.

_src/vmm/src/devices/virtio/block/vhost\user · high confidence

The VMM now exposes Rust bindings for the vmclock ABI, enabling guest virtual machines to access high-precision time synchronization data. This change adds the \vmclock\_abi\ module under \src/vmm/src/devices/acpi/generated\, which defines the necessary constants, types, and the \vmclock\_abi\ struct (including fields for time, counters, and status flags) required to interact with the ACPI-based vmclock device.

src/vmm/src/devices/acpi/generated · high confidence

New example programs have been added to the seccomp examples directory to demonstrate syscall filtering capabilities. These include 'harmless' and 'malicious' examples that perform basic I/O operations, a 'jailer' example that applies a deserialized BPF filter before executing a target binary, and a 'panic' example that applies a filter and then triggers a panic, allowing users to observe how seccomp filters interact with different execution paths.

src/firecracker/examples/seccomp · high confidence

Users can now attach a GDB client to a running VM to inspect and debug guest code on both x86\_64 and aarch64 architectures. This change introduces a new GDB stub implementation in the VMM that exposes a Unix socket for connection, handles the GDB remote protocol via an event loop, and implements architecture-specific logic for register access, memory translation, and hardware/software breakpoint management using KVM guest debug features.

src/vmm/src/gdb · high confidence

The VMM now includes a new \dumbo\ module providing minimalist implementations of a TCP listener, TCP connection, and HTTP/1.1 server, along with helper logic for parsing and writing protocol data units (PDU). This module exposes public types for Ethernet, ARP, and IPv4 frames, as well as a \ByteBuffer\ trait for efficient buffer handling, enabling the VMM to handle basic network protocol operations internally.

src/vmm/src/dumbo · high confidence

Added a new Unix Domain Sockets backend implementation for the vsock device, enabling communication between the guest and host via AF\_UNIX sockets. This change introduces the \VsockMuxer\ to manage connection multiplexing, along with dedicated queues for handling RX packets and connection termination timers, effectively replacing or augmenting the previous vsock transport mechanism with a host-side Unix socket mediator.

src/vmm/src/devices/virtio/vsock/unix · high confidence

Added the Virtio PCI transport layer, including the \VirtioPciDevice\ implementation, common configuration state management, and PCI capability structures. This enables the VMM to expose Virtio devices to guests via the standard PCI transport mechanism, supporting device status state machine enforcement, MSI-X interrupt handling, and BAR configuration.

src/vmm/src/devices/virtio/transport/pci · high confidence

Adds a new Virtio RNG (entropy) device that provides random bytes to the guest. The implementation uses aws-lc-rs for host-side random number generation and enforces a 64 KiB cap on per-request entropy allocation to prevent excessive host memory usage from overlapping descriptor chains. It includes rate limiting for both operations and bytes, detailed metrics for monitoring entropy events and failures, and support for device state persistence (save/restore) to ensure compatibility with snapshots.

src/vmm/src/devices/virtio/rng · high confidence

A new \cpu-template-helper\ CLI tool is added to manage CPU templates. It provides commands to dump guest CPU configurations into custom template files, strip common entries from multiple templates to reduce duplication, and verify that a template is applied as intended. Additionally, it supports fingerprinting by dumping host-related information (kernel, microcode, BIOS versions) alongside the guest CPU config, and comparing two fingerprint files to detect differences in specific fields.

src/cpu-template-helper · high confidence

This change adds the \log-instrument\ crate, which provides an \\#\[instrument\]\ procedural macro that automatically emits \log::trace!\ events when a function is entered and exited. The implementation tracks the call stack per thread to produce hierarchical trace logs (e.g., \\>\>function\ on entry, \\<\<function\ on exit), aiding in debugging and performance analysis. Several example files are included to demonstrate usage with both standalone functions and struct methods.

src/log-instrument · high confidence

Added a new, simplified TCP implementation (\dumbo\) within the VMM to handle passive-open connections for the MicroVM Metadata Service (MMDS). This includes a \Connection\ struct that manages the TCP state machine (SYN, SYNACK, ESTABLISHED, FIN, RST) and an \Endpoint\ struct that wraps this connection to handle HTTP request parsing and response generation using a fixed-size receive buffer. A \TcpIPv4Handler\ manages multiple concurrent connections, enforcing limits on active connections and pending resets, and provides an interface to receive IPv4 packets and write outgoing segments. This change replaces previous ad-hoc handling with a dedicated, in-tree TCP stack optimized for the isolated microVM environment.

src/vmm/src/dumbo/tcp · high confidence

A new \snapshot-editor\ command-line tool is added to inspect and modify MicroVM snapshot files. It provides an \info\ subcommand to print the snapshot version, vCPU states, and the full MicroVM state, and an \edit-memory\ subcommand to apply a diff snapshot on top of a base memory file. On aarch64 targets, it also includes an \edit-vmstate\ subcommand to remove specific vCPU registers from the snapshot. The tool relies on the \vmm\ crate's \Snapshot\ and \MicrovmState\ types for loading and saving state.

src/snapshot-editor · high confidence

Adds a new virtio-mem device implementation in the VMM to support dynamic memory hotplug for guests. This change introduces the core device logic (device.rs), request parsing and handling for plug/unplug/state operations (request.rs), event loop integration (event\_handler.rs), and snapshot/restore persistence (persist.rs). It also includes a dedicated metrics module (metrics.rs) to track activation, queue, and plug/unplug operations, enabling users to dynamically adjust guest memory size at runtime.

src/vmm/src/devices/virtio/mem · high confidence

Adds a new virtio-pmem device implementation that allows guests to access persistent memory regions via a backing file. The device includes a rate limiter to throttle I/O events, a metrics system for monitoring per-device activity (such as activation failures and queue events), and snapshot support to save and restore device state (including configuration and rate limiter status) using bitcode serialization. It also enforces strict validation on descriptor lengths and restored memory sizes to prevent errors.

src/vmm/src/devices/virtio/pmem · high confidence

The VirtIO device subsystem now supports two distinct hardware transport mechanisms: Memory-Mapped I/O (MMIO) and Peripheral Component Interconnect (PCI). This change introduces the \MmioTransport\ struct, which implements the VirtIO MMIO specification (version 2) to handle device initialization, feature negotiation, queue configuration, and interrupt signaling via memory registers. Additionally, a generic \VirtioInterrupt\ trait and \VirtioInterruptType\ enum are defined to abstract interrupt handling, allowing both transport types to manage configuration and queue interrupts uniformly. The \mod.rs\ file exposes these new transport modules, enabling VirtIO devices to be instantiated and communicated with via either MMIO or PCI interfaces.

src/vmm/src/devices/virtio/transport · high confidence

The VMM now includes a new \cpu\_config\ module that provides the infrastructure for defining and managing custom CPU templates. This change introduces types for both static and custom CPU templates, along with serialization and deserialization utilities that support hexadecimal and binary number formats for register values. It also adds support for specifying KVM capabilities (add or remove) and applying bit-mapped filters to CPU register values, enabling users to fine-tune CPU configuration for their virtual machines.

_src/vmm/src/cpu\config · high confidence

The jailer now supports cgroupv2, allowing users to configure resource limits and parent cgroups on modern Linux systems that use the unified hierarchy, while maintaining backward compatibility with cgroupv1. Additionally, the chroot mechanism has been hardened by switching from a simple chroot to a pivot\_root operation within a new mount namespace, providing stronger isolation of the jail environment from the host system.

src/jailer · high confidence

The MicroVM Metadata Service (MMDS) now supports generating session tokens via PUT requests in MMDS v1, addressing a gap in the previous version which only supported token retrieval. Additionally, a new compatibility mode allows MMDS to operate like the EC2 Instance Metadata Service (IMDS), enabling support for EC2 IMDS-compatible custom headers and case-insensitive header matching (e.g., for X-Forwarded-For). These changes enhance interoperability with workloads expecting standard AWS metadata service behaviors.

src/vmm/src/mmds · high confidence

Added \ab\_plot.py\ and \ab\_test.py\ scripts to the \tools\ directory. \ab\_test.py\ automates A/B performance testing by running integration tests against two different binaries and performing statistical regression analysis on the resulting metrics. \ab\_plot.py\ visualizes these A/B test results, generating HTML tables and PDF reports that compare performance metrics (p50, p90) between test groups, including color-coded diff columns to highlight regressions or improvements.

tools · high confidence

The VMM now includes a new \dumbo/pdu\ module that provides safe, zero-copy parsing and writing for Ethernet frames, ARP requests/replies, IPv4 packets, and TCP segments. This library introduces strict validation for protocol headers, including IPv4 checksum verification, TCP MSS option bounds checking, and segment length limits constrained by the IPv4 total length field, ensuring that malformed or oversized network packets are rejected before processing.

src/vmm/src/dumbo/pdu · high confidence

The \src/firecracker/examples/uffd\ directory now includes three new example programs: \on\_demand\_handler.rs\, \fault\_all\_handler.rs\, and \malicious\_handler.rs\. These examples demonstrate how to implement a userspace page fault handler (UFFD) for Firecracker, supporting both on-demand page loading and bulk faulting strategies, along with utilities for handling balloon device interactions and error scenarios.

src/firecracker/examples/uffd · high confidence

A new \acpi-tables\ crate has been introduced to provide a library for constructing and serializing ACPI System Descriptor Tables (SDTs) into guest memory. This library exposes modules for key ACPI structures including the Root System Description Pointer (RSDP), Extended System Description Table (XSDT), Differentiated System Description Table (DSDT), Fixed ACPI Description Table (FADT), Multiple APIC Description Table (MADT), and the Memory Mapped Configuration (MCFG) table. It also includes an AML (ACPI Machine Language) bytecode generation module for building ACPI object definitions. The implementation handles table headers, checksums, and guest memory writes, enabling the platform to expose standard ACPI hardware description data to the guest OS.

src/acpi-tables · high confidence

Introduces a new CLI tool in src/clippy-tracing that automates the addition, removal, and verification of \tracing::instrument\ attributes across Rust source files. Users can now run the tool to check if all functions are instrumented, automatically add the attributes to uninstrumented functions, or strip existing instrumentation, with support for custom suffixes, cfg\_attr conditions, and path exclusions.

src/clippy-tracing/src · high confidence

This change introduces a comprehensive set of pre-built Linux kernel configuration files for Firecracker microVMs, covering architectures aarch64 and x86\_64 across kernel versions 5.10, 6.1, and 6.18. It also adds specialized configuration profiles for CI testing (ci.config), debugging (debug.config), and tracing (ftrace.config), along with a new disclaimer document explaining the design trade-offs for high-density ephemeral workloads and a dedicated NVMe driver configuration.

_resources/guest\configs · high confidence

The VMM now includes dedicated modules for managing io\_uring submission and completion queues. This change introduces \SubmissionQueue\ and \CompletionQueue\ structs that handle memory-mapped ring buffers for submitting I/O operations and retrieving results, respectively. It also adds supporting utilities for memory mapping (\mmap.rs\) and defines specific error types (\SQueueError\, \CQueueError\) for these operations, replacing previous ad-hoc handling with a structured, module-based approach under \src/vmm/src/io\_uring/queue\.

_src/vmm/src/io\uring/queue · high confidence

The VMM now includes new implementations for legacy devices in the \src/vmm/src/devices/legacy\ module, specifically the i8042 PS/2 controller, the PL031 RTC (on AArch64), and the UART serial device. These devices expose aggregated metrics (errors, read/write counts, dropped bytes) for observability. The serial device specifically supports rate-limited output to prevent host resource exhaustion and allows redirecting guest serial output to a file, in addition to the default stdout or sink destinations.

src/vmm/src/devices/legacy · high confidence

The VMM now includes dedicated utilities for network address management. A new \MacAddr\ type has been added to \src/vmm/src/utils/net/mac.rs\, providing parsing, serialization, and deserialization support for MAC addresses, enabling consistent handling of network interface identifiers. Additionally, \src/vmm/src/utils/net/ipv4addr.rs\ introduces a validation function to check if an IPv4 address is compliant with RFC 3927 link-local standards, ensuring that only valid link-local addresses are accepted in network configurations.

src/vmm/src/utils/net · high confidence

A new \resources/rebuild.sh\ script has been added to automate the build process for CI artifacts. It handles installing dependencies (including Go), cloning the Amazon Linux kernel repository, applying version-specific patches, and compiling guest kernels for x86\_64 and aarch64 architectures. The script also supports building custom initramfs images with boot-time reporting and preparing the CI rootfs overlay.

resources · high confidence

The rootfs overlay now includes new systemd unit files (fcnet.service, var-lib-systemd.mount) and helper binaries (devmemread, fast\_page\_fault\_helper, fcnet-setup.sh, fillmem, go\_sdk\_cred\_provider, init, readmem) to support network configuration, memory testing, and boot signaling. Additionally, dedicated setup scripts (setup-al2023-ci.sh, setup-ubuntu-ci.sh) define the package installation and system configuration for building CI rootfs images on Amazon Linux 2023 and Ubuntu, respectively.

resources/rootfs · high confidence

The VMM now includes hardcoded static CPU templates for the C3, T2, T2A, T2CL, and T2S instance families. These templates define specific CPUID leaf modifiers to mask exposed CPU features, ensuring that virtual machines match the instruction set and architectural capabilities of their corresponding physical AWS instances. The T2A and T2CL templates are specifically configured to provide instruction set parity with Intel Cascade Lake and later, while the T2S template is designed to support secure snapshot migration between Intel Skylake and Cascade Lake hosts.

_src/vmm/src/cpu\_config/x86\_64/static\_cpu\templates · high confidence

The VMM module now includes a new \test\_utils\ module providing helper functions for creating \GuestMemoryMmap\ instances (single or multi-region, with or without dirty page tracking) and factory functions for building \Vmm\ instances with configurable options such as PCI and memory hotplug support. This centralizes test setup logic for microVM creation and memory management in the VMM layer.

_src/vmm/src/test\utils · high confidence

Added a new testing tool in tools/test-popular-containers that builds and validates Firecracker microVMs using root filesystems from popular Linux distributions (Amazon Linux 2023, Alpine, Ubuntu 22.04, 24.04, and 25.04). The tool automates the creation of minimal rootfs images with SSH and networking support, and runs integration tests to verify that Firecracker can successfully boot and operate within these environments.

tools/test-popular-containers · high confidence

The VMM now includes a new \utils\ module providing core helper functions and types. This adds a \Version\ struct for compact, comparable version encoding (major.minor.patch), and \align\_up\/\align\_down\ macros for memory alignment. It also introduces \open\_file\_nonblock\ to safely open files (including FIFOs) with \O\_NONBLOCK\ to prevent blocking, and \byte\_order\ functions for reading/writing integers in little/big endian formats. Additionally, it exposes \sigrtmin\ and \sigrtmax\ for real-time signal handling.

src/vmm/src/utils · high confidence

The VMM now supports loading an initial ramdisk (initrd) into guest memory during the boot process. A new \initrd\ module handles the configuration and memory allocation for the initrd image, and the boot builder integrates this step to ensure the initrd is available to the guest kernel alongside the main kernel image.

src/vmm/src · high confidence

The VMM now supports configuring multiple PCI segments, allowing guests to access a larger number of PCI devices. This is implemented via the new \PciSegment\ struct in \src/vmm/src/devices/pci\, which encapsulates the configuration space (MMIO and PIO on x86\_64), IRQ slots, and memory regions for a specific segment ID. The change introduces a modular structure where each segment manages its own \PciBus\ and registers its configuration interfaces with the VM's MMIO and PIO buses.

src/vmm/src/devices/pci · high confidence

The virtio balloon device has been rewritten to support free page hinting and free page reporting features, allowing the guest to proactively release unused memory pages to the host. The new implementation includes dedicated event handling for hinting and reporting queues, metrics tracking for these operations, and snapshot persistence for the hinting state. It also introduces bounds checking on stats descriptor lengths to prevent unbounded iteration and improves error handling for queue events.

src/vmm/src/devices/virtio/balloon · high confidence

The virtio block device implementation now handles discard requests, allowing guests to inform the host that specific blocks of storage are no longer in use. This capability is implemented in the new \src/vmm/src/devices/virtio/block/virtio/io\ module, which introduces a unified \FileEngine\ abstraction supporting both synchronous and asynchronous (io\_uring) backends. For synchronous engines, discards are executed via \BLKDISCARD\ ioctl for block devices or \fallocate\ with \FALLOC\_FL\_PUNCH\_HOLE\ for regular files. Asynchronous engines also expose a discard method, ensuring consistent behavior across IO modes. This change enables better storage efficiency and performance for guests using discard-capable filesystems.

src/vmm/src/devices/virtio/block/virtio/io · high confidence

The x86\_64 CPU configuration module now allows users to define custom CPU templates that modify specific CPUID leaves/subleaves and Model Specific Registers (MSRs) via bitmaps. This change introduces the \CustomCpuTemplate\ structure and associated serialization logic, enabling precise control over vCPU features (such as KVM capabilities and specific register bits) beyond the existing static templates (C3, T2, etc.).

_src/vmm/src/cpu\_config/x86\64 · high confidence

The API server implementation has been reorganized from a single file into a dedicated module (\src/firecracker/src/api\_server\) containing \mod.rs\, \parsed\_request.rs\, and \request.rs\. This change introduces a structured request parsing layer that routes HTTP methods (GET, PUT, PATCH, DELETE) to specific handler functions for resources like balloon, drives, PMEM, and hotplug memory, while centralizing the server loop, seccomp filter application, and metric reporting in the new module root.

_src/firecracker/src/api\server · high confidence

The \src/vmm/src/arch\ module has been introduced to consolidate architecture-specific logic for both aarch64 and x86\_64 platforms. This change adds the ability to query the host's kernel version and page size at runtime, enabling the VMM to adapt its behavior based on the underlying host environment. It also defines common types such as \DeviceType\, \BootProtocol\, and \EntryPoint\, and reorganizes existing boot configuration and memory region logic into this central location for better maintainability.

src/vmm/src/arch · high confidence

The device management layer has been restructured into a modular architecture with dedicated modules for ACPI (\acpi.rs\), legacy I/O devices (\legacy.rs\), MMIO devices (\mmio.rs\), PCI devices (\pci\_mngr.rs\), and persistence (\persist.rs\). This change introduces the \ACPIDeviceManager\ to handle VMGenID and VMClock devices, the \PortIODeviceManager\ for legacy serial and keyboard devices on x86\_64, and the \MMIOVirtioDevices\ manager for MMIO-based VirtIO devices. It also adds the \PciDevices\ manager for PCI-based VirtIO devices and comprehensive serialization support for all device states to enable snapshot save/restore functionality.

_src/vmm/src/device\manager · high confidence

The \vstate\ module has been reorganized into distinct submodules (\bus\, \interrupts\, \kvm\, \memory\, \resources\, \vcpu\, \vm\) to improve code structure and maintainability. This change decouples address range handling from device handles in the bus implementation, introduces a new \BusRange\ type for safer address space management, and centralizes interrupt and memory state handling within the \Vm\ object. Users benefit from improved reliability and clearer separation of concerns in the virtual machine state management layer.

src/vmm/src/vstate · high confidence

The vmm configuration logic has been reorganized from a monolithic structure into distinct modules for each subsystem. This change introduces dedicated configuration files for the balloon device, boot source (including initrd support and default kernel cmdline), block devices (with rate limiters and io engine options), entropy device, instance info, machine config (supporting huge pages, SMT, and dirty page tracking), memory hotplug, metrics (with instance ID and custom properties), MMDS, network interfaces, and rate limiters. Each module now encapsulates its own configuration structs, builders, and error types, improving code organization and maintainability while exposing the same API capabilities.

_src/vmm/src/vmm\config · high confidence

The API server's request handling logic has been reorganized from a monolithic structure into separate, dedicated modules (e.g., \actions\, \balloon\, \drive\, \machine\_configuration\, \metrics\, \mmds\, \net\, \pmem\, \serial\, \snapshot\). This change improves code maintainability and clarity by isolating the parsing and validation logic for each specific API endpoint and resource type, while preserving the existing API behavior and contract.

_src/firecracker/src/api\server/request · high confidence

The x86\_64 architecture code has been reorganized into a dedicated \src/vmm/src/arch/x86\_64\ module, introducing new files for CPU model definitions (\cpu\_model.rs\), memory layout constants (\layout.rs\), and interrupt handling (\interrupts.rs\). This change adds support for specific CPU models (Skylake, Cascade Lake, Ice Lake, Milan) and defines memory regions for legacy and MSI interrupts, as well as 32-bit and 64-bit MMIO spaces. The refactoring also includes new GDT handling logic and KVM-specific initialization code, improving the modularity and clarity of the x86\_64 virtualization layer.

_src/vmm/src/arch/x86\64 · high confidence

The aarch64 architecture module has been reorganized into dedicated submodules (cache\_info, fdt, kvm, layout, regs, vcpu, vm) to improve code clarity and maintainability. A new cache\_info module reads host cache topology from sysfs and uses it to override the CLIDR\_EL1 register on vCPUs for kernels 6.10+, ensuring the guest sees the correct cache levels. The FDT generation is now handled by a dedicated module that incorporates cache information, VMGenID, VMClock, and PCI nodes. The KVM initialization logic is separated into its own module, and the VM state management is consolidated in a new vm module that handles GIC state and resource allocator persistence. Memory layout constants are centralized in a layout module, and register definitions are moved to a regs module with improved macro support for ARM64 system registers.

src/vmm/src/arch/aarch64 · high confidence

The build process now explicitly uses an empty default seccomp policy (unimplemented.json) when compiling debug binaries, rather than the standard target-specific policy. This ensures that debug builds do not inadvertently enforce restrictive system call filtering, which can interfere with debugging workflows, while still maintaining the default policy for release builds.

src/firecracker · high confidence

The rebase-snap utility, which copies non-sparse sections from a diff memory snapshot onto a base file, is now marked as deprecated. Users will see a deprecation message when running the tool or checking its version, and are advised to use the 'snapshot-editor' tool instead.

src/rebase-snap · high confidence

The development container base image has been updated from Ubuntu 22.04 to 24.04, and the build process has been refactored into a multi-stage pipeline to improve efficiency and reproducibility. This change introduces several new capabilities for developers: the container now includes a built-in QEMU vhost-user-blk backend builder, static libseccomp support for musl builds, and pre-installed tools such as iperf3-vsock, git-secrets, and the codecov uploader. Additionally, cross-compilation toolchains for both x86\_64 and aarch64 are now included, along with updated Rust toolchain support and various utility packages like squashfs-tools, zstd, and trace-cmd, ensuring a more comprehensive and modern development environment.

tools/devctr · high confidence

The Firecracker binary has been refactored into a library crate (\lib.rs\) exposing public modules, with the main entry point (\main.rs\) now explicitly importing and wiring together the \api\_server\_adapter\, \metrics\, and \seccomp\ components. This change introduces a dedicated \api\_server\_adapter.rs\ module that manages the event-driven loop for API requests and MicroVM lifecycle, a \metrics.rs\ module for periodic metrics flushing via \TimerFd\, and a \seccomp.rs\ module for configuring and loading BPF filters (default, custom, or disabled). The default API socket path has been changed to \/run/firecracker.socket\, and the codebase now uses \thiserror\ and \displaydoc\ for error handling across these modules.

src/firecracker/src · high confidence

The VMM now applies Intel-specific CPUID normalization to virtual CPUs, ensuring that CPUID leaves match the Intel Software Developer's Manual. This process updates deterministic cache entries (Leaf 0x4) to correctly reflect core and CPU topology, disables Intel Turbo Boost and performance-energy bias preference features (Leaf 0x6), and sets specific extended feature flags (Leaf 0x7) to align with Linux kernel recommendations for virtualized environments.

_src/vmm/src/cpu\_config/x86\64/cpuid/intel · high confidence

The \src/utils\ module now includes a new \arg\_parser\ component that replaces the previous external dependency with a custom implementation, adding support for forbidden argument pairs, duplicate argument detection, and formatted help output. Additionally, new \validators\ utilities have been added to enforce constraints on instance IDs, ensuring they contain only alphanumeric characters and hyphens within a specific length range.

src/utils · high confidence

The VMM now exposes structured types for managing io\_uring submission and completion queue entries. Users interacting with the VMM's internal I/O layer can now utilize the \Operation\ type to construct read, write, and fsync commands, which are converted into raw \io\_uring\_sqe\ structures via a slab-based user data tracking mechanism. Completed operations are wrapped in the generic \Cqe\ type, providing safe access to transfer counts and error results derived from the kernel's return codes.

_src/vmm/src/io\uring/operation · high confidence

The VSOCK device now uses a new connection state machine implementation located in \src/vmm/src/devices/virtio/vsock/csm\. This change introduces a dedicated \VsockConnection\ struct to manage the lifecycle of AF\_VSOCK connections, including connection establishment, data transfer, and termination. It also adds a new \TxBuf\ ring-buffer to handle TX data buffering when the host stream cannot keep up with the guest's transmission rate. This refactoring separates the connection state management logic from the rest of the VMM, improving code organization and maintainability.

src/vmm/src/devices/virtio/vsock/csm · high confidence

The vsock device implementation has been restructured into a new modular layout (device, event\_handler, packet, persist, metrics) to improve code organization and maintainability. This change introduces dedicated metrics collection for the vsock device, tracking queue events, bytes/packets transferred, and connection lifecycle, which are now exposed via a dedicated metrics module rather than the generic logger. It also adds snapshot persistence support, allowing the vsock device state (including CID, queue states, and pending event acknowledgment) to be saved and restored, enabling VM checkpointing and migration. The event handling logic has been refactored to use a more explicit event-driven model with dedicated handlers for RX, TX, and event queues, improving clarity and potentially performance.

src/vmm/src/devices/virtio/vsock · high confidence

The Buildkite CI configuration has been rewritten from scratch using a new Python-based pipeline generation framework. This change replaces the previous pipeline definitions with a set of new Python scripts (e.g., \pipeline\_pr.py\, \pipeline\_perf.py\, \pipeline\_cross.py\) that dynamically generate Buildkite pipeline JSON. The new infrastructure introduces a \BKPipeline\ class and common helpers in \common.py\ to manage instance selection, platform defaults, and step dependencies. It adds support for new instance types (including Graviton4/5 and Granite Rapids) and kernel versions, implements A/B performance testing capabilities, and introduces dedicated pipelines for coverage, sanitizers, and release QA.

.buildkite · high confidence

A new \src/vmm/src/devices\ module has been introduced to organize virtual device emulation code, exposing submodules for ACPI, legacy, PCI, pseudo, and virtio devices. This change centralizes error handling by defining a \DeviceError\ enum that wraps specific device errors (such as TAP read failures, IRQ signaling issues, and virtio queue errors) and introduces a \report\_net\_event\_fail\ function. This function not only logs errors but also increments per-device network failure metrics, ensuring that network device performance issues are tracked accurately.

src/vmm/src/devices · high confidence

The PCI emulation logic has been reorganized into dedicated modules (bus, configuration, msix) within the VMM, introducing a new PciBus structure that manages device slots and a PciHostBridge for the root complex. Configuration space handling is now encapsulated in PciConfiguration with explicit BAR support for 32-bit and 64-bit addresses, while MSI-X state management is handled by MsixConfig with validation during snapshot restore. The PciSBDF type replaces raw u32 identifiers for segment/bus/device/function addressing, and device addition now returns errors instead of asserting on duplicate IDs.

src/vmm/src/pci · high confidence

The rate limiter now supports saving and restoring its state (including token bucket budgets and timer status) via the VMM snapshot mechanism, ensuring consistent throttling behavior across VM migrations or restarts. Additionally, the implementation has been refined to correctly arm the timer for sub-millisecond overconsumption debt, preventing potential timing inaccuracies when tokens are exhausted.

_src/vmm/src/rate\limiter · high confidence

The logger now rate-limits error, warning, and info messages to prevent log flooding from guest-triggerable paths, using a lock-free GCRA-based limiter (default 10 messages per 5-second window). Suppressed messages are tracked via a new \rate\_limited\_log\_count\ metric, and a warning is emitted when logging resumes after suppression. Unrestricted variants (\error\_unrestricted\, \warn\_unrestricted\, \info\_unrestricted\) are provided for host-only paths. Additionally, the logger now uses an \RwLock\ to allow signal handlers to log without deadlocking, and opens the log file before acquiring the logger lock to avoid re-entrancy issues during initialization.

src/vmm/src/logger · high confidence

The VirtIO device model has been restructured to enforce a strict activation lifecycle. Devices are now explicitly tracked as either Inactive or Activated via the new DeviceState enum, and the VirtioDevice trait now requires an activate() method that binds guest memory and interrupt handlers, returning an ActivateError if the operation fails. This change ensures that queues and memory mappings are only valid after successful activation, preventing use of uninitialized resources. Additionally, the queue implementation has been generalized and bounds-checked, with ring accesses now validated against queue sizes to prevent out-of-bounds errors.

src/vmm/src/devices/virtio · high confidence

The auto-generated Virtio device bindings in \src/vmm/src/devices/virtio/generated\ have been refreshed using Linux 6.12 kernel headers. This update introduces support for the new virtio-mem device (including memory plug/unplug request structures and state constants) and adds definitions for newer Virtio feature flags such as \VIRTIO\_F\_RING\_RESET\, \VIRTIO\_F\_ADMIN\_VQ\, and \VIRTIO\_F\_NOTIF\_CONFIG\_DATA\. It also expands the block device capabilities with zoned block commands (e.g., zone append, report, open, close) and updates network device features to include USO, RSS, and hash report support.

src/vmm/src/devices/virtio/generated · high confidence

The auto-generated Rust bindings in \src/firecracker/src/generated\ and \src/vmm/src/arch/x86\_64/generated\ have been refreshed to align with Linux 6.13 kernel headers. This update introduces new constants and structures for \prctl\ operations (such as \PR\_SET\_MDWE\ and \PR\_RISCV\_V\_SET\_CONTROL\), x86\_64 \arch\_prctl\ features (including \ARCH\_SHSTK\ and \ARCH\_GET\_UNTAG\_MASK\), and Hyper-V MSRs (like \HV\_X64\_MSR\SYNDBG\\*\ and \HV\_X64\_MSR\CRASH\\*\). It also updates MP specification tables, performance event MSRs, and general x86 MSR indices to reflect the latest kernel definitions, ensuring the VMM and Firecracker components maintain accurate low-level interface definitions.

_src/firecracker/src/generated, src/vmm/src/arch/x86\64/generated · high confidence

The project has standardized its development workflow by adopting the Keep a Changelog format for version history and enforcing stricter commit message guidelines via .gitlint (72-character limits, specific ignore rules). Markdown formatting is now consistently handled by mdformat with a .mdformat.toml configuration. Additionally, contributor attribution is improved through a new .mailmap file that deduplicates email addresses, and the repository includes updated CONTRIBUTING.md guidelines, a CHARTER.md defining project tenets, and a DEPRECATED.md listing retired features.

(repo-wide) · high confidence

The x86\_64 CPUID configuration logic has been reorganized into a dedicated \cpu\_config\ module, introducing a new \normalize\ phase that explicitly updates the vendor ID, feature information, extended topology, and extended cache features for each vCPU. This change ensures the guest vendor ID is correctly passed through from the host (leaf 0x0) and fixes the calculation of right-shift bits for socket ID addressing in extended topology leaves. Additionally, cache information from the host is now properly passed through to the guest, and the codebase adopts Intel SDM notation for internal constants and comments while replacing hand-coded MSR values with generated ones.

_src/vmm/src/cpu\_config/x86\64/cpuid · high confidence

The seccompiler build process now explicitly searches /usr/local/lib for the libseccomp library and links against it. This ensures the tool can locate and use the seccomp library installed in that specific directory during compilation.

src/seccompiler · high confidence

The seccompiler tool has been rewritten to generate Berkeley Packet Filter (BPF) code by calling the libseccomp C library via FFI bindings, replacing the previous implementation. This change introduces a new CLI interface (accepting JSON input, target architecture, and output path) and a library API that leverages libseccomp's \seccomp\_init\, \seccomp\_rule\_add\, and \seccomp\_export\_bpf\_mem\ functions to construct and export filters. The output format has also changed from bincode to bitcode serialization, with a new size limit check to prevent denial-of-service via oversized filters.

src/seccompiler/src · high confidence

The snapshot module now uses the bitcode library for serialization instead of bincode, changing the underlying storage format. To prevent denial-of-service attacks via large snapshot files, a 10MB limit has been enforced on the amount of memory used during snapshot deserialization, returning an error if the input exceeds this threshold.

src/vmm/src/snapshot · high confidence

The block device implementation has been refactored to introduce a unified \Block\ enum that abstracts over two distinct backend types: \VirtioBlock\ and \VhostUserBlock\. This change allows the VMM to manage both traditional virtio-blk devices and vhost-user-blk devices through a single interface, simplifying device creation and configuration via \BlockDeviceConfig\. The new structure includes dedicated persistence logic (\BlockState\) for snapshotting and restoring both backend types, while ensuring that operations specific to one backend (such as \update\_disk\_image\ or \config\_update\) correctly return errors when invoked on the unsupported backend type.

src/vmm/src/devices/virtio/block · high confidence

The generated Rust bindings for the vmclock ABI have been updated to support snapshot safety features. This includes adding the \vm\_generation\_counter\ field to the \vmclock\_abi\ struct and introducing new flags \VMCLOCK\_FLAG\_VM\_GEN\_COUNTER\_PRESENT\ and \VMCLOCK\_FLAG\_NOTIFICATION\_PRESENT\. The type definitions for several constants have been corrected from \u32\ to \u8\ or \u64\ to match the ABI specification, and the \vmclock\_abi\ struct now derives \Serialize\ and \Deserialize\ for improved serialization support. Additionally, patches were applied to fix \c\_char\ to \c\_uchar\ conversion in network interface bindings and to ensure \Clone\ and \Copy\ traits are correctly derived for io\_uring structures.

tools/bindgen-patches · high confidence

The VirtIO block device implementation has been restructured into a new modular layout (device, event\_handler, metrics, persist, request, and test\_utils modules) to improve maintainability and observability. Key functional additions include support for the VIRTIO\_BLK\_F\_DISCARD feature (allowing guests to issue discard/TRIM requests) and the VIRTIO\_BLK\_F\_TOPOLOGY feature (exposing physical block size, minimum I/O size, and optimal I/O size to the guest). The device now exposes granular, per-drive metrics (such as read/write bytes, operation counts, latency aggregates, and failure counters) via a new metrics module, replacing or augmenting previous aggregate logging. The refactoring also introduces a configurable file engine (sync vs. async/io\_uring), enforces stricter device activation states, and updates the persistence logic to save and restore the new configuration space fields and engine type.

src/vmm/src/devices/virtio/block/virtio · high confidence

The virtio-net device implementation has been restructured into a dedicated module under src/vmm/src/devices/virtio/net, introducing a new per-device metrics system that tracks network performance and errors (such as activate failures, buffer availability, and rate limiter events) with JSON serialization support. The device now supports snapshot persistence via the new persist module, allowing state restoration including rate limiters and MMDS network stacks. Additionally, the event handling logic has been refactored to use Events::with\_data() for more efficient queue and rate limiter event processing, and the device now properly handles activation state transitions to prevent spurious events before activation.

src/vmm/src/devices/virtio/net · high confidence

The io\_uring implementation has been relocated from the top-level \src/\ directory into \src/vmm/src/io\_uring\, making it a dedicated sub-module of the Virtual Machine Manager. This change includes regenerating the low-level bindings from Linux 6.13 kernel headers and refactoring the internal error handling and queue management logic to improve code readability and maintainability within the VMM context.

_src/vmm/src/io\uring · high confidence

Added MSR baseline data for Granite Rapids, Sapphire Rapids, and AMD Milan; Added Rust integration tests for VMM device and snapshot behavior; Added integration tests for Kani proof harnesses; Added integration tests for clippy-tracing CLI actions; Added integration tests for repository style and compliance; Added test to enforce caret version requirements for dependencies; New functional integration test suite for Firecracker; New host-side test utilities and validation tools; New integration test suite for security features; New integration tests for build-time checks and static analysis; New performance integration test suite; New pytest-based integration test framework; New test framework infrastructure and utilities.

The project has migrated to the Rust 2024 edition across all crates, including the main firecracker binary, the VMM, the jailer, and utility libraries. This edition upgrade is accompanied by significant updates to core dependencies, such as bumping \thiserror\ to version 2.0, \clap\ to 4.6, and \libc\ to 0.2.186. Additionally, the \vm-memory\ dependency has been updated to version 0.18.0, and the \aws-lc-rs\ cryptographic library has been upgraded to 1.17.0/1.18.1. The development container's Python dependencies, including \aiohttp\, have also been updated to their latest versions.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 51 → 78 (+27.5)
• Rubric changed (rubric-2026.08.15 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 94 → 90 (-4.3)
• Architecture 69 → 99 (+29.6)
• Maturity 79 → 78 (-0.8)
• Readiness 31 → 87 (+55.9)
• Security 60 → 70 (+10.4)
• Event Sourcing 100 (new)

• Coverage not measured — test suite did not build
• Dimension evaluation failed
• High: security finding (details withheld)
• Low IaC: DS-0026 (tools/devctr/Dockerfile)
• Low: security finding (details withheld)
• Low: security finding (details withheld)
• Low: security finding (details withheld)
• Medium IaC: DS-0013 (tools/devctr/Dockerfile)
• Medium IaC: DS-0013 (tools/devctr/Dockerfile)
• Medium IaC: DS-0013 (tools/devctr/Dockerfile)
• Medium IaC: DS-0013 (tools/devctr/Dockerfile)
• Medium IaC: DS-0013 (tools/devctr/Dockerfile)
• Medium IaC: DS-0013 (tools/devctr/Dockerfile)
• Medium IaC: DS-0013 (tools/devctr/Dockerfile)
• Medium IaC: DS-0013 (tools/devctr/Dockerfile)
• No exposed public API
• No tests found
• Secret: square-access-token (tools/devctr/poetry.lock)
• Test reliability not included

• Arguments::validate_requirements (cognitive 17) (src/utils/src/arg_parser.rs)
• BKPipeline._chunk_steps (cognitive 17) (.buildkite/common.py)
• Balloon::process_free_page_hinting_queue (cognitive 31) (src/vmm/src/devices/virtio/balloon/device.rs)
• Balloon::process_inflate (cognitive 25) (src/vmm/src/devices/virtio/balloon/device.rs)
• Change coupling: builder.rs ↔ mod.rs (src/vmm/src/builder.rs)
• Change coupling: completion.rs ↔ submission.rs (src/vmm/src/io_uring/queue/completion.rs)
• Change coupling: dist_regs.rs ↔ redist_regs.rs (src/vmm/src/arch/aarch64/gic/gicv3/regs/dist_regs.rs)
• Change coupling: mod.rs ↔ mmio.rs (src/vmm/src/acpi/mod.rs)
• Change coupling: mod.rs ↔ mod.rs (src/vmm/src/arch/aarch64/gic/gicv2/mod.rs)
• Change coupling: persist.rs ↔ persist.rs (src/vmm/src/mmds/persist.rs)
• Change coupling: rpc_interface.rs ↔ mod.rs (src/vmm/src/rpc_interface.rs)
• ClassTooLong: Balloon (src/vmm/src/devices/virtio/balloon/device.rs)
• ClassTooLong: Net (src/vmm/src/devices/virtio/net/device.rs)
• ClassTooLong: PciDevices (src/vmm/src/device_manager/pci_mngr.rs)
• ClassTooLong: VirtioMem (src/vmm/src/devices/virtio/mem/device.rs)
• ClassTooLong: VirtioPciDevice (src/vmm/src/devices/virtio/transport/pci/device.rs)
• ClassTooLong: VsockMuxer (src/vmm/src/devices/virtio/vsock/unix/muxer.rs)
• Connection::receive_segment (cognitive 72) (src/vmm/src/dumbo/tcp/connection.rs)
• Connection::receive_segment (cyclomatic 38) (src/vmm/src/dumbo/tcp/connection.rs)
• Connection::write_next_segment (cognitive 49) (src/vmm/src/dumbo/tcp/connection.rs)
• …and 216 more

• 189 commits — 166 feature/other, 23 fixes

• src/vmm — 71 commits
• tests/integration_tests — 37 commits
• (root) — 27 commits
• tests/framework — 14 commits
• resources/seccomp — 5 commits
• .github/workflows — 4 commits
• resources/guest_configs — 4 commits
• src/firecracker — 4 commits
• tests/conftest.py — 3 commits
• tests/data — 3 commits
• tools/devtool — 3 commits
• docs/RELEASE_POLICY.md — 2 commits
• tools/ab_test.py — 2 commits
• .buildkite/common.py — 1 commit
• docs/api_requests — 1 commit
• docs/block.md — 1 commit
• docs/seccomp.md — 1 commit
• docs/vsock.md — 1 commit
• resources/rebuild.sh — 1 commit
• src/cpu-template-helper — 1 commit

• fix: fix(aarch64): re-enable CONFIG_ARM64_ERRATUM_3194386 in guest kernels
• fix: fix(logger): do not log from the SIGPIPE handler
• fix: fix(logger): use an RwLock so a signal handler can log without deadlock
• fix: fix(memory): use checked arithmetic in memfd_backed region sum
• fix: fix(rate_limiter): arm timer for sub-millisecond overconsumption debt
• fix: fix(seccomp): allow rt_sigreturn on the API thread
• fix: fix(test): Set the used ring address in the alignment test
• fix: fix(tests): retry start_screen_process on non-zero screen -ls
• fix: fix(tests): tolerate systemd graceful shutdown in test_reboot
• fix: fix(tests): tolerate systemd shutdown in test_config_start_no_api_exit
• fix: fix(vhost-user-block): honour a readonly backend
• fix: fix(vmm): abort if discarding restored guest memory fails
• fix: fix(vmm): commit virtio-mem block state after the KVM slot update
• fix: fix(vmm): enable KVM_CAP_ARM_WRITABLE_IMP_ID_REGS on aarch64
• fix: fix(vmm): keep unplugged memory protected when discarding it
• fix: fix(vmm): preserve MAP_NORESERVE when discarding restored guest memory
• fix: fix(vmm): skip discarding a virtio-mem range with nothing plugged
• fix: fix(vsock): Make host connects nonblocking
• fix: fix(vsock): do not arm the TRANSPORT_RESET RX gate on bare resume
• fix: fix(vsock): forfeit a killed connection's TX buffer
• …and 169 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

firecracker-microvm/firecracker was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.