Macintosh Toolbox

The Macintosh Toolbox implements many of the high-level features of the Classic Mac OS, including a set of application programming interfaces for software development on the platform. The Toolbox consists of a number of "managers," software components such as QuickDraw, responsible for drawing onscreen graphics, and the Menu Manager, which maintain data structures describing the menu bar. As the original Macintosh was designed without virtual memory or memory protection, it was important to classify code according to when it should be loaded into memory or kept on disk, and how it should be accessed. The Toolbox consists of subroutines essential enough to be permanently kept in memory and accessible by a two-byte machine instruction; however it excludes core "kernel" functionality such as memory management and the file system. Note that the Toolbox does not draw the menu onscreen: menus were designed to have a customizable appearance, so the drawing code was stored in a resource, which could be on a disk.

Advent and implementation

On 68k systems

The original Motorola 68000 family implementation of the Macintosh operating system executes system calls using that processor's illegal opcode exception handling mechanism. Motorola specified that instructions beginning with 1111 and 1010 would never be used in future 68000 family processors, thus freeing them for use as such by an operating system. Further, they each had their own dedicated interrupt vector, separate from the generic illegal opcode handler. As 1111 was reserved for use by co-processors such as the 68881 FPU, Apple chose 1010 (A in hexadecimal) as the prefix for operating system calls. Handling illegal instructions is known as trapping, so these special instructions were called A-traps.^[1] When the processor encounters such an instruction, it transfers control to the operating system, which looks up the appropriate task and performs it. There were two advantages to this mechanism:

It results in compact programs. Only two bytes are taken by every operating system access, in contrast to four or six when using regular jump instructions.
The table used to look up the appropriate function is stored in RAM. Then, even if the underlying code was stored in ROM, it could still be overridden (patched) by replacing the ROM memory address with a RAM address.

The system was further optimized by allotting some bits of the A-trap instruction to store parameters to the most common functions. For example, memory allocation is a very common task, so it should be expressed in as few bytes of code as possible. Sometimes the programmer wants to clear the memory block to zeros, so either the allocation function should take a boolean parameter, or there should be two allocation functions. To pass a parameter would require an additional two-byte instruction, which would be inefficient. Having two functions would require at least an extra four bytes of RAM used for the address in the function look-up table. The most efficient solution is to map multiple A-traps to the same subroutine, which then uses the A-trap as a parameter. This is true of the most commonly used subroutines. However, the Toolbox was composed of the less commonly used subroutines. The Toolbox was defined as the set of subroutines which took no parameters within the A-trap, and were indexed from a 1024-entry, 4-kilobyte dispatch table.^[2] (Machines shipped with less than one megabyte of RAM use a single table of 512 entries, which corresponds to the 256-entry OS dispatch table of later ROM revisions.^[3])

On PowerPC systems

In 1994, Apple released Macintoshes using the PowerPC architecture, which lacked hardware support for the A-trap mechanism available on 68k systems. Because of their use in applying software patches, however, the dispatch tables were retained. The API library code underlying any Toolbox routine then does nothing except reference the dispatch table. The dispatch table linked only to emulated 68000 family code. Toolbox functions implemented in native PowerPC code have to first disable the emulator using the Mixed Mode Manager. For the sake of uniformity and extensibility, new function entries even continued to be added to the Toolbox after the PowerPC transition.

An alternative mechanism did exist, however, in the Code Fragment Manager, which was used to load and dynamically link native PowerPC programs. The PowerPC system call facility, analogous to the A-trap mechanism, was used to interface with the Mac OS nanokernel, which offered few services directly useful to applications.

Functionality

Programming interfaces

The Toolbox is composed of commonly used functions, but not the most commonly used functions. As a result, it grew into a hodgepodge of different API libraries.^[3] The Toolbox encompasses most of the basic functionality which distinguished the Classic Mac OS. Apple's references “Inside Macintosh: Macintosh Toolbox Essentials” and “Inside Macintosh: More Macintosh Toolbox”, similarly vague in scope, also document most of the Toolbox.

Use in booting

Because much of the Toolbox is implemented in ROM, alongside the computer's firmware, it was convenient to use as a bootloader environment. In conjunction with resources stored on the ROM chip, the Toolbox can turn the screen gray, show a dialog box with the signature "Welcome to Macintosh" greeting, and display the mouse cursor. By using Toolbox to help boot the machine, a rudimentary Mac-like environment can be initialized before ever loading the System suitcase from disk (in fact before ROMs on NuBus cards were executed), which is when the decision to use 24-bit or 32-bit addressing has to be made. (System 7's support for 32-bit addressing requires 32-bit clean ROMs, as older Mac ROMs do not have support for this). The need for diagnostics as in the BIOS resident for IBM PC compatibles' boards is not necessary since the Macintosh has most of its diagnostics in POST and automatically reports errors via the "Sad Mac" codes.

The similarity between the boot-up environment and the actual operating system should not be confused with being identical, however. Although the "Classic Mac OS" boot process is convoluted and largely undocumented, it is not more limited than an IBM PC compatible BIOS. Like a PC's master boot record, a ROM-based Mac reads and executes code from the first blocks ("boot blocks") of the disk partition selected as the boot device. The boot blocks then verify that a suitable rudimentary environment exists, and use it to load the System suitcase. A different operating system with a different file system can boot by simply using its own code in the boot blocks.^[4] This system was not used for PowerPC Linux, however, because Open Firmware in New World ROM machines requires a bootloader within an HFS filesystem—a reason having nothing to do with the Toolbox or "old-fashioned" Macs in general. More narrowly, the Startup Disk control panel in the Classic Mac OS and later macOS only allows the user to select a mounted filesystem with very particular constraints.

Legacy

In Mac OS X, the Toolbox is not used at all, though the Classic Environment loads the Toolbox ROM file into its virtual machine. Much of the Toolbox was restructured and implemented as part of Apple's Carbon programming API, allowing programmers familiar with the Toolbox to port their program code more easily to Mac OS X.

References

^ Apple Inc. (6 July 1996). "A-Line Instructions". Archived from the original on 2004-07-02. Alt URL
^ Apple Inc. (6 July 1996). "About the Trap Manager". Archived from the original on 2004-07-02. Alt URL
^ ^a ^b Olson, James H. (4 September 1997). "Mac Alamanac II". Linux/m68k for Macintosh.
^ Apple Inc. (6 July 1996). "Boot Blocks". Archived from the original on 2004-03-12. Alt URL