Macintosh Toolbox

Macintosh Toolbox
Original Macintosh logic board 630-0101; the Toolbox is in the two chips marked ROM HI and ROM LOW (photo: Dave Fischer, CC BY-SA 3.0)
Developer(s)	Apple Computer, Inc.
Initial release	January 24, 1984
Type	ROM firmware and application programming interface
Platform	Motorola 680x0 Macintosh
Size	64 KB (Macintosh 128K) to 512 KB (Macintosh IIci, IIfx); see ROM sizes
License	Proprietary

The Macintosh Toolbox is the set of routines in the ROM of the classic Macintosh that applications call for the user interface, graphics, events, windows, menus and resources. Apple's Inside Macintosh documents it; in the original Macintosh 128K the Toolbox and Operating System together occupy 64 KB of ROM.

The ROM that holds the Toolbox differs in size and form from model to model (below), and it is part of the startup path: on the Macintosh SE/30, Larry Pina's fix for both a checkerboard screen with no startup sound and a Sad Mac with 00000001 on the top line is to reseat the ROM SIMM. See also Sad Mac Error Codes.

ROM sizes

ROM configurations (Guide to the Macintosh Family Hardware, p. 232)

Model	ROM	Configuration
128K and 512K	64 KB	Two 256 Kbit ICs, 16-bit data bus
512K enhanced and Plus	128 KB	Two 512 Kbit ICs, 16-bit data bus; the Plus sockets accept 1 Mbit ICs
SE	256 KB	Two 1 Mbit ICs, the largest the SE sockets accept
Macintosh Portable	256 KB	Two 1 Mbit ICs, plus a connector for a ROM expansion card of up to 4 MB
II and IIcx	256 KB	Four 512 Kbit ICs, 32-bit data bus; sockets accept 1 Mbit ICs. The IIcx also has a ROM SIMM socket
SE/30 and IIx		A 64-pin ROM SIMM in a socket on the logic board
IIci	512 KB	Four 1 Mbit ICs, plus a 64-pin SIMM socket for expansion
IIfx	512 KB	One ROM SIMM carrying four 1 Mbit ICs

The 64-pin ROM SIMM is a different part from the 30-pin and 72-pin RAM SIMMs. The ROM base address is available as the constant romStart and in the global variable ROMBase.

ROM access rates (Table 5-9, p. 231)

Model	CPU	ROM access rate
Macintosh Plus	MC68000	3.92 MB/s
Macintosh SE	MC68000	3.92 MB/s
Macintosh SE/30	MC68030	15.67 MB/s
Macintosh Portable	MC68HC000	7.86 MB/s
Macintosh II	MC68020	12.53 MB/s
Macintosh IIx, IIcx	MC68030	15.67 MB/s
Macintosh IIci	MC68030	20.0 MB/s
Macintosh IIfx	MC68030	64.0 MB/s

The A-trap mechanism

Applications do not call ROM routines by address. They execute a trap word, and the trap dispatcher finds the routine through the trap dispatch table, so that Apple can move routines within ROM between revisions without breaking programs.

Trap words

Instruction words beginning with hexadecimal $A or $F are not valid 68000 instructions; executing one causes an "unimplemented instruction" trap. $A is reserved by Apple and $F by Motorola. The trap dispatcher examines the word and jumps to the routine (I-88).

Format of trap words (I-89)

Bits	Toolbox trap	Operating System trap
15–12	$A	$A
11	1	0
10	Auto-pop: the dispatcher pops the trap's return address, for language systems that call the trap word with JSR	Varies by routine (bits 9–10)
9	Reserved	Varies by routine (bits 9–10)
8	Trap number, bit 8	Set if the dispatcher does not preserve A0
7–0	Trap number	Trap number (so only the first 256 table entries are available to Operating System traps)

The dispatch table

