Appler
Apple ][ emulator for MS-DOS, written in 8088 assembly
Install / Use
/learn @zajo/ApplerREADME
APPLER
Alexander Patalenski | Emil Dotchevski
Introduction
Appler is an Apple ][ emulator for IBM PC, written in 8088 assembly, running on MS-DOS. It was developed in 1990, at a time when Apple IIe was still in production, so Appler is one of the first Apple ][ emulators ever made; it is probably also the fastest, although this distinction is no longer important.
This repo contains the executable binaries as well as the complete source code. Distributed under the Boost Software License - Version 1.0.
At the time of this writing, Apple ][ is an antique and MS-DOS is obsolete. However, Appler still runs on DOSBOX on Windows or on Mac. So now you can play Apple ][ games running on Appler running on DOSBOX running on MacOS. :)
Contents
- Running Appler
- Support
- The amazing Apple ][
- How Appler works
- Emulated hardware
- Startup sequence
- Utilities / navigation
- File formats
- Building Appler
Appendix
I. Appler debugger commands
II. Bulgarian semiconductor industry in the 1980s
III. The Electric Duet, improved
1. Running Appler
To download Appler, click the green Code button in GitHub, and in the drop-down menu select Download ZIP. Double-click the downloaded file to unzip it.
Next, download and install DOSBOX from https://www.dosbox.com/. Run DOSBOX, and on its command prompt enter the following commands (replacing <path-to-appler with the location where you unzipped Appler):
mount c <path-to-appler>
c:
cd bin
appler
2. Support
Feel free to create GitHub issues, hopefully I can help.
Appler's startup disk boots the classic Apple ][ game Lode Runner. A lot of Apple ][ software is available for download at:
- https://mirrors.apple2.org.za/ftp.apple.asimov.net/images/
- https://apple2online.com/
3. The amazing Apple ][
Before talking about Appler, I should introduce the machine it emulates, the amazing Apple ][.
The humble beginning
Apple Computer started in Steve Wozniak's apartment. Here he is, next to the other, more famous Steve:
Wozniak designed and put together the Apple I, which was sold as a kit, meaning the computer was sold barebones, and had to be assembled by the buyer. This is a nice surviving example, mounted in a briefcase:
Notice the compact cassette player. Back in those days, when you booted up the computer, there was no software loaded on it. You either write the code every time you turn the power on, or else read it from a cassette tape.
Next was the Apple ][, which had a yellowish skin:
Curiously, it supported the Cyrillic alphabet right out of the box.
I'm kidding of course, the above is the Bulgarian-made clone of the Apple ][. If you read the screen, it says ИМКО 2. You probably wonder why its name contains 3 spaces, that's because the engineers hacked directly into the binary code of the original ROM, where they simply replaced the 8 bytes that spelled Apple ][.
It is perhaps unfair to introduce the illegal clone before the original American masterpiece, but let me assure you, behind the commie skin the brilliance of Wozniak's design was intact, and it was built like a tank. The entire bottom of the case, on which everything else is bolted on, is a solid 2mm steel plate which doubles as a giant heat sink for 100% silent operation:
I don't know how much one of these cost, because in Communist Bulgaria such things were considered "means of production" and nobody could own one. Instead, they were available for free use at schools and at public computing centers.
Interesting detail: the original Apple ][+ did not support lowercase letters in text mode. This design shortcomming worked out great for the Bulgarians, because it meant that Western software didn't generally attempt to display lowercase, so that section of the character set could be used to add Cyrillic letters in a backwards-compatible manner; it is as if Wozniak had reserved space for Cyrillic in the original 7-bit character set.
Hardware
Enough about this Commie business. Naturally, the actual Apple ][ looked a lot nicer:
The Apple ][ uses the 6502 CPU, which was designed by a team lead by Chuck Peddle. The team worked for Motorola and proposed an idea for a new, cheaper, faster CPU. The company rejected it, the entire team quit and joined MOS Technology, which produced what became known as the 6502 (the Bulgarians copied that too, making the 100% compatible CM630).
But as great as the 6502 was, at the heart of Apple ][ is Wozniak's brilliant design. He alone designed the hardware as well as the system software.
If one studied the overall system design, it became clear that Wozniak was driven by a simple principle: if there was a way to save 5c in production cost, at the expense of making the life of the programmer 100x more difficult, he'd totally go for it.
As an example, consider the floppy disk controller for Apple ][:
Just kidding. :) The above is the floppy disk controller for the IBM PC/XT. The Wozniak design is below:
If you wonder how can these two cards do the same thing, they really don't. The IBM controller has its own CPU, supports DMA, and does a lot of heavy lifting that makes it easy to write the software. In contrast, the Wozniak design does about 10% of what most reasonable people would consider sufficient for it to be called Disk ][ Interface Card, and yet there it was, and it worked beautifully, although all low level encoding is done in software.
As another example, consider the Apple ][ speaker. Most other computers at least have a simple timer that lets you play a sound with a given frequency. But on the Apple ][, each access of address $C030 inverts the polarity of the speaker, and that's all of the support you get from the hardware. And yet, Paul Lutus gave us The Electric Duet, which plays two voice music (though it produced an audible 14,080 Hz noise as a side effect of duty cycle modulation; Alex wrote his own player from scratch to fix this, and hacked into the binary code to replace the original player. This improved Electric Duet sounded like this).
This minimalist approach seems counter-intuitive, but only if difficult to write software is seen as a downside; yet software -- unlike hardware -- is free to distribute. The result was a cheap, powerful and interesting machine.
Besides, programmers love solving complex problems and take pride in exceptionally clever masterpieces. Wozniak himself set an example of what's possible, managing to fit in 12 KB of memory a Basic interpreter, a program editor, and a debugger.
In popular culture
The Hollywood blockbuster The Terminator featured some 6502 code for Apple ][ in several scenes, seen on the Terminator's HUD:
4. How Appler works
The 6502 emulator
Most of the state of the emulated 6502 CPU is stored in 8088 registers:
A=>dlX=>cxY=>bpPC=>si
The Z and N flags are stored directly in the 8088 ZF and SF, while dh stores the C and the O flags. The stack pointer is stored in memory.
The reason the PC register is stored in si is that this makes it possible to load the next opcode or 8-bit operand using lodsb, and of course 16-bit operands can be loaded via lodsw.
All of the CPU emulation code occupies 64KB of contiguous memory, with the emulation routine for each opcode located at the beginning of each 256-byte segment. The bl register is kept at zero.
With this arrangement, here is the complete implementation of the 6502 instruction INX (increment the X register):
inc cl
lodsb
mov bh, al
jmp bx
Because incrementing cl leaves the ZF and SF in the correct state that matches the semantics of INX, there is no more work to do, we simply load and execute the next opcode.
All of these acrobatics are no longer needed, but back when we wrote this code Appler achieved 75% of the speed of a physical Apple ][ (which runs at 1 MHz) on a 4.75 MHz PC/XT.
Video memory and I/O memory
Depending on the selected video mode, writes to some 6502 memory addresses need to be visualized to emulate the Apple ][ video controller. This complicates memory access emulation in general, since each instruction may need to do extra work depending on the (dynamic) address it uses.
This is implemented by individual emulation routines for each 256-byte page of the 6502 address space. These routines share the same instruction space used to implement the 6502 opcodes, occupying the second half of each 256-byte segment (so, the emulation routine for opcode $20 (JSR) shar
