Programming Your Own Atari Cartridge

Two green Atari text screens: HELLO FROM AN 8K CARTRIDGE, OPTION BYTE $04, MEMLO = $0700; and the same with OPTION BYTE $05 and MEMLO = $1C6C

A cartridge is the simplest way to start a program on an Atari 8-bit: no loader and no DOS, just ROM appearing at $A000 the moment the machine is switched on. The operating system checks for one at every power-up and every RESET, using six bytes at the top of the cartridge's memory. Today you can build a cartridge image with a cross-assembler, test it in an emulator in seconds, and write it to a flash cartridge or EPROM for real hardware.

What you'll learn: the cartridge header byte by byte, the exact order in which the OS initialises and starts a cartridge (taken from the Rev. A OS source), what the option byte's bits do, how to let DOS boot underneath your cartridge, and how to produce .bin and .car files.

What you need: MADS, a few lines of Python (or any language) for the CAR header, and Altirra or atari800. The Atari 8-bit File Formats Explained guide introduces the CAR format, and this guide uses it.

1. Where cartridges live

Slot Address range Header at
Left (A), all models $A000–$BFFF (8K) $BFFA–$BFFF
Right (B), 800 only $8000–$9FFF (8K) $9FFA–$9FFF
16K cartridge, left slot $8000–$BFFF $BFFA–$BFFF

Nearly all cartridges, including BASIC, use the left slot. A 16K cartridge simply occupies both 8K windows from the left slot, so its header is still at the top of $BFFF. The cartridge's ROM replaces the RAM at those addresses, so the OS reports less memory: RAMTOP drops to $A0 (or $80 for 16K). On XL/XE machines an inserted cartridge also takes priority over the built-in BASIC ROM at $A000.

2. The six-byte header

Address Name Meaning
$BFFA/$BFFB CARTCS Run address, where the OS jumps to start the cartridge
$BFFC CART Must be 0. A non-zero value here means "no cartridge"
$BFFD CARTFG Option byte (bits below)
$BFFE/$BFFF CARTAD Init address, called with JSR at power-up and on every RESET

Option byte bits:

  • Bit 0 = 1: boot the disk as well. Without it, a cartridge-only system skips the disk boot completely.
  • Bit 2 = 1: start the cartridge (jump to CARTCS) once initialisation is complete. With bit 2 clear, the cartridge is initialised but not started.
  • Bit 7 = 1: diagnostic cartridge. The OS hands over control almost immediately, before it has set up anything.

So $04 means "run me, no disk", $05 means "boot the disk, then run me", and $01 means "boot the disk and let it run, but call my init on every reset". The last is how a cartridge can quietly add something to the system.

3. What the OS does, in order

The power-up and RESET code in the Atari 400/800 OS listing makes the sequence clear:

  1. Diagnostic check. Very early, before it clears memory or sizes RAM, the OS checks whether $BFFC reads 0. It then increments that byte and reads it back to make sure it is really ROM and not RAM. If it is ROM and bit 7 of the option byte is set, the OS jumps through CARTAD and never returns. Your code gets a machine with no RAM cleared, no vectors and no screen.
  2. Normal initialisation. RAM is cleared (only the OS areas on a warm start), the vectors and the HATABS handler table are set up, and MEMLO is set to $0700.
  3. Cartridge init. If the right cartridge is present it is checked first, and then the left one. For each one present (where $xFFC is 0), the OS sets a flag in page zero (location 6 for A, 7 for B) and calls CARTAD with JSR. Your init routine must end in RTS. The screen editor isn't open yet at this point, so don't try to print.
  4. Screen editor opened, cassette boot checked.
  5. Disk boot, if there is no cartridge or if either cartridge's option byte has bit 0 set. DOS loads, and so does an AUTORUN.SYS.
  6. Start. If cartridge A's bit 2 is set, the OS jumps through CARTCS. Otherwise it tries cartridge B, and otherwise it jumps through DOSVEC (DOS, or the Memo Pad if there is none).

A warm start (RESET) goes through the same path with the warm-start flag set. Your init routine is called again and your program is restarted from CARTCS. The cartridge port has no reset line, so bank-switched cartridges can't tell that RESET was pressed. Every bank that might be mapped in at the time needs valid startup code.

