tbxi/README.md
2019-08-04 21:07:05 +08:00

70 lines
2.5 KiB
Markdown

# `tbxi`: the Mac OS Toolbox Imager
`tbxi` is a command-line Python script to help with the inspection and
modification of Macintosh Toolbox ROM images. These images contain
varying amounts of high-level Mac OS code and low-level boot code.
`tbxi` has two modes, both with a `--help` option:
- `tbxi dump` converts a ROM image to a tree of self-describing text
files and small binaries.
- `tbxi build` rebuilds the image as accurately as possible.
In between running the two commands, the directory tree can be modified.
The text-file formats produced by `tbxi dump` are designed to be easily
editable using text editors and scripts.
## Patch Library
This repository contains known-good scripts to patch the ROM, for
example to add Mac mini G4 support to Mac OS 9:
https://github.com/elliotnunn/tbxi-patches
Patches can be applied to a dumped directory or the the ROM file itself.
## Background
"OldWorld" (pre-USB) Macs contain a real physical ROM. "NewWorld" Macs
(iMac and later) have an unusual "ROM in RAM" arrangement, which retains
compatibility with the ROM-based architecture of the Mac OS while easing
software updates. An almost-complete legacy ROM image is loaded from the
"Mac OS ROM" file in the System Folder (type code 'tbxi'), leaving only
a minimal Open Firmware "Boot ROM" in the hardware.
During the progression from 68k ROMs to NewWorld PowerPC ROMs, multiple
layers of wrapping and abstraction were added. These are reflected in
the multi-level output of `tbxi dump`:
- Open Firmware bootinfo file (`Mac OS ROM` => `Bootscript` textfile + binaries)
- structured binary of "Parcels" (`Parcels` => `Parcelfile` textfile + binaries)
- 4 MB PowerPC ROM (`MacROM` => `Configfile-1` textfile + binaries)
- 3 MB 68k ROM (`Mac68kROM` => `Romfile` textfile + binaries)
## Bugs
Some very quirky PowerPC OldWorld ROMs (e.g. PowerBook 1400/2400) cannot
be rebuilt correctly. NewWorld ROMs of version 2 or later (Sawtooth G4)
will be slightly different due to an uninitialised buffer in the
original build process.
ROM images predating before the "SuperMario" ROM (Quadra 660AV/840AV)
are not supported, excluding most 68k Mac ROMs.
The `tbxi dump` format is likely to change. If you keep a collection of
dumped ROM images to peruse, re-dump them regularly.
## Contributing
Yes please! Bug reports, suggestions and requests are welcome. Open a
GitHub pull request or image, or get in contact via the email on the
PyPI page.
All are welcome on our retro Mac-hacking mailing list:
https://lists.ucc.gu.uwa.edu.au/mailman/listinfo/cdg5