Abandoned Farmhouse Adventure now in Google Play Store

Back in April 2012, I wrote a text adventure game  as an experiment to try out the CC65 C compiler on the Briel Replica 1 computer  (an Apple 1 replica). Because it was written in C, it also ran under Linux, and any platform that supported a reasonable C compiler. I also ported it  to the Briel Altair 8800 computer running CP/M using the BDS C compiler.

When the Raspberry Pi store opened, I packaged it and submitted it as one of the first applications in the Raspberry Pi store.

Later, I made a GUI version using the Qt Toolkit , which is portable to a number of platforms. I intend to release the Qt version into the Raspberry Pi store, but have not gotten around to doing that yet.

With Qt now supporting Android, I tried building it for Android to run on a tablet, and it worked almost flawlessly without any changes. I made a few small tweaks for Android, and packaged it for the Google Play store. It is now available as a free Android application.

Android Version of The Abandoned Farmhouse Adventure

I doubt that any application before has run on an Apple 1, CP/M, Linux desktop, Raspberry Pi, and Android tablet - devices that span almost 40 years of computing and differences in computing power of several thousand times.

New Retro Computer Kit

Dubbed a Software Defined Computer, the Propeddle  is a new forthcoming computer kit that has a 65C02 processor as well as a Propeller CPU, and is planned to be able to emulate various 6502-based computers by changing the software. The prototype is already able to emulate an Apple 1.

The name Propeddle comes from the Propeller CPU used on the board, and Chuck Peddle, one of the designers of the 6502 microprocessor.

It has similarities to the Briel Replica 1, but aims to be able to be able to emulate different computers.

It looks like a interesting project, and one that I will keep my eye on. Being able to emulate a number of different old computers would be cool. It should be able to emulate, say, a KIM-1, Commodore PET, or Ohio Scientific Challenger by changing the firware. I wonder if it will have the processing power to emulate a more complex machine like the Apple II?

Updates: Apple II Monitor Port and GR-64 Video

A couple of updates to recent blog posts: I did a little more work on the Apple II Monitor port to the Apple 1, getting the source code to assemble the version that includes the Woz Monitor at the end. This version can be burned to a ROM (or EPROM or EEPROM) in the Replica 1, so you can have both the original Woz Monitor and Apple II Monitor in ROM from powerup. I confirmed that it does work when programmed into a ROM. It also works in the POM1 Apple 1 Emulator. As before, the Apple II Monitor port can be found here.

Apple II Monitor Running on Briel Replica 1

As a followup to my previous blog post, here is a transcript of running some Apple II Monitor commands on the Briel Replica 1. You can find documentation on the Monitor commands in a number of places, including here. The commands typed by the user are in bold.


Monitor prompt:

*

Dump memory:

*1000.100F
1000- A2 10 EA CA D0 FA 60 BE
1008- 00 00 4A 83 00 00 75 D7

Change memory:

*1000:01 02 03

*1000.100F
1000- 01 02 03 CA D0 FA 60 BE
1008- 00 00 4A 83 00 00 75 D7

Move Memory:

*1000<2000 .2fffm="" b="">

Verify Memory:

*1000<2000 .3000v="" b="">
3000-FF (00)

Disassemble:

*FF00L
FF00-   D8          CLD   
FF01-   58          CLI   
FF02-   A0 7F       LDY   #$7F
FF04-   8C 12 D0    STY   $D012
FF07-   A9 A7       LDA   #$A7
FF09-   8D 11 D0    STA   $D011
FF0C-   8D 13 D0    STA   $D013
FF0F-   C9 DF       CMP   #$DF
FF11-   F0 13       BEQ   $FF26
FF13-   C9 9B       CMP   #$9B
FF15-   F0 03       BEQ   $FF1A
FF17-   C8          INY   
FF18-   10 0F       BPL   $FF29
FF1A-   A9 DC       LDA   #$DC
FF1C-   20 EF FF    JSR   $FFEF
FF1F-   A9 8D       LDA   #$8D
FF21-   20 EF FF    JSR   $FFEF
FF24-   A0 01       LDY   #$01
FF26-   88          DEY   
FF27-   30 F6       BMI   $FF1F

Mini-Assembler:

*7666G

!1000:LDX #$10
1000-   A2 10       LDX   #$10
! NOP
1002-   EA          NOP   
! DEX
1003-   CA          DEX   
! BNE 1000
1004-   D0 FA       BNE   $1000
! RTS
1006-   60          RTS   

Call Monitor to Disassemble:

!$1000L
1000-   A2 10       LDX   #$10
1002-   EA          NOP   
1003-   CA          DEX   
1004-   D0 FA       BNE   $1000
1006-   60          RTS   
1007-   BE 00 00    LDX   $0000,Y
100A-   4A          LSR   
100B-   83          ???   
100C-   00          BRK   
100D-   00          BRK   
100E-   75 D7       ADC   $D7,X
1010-   00          BRK   
1011-   00          BRK   
1012-   F8          SED   
1013-   87          ???   
1014-   00          BRK   
1015-   00          BRK   
1016-   B5 F6       LDA   $F6,X
1018-   42          ???   
1019-   00          BRK   

