Re: Apple IIGS ROM listings and a general OS question

[dempson@actrix.gen.nz (David Empson)]

Lyndon Fletcher <uablyfl@uab.ericsson.se> wrote:

> I was still hoping for a ROM listing or for references to books that
> explain how the ROMs worked?

Apple never published a listing of any parts of the IIgs firmware.  The
only listing I'm aware of is the disassembly of Applesoft BASIC which is
produced by Sourceror.FP (part of Merlin-8), and even that didn't quite
handle the IIgs variant of Applesoft correctly.

I've looked into small snippets of code at various times, but never done
a large scale disassembly of the ROM.

The IIgs firmware is pretty complex, and it is generally easier to break
it down into logical modules rather than trying to consider all of it at
once.

The major functional blocks which occur to me are as follows:

- Hardware initialization and boot.
- System monitor (including a reasonably powerful debugger in ROM 3).
- Interrupt management.
- Applesoft BASIC.
- Self-test.
- Apple Desktop Bus.
- Control Panel CDA.
- Alternate Display Mode CDA.
- Programmers' utility CDAs (Visit Monitor and Memory Peeker).
- Serial drivers.
- AppleTalk drivers.
- 80-column support.
- Mouse driver (quite different arrangements for ROM 1 and ROM 3).
- SmartPort drivers (including drivers for the Apple 3.5" drive,
intelligent SmartPort drives like the UniDisk 3.5, RAM disk, and a stub
for the ROM disk driver).
- 5.25" drive boot code.
- Toolbox.

The toolbox is somewhat of a special case, as parts of it can be
replaced or augmented by the system software loaded from disk (ProDOS-16
or GS/OS).  If you are considering looking at the functionality of any
parts of the toolbox, it isn't appropriate to restrict yourself to the
ROM, but rather treat each toolset as a functional unit, whereever it
happens to reside (ROM or RAM).

For ROM 00 and 01, the following toolsets are located in the ROM (with
patches from the system disk): Tool Locator, Memory Manager,
Miscellaneous Toolset, QuickDraw II, Desk Manager, Event Manager,
Scheduler, Sound Tool Set, Apple Desktop Bus Tool Set, SANE Tool Set,
Integer Math Tool Set, Text Tool Set, Mystery toolset 13.

ROM 3 has all of the above in ROM, plus several higher level toolsets.
As with ROM 1, various patches are applied at system boot time, and in
some cases the toolsets are completely replaced with a newer version
loaded from disk.  I don't have a full list of the ROM-based toolsets
handy, but the following is about right: Window Manager, Menu Manager,
Control Manager, QuickDraw II Auxiliary, LineEdit Tool Set, Dialog
Manager, Note Syntheszer, Note Sequencer, List Manager.

I know the System Loader and Standard File Operations toolsets are not
in ROM, as they are heavily dependent on the operating system.  I'm not
sure about the Print Manager, Scrap Manager, Font Manager, Resource
Manager, Text Edit and some of the other System 5.0 toolsets.

I made a spreadsheet several years ago which lists the version of each
toolset in the ROMs and for each system release, which would show
exactly which ones were in ROM.  I don't have it handy right now (my
IIgs is packed up).


As far as documentation is concerned, the best place to start would be
Apple's own reference manuals.

- Apple IIgs Hardware Reference (you need the second edition if you want
to know about the 1 MB motherboard, usually referred to as "ROM 3").  It
doesn't cover the firmware to any great degree, but does explain the
underlying details, which help if you are trying to disassemble
anything.

- Apple IIgs Firmware Reference.  This doesn't have any firmware
listings, but does have details of entry points and publically defined
memory locations (e.g. lots of vectors in bank $E1), and explains how
some areas work.  There is a supplement which covers some new features
of ROM 3.

The Firmware reference covers the system monitor, ADB, serial ports,
80-column firmware, mouse support, SmartPort and 5.25" drive support.
It doesn't touch on the other areas, apart from mentioning them in
passing.

- Apple IIgs Toolbox Reference (three volumes).  This covers most of the
toolbox.  Volumes 1 and 2 are a set which cover everything up to about
System 2.0 (possibly a little later) and ROM 1.  Volume 3 covers new
features up to System 5.0 and ROM 3.

(An interesting omission is toolset 13, which Apple have never
documented.  The little investigation I did suggested that it was used
for low level operations related to the Memory Manager and the RAM
disk.)

- System 6 Programmers' Reference is a further supplement to the Toolbox
Reference which covers System 6.  (It also supplements the GS/OS
Reference with new features of the operating system.)  There is a
supplement for System 6.0.1.

- Release notes for each release of the system software cover new
features, including toolbox changes in some cases.

- Various technical notes go into more detail for some areas of the
firmware and toolbox.