Space Assault Port to 6800

Now, on to the bigger project I've been hinting at... :-)

So...Space Assault is a clone of the well known arcade hit Space Invaders, produced for the Tandy Color Computer by The Image Producers, (written by Lou Haehn?) and released in 1981. Some time ago, Darren Atkinson took it upon himself to disassemble the Space Assault ROM image for the CoCo and to do a binary translation of the 6809 code into a version for the 6803-based Tandy MC-10. The MC-10 version plays very much like the CoCo version, with modifications from Darren to accommodate use of the MC-10 keyboard in place of the CoCo joystick.

It occurred to me that this bit of MC-10 magic might be a good candidate for porting to my Micro Chroma 68 (uchroma68), so I sent Darren an email requesting access to his MC-10 Space Assault source. Darren was nice enough to oblige, so I immediately checked his source into a git repository and set about to making the initial superficial changes necessary to reproduce his MC-10 Space Assault binary using my chosen assembler, the old Motorola Freeware BBS assembler.

6803 > 6808

Working MC-10 code seems like a good place to start for a uchroma68 port, but some more preparation work is still required. The problem is that not all code that runs on the 6803 CPU in the MC-10 will also run on the 6808 CPU in the uchroma68. The 6808 (and the related 6802) execute the same instruction set as the earlier 6800, without any additions. But the 6803 (and the related 6801) use a somewhat improved architecture that supports a number of instructions that are not supported by their 6800/6802/6808 cousins. Not only are these extra instructions quite useful, they also make the 6803 a bit more like the 6809 architecturally. It is no surprise to learn that Darren used a number of these new instructions when porting Space Assault from the 6809 to the MC-10's 6803. Porting the MC-10 version of Space Assault to run on the uchroma68's 6808 will involve replacing these 6801/6803 instructions with 6800/6802/6808-compatible sequences.

Macro-like Translations


Several of the new 6801/6803 instructions involve an architectural change that allows the 8-bit A and B accumulators to be grouped together as the 16-bit D accumulator. Instructions like "LDD" and "STD" are easily replaced with "LDAA/LDAB" and "STAA/STAB" combinations, just as "ADDD" is easily replaced with an "ADDB/ADCA" combination. Using a macro processor (either built-in to an assembler or something external like m4) should make these substitutions trivial, requiring no changes to the source code at all. But as I am using the quite primitive assembler from Motorola, I simply made these changes directly in the source code -- the triviality made this more worthwhile than introducing an m4 pass in the Makefile.

Emulation Functions

Some of the other new 6801/6803 instructions are not so easily replaced. Equivalent instruction sequences are lengthy, and require allocation of memory for temporary storage of registers used in those sequences. Instructions such as "PSHX", "PULX", and "ABX" are in this category, and they are so useful that again it is no surprise that Darren makes hearty use of them in his MC-10 port of Space Assault. In this effort, I found that replacing these instructions with equivalent subroutine calls provided good results while only requiring six bytes for temporary storage of the D, X, and S registers and a few bytes for a temporary stack. (The S register storage and the temporary stack were required to avoid data corruption in a couple of places where an emulated "ABX" was required within a routine that was using S as a pointer for data movement.)

EMUSAVS    rmb       2            ; temp storage of S for 6801/6803 emu
EMUSAVX    rmb       2            ; temp storage of X for 6801/6803 emu
EMUSAVD    rmb       2            ; temp storage of D for 6801/6803 emu

EMUSTACK   rmb       3            ; temp stack for 6801/6803 emu calls
EMUSTKTOP rmb       1

emu_abx
          pshb
          psha
          stx        EMUSAVX
          clra
          addb     EMUSAVX+1
          adca     EMUSAVX
          staa      EMUSAVX
          stab      EMUSAVX+1
          ldx        EMUSAVX
          pula
          pulb
          rts

emu_pshx
          stx        EMUSAVX             ; save X
          tsx
          staa      EMUSAVD             ; save A & B
          stab      EMUSAVD+1
          ldaa      ,x                  ; get return address from stack
          ldab      1,x
          pshb                          ; push return address onto stack
          psha                          ; - also adjusts stack pointer
          ldaa      EMUSAVX             ; retrieve X value
          ldab      EMUSAVX+1
          staa      ,x                  ; save X value onto stack
          stab      1,x
          ldaa      EMUSAVD             ; restore A & B
          ldab      EMUSAVD+1
          ldx        EMUSAVX             ; restore X value
          rts