Go back to Monitor:

!$7F65G

Single step:

*1000S
1000-   A2 10       LDX   #$10
 A=10 X=10 Y=7D P=70 S=CA
*S
1002-   EA          NOP   
 A=10 X=10 Y=7D P=70 S=CA
*S
1003-   CA          DEX   
 A=10 X=0F Y=7D P=70 S=CA
*S
1004-   D0 FA       BNE   $1000
 A=10 X=0F Y=7D P=70 S=CA
*S
1000-   A2 10       LDX   #$10
 A=10 X=10 Y=7D P=70 S=CA
*

Display 6502 Registers:

*^E
 A=10 X=10 Y=7D P=70 S=CA

Hex arithmetic:

*12+34
=46
*FE-12
=EC

Go to BASIC:

*^B
>LIST

Apple II Monitor Ported to Apple 1

As announced here,  a cassette tape was found that contains a port of the Apple II Monitor to the Apple 1. It was done by Winston Gayler. Additional work was done by Wendell Sander, who posted documentation, cassette tape sound files and Woz Mon binaries here .

I've tested the code on a Briel Replica 1 and it works quite well. The only issue I found on the Replica 1 is that the commands that require Control keys do not work as the Replica 1 does not emulate Control keys when using a PS/2 keyboard. They will work if entered from the serial port.

This weekend I went a little further adapted the original monitor source from the "Red Book" to build under the CA65 assembler, then applied the changes for the Apple 1. The result is code that can be assembled from source and easily relocated.

References:

1. www.apple1notes.com/old_apple/Monitor_II_on_1.html
2. www.applefritter.com/content/apple-ii-monitor-ported-apple-1
3. github.com/jefftranter/6502/tree/master/asm/Apple%5D%5BMonitor

More About the Abandoned Farmhouse Adventure

I mentioned here earlier that I ported my Abandoned Farmhouse Adventure  game to the Raspberry Pi and got it into the Pi Store as a free download. Here are some more details about the game and how it was developed for people that may be interested.

The program was written in the C programming language, consisting of just over 800 lines of source code. I originally wrote it in March 2012 as a game for the Replica 1 Computer, a replica of the first computer, the Apple 1, offered by Apple Computer in 1976.

The Briel Replica 1 Computer

On the Replica 1 it was compiled using the CC65 compiler which supports the 8-bit 6502 microprocessor used by the Replica 1 (and Apple 1). It took me a few evenings and weekend mornings to design and write the game. The game had to fit within the hardware constraints of the Replica 1: a one MHz 8-bit processor with only a few kilobytes of memory and only text output.

I did most testing of the game on a Linux desktop system using the GNU gcc compiler, as it was faster and easier to build and debug than on the Replica 1.

The game was announced on the Briel Computers forum and made available to any Replica 1 or Apple 1 computer users who wanted to try it.

I've been following the Raspberry Pi since it's early development. With the announcement of the Raspberry Pi store, I thought it would be fun to get an application in the new store. The adventure game was already running on Linux so getting it on the Linux-based Raspberry Pi should be straightforward. Porting it to the Raspberry Pi involved adding lower case text (the Apple 1 could only display upper case text). I also removed some code that was specific to the CC65 compiler. Most of the work was figuring out how to publish an application in the Raspberry Pi app store, and waiting for it to pass through the application approval process.

Screen Shot Of The Game

For people trying the game, I won't give a solution or any spoilers, but here are a few hints. I suggest drawing out a map on a piece of paper and making notes as you play the game. Pay attention to any messages, like needing food or water, as these will soon become important in the game. Not all items in the game are necessarily needed to solve it; some may be red herrings. The game will take some time to solve. Keep at it. If you get frustrated, set it aside for a while and you may think of some new insight into how to solve it.

I would really like to hear from you if you solved the game, or even if you played it but did not complete it yet. As I write this the game has had 361 downloads but no one has actually reported completing the game. I don't think I made it too hard, but it is difficult as the developer to stand back and assess how challenging the game is.

I have been planning to make a version of the games with a Qt-based graphical user interface on it, which would be less like a retro text adventure game but more playable by people accustomed to modern GUIs.

Early Prototype of GUI Version of the Game

The game is open source and published under an Apache license. The source code can be found here. You are free to share, port, or modify the game subject to the terms of the Apache license. If you are really stuck solving the game and are at all fluent in C code, you could look at the source code to get some hints. Much of the code is data-driven and could be used to implement an entirely different adventure just by changing the map, strings, and some of the logic that handles special actions.

Finally, the farm described here is based on a real farmhouse where my father lived many years ago, right down to the layout of most of the rooms. And I also have a grandson who was almost three years old at the time I wrote this. It is interesting to think that in a few years he may come across this game in which he appears and maybe play it.

The Apple 1 Cassette Interface

