Deep Dives: Reading Order
This directory contains the 26 internals deep dives — the reference layer behind the nine
Levels. The levels are the spine: they tell you what to build and in what
order. The deep dives are the muscle: each one takes a single subsystem of Firecracker, points you at
the exact code with runnable rg/find commands, and makes you prove you understand it. A level says
"trace a virtio-block I/O down to a KVM_EXIT_MMIO"; the relevant deep dives are where you learn how
the descriptor chain, the MMIO bus, and the run loop actually fit together.
Everything you read here lives under the Firecracker Rust workspace in src/ — overwhelmingly inside
the big merged vmm crate (src/vmm/src/...), with the HTTP API server in the separate
firecracker binary (src/firecracker/). Paths drift between branches, so never trust a line
number in this book: every chapter names code by role and gives you the command that locates it on
your checkout. Where a fact is version-sensitive, it is flagged "(verify on your branch)" — confirm it
against CHANGELOG.md and the source before you rely on it.
Note: Each chapter ends with a "Validation: prove you understand this" section of six questions. Treat that as the gate before you call a chapter "read." If you cannot answer them from memory plus a
grep, you skimmed — go back. The deep dives are not optional background; they are where the real depth of the curriculum lives.
How the deep dives map to the levels
| Group | Chapters | Read alongside |
|---|---|---|
| Threading & control plane | the-vmm-threading-model, api-server-and-action-channel, the-event-manager | Level 3 |
| KVM, vCPUs & CPU | kvm-fundamentals, vcpu-run-loop-and-vm-exits, cpu-templates-and-cpuid, interrupts-and-irqchip | Level 4 |
| Boot & memory | the-boot-sequence, guest-memory-management, acpi-and-mptable | Level 6 |
| Devices & virtio | the-mmio-bus-and-device-manager, virtio-transport-mmio, virtqueues, virtio-block, virtio-net-and-tap, virtio-vsock, virtio-balloon, virtio-rng-entropy, serial-console-and-legacy-devices, rate-limiting-token-bucket | Level 7 |
| Security | the-jailer, seccomp-filtering | Level 9 |
| Snapshots | snapshotting, mmds-metadata-service | Level 9 |
| Observability & lifecycle | logging-and-metrics, signals-shutdown-and-reset | Level 5, Level 8 |
The 26 chapters, in reading order
Read top to bottom the first time through. Each group assumes the ones above it. Thereafter, use this page as a lookup: jump straight to the chapter for the failing component and follow its cross-links.
Group 1 — Threading and the control plane
These three chapters define what a Firecracker process is: one microVM, three thread classes, and the
channel that connects the control plane to the data plane. Read them before anything else — every later
chapter assumes you know who owns the Vmm struct and which thread you are on.
| # | File | What you walk away knowing |
|---|---|---|
| 1 | the-vmm-threading-model.md | One process = one microVM; the API / VMM / vCPU thread split; mpsc + eventfd wake-up; why the control plane is off the fast path. |
| 2 | api-server-and-action-channel.md | ParsedRequest → VmmAction → ApiRequest mpsc + eventfd → preboot/runtime controllers → ApiResponse; micro-http; the swagger spec. |
| 3 | the-event-manager.md | The EventManager epoll loop the VMM thread runs; Subscribers; how devices and the API eventfd register interest. |
Group 2 — KVM, vCPUs, and the CPU model
The layer beneath everything. How Firecracker reaches the hardware through /dev/kvm, what a vCPU
thread actually does in its loop, and how the guest's view of the CPU is configured.
| # | File | What you walk away knowing |
|---|---|---|
| 4 | kvm-fundamentals.md | /dev/kvm, the system/VM/vCPU fd hierarchy, the key ioctls, hardware virt (VT-x/SVM/EL2), how kvm-ioctls exposes it. |
| 5 | vcpu-run-loop-and-vm-exits.md | The KVM_RUN loop; the VcpuExit taxonomy; dispatch to the PIO/MMIO buses; the kvm_run shared page; VcpuEvent/VcpuResponse. |
| 6 | cpu-templates-and-cpuid.md | GET_SUPPORTED_CPUID → transform → SET_CPUID2; static vs custom templates; snapshot portability; cpu-template-helper. |
| 7 | interrupts-and-irqchip.md | The in-kernel irqchip; IRQFD/eventfd injection; MSI; how virtio devices signal the guest; GSI/IRQ allocation. |
Group 3 — Boot and guest memory
How a microVM goes from "no RAM, no kernel" to "executing guest code in long mode."
| # | File | What you walk away knowing |
|---|---|---|
| 8 | guest-memory-management.md | Host mmap → KVM_SET_USER_MEMORY_REGION; GuestMemoryMmap/GuestAddress; safe device access; dirty-page tracking; huge pages. |
| 9 | the-boot-sequence.md | InstanceStart through builder.rs: memory, vmlinux load, zero page/e820/cmdline, vCPU regs for long mode, devices, start vCPUs (+ aarch64 FDT). |
| 10 | acpi-and-mptable.md | How CPU topology is advertised: legacy MPTable vs ACPI (RSDP/MADT), and the deprecation in progress. |
Group 4 — Devices and the virtio model
The data plane. Start with the bus that routes a VM exit to a device, then the virtio transport and ring logic, then the individual devices.
| # | File | What you walk away knowing |
|---|---|---|
| 11 | the-mmio-bus-and-device-manager.md | MMIODeviceManager/PortIODeviceManager; the Bus that routes an exit's address to a device; fixed MMIO windows; registration during build. |
| 12 | virtio-transport-mmio.md | The virtio-mmio register block, the status state machine, feature negotiation, and the virtio-pci alternative. |
| 13 | virtqueues.md | Split virtqueues: descriptor table, available/used rings, kicks and interrupts, virtio-queue. |
| 14 | virtio-block.md | The block device: one request queue, file-backed I/O, Sync vs io_uring engines, rate limiting. |
| 15 | virtio-net-and-tap.md | The net device over a host TAP; RX/TX queues; rate limiting. |
| 16 | virtio-vsock.md | Host↔guest AF_VSOCK over a host Unix socket. |
| 17 | virtio-balloon.md | Inflate/deflate via madvise(MADV_DONTNEED); statistics. |
| 18 | virtio-rng-entropy.md | The entropy device; host randomness with a per-request cap. |
| 19 | serial-console-and-legacy-devices.md | The 16550 UART (vm-superio) and the partial i8042 (reset only). |
| 20 | rate-limiting-token-bucket.md | The two-bucket token-bucket limiter shared by net and block. |
Group 5 — Security, snapshots, observability
The cross-cutting subsystems a maintainer is held responsible for.
| # | File | What you walk away knowing |
|---|---|---|
| 21 | the-jailer.md | chroot/pivot_root, cgroups, namespaces, mknod, privilege drop, then exec firecracker. |
| 22 | seccomp-filtering.md | Per-thread-category BPF filters (vmm/api/vcpu); seccompiler; the JSON rule format. |
| 23 | snapshotting.md | The two snapshot files; full vs diff; the Persist trait; pause→create→resume; UFFD load. |
| 24 | mmds-metadata-service.md | The IMDS-like metadata service; V2 tokens; the dumbo in-VMM TCP/IP stack. |
| 25 | logging-and-metrics.md | The logger and metrics subsystems; FlushMetrics; structured output. |
| 26 | signals-shutdown-and-reset.md | The signal handler; SendCtrlAltDel; i8042 reset; clean vs faulted shutdown. |
A note on order vs. lookup
The first pass should be linear: threading, then KVM/vCPU, then boot/memory, then devices, then the cross-cutting subsystems. Each group leans on the previous one — read the-vmm-threading-model.md out of order and the device chapters will reference a thread split you have not internalized.
When you come back to fix a bug, do not re-read linearly. A guest that hangs after InstanceStart
starts in the-boot-sequence.md; a virtio device that never gets serviced starts in
the-mmio-bus-and-device-manager.md; an API call that returns 400
starts in api-server-and-action-channel.md. Use the cross-links inside
each chapter to walk the path.
The deep dives also pair with the rust-vmm section: when a chapter says
"Firecracker reaches KVM through kvm-ioctls," the rust-vmm pages are where you learn the crate itself.
Begin with The VMM Threading Model.