Key Types by Crate

This is the "where does X live" map for Firecracker's Rust source. When you have a behavior and need the type that implements it — or a type name from a panic, backtrace, or clippy warning and need to know which crate and module owns it — start here. Each section lists a crate (or a vmm module), its key types, a one-line role, and the rg that finds it on your checkout.

Warning — the layout is version-sensitive. A recent large refactor merged most former crates into vmm (devices/, rate_limiter/, mmds/, dumbo/, …), and vmm-sys-util was externalized to rust-vmm. Module paths, file names, and even whether something is a crate or a vmm submodule drift between branches. Treat every path below as "the role to grep for," not a fixed location, and confirm in your checkout:
# List the workspace members on your branch (source of truth):
rg -n "members" -A40 Cargo.toml
# Or let cargo tell you:
cargo metadata --no-deps --format-version 1 | python3 -m json.tool | rg '"name"'
# Find any type by role, never by remembered line number:
rg -n "struct Vmm\b|enum VmmAction\b|struct VmResources\b" src/

Jump to: The workspace · firecracker binary · vmm: top-level · vmm: vstate · vmm: arch · vmm: devices · vmm: device_manager · vmm: rpc & resources · vmm: persist & snapshot · vmm: mmds & dumbo · vmm: rate_limiter · vmm: seccomp/logger/signals · jailer / seccompiler / tooling · rust-vmm deps

The workspace (`src/`, `Cargo.toml`)

The Cargo workspace under src/. After the merge, most logic is in vmm; the binaries and a few tools are separate crates.

Crate	Role	Find it
`vmm`	Core VMM library: machine model, vCPU/KVM state, all device emulation, most subsystems — the big merged crate	`ls src/vmm/src/`
`firecracker`	The `firecracker` binary + the HTTP API server	`ls src/firecracker/src/`
`jailer`	The `jailer` binary (isolation barrier, then `exec` firecracker)	`ls src/jailer/src/`
`seccompiler`	Compiles JSON seccomp filters → BPF (in-tree)	`ls src/seccompiler/src/`
`cpu-template-helper`	Create / inspect / verify CPU templates	`ls src/cpu-template-helper/`
`snapshot-editor`	Inspect / edit snapshot files	`ls src/snapshot-editor/`
`rebase-snap`	Rebase diff-snapshot memory onto a base	`ls src/rebase-snap/`
`acpi-tables`	Build guest ACPI tables (RSDP/MADT/…)	`ls src/acpi-tables/`
`utils`	Internal shared utilities	`ls src/utils/`
`clippy-tracing`, `log-instrument`(`-macros`)	Dev/CI tooling (tracing instrumentation)	`rg -n "name = " src/*/Cargo.toml`

Note: The API server lives in the firecracker binary, not vmm. This trips up newcomers constantly — vmm is a library that knows nothing about HTTP; the binary owns the socket and drives the library.

`firecracker` (the binary + API server)

The executable: parses args, sets up the API thread (or --no-api config-file boot), and drives vmm. Lives in src/firecracker/src/.

Type / module	Role	Find it
`main.rs`	Entry point: arg parsing, `--api-sock` / `--config-file` / `--no-api`, seccomp install, hands off	`rg -n "fn main" src/firecracker/src/main.rs`
`ApiServer` (`api_server/`)	The HTTP server on the Unix socket; turns requests into `ParsedRequest`s	`rg -n "struct ApiServer" src/firecracker/src/`
`api_server_adapter`	Channel/thread wiring: `run_with_api()` / `run_without_api()` (NOT `main.rs`)	`rg -n "run_with_api
`ParsedRequest`	Parsed HTTP request → a `VmmAction` for the channel	`rg -n "struct ParsedRequest
`swagger/firecracker.yaml`	The OpenAPI spec — the authoritative API surface	`rg -n "swagger:

See ../deep-dives/api-server-and-action-channel.md and Lab 3.1.

`vmm`: top-level (machine model)

The files directly under src/vmm/src/ that assemble and own the microVM.

Type / file	Role	Find it
`Vmm` (`lib.rs`)	The running-microVM object owned by the VMM thread; holds memory, vCPUs, devices	`rg -n "pub struct Vmm\b" src/vmm/src/lib.rs`
`builder.rs` (`build_microvm_for_boot`, `build_and_boot_microvm`, `build_microvm_from_snapshot`)	Assembles a microVM from `VmResources` or a snapshot	`rg -n "fn build_microvm_for_boot
`EventManager` usage	The epoll loop the VMM thread runs (type from the `event-manager` crate)	`rg -n "EventManager
`signal_handler.rs`	Installs the signal handlers (faults → controlled exit)	`rg -n "fn register

