docs: catch the docs up with the finished package split

The plan doc's status records completion (all waves + phase 3) and its
execution notes describe the finished shape; the fresh-session pointer
names build-support's userBinary instead of the deleted
addUserBinaryImpl, and the size-check carry-along note is discharged.
README gains the build/ directory in the layout tree and splits the
source-map row across root build.zig / build/images.zig /
build/qemu.zig. testing.md points at the distributed per-package test
steps; threading.md, threading-plan.md, driver-model.md, efi.md,
display.md, system-requirements.md, and devices-csv.md's adding-a-
driver checklist stop describing the pre-package build.
This commit is contained in:
Daniel Samson
2026-07-30 04:24:34 +01:00
parent 3f9b6813f7
commit d03942b543
10 changed files with 73 additions and 53 deletions
@@ -96,7 +96,12 @@ in different namespaces — against the right `bus` column.
## Adding a driver
1. Build the driver binary and bundle it at `/system/drivers/<name>` (build.zig).
1. Create `system/drivers/<name>/` with the driver source plus a ~15-line
package `build.zig` + `build.zig.zon` (copy an existing driver package,
e.g. `system/drivers/pci-bus/`; per-driver extras go through
`build_support.programModule`). Then bundle it at `/system/drivers/<name>`:
one dependency + one bundled entry in the root `build.zig`, one line in the
root `build.zig.zon`.
2. Add a row to `etc/devices.csv` naming the identity it binds and its full path.
No device-manager change is required — the registry is the seam.
+1 -1
View File
@@ -29,7 +29,7 @@ which one you're holding decides what you can do.
- **The PCI class-0x03 device is the raw controller** — BARs, config space, registers,
IO ports. It is what you actually *own* after boot. On QEMU's emulated adapter
([`-device VGA,edid=on`](../../build.zig), the Bochs VBE/DISPI model) the `base` GOP handed
([`-device VGA,edid=on`](../../build/qemu.zig), the Bochs VBE/DISPI model) the `base` GOP handed
you *is* that device's linear-framebuffer BAR — the same physical memory, seen through
a different door. On a real discrete GPU, GOP's `base` is an aperture inside the GPU's
VRAM BAR. danos already decodes this device
@@ -145,9 +145,8 @@ The build side of this has since landed: the shared recipe in
device/service clients (`driver`, `block`, `display`, `input`), plus `mmio`,
`xkeyboard-config`, `acpi-ids` — into every user binary, and per-binary extras —
protocol modules, bus logic — are added with `programModule(exe).addImport(...)`.
Most binaries are still built by the root `build.zig`'s stanzas through that recipe;
a binary can instead own a package with its own ~15-line `build.zig` (pci-bus is the
first — see [build-packages-plan.md](../build-packages-plan.md)). That's the *entire*
Every binary owns a package with its own ~15-line `build.zig` calling that recipe
(see [build-packages-plan.md](../build-packages-plan.md)). That's the *entire*
mechanism — Zig modules already give you everything else.
The discipline that makes this work: **a class driver must not import a bus's *hardware*