Glossary

Glossary

Everything on this wiki, defined once. Written to be read straight through — the terms are grouped so that reading a group in order tells a small story, rather than alphabetically, which tells none.

---

Firmware and booting

Open Firmware — the boot firmware Apple used on PowerPC Macs, standardised as IEEE 1275. It is a Forth interpreter with a device tree, and it can be driven interactively from a serial console. It is not a BIOS: it has no fixed entry points at fixed addresses, and an operating system talks to it through a client interface rather than by calling numbered interrupts. Apple's version on this machine reports itself as Open Firmware 2.26NT. → Open Firmware

Device tree — Open Firmware's model of the machine: a tree of nodes, each with properties (name, reg, compatible, …) and methods. /bandit@F2000000/53c825@12/sd@0,0 is a path through it, naming a SCSI disk behind a PCI bridge.

Client interface — the handful of functions Open Firmware exposes to a program it has loaded: find a device, open it, read, write, seek, get a property, claim memory. Everything the firmware does for a loaded OS goes through it.

Forth — the language Open Firmware is written in and interpreted from. You will meet it if you ever type at the 0 > prompt. Postfix: " /bandit/53c825@12/sd@0,0" open-dev pushes a string and calls a word.

ARC — Advanced RISC Computing. The firmware standard Windows NT expects on a non-x86 machine: a configuration tree describing the hardware, a firmware vector table of functions the loader can call, a set of environment variables telling it what to boot, and NVRAM to keep them in. NT's PowerPC edition assumes ARC absolutely. → ARC

ARC path — how ARC names a device, e.g. multi(0)scsi(1)disk(0)rdisk(0)partition(2). Read it as a route down the configuration tree: adapter, controller, disk, unit, partition.

The veneer — VENEER.EXE, written by FirmWorks for Microsoft. A program that runs on top of Open Firmware and presents an ARC firmware to whatever it loads: it converts the device tree into a configuration tree and implements the ARC vector table over the client interface. On this machine it is the reason NT can boot at all. → The veneer

PReP — PowerPC Reference Platform. IBM and Motorola's PowerPC machine standard, which included ARC firmware. NT 4.0's PowerPC edition shipped for PReP machines. Apple's Power Macs are not PReP, which is the root of everything on this wiki.

CHRP — Common Hardware Reference Platform, the later joint standard that used Open Firmware. Too late for NT 4.0.

OSLOADER.EXE — NT's operating-system loader on ARC machines: the equivalent of NTLDR on a PC. Reads its parameters from ARC, opens the boot partition, loads the registry's SYSTEM hive, loads the boot drivers, and hands control to the kernel. → The NT boot chain

SETUPLDR — the same loader, in the form that boots NT's installer from the CD.

---

Windows NT internals

HAL — Hardware Abstraction Layer, HAL.DLL. The module that knows what the machine actually is: interrupt controller, timers, bus access, DMA, the clock. NT's kernel is written against the HAL's interface so that one kernel binary runs on many machines. Writing one is what this project is. → The HAL contract

Bugcheck — the blue screen. A kernel-detected fatal error, with a code and four parameters, e.g. 0x50 PAGE_FAULT_IN_NONPAGED_AREA. → Decoding a bugcheck

IRQL — Interrupt Request Level. NT's priority scheme for interrupt masking. Unusually, on PowerPC the HAL owns it and stores it in the PCR; the kernel asks the HAL to raise and lower it.

PCR — Processor Control Region. A per-processor structure at a fixed address holding, among much else, the current IRQL and the table of interrupt-dispatch routines the HAL fills in.

Loader block — the structure OSLOADER.EXE hands the kernel: where every loaded module is, what memory exists, what the firmware's configuration tree looked like, which device was booted from.

Memory descriptor — one entry in the loader block's list of physical memory ranges, each with a type (free, system code, firmware-reserved, …). The kernel builds its physical-memory map from these — which is why a HAL can influence what NT believes is RAM.

Miniport — a small, hardware-specific driver that plugs into a generic NT port driver. symc810.sys is a SCSI miniport under SCSIPORT.SYS; cirrus.sys is a video miniport under videoprt.sys.

videoprt.sys — NT's video port driver. Owns resource arbitration and talks to a miniport below it and a display driver above it. → The NT video stack

Text-mode Setup / graphics-mode Setup — NT 4.0 installs in two stages. The first is the blue character-mode installer that partitions, formats and copies files. The machine then restarts and the second, graphical stage runs from the installed system. Getting to the second is the current goal.

