GS/OS System 6.0.1 FST Disassembly

Apple Computer created a number of operating systems for the Apple II. First there was DOS (Disk Operating System), which worked well for 140KB floppy disks but was pretty awful for anything else. Then there was the UCSD Pascal operating system, which was fast but a little quirky. Then came ProDOS (Professional Disk Operating System), the younger sibling of Apple /// SOS (Sophisticated Operating System), which could handle insanely large volumes (32MB!). For the Apple IIgs, an extended version called ProDOS-16 was released. Finally, in 1988, GS/OS was released. The last official version, System 6.0.1 (featuring GS/OS v4.02), shipped in 1993.

System 6.0.1 had enough new features that it perhaps should have been System 6.1. Rumor has it that Apple didn't want to spend the resources expected for a minor system release (e.g. full documentation update), so the developers gave it a bug-fix release number instead.

One of the features introduced in GS/OS was the File System Translator (FST). These provided direct access to multiple filesystems, including ProDOS, HFS, UCSD Pascal, DOS 3.3, and MS-DOS. Because the implementations of FSTs were closely tied to non-public GS/OS interfaces, no specifications for FSTs were published, and the file type note for FST ($BD) goes so far as to say, "no documentation is available, and disassembly of the code for this purpose is not permitted".

The DOS 3.3 FST provides read-only access to DOS volumes on 5.25" disks. The disassembly reveals that it has partial support for 400KB images, which some 3rd-party programs could create on hard drives or 3.5" disks, though this feature was not enabled.

Disassembly listing of DOS 3.3 FST.
Project set - project files and binaries (requires SourceGen v1.7 or later).

GS/OS is copyright Apple Computer, Inc.

Notes on GS/OS Internals

Disassemblies of GS/OS code make more sense if you know a few things about how GS/OS works. Reading through Apple's GS/OS Reference ("for GS/OS System Software Version 5.0 and Later") is an essential starting point. For deeper subjects, familiarity with Apple's GS/OS Device Driver Reference is also helpful. The Brutal Deluxe GS/OS Internals document has a lot of information on non-public structures and interfaces.

If nothing else, you'll need to know some of the terminology:

Device: a physical or virtual device. 5.25" drives, hard drives, network cards, printers, and console character output are all devices. Active devices are enumerated by the system, allowing programs to walk through the list by passing 16-bit device numbers, starting from 1.
Volume: a disk image or partition with a filesystem on it. At any given time they are mounted in a device, but can move between devices, e.g. moving a floppy from drive 1 to drive 2.

DIB: Device Information Block. Holds device characteristics like block counts and slot numbers. Applications can get the data through the DInfo call. See figure 8-4 in the Device Driver Reference.
Device ID: 16-bit value, used to identify a device's type. $0000 is a 5.25" drive, $0001 is a 5MB ProFile, $0009 is a modem, etc. See table 8-1 in the Device Driver Reference.
Device Num: 16-bit index into the active device list. Used to uniquely reference a device. Devices are added as they are found, so there isn't a hard-coded association between devices and numbers. Once assigned, a device's device number won't change unless the device disconnects and reconnects.
FST ID / File System ID: 16-bit value, used to identify a filesystem. $0001 is ProDOS, $0002 is DOS 3.3, and so on. See table 11-2 in the GS/OS Reference.
Ref Num: 16-bit value, used to identify an open file. The file reference number is similar to a file descriptor on UNIX.

VCR: Volume Control Record. Holds information about an open volume. Created and used by FSTs.
VCR ID: 16-bit value, used to reference a VCR.
FCR: File Control Record. Holds information about an open file. Created and used by FSTs. FCRs are uniquely identified by ref nums.
Virtual Pointer: a 32-bit value used by GS/OS to point to internal allocations. Not a pointer, not a handle. Can be converted to a pointer with the internal DEREF call.

File System Translators

As noted earlier, Apple actively discouraged people from developing FSTs. A few people have written them in more recent times, including the Brutal Deluxe crew and Kelvin Sherlock, using information obtained by disassembling the core parts of GS/OS.

Apple's position seems reasonable when you consider the interface. All of the inbound arguments are simply available on the GS/OS direct page. The FST implements the GS/OS calls directly, writing output values into the caller's parameter block as specified by the pCount, rather than placing them in intermediate storage for common GS/OS code to handle. Various low-level system services are invoked directly. The absence of an abstraction layer reduces overhead and allows maximum flexibility for the implementation, but means that changes to the operating system would tend to break things, and the FST may be responsible for handling obscure edge cases.

While the interface is a bit "raw", GS/OS does a lot of prep work before invoking the FST. For a file-based call, the ref num is validated, and the VCR and FCR are passed in. For a path-based call, the pathname is normalized, so the FST doesn't have to deal with resolving numbered prefixes.

One of the primary interactions between FSTs and the rest of GS/OS is through VCRs and FCRs. These are allocated by the FSTs, using internal service calls (ALLOC_VCR, ALLOC_FCR). For example, an FST will call ALLOC_FCR when a file is opened, and GS/OS will return it with the file ref num field filled in. The size of the allocations is determined by the FST, allowing them to over-allocate the storage to hold additional data, such as the file mark or a virtual pointer to a work buffer.

An FCR is associated with a VCR, and a VCR is associated with a device. However, the device association can change, e.g. if somebody moved a 5.25" floppy from drive 1 to drive 2. Detecting this must be handled by the FST, because the FST issues the driver read/write commands. (FWIW, the driver for 5.25" drives reports "disk switched" if it hasn't been accessed for more than 1 second, because the hardware lacks an ejection detector.)

VCRs have a count of the number of open files. If the count is zero, the VCR can be discarded. Code inside the FST will sometimes temporarily increment the open count to ensure the VCR isn't discarded by other subroutines.