The Apple Cassette Interface (ACI) was the only accessory sold for the Apple 1 computer. It allowed saving and loading programs from cassette tape using an inexpensive tape recorder.

Vince Briel  recently made a batch of replica ACI boards both as kits or pre-assembled. The board is similar to the original except using a more easily obtainable EEPROM chip rather than the ROM chips on the original design. I got one of the first batch of kits and assembled it.

ACI parts and manual ready to be assembled

I have a couple of tape recorders from that era. I have a GE model that I bought around 1980 and used with my Ohio Scientific Superboard computer for tape storage. I also recently picked up a Panasonic model from the 1970s or 1980s at a thrift store.  I don't the Panasonic RQ-2102 model that Apple originally recommended (amazingly it is still be manufactured and available).

GE Cassette Recorder circa 1980

Panasonic Recorder picked up a thrift shop

Panasonic RQ-2102 Recommended by Apple

The original Apple Cassette Interface manual is available on-line. The software is on-board the ACI and consists of only 256 bytes of code written by Woz. It is primitive and has no error detection. The later Apple II had a similar cassette interface circuit built into the motherboard (in models up to the Apple 2c). The Apple II used a similar storage scheme but added a checksum verification to detect errors.

Assembled ACI Replica

I haven't got mine to work reliably yet. I am working with some other kit builders to track down why. It is known to be tricky to get working. As well as a tape recorder I've been using my computer's sound card and an oscilloscope to debug it. I'll report more here on my progress toward getting it to work reliably. 

ACI Installed in the Replica 1

Replica 1 Quick Reference, Apple 1 on the Raspberry Pi, and the return of IMSAI

Earlier I made a one page reference of useful addresses for the Replica 1. I've extended that into a more comprehensive four page quick reference. You can download it from here. That directory also has some documents I wrote like a summary of the 65C02 and 65816 processors and some errata for Apple 1 manuals.

---

I recently got a Raspberry Pi board. This is a very small (credit card sized), low cost ($35) embedded desktop computer that can run Linux. For fun I compiled the POM1 Apple 1 Emulator on it. It ran quite well although it was a little slow on the Raspberry Pi's 600MHz ARM CPU. I've ordered a hardware expansion board for the Raspberry Pi called the Gertboard and plan to use if for some hardware experiments.

---

I've started playing with the Propeller CPU on the Replica 1. It is quite an amazing chip - 8 CPUs with shared memory, a built-in high level language interpreter as well as machine language, and hardware I/O ports. It can even generate video (which it does for the Replica 1). I'll have more to say here as I explore it further.

---

I'm looking forward to getting the Apple Cassette Interface when Briel computers starts shipping them. It sounds like big things are in store for Briel Computers. Vince Briel is planning to purchase the assets
of IMSAI computer. They were one of the first home computer manufacturers (along with Altair) and a portion of the company was still in business. He is hoping to restart a project they had to introduce a new replica of the original IMSAI 8080 computer.

Converting Between Floating Point and Human Readable Format

In my last post I mentioned 6502 code that can convert between ASCII and floating point formats that was written by Marvin L De Jong and published in the February and April 1981 issues of COMPUTE! magazine.

I've now entered it and ported it to the CC65 assembler to run on the Replica 1.

As often seems to be the case, there were a number of errors in the printed code, such as symbols that were never defined. The "#" sign was also not used to specify immediate addressing (this was apparently a coding convention that the author followed in all of his published code).

Fortunately it seemed that the generated machine code in the listing was correct, so in most cases I was able to use that as a reference to determine what the code should be.

I also had to combine the code in the first article with changes in the second one as there was no complete listing of the final software.

The code used some i/o routines for the AIM-65 machine so those needed to be be replaced with equivalents for the Replica 1.

After a couple of evenings of porting and testing I had the string to floating point and floating point to string functions working (De Jong refers to it as "BCD format" but it is really an ASCII string format). So, for example, I could now convert a string like "+6.02214E23" or "-1.2E-19" to floating point and back to ASCII. I then updated my little test/demo program to support calling the new routines.

The floating point format used by the De Jong code is a little different from the format used by the Woz code, but I was able to convert them easily enough.

The final result is the demo program which exercises all the functions. Here is an example run:

FLOATING POINT DEMONSTRATION PROGRAM

F - FIXED TO FLOATING POINT
P - FLOATING TO FIXED POINT
L - NATURAL LOG
N - COMMON LOG
E - EXPONENTIAL
A - FLOATING POINT ADD
S - FLOATING POINT SUBTRACT
M - FLOATING POINT MULTIPLY
D - FLOATING POINT DIVIDE
B - STRING TO FLOATING POINT
T - FLOATING POINT TO STRING
? - THIS HELP SCREEN
X - EXIT

SELECT A FUNCTION: B
STRING TO FLOATING POINT
ENTER FP STRING: 1234
FLOATING POINT IS: 8A 4D2000

SELECT A FUNCTION: T
FLOATING POINT TO STRING
ENTER EXPONENT AND MANTISSA: 8A 4D2000
FLOATING POINT IS: 1234