emu_pulx

          tsx
          staa      EMUSAVD             ; save A & B
          stab      EMUSAVD+1
          ldab      3,x                 ; get X from stack
          ldaa      2,x
          staa      EMUSAVX             ; save X
          stab      EMUSAVX+1
          pula                          ; get return address from stack
          pulb                          ; - also adjusts stack pointer
          stab      3,x                 ; save return address onto stack
          staa      2,x
          ldaa      EMUSAVD             ; restore A & B
          ldab      EMUSAVD+1
          ldx        EMUSAVX             ; set new X value
          rts

Simple Rewrite

Perhaps the most complicated new 6801/6803 instruction is "MUL", which of course multiplies the 8-bit accumulators A and B to produce a 16-bit product in the D accumulator. I anticipated coding a lengthy routine to emulate this instruction, but I found that the code was only doing a multiply by a fixed value of 5! Two left shifts and a single add produced equivalent results, so "MUL" was no longer an issue... :-)

More To Come

I think that covers the remaining "prep" work for the uchroma68 port of Space Assault. At this point, I have code for a machine that does not exist: an MC-10 with a 6800 CPU. The result, of course, will run on a normal MC-10 -- but that would be a pointless objective. I would show a demo video here, but the result is virtually indistinguishable from Darren's original code. Hopefully you can just trust me -- it works. ;-)

The next step will be accounting for differences between the board-level architectures of the MC-10 and the uchroma68. This involves differing locations for video memory, and for where the code and data are loaded and stored. It also involves accounting for I/O differences, such as reading inputs from the keyboard and possibly making sounds. It will all be very much "in the weeds", of course...stay tuned!

Micro Chroma 68 Tape Storage

In my previous post, I showed video of me loading and running code on an emulated Micro Chroma 68 (aka uchroma68) machine, and hinted at a bigger project. I intended to be back sooner to describe the code loading process and then move-on to the bigger project. But, I got started on the bigger project and neglected the next blog update -- time to get back on track!

Audio-Encoded Data

Code can be loaded onto the uchroma68 in a variety of ways, including from the keyboard input or over an audio-encoded interface intended for using "compact cassettes" for mass storage. For real hardware, other options include modifications to use an ACIA for serial input or modern interfaces to drive the keyboard interface from a remote computer. But since our objective includes targeting the unmodified MAME-emulated uchroma68, it seems best to pursue only standard options for loading code.

So, how to convert object coded into appropriate audio?

Kansas City Standard

The Kansas City standard (KCS), or Byte standard, is a way of storing digital data on standard Compact Audio Cassettes at data rates of 300 to 2400 bits per second (at 300–2400 baud) that was first defined in 1976. It originated in a symposium sponsored by Byte magazine in November 1975 in Kansas City, Missouri to develop a standard for storage of digital microcomputer data on inexpensive consumer quality cassettes.

The uchroma68 uses the Kansas City Standard for audio data encoding. This old standard defined how to transfer bits and bytes as audio, suitable for storage on consumer audio tape. Fortunately for me, open source tools (e.g. py-kcs) already exist for encoding and decoding such audio. Unfortunately, some of those tools presume to deal only with ASCII-encoded test files (e.g. BASIC programs). Since I needed to deal with binary data, I did have to write a patch to allow for handling binary input to the KCS encoder:

 diff --git a/kcs_encode.py b/kcs_encode.py
index 21bbf080917d..1f078dd0b537 100755
--- a/kcs_encode.py
+++ b/kcs_encode.py
@@ -52,7 +52,7 @@ def kcs_encode_byte(byteval):

 # Write a WAV file with encoded data. leader and trailer specify the
 # number of seconds of carrier signal to encode before and after the data
-def kcs_write_wav(filename,data,leader,trailer):
+def kcs_write_wav(filename,data,leader,trailer,binary):
     w = wave.open(filename,"wb")
     w.setnchannels(1)
     w.setsampwidth(1)
@@ -64,7 +64,7 @@ def kcs_write_wav(filename,data,leader,trailer):
     # Encode the actual data
     for byteval in data:
         w.writeframes(kcs_encode_byte(byteval))
-        if byteval == 0x0d:
+        if not binary and byteval == 0x0d:
             # If CR, emit a short pause (10 NULL bytes)
             w.writeframes(null_pulse)
   
@@ -74,16 +74,29 @@ def kcs_write_wav(filename,data,leader,trailer):

 if __name__ == '__main__':
     import sys
-    if len(sys.argv) != 3:
-        print("Usage : %s infile outfile" % sys.argv[0],file=sys.stderr)
+    import optparse
+
+    p = optparse.OptionParser()
+    p.add_option("-b",action="store_true",dest="binary")
+    p.add_option("--binary",action="store_true",dest="binary")
+    p.set_defaults(binary=False)
+
+    opts, args = p.parse_args()
+    if len(args) != 2:
+        print("Usage : %s [-b] infile outfile" % sys.argv[0],file=sys.stderr)
         raise SystemExit(1)

