# system.img — the boot capsule ## What it is `boot/system.img` is the **boot capsule**: every bundled user binary — init, the services, the drivers, the test programs — packed into **one file** on the boot volume. It is not a filesystem image and it is not compressed; it is exactly the kernel's **initial-ramdisk wire format** (`system/initial-ramdisk.zig`, format v2), written to disk ahead of time. The EFI loader reads it in a single sequential pass and hands the bytes to the kernel unmodified. The capsule is a *performance artifact*, not a source of truth. The boot volume's `/system` and `/test` file trees remain the canonical layout (see [file-system-hierarchy.md](../file-system-development/file-system-hierarchy.md)); the capsule is a pre-baked snapshot of the same binaries, derived from the same build graph, so the running system is identical whether the loader read the capsule or walked the tree. ## Why it exists Firmware file I/O has exactly one fast shape: **one open + one sequential read**. Everything else is a lottery. Loading the system per-file — dozens of opens, seeks, and short reads through the firmware's FAT driver — measured **minutes** on real hardware, against milliseconds in QEMU/OVMF. Packing the binaries into a single file turns the whole of user space into the shape firmware is good at. Because the capsule already *is* the ramdisk wire format, the loader doesn't even repack it: `loadCapsule` (`boot/efi.zig`) validates the magic and passes the buffer straight through as `BootInformation.initial_ramdisk_base`/`len`. ## The format The container is deliberately trivial — danos owns both producer and consumer, so it need be no fancier. Little-endian throughout: ``` Header magic: u32 = "DNR2" (0x32524E44), count: u32 Entry × count name: [64]u8 (NUL-padded hierarchy path), offset: u64, len: u64 blobs... each entry's file bytes, at its offset within the image ``` - **Names are full hierarchy paths** (`/system/services/init`), not basenames — that is what "v2" means. The 64-byte capacity matches `abi.maximum_process_name`, so a task named after its binary path is never truncated. Paths longer than 63 bytes are a build error (`pack-system-image.py` rejects them). - **The v1 magic (`"DNRD"`, basename entries) is rejected**, not tolerated: a stale image should fail loudly at `Reader.init`, not misparse names. - `initial_ramdisk.Reader` is the one validated view over the bytes — magic check, table bounds, per-blob bounds — used by the kernel and shared with the loader. `Reader.find` resolves a binary by exact path first, then by unique basename, ASCII case-insensitively (the entries come from a FAT volume, whose name lookups are case-insensitive by definition). ## How it is built `build.zig` maintains one `bundled` list — every user binary and its hierarchy home. Three artifacts are derived from that same list, in the same build graph, so they cannot drift apart: 1. **The tree**: each binary installed at its hierarchy path (`zig-out/system/...` and `zig-out/test/...`, mirrored onto the FAT boot volume by `tools/make-fat-image.py`). 2. **The manifest** (`system/manifest`): the hierarchy path of every bundled binary, one per line — the loader's per-file fallback input. 3. **The capsule**: `tools/pack-system-image.py` packs the same binaries into the v2 container, installed at `zig-out/boot/system.img` and placed on the boot volume at `boot/system.img`. Note what the capsule does *not* contain: the kernel (`system/kernel` is loaded separately by `loadKernel`, as an ELF) and the EFI loader itself. It is user space only. ## How it is loaded `loadSystemTree` (`boot/efi.zig`) tries three strategies, most portable first — the running system cannot tell which one ran, because all three produce the same in-RAM ramdisk image: 1. **The capsule** — open `boot\system.img`, read it whole, check the magic, hand it over as-is. The normal path on any build-produced volume. 2. **The manifest** — read `system\manifest` and open each listed path *by name*. FAT name lookup is case-insensitive and firmware-portable, unlike directory enumeration. The loader assembles the v2 image in RAM itself. 3. **The tree walk** — enumerate `/system` and `/test` recursively (`/test` is optional: a stick without fixtures still boots). Last resort for hand-assembled sticks with neither file: some firmware FAT drivers return bare 8.3 names uppercase from enumeration, which is why this is the fallback and not the primary path. All three are best-effort: a **kernel-only volume still boots** — the kernel just has no user binaries to spawn and reports the absence. One operational consequence of the ordering: the capsule *shadows* the tree. If you hand-edit binaries on a stick that also carries a `boot/system.img`, your edits are invisible — the loader boots the capsule's snapshot. Delete `boot/system.img` from the volume to force the manifest/tree path. ## What the kernel does with it The loader records the image's physical base and length in `BootInformation`; the kernel (`kernel.zig`) then publishes the same bytes twice, to two consumers: - **The process layer** (`process.zig`): `system_spawn` looks binaries up in the ramdisk via `Reader.find` — exact hierarchy path, or unique basename for pre-path callers — and loads them as fresh ring-3 processes. The stored path becomes the task's name. - **The VFS root** (`vfs.zig`, `setInitialRamdisk`): the image is mounted as kernel-backed, read-only mounts — one per top-level tree named by the entry paths, so `/system` and, when the fixtures are bundled, `/test`. Directory nodes are derived from the entry paths (the unique parents), so the trees are listable and their files readable over the normal VFS protocol — the boot tree every process sees comes straight out of the capsule bytes. The image is never copied after the handoff and never mutated: the initrd is immutable, which is what makes the VFS's node serving lock-free. ## What it is not - **Not `danos-usb.img`.** That is the 64 MiB FAT32 *boot volume* built by `tools/make-fat-image.py` — the thing a machine actually boots, which *contains* `boot/system.img` alongside the loader, kernel, manifest, and tree. See [efi.md](efi.md) and [release-iso.md](release-iso.md). - **Not a mountable filesystem.** No FAT, no block device, no driver — just a header, a table, and concatenated blobs, parsed by ~90 lines of `initial-ramdisk.zig`. - **Not required.** It is the fast path, with two slower equivalents behind it. - **Not a place where state lives.** It is regenerated on every build from the bundled binaries; nothing writes to it, at build time or runtime.