As documented for the original ROM in Inside Macintosh Volumes I–III, the trap dispatch table is in RAM, is 1024 bytes long and has 512 one-word entries. The high bit of each entry says whether the routine is in ROM (0) or RAM (1); the other 15 bits are a word offset from ROMBase or RAMBase. Because the table is in RAM, entries can be changed to point at replacement routines, which is how Apple patched ROM routines at startup; the documented calls are GetTrapAddress and SetTrapAddress (I-87).

Trap numbers

Examples from Appendix C, "System Traps" (III-215 to III-225):

Trap word	Routine
$A11E	NewPtr
$A122	NewHandle
$A873	SetPort
$A876	PortSize
$A913	NewWindow
$A9C6	Secs2Date
$A9F2	Launch

QuickDraw

QuickDraw is the Toolbox's graphics package. It draws in a GrafPort, the drawing environment, into a BitMap; shapes include rectangles, ovals, rounded rectangles, arcs, polygons and regions, and CopyBits transfers pixels with the transfer modes srcCopy, srcOr, srcXor and srcBic and their "not" variants (I-156). Coordinates are integers from −32768 to 32767 (I-138).

Window Manager

The Window Manager keeps the windows in a list in front-to-back order. Each WindowRecord begins with a complete GrafPort, so a window pointer can be used wherever a GrafPort pointer is expected.

Window definition IDs (I-273)

ID	Constant	Window
0	documentProc	Standard document window
1	dBoxProc	Alert box or modal dialog box
2	plainDBox	Plain box
3	altDBoxProc	Plain box with shadow
4	noGrowDocProc	Document window without a size box
16	rDocProc	Rounded-corner window

A window definition ID combines the resource ID of the window definition function (WDEF) with a variation code: IDs 0 to 4 are variations of one WDEF, and rDocProc is a second one.

Event Manager

Applications poll the Event Manager in an event loop. The event queue normally holds 20 events (I-245).

Event codes (I-249)

Code	Constant	Meaning
0	nullEvent	No event
1	mouseDown	Mouse button pressed
2	mouseUp	Mouse button released
3	keyDown	Key pressed
4	keyUp	Key released
5	autoKey	Key held down, repeating
6	updateEvt	Window needs updating
7	diskEvt	Disk inserted
8	activateEvt	Window activated or deactivated
10	networkEvt	Network
11	driverEvt	Device driver
12–15	app1Evt to app4Evt	Application-defined

The auto-key threshold and rate are kept in the globals KeyThresh and KeyRepThresh, the double-click interval in DoubleTime and the caret-blink interval in CaretTime; the user sets them in the Control Panel, and applications read them with GetDblTime and GetCaretTime (I-246, I-260).

Resource Manager

Every file can have a resource fork, addressed by resource type and ID. The Resource Manager searches open resource files in the reverse of the order in which they were opened, so the most recently opened file is searched first and the System file, opened at startup, last (I-104).

Resource attributes (I-111)

Constant	Value	Meaning
resSysHeap	64	Read into the system heap
resPurgeable	32	Purgeable
resLocked	16	Locked
resProtected	8	Protected
resPreload	4	Read in when the file is opened
resChanged	2	To be written to the resource file

Apple's notes: a locked resource is neither relocatable nor purgeable, so resLocked overrides resPurgeable; resChanged is set as a side effect of ChangedResource and should not be set directly; resSysHeap should not be set for an application's own resources (I-111 to I-112).

Memory Manager

Most of the Toolbox uses the Memory Manager's heap of relocatable blocks reached through handles. A routine that can move or purge memory invalidates any pointer made by dereferencing a handle, so lock the handle (HLock and HUnlock) or dereference it again after the call. NewPtr allocates a non-relocatable block and returns a pointer; NewHandle allocates a relocatable block and returns a handle.

Related pages

• Macintosh Old World ROM
• Sad Mac Error Codes
• Inside Macintosh Volumes I-II-III 1985
• Macintosh repair resources