Skip to content

The Toolbox headers

include/ has the Toolbox headers. Include them the way Apple's Universal Interfaces are included (#include <Quickdraw.h>, <Windows.h>, <Events.h>, ...) or all at once with <Multiverse.h>. The same headers work for both targets:

clang --target=m68k-apple-macos     -O2 -Iinclude -c hello.c   # 68k
clang --target=powerpc-apple-macos9 -O2 -Iinclude -c hello.c   # PowerPC
  • On 68k, Toolbox calls are pascal functions whose calls become their trap words (__attribute__((raw_inline(...)))). Register-based traps (most OS traps, such as NewPtr, Gestalt and Delay) are inline functions that load the registers and emit the trap.
  • On PowerPC, the calls are plain declarations that the linker imports from InterfaceLib and the other shared libraries.
  • Records use 68k alignment on both CPUs, as on a real Mac, so they have the sizes Inside Macintosh gives (tests/sizes.c checks them).
  • 32-bit types are long, as in Apple's headers, so existing code that passes long * compiles unchanged.

examples/hello.c uses them; built as a fat application it runs on every System we have, from System 0.1 on the Mac 128K to Mac OS 9.2.1 on PowerPC, in emulators (MAME, QEMU and SheepShaver).

Old routine names

Code written before 1993 uses the original names (GetCtlValue, DisposPtr, GetDItem, SetCTitle, IUGetIntl, TextBox, ...). Compile with -DOLDROUTINENAMES=1 and they map to the current ones, as with Apple's interfaces; 92 names are covered.

Where they come from

The headers are generated by tools/gen-headers.py from the API definitions in defs/, which come from Multiversal Interfaces (MIT license, defs/COPYING.multiversal). Those were derived from the clean-room Executor project, not from Apple's headers, so they can be redistributed freely. To regenerate after changing a definition:

pip install pyyaml
python3 tools/gen-headers.py

Since then the definitions have been extended here with the rest of the documented Toolbox: the Component, Display, Text Services, Power, Slot, SCSI, Cursor Device, MIDI, Dictionary and Data Access Managers, the PPC Toolbox, AppleTalk (MPP, ATP, NBP, ZIP, ASP and AFP), Ethernet, the Communications Toolbox (Connection, Terminal and File Transfer Managers, the Communications Resource Manager and the CTB utilities), the HFS Plus API and more.

The QuickTime definitions (defs/QuickTime.yaml, after the first 21 calls) are different: tools/mpw2defs.py generated them from Apple's QuickTime 1.5 C interfaces on the Developer CD Series (1992). It parses the headers with clang, so the records, constants and each call's inline 68k code are what Apple's compiler saw, and writes them as definitions; Apple's headers themselves are not in this repository. Point the tool at your own copy to regenerate them:

CLANG=clang python3 tools/mpw2defs.py -I path/to/CIncludes -I path/to/QuickTime \
    -o defs/QuickTime.yaml ImageCompression.h Movies.h MoviesFormat.h \
    QuickTimeComponents.h MediaHandler.h ImageCodec.h

Checked against a real ROM

The 68k trap words and selectors are checked against the Mac OS ROM. A Power Macintosh ROM contains InterfaceLib, whose PowerPC glue calls each 68k trap through the Mixed Mode Manager; that glue names the trap, the selector and where each argument goes.

  • tools/trapinfo.py ROM > data/trapinfo.json reads that glue (from a 4 MB OldWorld ROM image, such as the Beige G3's) and records each call. The checked-in data/trapinfo.json came from the Beige G3 ROM.
  • tools/check-traps.py compares every call in the headers with it. All 1,960 calls that the ROM and the Mac OS 8 and 9 libraries describe match.
  • tools/add-protos.py defs/X.yaml < protos.h turns C prototypes into definitions, with the 68k details from data/trapinfo.json, and refuses a prototype whose argument sizes disagree with the ROM. tools/add-types.py does the same for records and constants.
  • tools/blockinfo.py ROM > data/blockinfo.json does the same for the Communications Toolbox calls, which pass their arguments as a block (laid out like Pascal arguments under a selector word, with A0 pointing at it) to _CommToolboxDispatch. It records the selector and each argument's offset and size; tests/blocks.py checks all 166 such calls in the headers against it. It needs llvm-mc with the PowerPC target.
  • tools/check-mpw.py path/to/CIncludes [more dirs] compares the 68k code of every call with the inline code in Apple's MPW C interfaces (the trap word, and the selector loaded before it, however it is loaded). Against MPW 3.2's interfaces (June 1992) and QuickTime 1.5's, all 2,105 calls both declare match; the 18 MPW calls it reports missing have C or glue equivalents here (the low-memory accessors, Fix2X and friends).
  • tools/coverage.py writes docs/coverage.md.

Calls with no trap of their own get their 68k glue as inline C in the headers (m68k-body in the definitions; tools/set-body.py adds it). The AppleTalk calls set the driver and control code and call PBControl, as the ROM's PowerPC glue does; the high-level File Manager, Device Manager and serial calls fill in a parameter block; the lowercase C-string calls (fsopen, getwtitle, ...) convert their strings and call the Pascal routine. The glue avoids memcpy, memset and 32-bit multiplies, so the headers work without the runtime library (BlockMoveData copies instead). The exceptions are the FixMath conversions between Fixed or Fract and floating point (Fix2X, X2Fix, Frac2X, X2Frac) and the 64-bit wide arithmetic (WideAdd, WideMultiply, WideDivide, ...), which use soft float and 64-bit helpers and so need the runtime library (X2Fix and X2Frac round to nearest and saturate, as SANE does). The wide calls follow QuickDraw GX's documentation, where they came from: WideDivide and WideWideDivide round the quotient when given no remainder, a WideDivide quotient that does not fit is pinned to 0x7FFFFFFF or 0x80000000, WideShift rounds a right shift and WideBitShift does not, and WideSquareRoot takes an unsigned value (its root is rounded to nearest, which the documentation does not say). SetUpA5 and RestoreA5 keep the saved A5 in a common block of 32 slots rather than on the stack as MPW's do, since clang addresses locals from SP; they nest, also from interrupts, up to 32 deep. The Power Manager extras (BatteryStatus, ModemStatus and the wakeup timer) send the same _PMgrOp commands as MPW's glue (from the 1992 Interface.o), and SetSoundVol makes the same control call to the Sound Driver. TESetWordBreak and TESetClickLoop take a pascal Boolean function, as MPW's did, and install a trampoline that TextEdit calls with its arguments in registers and its answer in the Z flag; each call site has its own trampoline and remembers one function. StartSound plays synchronously when given no completion routine, and otherwise writes to the Sound Driver asynchronously with one of 8 parameter blocks shared by every call site (it waits when all 8 are in use); StopSound kills the requests and calls the completion routines that did not run, and SoundDone says whether any request is left. The Component Manager 3 calls (QuickTime 2.5 and later: OpenAComponent, GetComponentResource, ...) use the selectors of Apple's Universal Interfaces 3.x, and TempInsertROMMap sets the low-memory globals as their inline code does. Glue that keeps state, or a trampoline, reaches it with 32-bit addresses, so it works in programs of any size. include/needs-glue.txt lists what is left: mostly calls that never ran on 68k (Navigation Services, Driver Services, the Name Registry).