Project The story

The story

This page owns: a signpost to the narrative. The story itself lives in the repository.

STORY.md — Every wall, and how it fell — is the account of how this project actually happened: every obstacle, in the order it bit, with the symptom as the machine reported it, what it turned out to be, how that was established, the fix, and what the fix bought.

It is about 1,400 lines and the most-read thing in the repository. If you like reading how something was figured out rather than how it is supposed to work, start there rather than here.

---

How the walls are numbered

A wall is one obstacle. They are numbered in the order they bit and are never renumbered, so a reference from an old document still resolves. Forty-nine so far.

Each gets the same structure — symptom, what it was, how that was found, the fix, what it bought — and a few are marked still open, which is the current truth rather than an oversight.

Crucially, wrong theories are left in. Several of the explanations in those documents were wrong within hours of being written, and recording that is the point: a narrative that only contains correct conclusions teaches nothing about how they were reached.

---

The parts

Part	What it covers
0	The starting line — what the emulator had to do before any HAL existed
1	Getting Setup to ask for a HAL — five firmware walls
2	A PE the NT PowerPC loader will accept
3	The ABI the kernel actually speaks
4	Surviving driver initialisation
5	Storage — four bugs between NT and its own disk
6	Video
7	The keyboard
8	The drive that did not exist
9	A disk with nothing on it
10–11	Installing, and installing for real
12	Booting what Setup installed

Then the ledger of workarounds, what the HAL actually is now, and ten things this taught, that generalise.

---

Where to start if you only read one part

Part 3 — the ABI the kernel actually speaks. It is short, and it is the part most likely to be useful to someone working on an unrelated system: two opposite conventions for the same type, and a stack frame whose first bytes belong to the callee by agreement.

Wall 49, at the end, is the same lesson arriving five days late and costing a week. → The NT PowerPC ABI

---

What generalises

The closing section is the part with the least to do with 1996 hardware. In summary:

• A missing symptom is not evidence. "The interrupt never arrives" was a stubbed allocator four layers up.
• The binary is the specification. Twice, the caller settled a question no header could.
• Make the wrong thing impossible. One _Static_assert on a structure size is the highest-value line in the project.
• Write down which patches you are ashamed of. The difference between a project that can be published and one that quietly depends on eight undocumented pokes.
• Your instrumentation lies too, and you will believe it. → When your instrumentation lies
• A borrowed binary carries assumptions about hardware you both thought you shared.
• Some bugs are cheaper to read than to run into.
• A workaround is only correct in the situation that produced it, and nothing marks where that situation ends. → The ledger of workarounds
• When two ABIs meet, guard the seam in both directions. A comment that states an invariant is an invitation to check every place it applies.

---

The screenshots

traces/ carries one image per Setup screen reached, in order — the hardware list offering "Apple Network Server 500/700", the partition table, the format, \WINNT, Windows NT copying itself onto the disk, and "This portion of Setup has completed successfully."

There is also a blue screen, drawn by the HAL's own framebuffer console, which is the single most on-brand artefact the project has produced.

---

Next

• Status and roadmap — where the story has got to.
• Provenance and credits — whose work it stands on.