Appendices & Reference
The chapters in this curriculum are meant to be read — first principles, then
the real vmm/firecracker/jailer source, then a lab where you prove you
understood it by running it. This appendix is the opposite kind of document. It
is meant to be looked up. When you are mid-task — staring at a KVM_EXIT
reason you don't recognize, drafting a PR, building a curl against the API
socket, or trying to remember which crate owns a behavior — you do not want to
re-read a 2,000-line deep dive. You want a table, an exact name, and a one-click
jump to the chapter that explains it.
That is what these six reference documents give you. They are deliberately tables-first, comprehensive, and heavily cross-linked back into the rest of the book. Nothing here is new material; everything points at a chapter, level, or lab that teaches the concept in full. Think of the appendix as the index card layer that sits on top of the curriculum.
Warning: Treat every name, address, default, and ioctl number in this appendix as a starting point to verify, not gospel. Firecracker moves fast: a big refactor recently merged most crates into
vmm, layout constants live in per-arch files that change, the API gains endpoints between minor releases, and rust-vmm crate versions bump under you. Every table here tells you therg,cargo doc,gh, orcurlthat confirms the current truth in your checkout on your branch. When the appendix and yourrgdisagree, yourrgwins — and that is often a documentation fix worth a PR. Items that are especially version-sensitive are flagged (verify on your branch).
The six reference documents
| # | Document | What it gives you | Reach for it when… |
|---|---|---|---|
| 1 | Glossary | A–Z definitions of every VMM / KVM / virtio / Firecracker term in the curriculum, each 1–3 lines, with a link to the chapter that covers it | A term in an issue, PR, log line, or swagger.yaml is unfamiliar, or you want the one-sentence version plus where to go deep |
| 2 | Key Types by Crate | The "where does X live" map: for each crate and vmm module, a table of the key Rust types, their one-line role, and the rg that finds them | You have a behavior and need the type, or a type name from a panic/backtrace and need to know which crate/module owns it |
| 3 | API Endpoint Map | The full REST surface over the Unix socket: every endpoint, its methods, an example JSON body, and which level/deep-dive covers it | You are scripting the API, tracing a PUT from the socket to a VmmAction, or checking whether an endpoint is pre-boot or runtime |
| 4 | KVM ioctl Cheat-Sheet | Every key /dev/kvm ioctl by fd level, what it does, its kvm-ioctls wrapper, and the VcpuExit reasons table | You are reading the vCPU run loop, writing a minimal KVM VMM by hand, or decoding a VM exit |
| 5 | Memory Layout Cheat-Sheet | The x86_64 and aarch64 guest-memory maps: every layout constant, an ASCII memory map, and where each region comes from | You are tracing the boot sequence, debugging a kernel that won't load, or placing a device on the MMIO bus |
| 6 | Firecracker vs. Other VMMs | The full multi-dimensional comparison — Firecracker vs QEMU, Cloud Hypervisor, gVisor, Kata, runc, unikernels — plus the trade-off prose | Someone asks "why not just use QEMU," you are writing a design justification, or you need to place Firecracker in the isolation landscape |
How the appendix relates to the rest of the book
The curriculum has several layers, and the appendix indexes all of them:
flowchart LR
A["Appendix<br/>(look up)"] --> LV["level-1..9/<br/>(graded curriculum)"]
A --> DD["deep-dives/<br/>(26 internals chapters)"]
A --> RV["rust-vmm/<br/>(the crates beneath FC)"]
A --> MC["masterclass/<br/>(feature intensives + labs)"]
A --> EN["engineering/<br/>(scale & design problems)"]
A --> GOV["release-governance/<br/>(how FC is run)"]
- The levels (
../level-1/index.md…../level-9/index.md) are the graded, hands-on spine: build → onboard → architecture → KVM → testing → boot → virtio → real issues → advanced maintainer. - The deep dives (
../deep-dives/index.md) are the internals reference: 26 chapters mirroring the request path, the boot path, the device model, and the security model. The glossary and key-types map point here most often. - The rust-vmm chapters (
../rust-vmm/index.md) cover the shared crates below Firecracker:kvm-ioctls,kvm-bindings,vm-memory,linux-loader,virtio-queue,vm-superio,event-manager,seccompiler,vmm-sys-util. - The masterclasses (
../masterclass/index.md) are feature-by-feature intensives with runnable labs — KVM & vCPUs, the boot process, virtio devices, snapshotting, security, networking, debugging, performance. - The engineering chapters (
../engineering/index.md) cover the real design problems: snapshotting at scale, oversubscription, I/O engines, the minimal-device-model philosophy, boot-time optimization.
How to use these while contributing
The appendix earns its keep in the middle of real work. A few concrete patterns:
You hit an unfamiliar term in an issue or PR. Start in the Glossary. Get the one-sentence version, then follow the chapter link only if you need to go deep. Most terms resolve in ten seconds.
You have a panic or backtrace and need to orient. Take the most specific type
name and look it up in Key Types by Crate. That tells
you which crate and vmm module owns the failure and which chapter explains it —
so you read the right 2,000 lines, not all of them.
You are scripting or tracing the API. Open the
API Endpoint Map, find the endpoint, copy the example
body, and follow it to the level/deep-dive that traces the path from the socket
through ParsedRequest → VmmAction → the VMM thread.
You are reading the vCPU run loop. Keep the
KVM ioctl Cheat-Sheet open: decode the ioctls, then
the VcpuExit reason the loop is dispatching on.
You are debugging a boot or placing a device. Open the
Memory Layout Cheat-Sheet and classify every
guest physical address against the map — then verify the constant in
arch/<arch>/layout.rs on your branch.
Someone challenges the design. Cite Firecracker vs. Other VMMs — it is the reference for "why a minimal VMM," "why not QEMU," and "where Cloud Hypervisor, gVisor, and Kata fit instead."
The verification reflex
Three commands settle almost every "is this still true?" question. From a Firecracker source checkout:
# Confirm a type still exists and see its module / role:
rg -n "struct Vmm\b|pub struct Vmm\b" src/vmm/src/
# Confirm an ioctl wrapper / exit reason in the rust-vmm dep:
cargo doc -p kvm-ioctls --open # then browse VcpuFd / VcpuExit
# Confirm an API endpoint and its body shape from the spec, not memory:
rg -n "boot-source|machine-config|/snapshot/" src/firecracker/swagger/firecracker.yaml
From the GitHub side:
# Has this endpoint/field/constant changed recently? Read the CHANGELOG and PRs:
rg -n "snapshot|machine-config|cpu-template" CHANGELOG.md
gh pr list --repo firecracker-microvm/firecracker --search "machine-config" --state merged
Keep this appendix open in one pane and your checkout in another. The reference is
fast; the rg/cargo doc/gh is authoritative. Use both.
Next: start with the Glossary for the vocabulary, then jump to whichever reference your current task needs. If you are new to the curriculum, read the Introduction and Overview first.