Producing Commodore 64 programs

Commodore 64 programs are stored in the PRG format on disk. Some emulators (such as CCS64 or VICE) can run PRG programs directly; others need them to be transferred to a D64 image first.

The PRG format is ludicrously simple. It has two bytes of header data: This is a little-endian number indicating the starting address. The rest of the file is a single continuous chunk of data loaded into memory, starting at that address. BASIC memory starts at memory location 2048, and that's probably where we'll want to start.

Well, not quite. We want our program to be callable from BASIC, so we should have a BASIC program at the start. We guess the size of a simple one line BASIC program to be about 16 bytes. Thus, we start our program at memory location 2064 ($0810), and the BASIC program looks like this:

10 SYS 2064
    

We SAVE this program to a file, then study it with a hex dumper. It's 15 bytes long:

00000000  01 08 0c 08 0a 00 9e 20  32 30 36 34 00 00 00     |....... 2064...|
    

The first two bytes are the memory location: $0801. The rest of the data breaks down as follows:

That's 15 bytes, of which 13 are actually loaded into memory. We started at 2049, so we need 2 more bytes of filler to make our code actually start at location 2064. These 17 bytes will give us the file format and the BASIC code we need to have our machine language program run.

These are just bytes—indistinguishable from any other sort of data. In Ophis, bytes of data are specified with the .byte command. We'll also have to tell Ophis what the program counter should be, so that it knows what values to assign to our labels. The .org (origin) command tells Ophis this. Thus, the Ophis code for our header and linking info is:

.byte $01, $08, $0C, $08, $0A, $00, $9E, $20
.byte $32, $30, $36, $34, $00, $00, $00, $00
.byte $00, $00
.org $0810
    

This gets the job done, but it's completely incomprehensible, and it only uses two directives—not very good for a tutorial. Here's a more complicated, but much clearer, way of saying the same thing.

.word $0801
.org  $0801

        .word next, 10       ; Next line and current line number
        .byte $9e," 2064",0  ; SYS 2064
next:   .word 0              ; End of program

.advance 2064
    

This code has many advantages over the first.

• It describes better what is actually happening. The .word directive at the beginning indicates a 16-bit value stored in the typical 65xx way (small byte first). This is followed by an .org statement, so we let the assembler know right away where everything is supposed to be.

• Instead of hardcoding in the value $080C, we instead use a label to identify the location it's pointing to. Ophis will compute the address of next and put that value in as data. We also describe the line number in decimal since BASIC line numbers generally are in decimal. Labels are defined by putting their name, then a colon, as seen in the definition of next.

• Instead of putting in the hex codes for the string part of the BASIC code, we included the string directly. Each character in the string becomes one byte.

• Instead of adding the buffer ourselves, we used .advance, which outputs zeros until the specified address is reached. Attempting to .advance backwards produces an assemble-time error. (If we wanted to output something besides zeros, we could add it as a second argument: .advance 2064,$FF, for instance.)

• It has comments that explain what the data are for. The semicolon is the comment marker; everything from a semicolon to the end of the line is ignored.

We can do better still, though. That initial starting address of 2064 was only ever a guess; now that we know that we overshot by two bytes, we can simply change the starting address to 2062 and omit the .advance directive entirely. In fact, we can even remove the space before the number and make it 2061 instead—BASIC doesn't need that space in its instruction and it's arguably a wasted byte.