Apple /// user Egan Ford has done some additional testing on the driver and even posted a nice harddisk image to reproduce his results. So here’s some more things the Apple /// driver can do. (At the request of Tony Diaz, I’m posting aspect-corrected screenshots here to better represent how the emulation actually looks).

AppleWriter ///

Advanced VisiCalc

Turbo Pascal for CP/M running off the emulated IDE harddisk

Zork for CP/M

Zork II for CP/M

Zork III for CP/M

For my own benefit as much as anyone’s, here’s how Apple /// extended addressing works. (This doesn’t need to be linked at MW; there’s no end-user value here unless you are an end user who plans to write new software for the Apple ///).

The hardware outside of the CPU knows *nothing* about what instruction the CPU is executing. Therefore, for emulation, you do not need to modify a standard 6502 core to emulate the /// successfully. You *do* need a core that outputs the SYNC pin or otherwise signals opcode fetches, however, and emulation of the false reads and prefetch quirks helps.

On each and every CPU read:
– If it’s not an opcode fetch (6502 SYNC pin is low)
– And it’s to the zero page (original 6502 address is 0x00xx)
– And the current zero page (VIA 0 port B) has bits 3 and 4 set ((zp & 0x18) == 0x18)
– Fetch the corresponding byte from “page X” (current zero page XOR 0x0c00) (this is called the “X byte”)
– If bit 7 of the X byte is set, enable extended addressing for every read and write until the next opcode fetch (rising edge of SYNC). Because some opcodes do a false read, it’s important that this continue until the opcode fetch.
– If bit 7 of the X byte is clear, do nothing, the memory address occurs as normal

When extended addressing is enabled:
– If the low nibble of the X byte is 0-0xe, the address space has the bank specified by that nibble from 0000-7fff and the next bank up from that at 8000-ffff. (Apple /// banks are 32k)
– If the low nibble of the X byte is 0xf, bank 0 is mapped from 2000-9fff and RAM is mapped in from 0000-1fff and a000-ffff. In particular, the RAM hidden under the two VIAs is accessible in this manner; SOS uses those bytes for the time and date.
– Bits 4, 5, and 6 of the Xbyte are ignored. Old versions of MESS tried to do something special for Xbyte = 0xff, but that’s incorrect, the hardware treats that as 0x8f.
– It should go without saying, but the check for extended addressing is not done while you are already in extended addressing mode. So an extended read to a zero page location will follow the rules immediately above here; they won’t follow the initial flowchart to determine if extended addressing should be enabled).

Finally, this isn’t related to the extended addressing, but it’s easy to get wrong. When ROM is banked in from f000-ffff, writes to that region will go through to the underlying RAM unless the write protect bit (bit 3) in the environment register (VIA 0 port A) is set. The diagnostics disk won’t boot with this wrong.

When last we left the Apple /// emulation, we had world’s-first app compatibility but general unease over seemingly random instability in the System Utilities, and the Selector /// installer failed every time. After taking a dive into the schematics, I realized that the instruction modification trick was actually far, far simpler than I’d been giving it credit for (this is a computer released in 1980). I rewrote it according to my understanding of the schematics, which cut the size of the relevant code to about 25% of what it was before, kept compatibility high, and cured the instability.

Armed with this, and a fix to the CFFA2 card emulation, I was able to install Selector /// and a selection of application software to an emulated 40 meg IDE harddisk and do a quick run-through to show them all working. Here’s the video result:

The Apple /// computer, codenamed “Sara”, has been something of a white whale of emulation for over a decade now. In the late 90s Chris Smolinski of Black Cat Systems started an emulator named Sara. It was originally for 680×0-based Macs running the “classic” MacOS, and later moved targets, first to PowerPC, then to Mac OS X, and finally to Intel Mac OS X. It eventually could run some limited Apple /// software but had issues with the diagnostics disk and Business BASIC, among other things. Sara itself was last released in 2008.

The reason emulating the system is hard is simple: in order to fit up to 512K RAM into an 8-bit system (which could normally only access 64K) the engineers involved chose to do something weird: they put hardware between the CPU and the rest of the system which watches the CPU fetch instructions and alters their behavior on-the-fly to facilitate some really interesting memory gymnastics. Most systems just set aside one or more pieces of the 64k space and let you switch out what portion of the total memory appears in it at a time; the Apple III does that *too*, but the centerpiece was definitely the realtime instruction modification capability, with which programs could access the entire 512K of RAM more or less seamlessly. That wouldn’t be so bad, except that public documentation on the setup is quite sparse. The official Apple service manual has a rudimentary discussion, but misses a lot of details. A couple of articles from Softalk magazine further document the details, but still don’t complete the picture.

The machine itself was a failure, by the way. Around 120,000 total units were sold before Apple gave up on it in 1984. This was in part because the original motherboards were produced with an incorrect process that caused persistent intermittent failures. This was originally blamed on the system’s lack of a fan, but recent interviews with the engineers involved pointed the finger instead at the manufacturing process. This is one reason there have been few attempts to emulate it.

