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
pascalfunctions whose calls become their trap words (__attribute__((raw_inline(...)))). Register-based traps (most OS traps, such asNewPtr,GestaltandDelay) 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.cchecks them). - 32-bit types are
long, as in Apple's headers, so existing code that passeslong *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:
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.jsonreads that glue (from a 4 MB OldWorld ROM image, such as the Beige G3's) and records each call. The checked-indata/trapinfo.jsoncame from the Beige G3 ROM.tools/check-traps.pycompares 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.hturns C prototypes into definitions, with the 68k details fromdata/trapinfo.json, and refuses a prototype whose argument sizes disagree with the ROM.tools/add-types.pydoes the same for records and constants.tools/blockinfo.py ROM > data/blockinfo.jsondoes 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.pychecks all 166 such calls in the headers against it. It needsllvm-mcwith 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,Fix2Xand friends).tools/coverage.pywrites 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).