4. The example cartridge

This 8K cartridge prints three lines through the screen editor. It shows its own option byte and the current value of MEMLO, which tells you whether DOS was loaded.

; 8K cartridge - mads cart.asm -o:cart.bin
FLAGS   = $04           ; option byte: bit 2 = run, bit 0 = boot disk too
MEMLO   = $02E7
COLOR2  = $02C6
CIOV    = $E456
ICCOM   = $0342
ICBAL   = $0344
ICBLL   = $0348
buf     = $0600         ; ROM can't be written: build text in RAM

        opt h-f+        ; raw binary, one continuous block
        org $A000

init    rts             ; CARTAD: called at power-up and every RESET

start   lda #$C4        ; CARTCS: the OS jumps here when bit 2 is set
        sta COLOR2      ; green background shows the cart is running
        ldy #0          ; copy "MEMLO = $" into RAM
cp      lda msg3,y
        sta buf,y
        iny
        cpy #msg3len
        bne cp
        lda MEMLO+1     ; append MEMLO in hex and an EOL
        jsr hex
        lda MEMLO
        jsr hex
        lda #$9B
        sta buf,y
        ldx #<msg1
        ldy #>msg1
        jsr print
        ldx #<msg2
        ldy #>msg2
        jsr print
        ldx #<buf
        ldy #>buf
        jsr print
loop    jmp loop        ; a cartridge program never returns

hex     pha             ; A -> two hex digits at buf,Y
        lsr
        lsr
        lsr
        lsr
        tax
        lda digits,x
        sta buf,y
        iny
        pla
        and #$0F
        tax
        lda digits,x
        sta buf,y
        iny
        rts

print   stx ICBAL       ; PUT RECORD on IOCB 0 (E:, already open)
        sty ICBAL+1
        lda #9
        sta ICCOM
        lda #40
        sta ICBLL
        lda #0
        sta ICBLL+1
        ldx #0
        jmp CIOV

msg1    dta c'HELLO FROM AN 8K CARTRIDGE',$9B
msg2    dta c'OPTION BYTE $0',c'0'+FLAGS,$9B
msg3    dta c'MEMLO = $'
msg3len = *-msg3
digits  dta c'0123456789ABCDEF'

        org $BFFA       ; the cartridge header
        dta a(start)    ; $BFFA CARTCS: run address
        dta 0           ; $BFFC: 0 = cartridge present
        dta FLAGS       ; $BFFD: option byte
        dta a(init)     ; $BFFE CARTAD: init address

Notes:

  • opt h-f+ tells MADS to write a raw file with no DOS load headers, as one continuous block. The gap between the code and the header is filled with $FF, so the output is exactly 8,192 bytes, $A000–$BFFF. For 16K, start at org $8000 and you get 16,384 bytes.
  • The code is in ROM. You can't keep variables in it or modify it, so any data you write must go to RAM. The text buffer here is in page 6. A cartridge that doesn't ask for a disk boot owns all memory from $0480 to MEMTOP, and if it doesn't use the floating-point package or BASIC it can use page zero from $80 up as well.
  • CIO is fine in the run routine, because the screen editor was opened in step 4. In the init routine it isn't open yet.
  • Never return from CARTCS. There is nothing to return to. A cartridge that wants to give control to DOS when it's done can jump through DOSVEC ($0A).

5. Building .BIN and .CAR

The raw cart.bin is a ROM image, exactly what goes into an EPROM or onto a flash cartridge. Emulators also accept it, but a raw dump doesn't say what kind of board it came from. Atari800 asks for, or takes, the type, and Altirra guesses from the size. The CAR format adds a 16-byte header: the text CART, the cartridge type as a 32-bit big-endian number, a 32-bit big-endian checksum (the sum of all ROM bytes), and four zero bytes. In the atari800 type table, type 1 is the standard 8K cartridge, type 2 the standard 16K one and type 21 the 800's right-slot 8K cartridge.

