Learning Assembly — Part 5

How to use an Apple ii!

Travel back to 1977 to see how one of Apple’s earliest computers worked.

Photo by Liana Mikah on Unsplash

Long before the iPad, iPhone, and MacBook, Apple’s most successful product was the Apple ii. The Apple ii (or Apple ][, if you’re feeling stylish) is a personal computer from 1977 that sold exceptionally well for Apple, becoming the first personal computer to achieve commercial success. This was, in part, due to its appeal to not only hobbyists but also “normal” people. What this success means for us is that there are a huge amount of games and programs that can run on the hardware. In this article, we will go through the process of emulating the Apple ii and look at how to load programs onto it. The program we will load will be a small piece of code that we will write ourselves. However, this process could also be used to load on The Oregon Trail game, Ultima 1, Lode Runner, or any other piece of famous Apple ii software.

This is a multi-step process. We will focus on how to get this to run on Linux or Mac, but this should also be transferable to Windows. Let’s quickly break the process down:

• We will need to find a way to emulate the Apple ii (we’ll use AppleWin)
• For those of us without a Windows machine, we will need a way to run the emulation (we’ll use Wine for this)
• We will communicate between our modern machine and the emulator by using CiderPress
• We will compile 6502 Assembly code using cc65

I will also assume a basic knowledge of how to navigate the terminal. If you aren’t familiar with ls-ing and cd-ing you can find some tips here. This is part 5 of my learning assembly series, but whether or not you have read the rest should not matter (hopefully). If all you want to know is how to emulate the Apple ii this should be a groovy read as well.

A 1976 ad for the Apple ii — Source

Wine

If you run Mac or Linux, obviously, you cannot natively run Windows programs. However, the programs that we want to use in this article are exclusively on Windows. We don’t want to install and pay for a large emulator or dual-boot our laptops so to avoid this we can use Wine. Wine (an acronym of Wine Is Not an Emulator) is described as not being an emulator or virtual machine. Instead, it is described as a “compatibility layer capable of running Windows applications”. Honestly, I don’t know what that means but — nevertheless — it will allow us to run the Window’s programs required. To install:

Mac

Open the terminal and enter the following commands:

• brew cask install xquartz
• brew cask install wine-stable

Linux

Go to the terminal and enter:

• sudo apt-get install wine-stable

Some websites give instructions on how to install newer versions of Wine on Linux, but the above command works correctly as well.

Let’s get installing!

We need to download the two Windows programs we need. They are available here:

• Ciderpress: https://github.com/fadden/ciderpress/releases
• AppleWin: https://github.com/AppleWin/AppleWin/releases

Find a version that you like the look of (the newest, probably) and download the .zip file under that “Assets” dropdown.

Let’s get these both working, starting with Ciderpress:

1) Unzip the downloaded file.

2) Navigate to the folder in the terminal.

3) Using the magic on Wine we can install the .exe file provided. To do this type the command wine Setup403.exe. If the .exe is not called the same thing for you then enter the appropriate name instead.

4) Go through the installation process.

5) Now, with Ciderpress installed navigate to: ~/.wine/drive_c/Program\ Files/. For me, this was where it was however it could be in another folder, potentially Program Files (x86).

6) Inside you should be able to navigate to a Ciderpress folder. For me, it was located at Faddensoft/Ciderpress

7) Finally, to run Ciderpress just type wine Ciderpress.exe

And like magic, Ciderpress, a Windows program, should be running on your Mac or Linux machine. The process to get AppleWin installed is even easier:

1) Unzip the downloaded AppleWin file.

2) Navigate to the folder in the terminal.

3) The command wine applewin.exe should launch the application.

We should now have versions of AppleWin and Ciderpress that we can use! While I won’t be discussing it here, please note that there is an application called WineBottler for macs as well. This aims to improve the Wine experience by allowing you to access these programs like any other normal Apple program.

Ciderpress

Ciderpress is a disk image utility that gives us a way to create and manage Apple ii disks. Effectively, this will be a way to transfer things onto the emulator from our machine. This will allow us to write a program in our editor of choice then send it to the emulator to run. Before we begin to use AppleWin we first need to do some preparation; we need to create a disk with an operating system on it for the Apple ii to boot into. To do this:

1) Open Ciderpress.

2) Click File > New > Disk image...

3) Under Filesystem select DOS 3.3 and leave everything else as default.

4) Give it a nickname, make sure it has the extension “.do” and save it in a sensible place.

