Project Contributing

Contributing

This page owns: the rules, especially the two that are not negotiable.

Patches are welcome. The authoritative text is CONTRIBUTING.md in the repository; this page explains why each rule exists, which is the part that makes them easier to follow.

Two rules are absolute, because the project cannot be published without them. Everything else is ordinary taste.

---

Rule 1 — provenance is logged at the time it is borrowed

PROVENANCE.md has one row per file or function that is not original work: where it came from, under what licence, and how much was taken — verbatim, adapted, or rewritten from reading.

• The row goes in the same commit as the code. Never reconstructed afterwards, because a reconstruction is a guess.
• A pull request that adds code without a row is not merged.
• Rows are append-only. Removing borrowed code adds a row saying so.

Why this is not bureaucracy: the project's licence is derived from that table. GPL-2.0 is a consequence of having learned the HAL's shape from GPL-2.0 source, and a missing row makes the licence of the whole work unknowable.

Rule 2 — clean room: no leaked Microsoft source, ever

Everything here is derived from:

• the DDK-documented Hal* contract,
• the export and symbol tables of shipped binaries — several of which ship with their own COFF symbols,
• observed behaviour under a debugger,
• hardware documentation from Apple, Motorola, Symbios, Zilog and Cirrus.

The leaked Windows NT source trees are not consulted and must not be. If you have seen them, you cannot contribute to the files they would inform. Each source file's header states this; keep it accurate.

Reading a shipped binary to learn an interface is normal engineering and is exactly what the provenance rows record. → Reading NT binaries

---

What must never be committed

	Why
Microsoft binaries — VENEER.EXE, SETUPLDR, HAL*.DLL, NTOSKRNL.EXE, anything off the CD	proprietary. Cite by name and origin
Microsoft DDK/SDK headers or PowerPC import libraries	the EULA permits building with them, not redistributing them. This build does not need them
Apple, Symbios, Motorola or Cirrus documentation, or extracted text	proprietary. Cite chapter and section
maciNTosh's NT binaries (halgoss.dll, usbadb.sys, …)	GPL-2.0 with no published source, so §3 cannot be satisfied. Reading one locally is fine; redistributing is not
ROMs, CD images, disk images, checkpoints	inputs you supply, not project content

.gitignore carries patterns for these as a backstop, not a policy.

---

Contributing to this wiki

The wiki is its own repository — powermac-nt-hal.wiki.git — and a commit to it publishes immediately: no pull request, no review, no CI. If you do not have write access, the way in is an issue on the main repository. Corrections are welcome and are usually the most valuable kind, because nothing else catches an error here.

Three conventions:

• The wiki owns durable explanation; the repository owns anything version-locked. Code, the wall-by-wall narrative, the ledger and the provenance log live in the repo and are linked, not copied.
• Links out of the wiki must be absolute. A repository-relative path like ../STORY.md resolves in a local checkout and breaks on the published page.
• The never-commit list above applies here too — and with nothing between a commit and the live page, it applies with no safety net.

Screenshots of our own emulator output are fine.

---

Style

Match what is there. A few things that are load-bearing rather than taste:

• Every claim names its source — a thread post, a document and section, a chip manual, or a file in traces/.
• Dead ends are recorded alongside results. Several theories in these documents were wrong within hours, and saying so is the point.
• Workarounds go in the ledger the moment they are introduced. → The ledger of workarounds

---

Testing a change

Before opening a pull request:

make                                                  # builds clean
llvm-objdump -d build/hal.elf | grep -E 'lwbrx|stwbrx|lhbrx|sthbrx'   # prints nothing

If the change touches anything the kernel calls, re-read The NT PowerPC ABI §7's checklist. If it touches byte-at-a-time code, re-read Little-endian PowerPC §5.

Then run it: Iterating on the HAL is a fifteen-minute loop that does not require reinstalling.

---

The most useful contributions right now

1. Trying it on real hardware. Nobody has. → What is known and unknown
2. A video driver or miniport that does not claim the legacy VGA aperture — this retires the one indefensible workaround. → The NT video stack
3. An ADB port driver of our own, so the project stops depending on a binary it may not redistribute.
4. An ARC environment store backed by Open Firmware's nvram.

→ Status and roadmap