#!/usr/bin/env python3
"""mkcar.py rom.bin out.car TYPE  - wrap a raw cartridge dump in a CART header."""
import struct, sys
rom = open(sys.argv[1], 'rb').read()
ctype = int(sys.argv[3])              # 1 = standard 8K, 2 = standard 16K
csum = sum(rom) & 0xFFFFFFFF          # simple sum of all ROM bytes
open(sys.argv[2], 'wb').write(b'CART' + struct.pack('>II', ctype, csum) + bytes(4) + rom)
print(f'{sys.argv[2]}: type {ctype}, {len(rom)} bytes, checksum {csum:#010x}')
mads cart.asm -o:cart.bin
python3 mkcar.py cart.bin cart.car 1
atari800 -xl -cart cart.car                     # CAR: type taken from the header
atari800 -xl -cart cart.bin -cart-type 1        # raw: tell it the type

In Altirra, use File > Boot Image or the /cart command-line switch. Altirra checks the CAR checksum, so a hand-edited file with a stale checksum is rejected. Its /nocartchecksum switch exists for development builds that leave the field empty.

6. Testing the option byte

The screenshot shows the same cartridge built twice, both times with a DOS 2.5 disk in drive 1:

  • With FLAGS = $04, the drive is never accessed. The cartridge starts at once and MEMLO is still the OS default, $0700.
  • With FLAGS = $05, DOS 2.5 boots first and then the cartridge runs. MEMLO is now $1C6C, above DOS and its buffers. Through DOSINI, DOS would also reinstall itself on every RESET, so a cartridge built this way can open D: files.

This is the mechanism BASIC uses. Atari BASIC's header, as printed in The Atari BASIC Source Book, is a run address of $A000 (its cold start), a 0 byte, the option byte $05, and an init address pointing at a single RTS at $BFF9. That is the same pattern as the example: DOS loads underneath, and then you land in BASIC rather than the DOS menu.

7. Diagnostic cartridges and other variants

Setting bit 7 of the option byte makes the OS jump to CARTAD from its very first routine, before it clears RAM, initialises the hardware registers or sizes memory. That suits test or recovery programs that must not depend on the OS. Your code must do everything itself, including setting up the stack and display. Atari used diagnostic cartridges during development. The Altirra Hardware Reference Manual warns that some flash cartridges whose own power-on reset is slow can fail to start reliably as diagnostic cartridges.

Things to know about the XL/XE models:

  • The XL/XE OS detects the cartridge through the RD5 line, which it reads as the TRIG3 input, and stores that state in GINTLK ($03FA). Pulling a cartridge out of a running XL/XE crashes it. Bank-switched cartridges that switch themselves off change TRIG3 too.
  • The 1200XL also keeps a checksum of the cartridge in CARTCK ($03EB) and cold-starts if it changes.

For bigger programs, bank-switched formats (XEGS, Williams, AtariMax and others) map 8K banks into $A000–$BFFF through writes or reads at $D500–$D5FF. They use the same header in whichever bank is visible at power-up. Each has its own CAR type number.

Troubleshooting

  • Machine boots to BASIC or the Memo Pad instead: $BFFC isn't 0, bit 2 of the option byte is clear, or the file isn't 8,192 bytes so the header isn't at $BFFA.
  • Crash at power-up, works after RESET (or the reverse): your init routine is using the screen, which isn't open yet, or assumes RAM contents that are only there on a warm start.
  • Emulator refuses the .car: wrong type number or checksum. Rebuild with the script.
  • Variables don't change: you're writing to ROM. Move them to RAM.
  • DOS doesn't load with a $05 cartridge: check that the disk boots on its own. On an XL/XE, remember the cartridge replaces built-in BASIC.

Further reading

  • Mapping the Atari by Ian Chadwick: locations 6–7, 1003 (CARTCK), 1018 (GINTLK), and the cartridge sections at 32768–49151.
  • Atari 400/800 Operating System Source Listing (Atari, 1981): PWRUP, SPECL, CAINI, BOOT and the code that follows.
  • Altirra Hardware Reference Manual, chapter 8 (cartridges) and the cartridge-sense section on TRIG3.
  • The atari800 emulator's DOC/cart.txt: the CAR format and the full list of type numbers.
  • On this site: Atari 8-bit File Formats Explained, Writing a Bootable Disk Program and The MADS Assembler.

Credits