SELECT A FUNCTION: B
STRING TO FLOATING POINT
ENTER FP STRING: 6.02214E23
FLOATING POINT IS: CE 7F8616

SELECT A FUNCTION: T
FLOATING POINT TO STRING
ENTER EXPONENT AND MANTISSA: CE 7F8616
FLOATING POINT IS: 60221399.E16

With the facilities here you could implement a math program like a scientific calculator. I may do that at some point.

I learned a little about floating point code with this project. It also reminded me that back at the time this code was written there was no standard for representing floating point numbers. That was addressed by the IEEE Standard for Floating-Point Arithmetic (IEEE 754) and most modern CPU chips that have floating point hardware now support this standard, and language compilers typically support it in their run-time libraries. CPUs that lack floating point hardware typically emulate it in software, using code much like the 6502 code here, but more complex and typically written in C.

As usual, all of the code can be found here and you are welcome to use it.

A YUMmy New Game

I wanted to write another game for the Replica 1, and after considering a few alternatives, I decided to write a computer version of YUM, a game that is popular with our family.

YUM is a dice game, similar to games known as Yahtzee, Yacht and Generala. Each player rolls five dice up to three times and then applies the dice toward a category to claim points. The game has 12 rounds during which each player attempts to claim the most points in each category.

The winner is the person scoring the most points at the end of the game. This version supports up to three players of which any can be human or computer players.

It would be a little frustrating to write in BASIC and tedious in assembler so I wrote it in C using the CC65 6502 compiler/assembler. This had the advantage that I could develop and test it on a desktop Linux system.

There is nothing particularly novel about the code. The computer players play a relatively good game based on some simple rules. The game could support more than three players by changing a compile-time constant -- the only limitation is that the screen size only conveniently fits a table of scores for three players.

Because it was intended to run on the Replica 1 it was kept small and efficient to run within the 32K memory limit and only use uppercase characters and fit on a 40x24 character screen.

The source is released under an Apache license. Both the source code and a binary that will run on a Replica 1system  can be found at here.

If you want to run it on a real Apple 1 or similar, you will need to have just over 16K of RAM. With a little effort I could probably get the code size down a little to fit in 16K (the Replica 1 has 32K).

---

For my next Replica 1 project I am eagerly awaiting the Apple Cassette Interface kits that Vince Briel is offering. I expect to be one of the first beta testers for this, and I have a cassette tape player ready to go.

Getting Info About the System

I recently added a few more features to JMON. The main one is a new iNfo command which displays information about the system it is running on. Here is sample output:

         CPU TYPE: 65C02
        CPU SPEED: 2.0 MHZ
RAM DETECTED FROM: $0000 TO $7FFF
       NMI VECTOR: $0F00
     RESET VECTOR: $FF00
   IRQ/BRK VECTOR: $0100
         ACI CARD: NOT PRESENT
       CFFA1 CARD: NOT PRESENT
   MULTI I/O CARD: PRESENT
        BASIC ROM: PRESENT
     KRUSADER ROM: PRESENT
       WOZMON ROM: PRESENT

The way some of this information was generated is somewhat interesting. I'll explain a bit about how the code was implemented.

To determine the CPU type I used some code from the Western Design Center manual for the 65xx series processors. The code first distinguishes between 6502 and 65C02 processors by the behavior of the negative flag in decimal mode. The 65C02 fixed the behavior to make the flag valid (also V and C) while the 6502 did not. It then tries a 65816 instruction which will change the carry flag but is an unimplemented instruction and hence a NOP on the 65C02. From this it determines if it is running on a 6502, 65C02, or 65816 processor.

There are different manufacturers of 65C02. I don't know of any easy way to distinguish between a Rockwell and WDC 65C02. Thw only added instructions on the WDC are STP and WAI which both stop the CPU from running. They require either a reset or an interrupt to restart the CPU.

To find the range of RAM the code does the following. Starting from address zero, it in turn writes all ones, all zeroes, and alternating ones and zeroes to each memory location. If the same data is read back, it is considered RAM. The original data at the location is then written back to avoid corrupting what is in memory (namely, JMON). This is done until memory is found that cannot be written to and read back with the same data. I then stop, so the test only checks for contiguous RAM starting at zero.

A wrinkle is to avoid writing to the area of memory where the code itself is running since it would get corrupted in the middle of execution. I do this by avoiding testing the 256 byte page where the memory test code resides.

Next is the CPU speed. We want to determine the approximate clock speed of the CPU. But how, since we have no reference to actual time? The trick I used is to make use of a serial port, which is available when a Multi I/O board is present. If we send some characters out the serial port and see how many CPU cycles it takes, we can determine how fast the CPU is running since the serial port works at baud rates that are independent of the CPU clock speed. The code is calculated to give a value that is approximately the clock speed in megahertz to two significant figures.

For testing if certain ROMS are present, like the Krusader assembler, we can check the first few bytes for known data.