See ../deep-dives/the-vmm-threading-model.md and Level 6.

`vmm/vstate` (vCPU / VM / KVM state)

The KVM-facing core: src/vmm/src/vstate/.

Type / file	Role	Find it
`Vcpu` / `KvmVcpu` (`vstate/vcpu/`)	A virtual CPU; owns the vCPU fd and runs the `KVM_RUN` loop in its own thread	`rg -n "struct Vcpu\b
the run loop (`vstate/vcpu/`)	`KVM_RUN` → match `VcpuExit` → service I/O/MMIO/halt	`rg -n "fn run
`Vm` (`vstate/vm.rs`)	Wraps the KVM VM fd; creates vCPUs, registers memory, sets up the IRQ chip	`rg -n "struct Vm\b
guest memory (`vstate/memory.rs`)	Builds `GuestMemoryMmap`, registers regions with KVM	`rg -n "GuestMemoryMmap
`VcpuEvent` / `VcpuResponse`	The Pause/Resume/… channels between VMM thread and vCPU threads	`rg -n "enum VcpuEvent

See ../deep-dives/vcpu-run-loop-and-vm-exits.md, ../deep-dives/kvm-fundamentals.md, ../deep-dives/guest-memory-management.md, and Lab 4.1.

`vmm/arch` (boot + memory layout)

Architecture-specific boot and layout: src/vmm/src/arch/{x86_64,aarch64}/.

Type / file	Role	Find it
`arch/x86_64/layout.rs`	The x86 layout constants: `ZERO_PAGE_START`, `CMDLINE_START`, `HIMEM_START`, the MMIO gap, …	`rg -n "ZERO_PAGE_START
`arch/x86_64/` (regs/gdt/msr/cpuid)	Initial vCPU register setup, GDT/page tables, long mode, CPUID/MSR setup	`rg -n "long mode
`arch/x86_64/mptable` / ACPI	CPU topology via MPTable (legacy) / ACPI (RSDP/MADT)	`rg -n "mptable
`arch/aarch64/layout.rs`	The aarch64 layout: `DRAM_MEM_START`, FDT placement, GIC	`rg -n "DRAM_MEM_START
`arch/aarch64/` (fdt, gic, regs)	Build the FDT (`vm-fdt`), set up the GIC, set `x0` to the FDT address	`rg -n "FdtWriter
`cpu_config/`	CPU template machinery: normalize CPUID/MSRs (static + custom templates)	`rg -n "CpuConfiguration

See ../deep-dives/the-boot-sequence.md, ../deep-dives/cpu-templates-and-cpuid.md, the memory layout cheat-sheet, and Level 6.

`vmm/devices` (the device model)

All emulated devices: src/vmm/src/devices/. Virtio devices are under devices/virtio/; legacy under devices/legacy/.

Type / file	Role	Find it
`devices/virtio/queue.rs`	The split-virtqueue logic: descriptor table, avail/used rings	`rg -n "struct Queue\b
`devices/virtio/block/`	virtio-block (type 2): request queue, file backend, io engine	`rg -n "struct Block\b
`devices/virtio/net/`	virtio-net (type 1): RX/TX queues over a host TAP	`rg -n "struct Net\b
`devices/virtio/vsock/`	virtio-vsock (type 19): host↔guest `AF_VSOCK` over a Unix socket	`rg -n "struct Vsock\b
`devices/virtio/balloon/`	virtio-balloon (type 5): inflate/deflate via `MADV_DONTNEED`	`rg -n "struct Balloon\b
`devices/virtio/rng/`	virtio-rng / entropy (type 4): host randomness	`rg -n "struct Entropy\b
`devices/virtio/mmio.rs`	The virtio-MMIO transport: register block, status state machine	`rg -n "MmioTransport
`devices/legacy/serial.rs`	The 16550 serial console (wraps `vm-superio`)	`rg -n "Serial
`devices/legacy/i8042.rs`	The partial i8042 (reset/reboot only)	`rg -n "I8042