Hive — a registry file. \WINNT\SYSTEM32\CONFIG\SYSTEM is the one the loader must read before the kernel can start, because it lists the boot drivers.

---

PowerPC

PowerPC 604 / 604e — the processors in these machines. 32-bit, big-endian by default, with an optional little-endian mode.

Little-endian mode — NT runs PowerPC little-endian. The 604 implements this not by swapping data but by munging addresses: a byte access to address A is routed to physical A ^ 7, a word access to A ^ 4. Everything that touches memory from outside the CPU — DMA, a debugger, a bridge — has to agree with that view or you get nonsense. → Little-endian PowerPC

Address munging — the ^ 7 / ^ 4 above. The single most common source of "impossible" off-by-four bugs on this project.

MSR — Machine State Register. Holds, among other bits, LE (little-endian) and IR/DR (instruction and data address translation on/off).

SRR0 / SRR1 — where the processor saves the faulting instruction's address and the MSR when it takes an exception. SRR0 is how you find out which instruction faulted.

DAR / DSISR — Data Address Register and its status register: the address a faulting memory access referenced, and why it failed.

BAT — Block Address Translation register. Maps a large, aligned region of physical memory without page tables. There are only four data BATs, which is a real constraint when a machine has 256 MB of device space.

KSEG0 — the kernel virtual region that maps straight onto physical memory with a fixed offset (0x80000000 here). If an address starts 0x8…, subtracting 0x80000000 usually gives you the physical one.

Function descriptor — on NT PowerPC, a "pointer to a function" is really a pointer to a two-word structure { entry, toc }. Calling through it means loading both. → The NT PowerPC ABI

TOC — Table Of Contents. A per-module table of pointers, addressed relative to register r2. Every module has its own, and r2 must be correct for the module currently executing.

SVR4 ABI — the System V PowerPC calling convention, which is what a Linux-targeted compiler emits. It disagrees with NT's convention about who owns which bytes of a stack frame, and that disagreement caused one of the longest-lived bugs in this project.

Import glue / thunk — the few instructions that sit between a call and its target across a module boundary, loading the callee's TOC and jumping to it.

---

Apple hardware

TNT — Apple's internal name for the chipset generation used by the Power Macintosh 7500/8500/9500 and the Network Server. → The PowerMac TNT family

Shiner — Apple's codename for the Network Server logic board. The HAL is named HALSHINR.DLL after it.

Bandit — the PCI host bridge. This machine has two, each rooting its own PCI bus. Notably it has an endian bit that reverses byte lanes so that a little-endian CPU sees PCI correctly.

Grand Central — the I/O controller: the interrupt controller, DBDMA channels, serial, floppy, Ethernet, sound, and the VIA that Cuda hangs off.

Hammerhead — the memory controller. The firmware configures it; a HAL does not have to.

Cuda — a small microcontroller reached over a VIA, responsible for ADB (keyboard and mouse), the real-time clock, PRAM, and system reset.

ADB — Apple Desktop Bus. Apple's keyboard and mouse bus. NT has no ADB driver of its own, which is why a keyboard was a project of its own here.

DBDMA — Descriptor-Based DMA, Apple's DMA engine programming model in Grand Central.

IDSEL — the PCI signal that selects which device responds to a configuration cycle. On these bridges it is encoded in the configuration address, which is why config access looks unusual.

53C825A — the Symbios/NCR SCSI controller. The Network Server has two.

Cirrus 54M30 — the on-board PCI video chip, a CL-GD5430-class part. NT's cirrus.sys supports the family; the HAL also drives it directly for its own console.

ESCC / ttya — the serial controller and the port used as the firmware and debug console. Almost every trace on this project came out of it.

---

This project

Granny Smith — the Macintosh emulator this HAL is developed against. It models the TNT hardware well enough to run Open Firmware, the veneer and NT. → Getting Granny Smith

Checkpoint — a saved emulator state. Because a cold boot to Setup's menus takes many minutes, nearly every experiment starts from one. → Checkpoints and deltas

Delta — the copy-on-write file a checkpoint load creates for each writable disk image. Edits to the base image on disk are never read once a checkpoint exists; the delta is the disk.

Wall — this project's unit of progress: one obstacle, numbered in the order it bit, written up with the symptom, what it actually turned out to be, and what the fix bought. There are forty-nine so far, in STORY.md.

The ledger — the table of everything currently in the loop that is a workaround rather than a fix, kept so that none of them is quietly forgotten. → The ledger of workarounds