Fortunately, source code for the operating system (SOS, which later evolved into ProDOS for the Apple II), the BASIC interpreter, and many of the device drivers has been available on the Internet for a few years and they can reward a determined spelunker with a good 6502 background by implying or flat-out revealing a lot of the “secrets”.

Around 2005, MESS’s Nathan Woods added a MESS driver based in part on code kindly shared from the Sara emulator, but it was even less compatible than Sara itself and the driver kind of rotted after that. With the advent of Olivier Galibert’s perfect-accuracy cycle-by-cycle 6502 core, the stage was finally set for someone to make a serious run at the Apple /// in MESS. You’ll be shocked to learn that the person dumb enough to try running head-first at a brick wall that had stymied emulation for over a decade was me.

Things started out slowly. I implemented the instruction modification trickeration according to the Softalk articles, and then improved the interrupt generation and handling, and implemented alternate behavior that Rockwell’s version of the 6551 serial chip exhibited. This got us a full pass from the “Confidence Test”, something Sara couldn’t do:

After that I implemented the Apple ///’s 3 sound sources, including crude sample playback capability. That allowed the same “Confidence Test” to speak when it passed, which must have seemed like witchcraft in 1980.

At this point we outdid Sara on a synthetic benchmark, but Sara was able to actually boot SOS and run some application software, while MESS failed on all attempts – in all cases SOS loaded the startup executable correctly but the executable would typically fail when calling SOS’s services to load their data files and such. About 12 hours of tracing through SOS code over 3 separate days made me realize the first hole in Softalk‘s description of the instruction rewriting. I implemented that and application software came to life:

Trivia digression: “3 E-Z Pieces” was an integrated word processor/spreadsheet/database by Rupert Lissner. It was a small sensation on the Apple ///, but when it followed SOS over to the Apple II the program became *the* killer app for the ProDOS operating system. It was renamed “AppleWorks” for it’s Apple II debut but maintained the same file-folder text-based UI and file formats.

Anyway, at this point I rewrote the Apple ///’s keyboard handling from scratch because it was outdated (the driver having last been seriously maintained in 2006 or so) and not working properly anyway. At this point we were basically tied with Sara for compatibility. Both emulators loaded Business BASIC, and you could type in or load a program and LIST it correctly, but the RUN command would fail immediately with a syntax error, sometimes on a line that didn’t exist.

Several more hours of code tracing later (again with the help of the source code, although the released source doesn’t exactly match any of the released binaries which made things interesting) I found the routine that was causing the problem. It didn’t seem to be doing anything immediately interesting, but there was this unusual comment in the source code:

BECAUSE SARA GOES BY WHETHER THE ADDR IS GOING THROUGH ZERO PAGE, THIS GOES THROUGH THE BANK STUFF ALSO.

What that means in English was that even though the instructions were not normally of a class that would trigger the behavior modification, they would get modified anyway due to where in memory they were located. I had started to develop a hunch that that could be the case anyway, and the comment pushed me over into trying it out. Sure enough, BASIC programs began running fine:

This also fixed an aftermarket enhanced version of SOS called BOS into working:

After that, I turned to some areas where MESS being MESS could net us some easy wins. The Apple /// has slots that are electrically compatible with Apple II expansion cards, but unlike the Apple II it ignores any firmware drivers that might exist in the card’s ROM in preference to disk-based drivers. This was very forward looking in 1980 (it’s how all computer OSes handle expansion hardware now) but it also means that the number of otherwise useful Apple II cards that could be used was very low. One of those cards from that time was the PCPI AppliCard, which allowed running CP/M on a fast 6 MHz Z80 processor. MESS was the first Apple II emulator to support that particular card, and is still the only one to my knowledge. I modified the driver to support plugging the AppliCard into one of the 4 slots in the Apple ///, located the startup/driver disk, and CP/M booted up first try. Nice!

Jumping forward, there was also a driver/utilities disk for the CFFA2, a popular compact flash/IDE hard disk interface for Apple IIs created in the mid-2000s. MESS already supported that card for our Apple II emulation, so I made it available to the Apple /// emulation as well, and once again the utilities recognized the card and were able to partition and format a .CHD image first try. No modifications to the existing emulation of the card were necessary.

From there I added full save state support and fixed an issue with the highest-resolution monochrome graphics mode, so this 1990 “Sara’s 10th birthday” screen renders correctly:

There’s still more work to do on this little-known computer (emulation of it’s clock/calendar chip, joysticks, and the Apple ProFile harddisk for starters) but it’s nice to have MESS clearly in the lead on emulation of a system.

A quick note: the common disk image of the Apple /// System Demo is a bad dump. This image has an MD5 sum of 386db054b29ec666af8c04033fe4cfd8 and it doesn’t boot in MESS or Sara (it shows SYSTEM ERROR $06 after the SOS splash screen). A correct image of that same demo is available as part of the Washington Apple Pi user’s group disk collection, named APPLE-3-WAP-sys-03b.dsk with an MD5 sum of d07a5daed3d64aab17a631ee5a149f37. The correct image runs beautifully in the current MESS driver.

UPDATE: Read more of the story and see a video of the driver in action in our next entry!