See ../deep-dives/virtqueues.md, ../deep-dives/virtio-block.md, ../deep-dives/virtio-net-and-tap.md, ../deep-dives/virtio-vsock.md, ../deep-dives/virtio-balloon.md, ../deep-dives/virtio-rng-entropy.md, ../deep-dives/serial-console-and-legacy-devices.md, and Level 7.

`vmm/device_manager`

Places devices on the bus and dispatches accesses: src/vmm/src/device_manager/.

Type	Role	Find it
`DeviceManager`	The wrapper owning the managers below	`rg -n "struct DeviceManager\b" src/vmm/src/device_manager/`
`MMIODeviceManager`	Assigns each virtio-MMIO device a register window + IRQ; dispatches MMIO	`rg -n "struct MMIODeviceManager" src/vmm/src/device_manager/`
`PortIODeviceManager` (x86)	Dispatches PIO accesses (serial, i8042)	`rg -n "struct PortIODeviceManager" src/vmm/src/device_manager/`
`ACPIDeviceManager` (x86)	Registers ACPI-exposed devices	`rg -n "struct ACPIDeviceManager" src/vmm/src/device_manager/`

See ../deep-dives/the-mmio-bus-and-device-manager.md.

`vmm`: `rpc_interface` / `resources` / `vmm_config`

The control-plane types and pre-boot configuration.

Type / file	Role	Find it
`VmmAction` (`rpc_interface.rs`)	The control-plane command enum sent API thread → VMM thread	`rg -n "enum VmmAction\b" src/vmm/src/rpc_interface.rs`
`VmmData` / `VmmActionError`	The reply payload / error of a `VmmAction`	`rg -n "enum VmmData
`PrebootApiController` / `RuntimeApiController`	Dispatch `VmmAction`s before / after `StartMicroVm`	`rg -n "PrebootApiController
`VmResources` (`resources.rs`)	The aggregated pre-boot config the builder consumes	`rg -n "struct VmResources\b" src/vmm/src/resources.rs`
`MachineConfig` (`vmm_config/`)	vCPUs, mem, smt, huge_pages, cpu_template, track_dirty_pages	`rg -n "struct MachineConfig" src/vmm/src/vmm_config/`
`vmm_config/` (boot_source, drive, net, vsock, balloon, …)	One config struct per API resource	`ls src/vmm/src/vmm_config/`

See ../deep-dives/api-server-and-action-channel.md, the API endpoint map, and Level 3.

`vmm`: `persist` / `snapshot`

Snapshot create/restore: src/vmm/src/persist.rs and src/vmm/src/snapshot/.

Type / file	Role	Find it
`persist.rs` (`create_snapshot`, `restore_from_snapshot`)	Orchestrates microVM-state file + memory file	`rg -n "fn create_snapshot
`Persist` trait	Each device's serialize/restore contract	`rg -n "trait Persist\b" src/vmm/src/`
`snapshot/` (versioned serialization)	The snapshot file format / versioning	`ls src/vmm/src/snapshot/`
`mem_backend` (File / Uffd)	How restore maps guest RAM: file-backed or UFFD lazy faulting	`rg -n "MemBackendType

See ../deep-dives/snapshotting.md, ../masterclass/snapshotting/lab-02-uffd-page-fault-handler.md, and Lab 9.2.

`vmm`: `mmds` / `dumbo`

The metadata service and its tiny TCP/IP stack.

Type / file	Role	Find it
`mmds/` (`Mmds`, V1/V2)	The metadata store; V2 token/session (IMDSv2-like)	`rg -n "struct Mmds\b
`dumbo/`	The in-VMM TCP/IP stack backing MMDS over HTTP	`rg -n "tcp

See ../deep-dives/mmds-metadata-service.md and ../masterclass/networking/lab-03-mmds.md.

`vmm`: `rate_limiter`

Token-bucket I/O limiting: src/vmm/src/rate_limiter/.

