SPDK Learning Plan · v26.01

Understanding SPDK,
layer by layer.

A curriculum for the diskengine maintainer who wants SPDK to stop being a black box and start being a tool you understand. Built around your code, your bugs, and your goal of writing a bdev module from scratch.

~30 explainers 10 layers Polished HTML, no exercises Annotated C walkthroughs

How to use this site

Start at Layer 0 (the primer) if SPDK is "magic C that does disks fast" to you today. The primer is short — three explainers, ~30 minutes total — and it builds the vocabulary the rest of the curriculum assumes.

From there, the layers are layered outside-in: you go from "what is SPDK" down to "how a VM gets its disk" and finally "how to write a bdev module from scratch." Each explainer is self-contained — you can read in order, or jump to whatever's blocking you.

Where you are vs where you want to be

Now

You call JSON-RPC, things happen.

You've heard of bdev, lvol, nvmf, vhost but can't trace a single I/O through them.

Polling vs interrupts, reactors, and "you must be on the right thread" are folklore, not knowledge.

Bugs like the VFIO/QMP quit wedge feel mysterious.

Target

You can read module/bdev/passthru and explain every line.

You know which thread an RPC handler runs on and why.

You understand why the QMP wedge happens, not just that it happens.

You can extend diskengine with new SPDK-backed features confidently.

The curriculum at a glance

Ten layers, ~30 explainers. Each one is a page in the sidebar. Click any to start reading.

Layer	What you'll learn	Pages
Layer 0	Prerequisite primer — userspace I/O, NVMe hardware, poll vs interrupt	3
Layer 1	What SPDK is and how the v26.01 repo is laid out	2
Layer 2	The reactor, spdk_thread, io_channel, threading rules	4
Layer 3	How your Go spdkclient talks to SPDK's C — JSON-RPC end-to-end	2
Layer 4	The bdev framework — the plugin model at the heart of SPDK	4
Layer 5	lvol — thin provisioning, snapshots, copy-on-write	4
Layer 6	nvmf — NVMe-oF, the path that exposes volumes over the network	4
Layer 7	vhost / virtio / VFIO-user — and the QMP quit wedge	4
Layer 8	Write a bdev module — the "from scratch" path, distilled	3
Layer 9	Operations & debugging — spdk_top, tracing, failure retrospectives	3

The format of an explainer

Every explainer is one self-contained page. They have the same anatomy: an eyebrow with the layer, a big title, a lede, and a "table of contents" near the top so you know what's coming. After that, the body alternates between concept (plain prose with diagrams) and annotated C source (real code from the SPDK repo with line-by-line commentary).

Diagrams are interactive: zoom with scroll, drag to pan, double-click or the ↗ button for fullscreen. They use Mermaid, rendered client-side. You can read the same content fine on a phone — the layout reflows.

Where things live

Every explainer is an MDX file at src/pages/<layer>/<slug>.mdx in this Astro project. The compiled site lives in dist/ after you run npm run build. The source repo (SPDK, in spdk_v26_01_migration/) is referenced but not modified.