-    in_filename = sys.argv[1]
-    out_filename = sys.argv[2]
-    data = open(in_filename,"U").read()
-    data = data.replace('\n','\r\n')         # Fix line endings
-    rawdata = bytearray(data.encode('latin-1'))
-    kcs_write_wav(out_filename,rawdata,5,5)
+    in_filename = args[0]
+    out_filename = args[1]
+    if opts.binary:
+        data = open(in_filename, 'rb').read()
+        rawdata = bytearray(data)
+    else:
+        data = open(in_filename, 'r', newline=None).read()
+        data = data.replace('\n','\r\n')         # Fix line endings
+        rawdata = bytearray(data.encode('latin-1'))
+
+    kcs_write_wav(out_filename,rawdata,5,5,opts.binary)

With that, I could encode audio data for the uchroma68 by using the '-b' option which I added to kcs_encode.py. But what about the logical format of that data?

JBUG-Compatible Format

Knowing how to send 0's and 1's is not too helpful until one knows what 0's and 1's to send. Even a program binary still needs to be accompanied by information such as where to write the program in memory and perhaps protocol data used to manage the transfer. The TVBUG firmware on the uchroma68 uses a format for binary data that is compatible with the format used by the JBUG firmware from the MEK6800D2 board which had preceded it, although TVBUG allows for an extension to the format that provides for the program name to be encoded along with the program data. Based on information from the TVBUG and JBUG manuals and some reading of the assembly language listings of those programs, I was able to write a script that converts a binary program file into a hex dump representing the data prepared for audio encoding:

#!/bin/sh

###########################################################
# Convert a binary to hexdump of JBUG logical tape format
#       (used by both JBUG and TVBUG)
###########################################################

usage() {
        cat <<USAGE
usage: $(basename $0) [-l <loadaddr>] [-n <progname>] [-p] <filename>

        -l <loadaddr>   base load address
        -n <progname>   output program name
        -p              pad tape output with 0xff characters
        <filename>      input data file
USAGE
}

while getopts ":l:n:p" opt
do
        case ${opt} in
        l)
                LOADADDR=$OPTARG
                ;;
        n)
                PROGNAME=$OPTARG
                ;;
        p)
                PADOUT=1
                ;;
        \?)
                echo "Invalid option: $OPTARG" 1>&2
                ;;
        :)
                echo "Invalid option: $OPTARG requires an argument" 1>&2
                ;;
        esac
done
shift $((OPTIND-1))

# Set default load address of zero (if not specified on command-line)
LOADADDR=${LOADADDR:-0}

if [ $# -ne 1 ]
then
        usage
        exit 1
fi

INFILE=$1
INSIZE=$(stat -c %s $INFILE)

if [ x$PADOUT = x1 ]
then
        for i in $(seq 1 1024)
        do
                echo -n 'ff'
        done
        echo
fi

if [ -n "$PROGNAME" ]
then
        echo -n $PROGNAME | xxd -p
        echo '0d'
fi

OUTSIZE=0
while [ $OUTSIZE -lt $INSIZE ]
do
        BLOCKSIZE=$(($INSIZE - $OUTSIZE))
        if [ $BLOCKSIZE -gt 256 ]
        then
                BLOCKSIZE=256
        fi

        echo -n 'ff'
        echo -n '42'
        printf '%x' $(($BLOCKSIZE - 1))
        printf '%04x' $(($LOADADDR + $OUTSIZE))

        xxd -p -g 1 -l $BLOCKSIZE -s $OUTSIZE $INFILE

        OUTSIZE=$(($OUTSIZE + $BLOCKSIZE))
done

if [ x$PADOUT = x1 ]
then
        for i in $(seq 1 144)
        do
                echo -n 'ff'
        done
fi

echo -n 'ff'
echo '47'

The hex dump output can be fed to the xxd utility (e.g. 'xxd -p -r'), captured, and then encoded to Kansas City Standard format audio.

Demo

In my earlier post, I mentioned "a text-based animation that I originally ported from a VZ-200 C program to assembly language for the MC-10 which I had always suspected would be easy to get on the uchroma68". Well, I was right -- changing two "equ" statements (one for the load address and one for the screen address) was all that was required...

But wait -- there's more! The bigger project involves more porting from the MC-10 to the Micro Chroma 68, this time porting some code that originated on the Tandy Color Computer before being ported by Darren Atkinson.

Intrigued? Then stay tuned...