Type	Role	Find it
`RateLimiter`	Two token buckets (ops/s + bandwidth) per net/block device	`rg -n "struct RateLimiter\b" src/vmm/src/rate_limiter/`
`TokenBucket`	One bucket: `size`, `one_time_burst`, `refill_time`	`rg -n "struct TokenBucket\b

See ../deep-dives/rate-limiting-token-bucket.md and ../masterclass/networking/lab-02-rate-limiting.md.

`vmm`: `seccomp` / `logger` / `signal_handler`

Type / file	Role	Find it
`seccomp.rs`	Loads/installs the compiled BPF filters per thread category	`rg -n "seccomp
`logger/`	Structured logging + the metrics sink (`/logger`, `/metrics`)	`rg -n "Logger
`signal_handler.rs`	`SIGSYS`/`SIGBUS`/… handlers → controlled shutdown	`rg -n "SIGSYS

See ../deep-dives/seccomp-filtering.md, ../deep-dives/logging-and-metrics.md, and ../deep-dives/signals-shutdown-and-reset.md.

`jailer`, `seccompiler` & standalone tooling

Crate	Key types / role	Find it
`jailer`	The isolation barrier: `pivot_root`/chroot, cgroups, namespaces, `mknod`, then `setuid`/`exec` firecracker	`rg -n "fn main
`seccompiler`	JSON filter → BPF compiler: `SyscallRule`, `default_action`, operators `eq/ge/gt/lt/ne/masked_eq`	`rg -n "SyscallRule
`cpu-template-helper`	Dump/strip/verify CPU templates against the running host	`rg -n "fn main
`snapshot-editor`	Inspect/edit fields of a snapshot state file	`rg -n "fn main
`rebase-snap`	Apply a diff memory file onto a base	`rg -n "fn main
`acpi-tables`	Build RSDP/MADT/… for the guest	`rg -n "Rsdp

See ../deep-dives/the-jailer.md, ../deep-dives/seccomp-filtering.md, ../deep-dives/acpi-and-mptable.md, Lab 9.1, and ../integration-labs/lab-i2-jailer-in-production.md.

rust-vmm (external dependencies)

These are not in this repo — they are crates from the rust-vmm project that Firecracker depends on. To inspect them, use cargo doc (open the rendered API) or read the vendored source under your cargo registry cache.

Crate	Role in Firecracker	Inspect it
`kvm-ioctls`	Safe KVM wrappers: `Kvm`, `VmFd`, `VcpuFd`, `VcpuExit`	`cargo doc -p kvm-ioctls --open`
`kvm-bindings`	Raw KVM struct/ioctl bindings	`cargo doc -p kvm-bindings --open`
`vm-memory`	Guest memory: `GuestMemoryMmap`, `GuestAddress`	`cargo doc -p vm-memory --open`
`linux-loader`	Kernel ELF parsing (`loader::Elf`) + boot params (`bootparam`)	`cargo doc -p linux-loader --open`
`vm-superio`	Legacy devices: serial / i8042 / RTC	`cargo doc -p vm-superio --open`
`event-manager`	The epoll loop the VMM thread runs (`EventManager`, `Subscriber`)	`cargo doc -p event-manager --open`
`vmm-sys-util`	`EventFd`, ioctl macros (externalized; no longer vendored)	`cargo doc -p vmm-sys-util --open`
`vm-fdt`	aarch64 FDT/DTB builder (`FdtWriter`)	`cargo doc -p vm-fdt --open`

Tip: To see the exact versions Firecracker pins, read Cargo.lock (rg -n "name = \"kvm-ioctls\"" -A2 Cargo.lock) — never assume the latest upstream. Firecracker donated seccompiler, event-manager, and vm-superio upstream, so the in-tree and rust-vmm versions can diverge. See ../rust-vmm/index.md.

From a panic or backtrace to the right chapter

# 1. Take the most specific frame, e.g.:
#    vmm::devices::virtio::block::device::Block::process_queue

# 2. Find the section in this doc (vmm/devices), confirm the type:
rg -n "struct Block\b|fn process_queue" src/vmm/src/devices/virtio/block/

# 3. Read the chapter the row points at, then return to the trace.

Note: A frame in kvm_ioctls::* or vm_memory::* means the failure is below Firecracker — in a rust-vmm crate. Switch to the ../rust-vmm/index.md chapters and cargo doc that crate. A frame in seccompiler::* or jailer::* is in a sibling binary, not vmm.

Next: API Endpoint Map — the full REST surface over the Unix socket.

Open-Source Engineer & Contributor