For expansion cards, like the CFFA1, they may have ID bytes in hardware (the CFFA1 does) or we can look at the hardware registers like the 6551 on the Multi I/O board and check for behavior of the registers, such as specific bits that can or can't be changed. I wrote tests for the cards that I have, the CFFA1 flash card, Multi I/O card, and ACI Apple Cassette Interface (the latter I don't yet have).

I tested the new info command with 6502, 65C02, and 65816 processors and 1 MHz and 2 MHz crystal oscillators. I also tested it on the POM1 emulator. A screenshot under POM1 is shown below.

Info Command Running on the POM1 Emulator

With these changes I am running out of features to add to JMON so I am considering it to be feature complete and calling it version 1.0.

I noticed it recently exceeded 8K in size, so it no longer fits in a single 8K EPROM. I could reduce it to under 8K by disabling some features. The disassembler has some reasonably large tables (which the assembler also uses).

JMON Trace Function

I've implemented one of the features missing from JMON, and one that I had been relying on Krusader's mini monitor for: an instruction trace function. This function allows you to single step through a program, see a disassembly of the current instruction, and see the values of the hardware registers. This feature is almost indispensable for debugging code. Krusader does this but I wanted to write my own.

I can think of at least three ways to single step code. One is a hardware solution. The Apple 1 manual actually shows a circuit that does this, and presumably Woz used this circuit to debug the Apple 1. This approach is very useful for bringing up new hardware that may not yet be working, but it is complex and expensive.

A second approach is the use the breakpoint instruction (BRK). By inserting a BRK instruction in code, when executed it can jump to the break vector which can run code which shows the current values of the registers. You can then replace the BRK with the original instruction and place a BRK at the next instruction, and continue execution. A disadvantage of this approach is that it only works for code in RAM and not ROM, since the program memory must be written to with the BRK instruction.

A third approach, and the one I used, is to look at the next instruction to be executed, copy it to a buffer, and execute it in place. The instruction can be followed by code that jumps back into the trace code in the monitor program. This approach has the advantage of working even for code that is in ROM.

To make this work there are a couple of wrinkles. Some instructions change the flow of control (e.g. JMP and JSR) and would jump out of the trace code. To trace these I simulate instead of execute them, doing the equivalent of what the instruction would do. For example. a JMP instruction just needs to update the value of the program counter. These special instructions are JMP, JSR, RTS, RTI, and BRK. Similar are the branch instructions. Initially I thought I would simulate these, looking at the CPU registers to determine whether the branch was taken or not. This would get a little complex as there are about 8 branch instructions to simulate, each checking a different condition. Instead I use a simpler approach that can use the same code for all branches. I execute the branch instruction in the buffer, but I adjust the branch destination so it jumps to a known location in the trace code. Whether the branch is taken or not, it stays under control of the trace code.

My trace function produces similar output to Krusader's mini monitor. You can set the register values use the Register command, including the Program Counter. The "." command traces/executes one instruction.

The breakpoint feature of JMON works in conjunction with this. If a breakpoint is hit, it updates the register values and you can single step as desired. You can also use the Go command to execute from the current program counter address.

It took a little work to get all of this correct for all instructions. It leveraged the previous work on the disassembler and mini assembler. For example, I needed to know the length of each instruction and this information was already available in tables used by the disassembler.

A sample session is shown below. Commands entered by the user are in bold. The actual trace commands "." are not echoed.

JMON MONITOR 0.99 BY JEFF TRANTER
? R
A-00 X-00 Y-00 S-0140 P-00 ........
0000   00          BRK
A-00 X-00 Y-00 S-0140 P-00 ........
PC-6000
? R
A-00 X-00 Y-B0 S-0140 P-00 ........
6000   EA          NOP
A-Esc
? A-00 X-00 Y-B0 S-0140 P-30 ..-B....
6001   A9 01       LDA   #$01
? A-01 X-00 Y-B0 S-0140 P-30 ..-B....
6003   A0 01       LDY   #$01
? A-01 X-00 Y-01 S-0140 P-30 ..-B....
6005   A2 01       LDX   #$01
? A-01 X-01 Y-01 S-0140 P-30 ..-B....
6007   08          PHP
? A-01 X-01 Y-01 S-013F P-30 ..-B....
6008   68          PLA
? A-30 X-01 Y-01 S-0140 P-30 ..-B....
6009   38          SEC
? A-30 X-01 Y-01 S-0140 P-31 ..-B...C
600A   18          CLC
? A-30 X-01 Y-01 S-0140 P-30 ..-B....
600B   69 01       ADC   #$01
? A-31 X-01 Y-01 S-0140 P-30 ..-B....
600D   F8          SED
? A-31 X-01 Y-01 S-0140 P-38 ..-BD...
600E   69 10       ADC   #$10
? A-41 X-01 Y-01 S-0140 P-38 ..-BD...
6010   D8          CLD
? A-41 X-01 Y-01 S-0140 P-30 ..-B....
6011   4C 17 60    JMP   $6017
? A-41 X-01 Y-01 S-0140 P-30 ..-B....
6017   20 15 60    JSR   $6015
? A-41 X-01 Y-01 S-013E P-30 ..-B....
6015   EA          NOP
? A-41 X-01 Y-01 S-013E P-30 ..-B....
6016   60          RTS
? A-41 X-01 Y-01 S-0140 P-30 ..-B....
601A   A9 28       LDA   #$28
? 