We are now ready to play with our emulator! Throughout this, we might see that AppleWin will not want to open our file, or that Ciderpress will open the disks as read-only. This may be caused by the other program currently being open and trying to read the disk. To solve this just close AppleWin when trying to use Ciderpress, and vice versa.

AppleWin

Definitely the real Steve and Woz, 1998

The Apple ][ is one of the best-selling computers in the world. It was designed by Steve Wozniak in the seventies and, importantly for us, runs on a 6502 processor. There are lots of interesting and neat things about this machine but for today we will focus on getting some code running. First, open the emulator (AppleWin) using Wine. It should look similar to the image below:

An emulated Apple ii

I love the aesthetic. Now, let’s boot into it:

1) Press the disk 1 icon, this selects what disk will be in the Apple’s first disk drive.

2) A file browser should open, find the “.do” file you just created and select it. This is the disc the apple ii will try to boot into.

3) Now press the rainbow Apple logo to launch the machine. By default, whatever is in the first drive will launch when this button is pressed.

Now, the emulator should boot up and give a nice, happy beep. If this does not happen, you may need to open the options (using the button with a speaker and joystick on) and configure the sound device settings.

There should be a “]” on the screen followed by another flashing symbol. This is telling us that the machine is ready to accept input. Something really cool here is that we can now just start typing code right into the home screen! This language is called BASIC. Try typing the following lines in:

NEW
10 PRINT "HELLO WORLD"
20 GOTO 10
RUN

This is an infinite loop that prints “HELLO WORLD”. You can press the rainbow Apple button to reboot and stop it. The first line “NEW” clears the memory, and “RUN” will run the BASIC program we have entered. Interestingly, we have manually given the lines numbers. We have chosen 10 and 20. This would give us space to add more code in-between if, hypothetically, we wanted to add more functionality to the program. BASIC, as you might guess, is a very basic language. In the 70s and 80s, you could buy magazines with BASIC code for entire games in it. You would be able to write it directly into your Apple ii and play — imagine trying to do that for a modern Xbox One game!

A final note: typing CATALOG shows us any content on the disk.

Our Code

We have managed to get the emulator running now. Let’s move onto our code. The example we will use is based on the additional example that we made in a previous article (found here). In fact, it is almost identical. The code we will use is below:

CLC      ; CLEAR CARRY BIT
CLD      ; CLEAR DECIMAL BIT
ADR1 = $6100 ; WHERE IN MEMORY ARE THESE THINGS
ADR2 = $6101
ADR3 = $6102
LDA #01
STA ADR1 ;load ADR1 with the value 1
LDA #02
STA ADR2 ;load ADR2 with the value 2
LDA ADR1 ; LOAD CONTENTS OF ADR1 INTO ACCUMULATOR
ADC ADR2 ; ADD CONTENTS OF ADR2 INTO ACCUMULATOR 
STA ADR3 ; TRANSFER CONTENT OF ACC TO ADR3
RTS

This code is going to add the values 1 and 2. The only difference from what we saw in the previous article is the inclusion of the instruction RTS. This tells the machine to return from the program. On your “real” machine (not inside the emulator!) copy the code into a file and save it as add.asm .

ca65

We will need to “assemble” this code before it will be executable. This is done using a program called cc65. Before we discuss it too much, we will try to get it installed.

For a Mac, in the terminal, enter the command:

brew install cc65

For a Linux machine, enter the following command in the terminal:

sudo apt-get install cc65

This will have installed cc65 — a program that can compile C code into something a 6502 machine can run. It can also assemble the file we have just written. Go to the folder in which you saved the code and run the command:

ca65 add.asm

This will have assembled our code. However, we are not yet ready! We need another stage, where we link this code, using a linker, to any other information it may need to know. This might be the libraries it uses or, in our case, information about the machine it will be run on. This needs to be done so it knows the areas of memory it is allowed to access. At the moment, being compiled on a modern machine, it will not have any idea of the memory map of the Apple ii. We can provide the relevant parts of it ourselves.

MEMORY {
RAM: start = $6000, size = $8E00, file = %O;
}
SEGMENTS {
CODE: load = RAM, type = ro;
DATA: load = RAM, type = rw;
}

The above code should be saved in a file called apple2bin.cfg in the same directory as our assembled code. It is telling the linker where the RAM will start, where the program can store the code and data, and its read/ write privileges. To link this to our assembled file, and output a binary the Apple ii can run, we need to run the following command:

ld65 -o add#066000.bin -C apple2bin.cfg add.o

Let’s discuss this command:

Part 1: -o add#066000.bin: this names our output. It is given this strange name to provide Ciderpress with some necessary information about its file type and its starting memory location.

Part 2: -C applebin.cfg tells the linker about the config file we made

Part 3: add.o - this is the code we assembled

Running this will output a “.bin” file — this is something that will be executable on an Apple ii! We are now ready to begin loading this onto the emulator.

Running our Code

To get our code to run we will first need to make a blank disk to store it on. Then, when we have this we can transfer our program file onto it and run it on the emulator, AppleWin. To do this:

1) In the emulator, press the button for Disk 2.

2) A file explorer will pop up, navigate to a location where you want to store the disk.

3) Enter a sensible name for the new disk and press “ok”.

4) Now, in the Apple ii command line type INIT BLANK,D2. This will format our new disk.

5) We should now see the name of our disk in the disk 2 button.

That is us done with the emulator for this step. Now, hop into Ciderpress. If you recall, this is how we will “talk” to the emulator from our normal, modern, machine. Here, we want to:

1) In Ciderpress, open the disk we just made in AppleWin.

2) Click Actions > Add files .

3) Find and select add#066000.bin .

4) Under “File Attribute Preservation” select “Use File Attribute Preservation Tags” — this is very important, it tells Ciderpress to use the information encoded in the name when adding it to the disk.

5) Now, press “Accept”.

Now, in the Ciderpress window, we should see the file “ADD” in the disk. Hop back to AppleWin which actually lets us run our program! Note, to see the effect of us modifying the contents of the disk we will need to close the emulator and open it again using wine.

1) Press the rainbow button to boot into the Apple ii.

2) Press the switch-drive button (it has two numbered drives switching positions on it) to load into our second drive.

3) Enter the command CATALOG - we should hopefully see a new file called “ADD”.

4) To now run the program, enter the command BRUN ADD

Congratulations, you have just written, assembled, and run some 6502 assembly language code! However, you will notice that there is no immediate output. That is because at no point in our code did we tell it to print anything. We just asked it to move things in memory. To see the effects of our work we need to look into the memory locations we have affected. The Apple ii, helpfully, gives us the power to do that. Run the following three commands:

• PRINT PEEK (24832)
• PRINT PEEK (24833)
• PRINT PEEK (24834)

This is telling the Apple ii to print the contents of the memory locations 24823, 24833, and 24834. These are all decimal values. In hex, they are written as 6100, 6101, and 6102 — exactly where we stored the two numbers to add and its result. Hopefully, your results will agree with mine:

Output on the Apple ii of running our program and Peek commands

This is exactly what we would expect: 1+2=3.

Conclusion

Well done! You have finally written, assembled, and run your first assembly program. This same procedure we went over today can be used for all the code we have written so far. Also, with the knowledge of how to transfer things onto the Apple ii, you can download and run classic Apple games and programs (from somewhere like here). There is a lot more to say about assembling and emulation but, for now, I will just give a few recommendations of interesting things to use and play around with. First, there is easy6502. This is a website that has an in-browser assembler and emulator which you can use to write 6502 assemblies to modify the color and position of pixels. It even gives a great example of the game Snake. Another, slightly more advanced site is 8bitworkshop. This has a full 6502 IDE on it to use to make games for classic consoles. Finally, an alternative way to write and assemble your code is to do it directly on the Apple ii using an editor called Merlin.

While we have covered a lot of ground there is still a lot that we could discuss (if people are interested). A lot of topics, such as how to I/O and how to address memory (something I find really interesting) have not been mentioned yet in our articles. These are slightly more advanced topics but show off what the 6502 processor is capable of.

Thanks for reading!

This is the fifth part of my “learning assembly” series. The rest can be found here:

• Part 1: Introduction to 6502 Assembly
• Part 2: Get to Grips with Binary Numbers
• Part 3: How do Processors work?
• Part 4.1: Let’s Write Some Assembly!
• Part 4.2: Let’s Write Some (Harder) Assembly!

This article has been adapted from my personal blog. Most of the content I talk about will come from two main sources: “6502 Assembly Language Programming” by Lance A.Leventhal and “Programming the 6502” by Rodney Zaks.

PS. Any O’Reilly editors out there — please, please let me write a book 📖