zfs-codebase
A guided walkthrough for engineers who want to navigate, understand, and contribute to OpenZFS.
Motivation
Understanding what ZFS stores on disk and understanding how the code that manages those structures works are two different problems. The zfs-ondiskformat project documents the former in detail. This series is intended to cover the latter.
Reading OpenZFS source cold is hard. The codebase spans kernel modules, userland libraries, and command-line tools, and the boundaries between layers are not always obvious from the directory structure. Existing contributor documentation covers build setup and testing, but not where to start reading or how the major code paths connect. This series fills that gap.
Series
- Part 1: Architecture — The mental model to build first: how the foreground path (which accepts writes) and the sync path (which commits them durably) relate. The major layers, their boundaries, and a reading order for the source.
- Part 2: Repository layout — Maps the architecture onto the actual directory tree. What lives in module/zfs/, module/zcommon/, lib/, cmd/, and include/ — and common navigation traps (such as the distinction between portable core and OS-specific glue).
- Part 3: The I/O path — Traces a single write() call from Linux VFS entry through ZPL, DMU, transaction group sync, the ZIO pipeline, and down to the uberblock commit. Covers the key insight: syscall completion and durable pool commit are not the same moment.
- Part 4: Block pointer handling in code — The blkptr_t structure as it appears in the runtime: accessor macros, birth semantics, compression and checksum dispatch. Bridges the on-disk layout documented in zfs-ondiskformat to the code that reads and writes it.
- Part 5: Feature flags — How feature flags are registered, stored on-disk, and checked at import time. The refcount-based state model, the two-stage compatibility check, and what it takes to add a new format-affecting feature.
- Part 6: Contributor guide — A practical developer loop: debug builds, the test pyramid, essential tools (zdb, zhack, zinject, ztest), and a first-patch playbook from clone to submitted PR.