As part of my testing I modified the code to stay in trace mode and ran the Woz monitor and Apple BASIC under the trace code. They executed correctly, although a little slower than normal.

The code supports 65C02 instructions without any extra coding except the BBR and BBS commands which would need some additional branch instruction support. Some 65816 instructions should work but the new instructions which change flow of control would fail and it doesn't understand the variable length of instructions depending on the CPU mode (but it would be quite straightforward to add).

This new trace function should prove useful for debugging future code I write. As always, the code can be found here.

Android version of POM1 Emulator

I earlier talked about the POM1 Apple 1 Emulator. John Corrado recently ported it to Android so it runs on Android devices like phones and tablets. It's quite cool to see Apple 1 code running on a phone. It's also quite shocking how much computer power has improved - my phone has at least 1000 times the computing power and resources of the Apple 1.

Below is a picture of JMON running on my Android phone:

POM1 Running on an Android Phone

And here are a couple screen shots of JMON running on the desktop version of the POM1 emulator:

JMON Help Screen

JMON Disassembly Feature

You can get the Android version from the Google Play app store. Look for "pom1". The POM1 simulator is maintained at pom1.sourceforge.net.

---

I mentioned planning to add 65C02 support to the mini assembler in JMON. Well, that only took about an hour, as it only involved adding support for the two new addressing modes. It now supports 65C02 instructions, other than the BBR and BBS instructions which have a special syntax.

---

While I was adding 65C02 support I thought I would write a little quick reference like I did for the 65816. I've almost finished the one page document which outlines the new software features of the 65C02 over the 6502. It will be available for download here.

Implementing A Mini Assembler

One of the features missing from JMON was a "mini assembler" like the one included in the Apple II computers.

I implemented one with roughly the same features and limitations as the one in the Apple II, i.e. it assembles simple 6502 assembly language code where all numeric values are in hex and there is no support for symbols or labels.

It is very handy for writing short assembly language programs where you don't want to fire up a cross-assembler or even Krusader.

In conjunction with the disassembler you can verify the program you entered and then run it.

The code leveraged the data tables in the JMON disassembler. Most of the work is parsing the entered code to validate it and determine the addressing mode.

While I only implemented 6502 support in this first version, because it uses the tables from my disassembler, it does accept 65C02 and even 65816 instructions that use the standard 6502 addressing modes. It just doesn't yet understand the new addressing modes for the 65C02 or 65816.

A sample session is shown below, where the user entered text is in bold.

? A 6F00
6F00: CLD
6F01: CLI
6F02: LDY #7F
6F04: STY D012
6F07: LDA #A7
6F09: STA D011
6F0C: STA D013
6F0F: LDA #5C
6F11: JSR 6FEF
6F14: JSR 6F1B
6F17: BCC 6F0F
6F19: BCS 6F14
6F1B: JSR 6EE5
6F1E: LDY #01
6F20: DEY
6F21: BMI 6F1B
6F23: JSR 6EBE
6F26: STA 0200,Y
6F29: CMP #0D
6F2B: BEQ 6F38
6F2D: CMP #5F
6F2F: BEQ 6F20
6F31: CMP #1B
6F33:

It provides meaningful error messages and checks the validity of the code. Below are some error messages:

6000: LDA #1234
INVALID OPERAND
6000: LDA (1234)
INVALID ADDRESSING MODE
6000: BNE 7000
RELATIVE BRANCH OUT OF RANGE
6000: LDB
INVALID INSTRUCTION

I tested it as I built up the code, but the final test was to disassemble about a thousand lines of JMON code and then feed that back to the assembler and confirm that it accepted it and generated the same code.

I'll probably add support for the rest of the 65C02 instructions in future and maybe also the 65816.

As always, the code is available here.

65816 Disassembly - 8 and 16 bit modes

Today I made JMON a little smarter about 65816 disassembly. It now handles 8-bit and 16-bit instructions, looking at SEP and REP instructions to determine what mode the CPU is currently in. Of course, it cannot always get this correct as it doesn't know if code could be called when the CPU is in a specified mode. It starts in all 8-bit mode. This is similar to how the CC65 assembler works in "auto" mode unless you use assembler directives to explicitly set the mode.

While I was testing this I noticed the SEP instruction was disassembled as CPX. There is actually an error in the Western Design Center manual in Chapter 19, Instruction Lists, which I had copied when I entered the op codes. The byte $E2 is SEP but is listed as CPX.

Here is sample disassembly output from JMON showing all 4 combinations of 8 and 16-bit accumulator and index register modes (I've manually added spaces to highlight where the mode changes).

JMON MONITOR 0.97 BY JEFF TRANTER
? U 60B9
60B9   E2 30       SEP   #$30
60BB   09 12       ORA   #$12
60BD   29 12       AND   #$12
60BF   49 12       EOR   #$12
60C1   69 12       ADC   #$12
60C3   89 12       BIT   #$12
60C5   A9 12       LDA   #$12
60C7   C9 12       CMP   #$12
60C9   E9 12       SBC   #$12
60CB   A0 12       LDY   #$12
60CD   A2 12       LDX   #$12
60CF   C0 12       CPY   #$12
60D1   E0 12       CPX   #$12


60D3   C2 30       REP   #$30
60D5   09 34 12    ORA   #$1234
60D8   29 34 12    AND   #$1234
60DB   49 34 12    EOR   #$1234
60DE   69 34 12    ADC   #$1234
60E1   89 34 12    BIT   #$1234
60E4   A9 34 12    LDA   #$1234
60E7   C9 34 12    CMP   #$1234
60EA   E9 34 12    SBC   #$1234
60ED   A0 34 12    LDY   #$1234
60F0   A2 34 12    LDX   #$1234
60F3   C0 34 12    CPY   #$1234
60F6   E0 34 12    CPX   #$1234


60F9   C2 20       REP   #$20
60FB   E2 10       SEP   #$10
60FD   09 34 12    ORA   #$1234
6100   29 34 12    AND   #$1234
6103   49 34 12    EOR   #$1234
6106   69 34 12    ADC   #$1234
6109   89 34 12    BIT   #$1234
610C   A9 34 12    LDA   #$1234
610F   C9 34 12    CMP   #$1234
6112   E9 34 12    SBC   #$1234
6115   A0 12       LDY   #$12
6117   A2 12       LDX   #$12
6119   C0 12       CPY   #$12
611B   E0 12       CPX   #$12


611D   E2 20       SEP   #$20
611F   C2 10       REP   #$10
6121   09 12       ORA   #$12
6123   29 12       AND   #$12
6125   49 12       EOR   #$12
6127   69 12       ADC   #$12
6129   89 12       BIT   #$12
612B   A9 12       LDA   #$12
612D   C9 12       CMP   #$12
612F   E9 12       SBC   #$12
6131   A0 34 12    LDY   #$1234
6134   A2 34 12    LDX   #$1234
6137   C0 34 12    CPY   #$1234
613A   E0 34 12    CPX   #$1234

DEBUG16 - 65816 Disassembler and Trace Utility

Now that my Replica 1 is running with a 65816 processor, I wanted to try a program that was more substantial than the small demo programs I had tried.

The manual Programming the 65816 Including the 6502, 65C02 and 65802 available from The Western Design Center has a chapter describing and giving the source code for a program called DEBUG16. The program can perform disassembly and instruction tracing of 65816 machine code. It is about 1700 lines of assembler code. I thought I would try porting it to my Replica 1 using the CC65 assembler.

The first step was copying and pasting the assembler listings from the PDF file for the manual. That gave me a text file with the assembler listing of the original code.

Then I stripped out the the listing portion of the file to generate an assembler source file. It needed some changes to port it to the CC65 assembler, due to differences in it's assembler directives. After making a number of changes I had a file which would assemble and I could compare to the original listing.

It turns out there are a number of typographical as well as logic errors in the listing in the manual. A Google search shows at least one other person tried getting this code to work (about 10 years ago) and noticed the errors. After some detective work I think I was able to determine what the errors were, and obtained a file which could successfully build and generated the same code as in the original listing.

The original code was intended for running on an Apple //e with a 65816 card. The Apple specific code (e.g. for input and output) was clearly indicated in the source. I made the necessary changes to the input/output code to work on the Replica 1.

Next, I wrote a small main routine to call the LIST routine which disassembles 65816 code (I had it disassemble itself). Somewhat to my surprise, it actually produced reasonable output on the first try. I found a few errors in the code, such as an instruction or two that were disassembled incorrectly. I fixed that, although there may be some issues with a few instructions. It is at least correct enough for 6502 code that I can disassemble my entire JMON program and get the same output as from the 6502 disassembler that I wrote.

A sample of the output is shown here:

00:6013   08        PHP                                               
00:6014   18        CLC                                               
00:6015   FB        XCE                                               
00:6016   08        PHP                                               
00:6017   0B        PHD                                               
00:6018   F40000    PEA     $0000                                     
00:601B   2B        PLD                                               
00:601C   C220      REP     #$20                                      
00:601E   E210      SEP     #$10                                      
00:6020   649D      STZ     $9D                                       
00:6022   A580      LDA     $80                                       
00:6024   8584      STA     $84                                       
00:6026   A682      LDX     $82                                       
00:6028   8686      STX     $86                                       
00:602A   A780      LDA     [$80]                                     
00:602C   AA        TAX                                               
00:602D   8687      STX     $87                                       
00:602F   207762    JSR     $6277                                     
00:6032   204760    JSR     $6047                                     
00:6035   208F60    JSR     $608F                                     
00:6038   20CD61    JSR     $61CD                                     
00:603B   9005      BCC     $6042                                     
00:603D   20D462    JSR     $62D4                                     
00:6040   80DA      BRA     $601C                                     
00:6042   2B        PLD                                               
00:6043   28        PLP                                               
00:6044   FB        XCE                                               
00:6045   28        PLP                                               
00:6046   60        RTS                                               
00:6047   201D62    JSR     $621D                                     
00:604A   E230      SEP     #$30                                      
00:604C   A000      LDY     #$00                                      
00:604E   A586      LDA     $86                                       
00:6050   20F761    JSR     $61F7

The other function of DEBUG16 is a trace facility that allows stepping through 65816 code and seeing the current value of registers and disassembled instructions. This code has significantly more dependencies on Apple II functions and is harder to port. I spent some time on it, but it is tricky to debug the code as the 65816 changes in and out of native mode and 8/16 bit data and index register modes, and existing debug tools I have like Krusader's mini-monitor will not work in the 65816's native mode. I set this aside to look at later.

So the current status is that the disassembly routine is working well although it has not been tested exhaustively for all 65816 instructions. The trace function has not yet been tested or debugged. The code is available here.

While I was playing with the 65816, I took the time to make a little 65816 quick reference document. It can be printed on one double-sides page, and lists the register model, new addressing modes and instructions, and some other specifics of the 65816. It is most useful if you are familiar with the 6502 and are looking for a quick summary of what is added by the 65816. You can get it here in both OpenOffice.org and PDF formats.

Using the 65816 Processor

The Western Design Center 65816 is a 6502 family processor. It is backwards software compatible with the 6502 and 65C02 and was used on a number of computers including the Apple IIGS.

I've been playing with one using the CPU adaptor board I built for my Replica 1.

The 65816 comes up in "emulation mode" where it is software compatible with the 6502 and 65C02. It also implements a number of new instructions, some of which are in the 65C02 and some are new ones.

You can switch the 65816 to "native mode" at any time under software control. Native mode offers 16-bit X and Y registers and accumulator, a 24-bit address space (16 megabytes), new instructions and new addressing modes. In native mode you independently configure whether the accumulator and index registers are 8 or 16-bit. Zero page (now called direct page) and the stack can be relocated anywhere in memory.

The chip is not electrically compatible with the 6502 or 65C02. The 65802 was plug-in compatible with the 6502 but is no longer being made. The 65816 is almost compatible. The adaptor I constructed makes it compatible, or at least compatible enough for the Replica 1.

There are some limitations of the adaptor: the system still only has 16 address lines so 16MB addressing is not possible. The extra 8 high order address lines are ignored. Some hardware pins are also not supported, such as SO and SYNC, but these are not used on the Replica 1.

The only compatibility issue I have run onto is with the CFFA1 compact flash adaptor. It gives an "I/O" error. I suspect it is either due to instruction timing differences or more likely the timing of the clock signals generated by the adaptor is not quite right. I need to investigate further.

Having 16-bit registers is a nice luxury and you can still use 8-bits when you need it, by switching modes, which can save speed and code size.

There are even two new memory copy instructions which can copy a range of memory, up to the full address space, in a single instruction.

I wrote three small demo programs, available here. They compile with the CA65 assembler which fully supports the 65816 instruction set. It even has a "smart" mode where the assembler tracks whether the CPU is in 8 or 16-bit accumulator and index registers modes and generates the code accordingly.

Demo 1 uses some of the new instructions in emulation mode and then switches to native mode, first with 8-bit accumulator and index registers, and then switches to 16-bit. What can be confusing is that an instruction like PHA can push 1 or 2 bytes on the stack depending on the mode selected. An instruction like LDA #$1234 is only valid in 16-bit accumulator mode. As you can imagine, existing 8-bit 6502 machine code will soon break if run in 16-bit mode.

Demo 2 uses the MVP (MOve Positive) instruction. First it copies an overlapping range of memory, demonstrating how it can be used to fill a range of memory, in this case with zeroes. Then it does the more commonly uses copy of a range of memory from one area to another. With this single instruction you can move any amount of memory up to the full 24MB address space, taking 7 cycles per byte copied.

Demo 3 is an example taken from the Western Design Center manual which determines the CPU type: 6502, 65C02, or 65816. I extended it to be a complete program which displays the result on the Replica 1.

Links

Here are some useful links related to the 65816:

1. http://en.wikipedia.org/wiki/WDC_65816/65802
2. http://www.zophar.net/fileuploads/2/10538ivwiu/65816info.txt
3. http://www.defence-force.org/computing/oric/coding/annexe_2/
4. http://www.smwiki.net/wiki/65c816
5. http://www.zophar.net/documents/65816.html

The definitive manual is Programming the 65816 Including the 6502, 65C02 and 65802 and is available as a free download from Western Design Center's web site, as is the data sheet.