Programming Your Own Atari Cartridge
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:
- 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.
- 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.
- 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.
- Screen editor opened, cassette boot checked.
- 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.
- 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 atorg $8000and 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 openD: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,BOOTand 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
- Picture: The example cartridge with option byte $04 (no disk boot, MEMLO $0700) and $05 (DOS 2.5 booted first, MEMLO $1C6C), both with the DOS disk in the drive. — Program authors; screenshot by the site
- Atari 400/800 Operating System Source Listing, Rev. A (PWRUP, SPECL, CAINI/CBINI, BOOT, cartridge start) — ksquiggle
- Mapping the Atari (revised) — cartridge A/B sections, 49146-49151 header, 1003 CARTCK, 1018 GINTLK — AtariArchives.org
- Altirra Hardware Reference Manual, chapter 8 (cartridges) and cartridge sense via TRIG3 — Avery Lee (Altirra)
- The Atari BASIC Source Book — Atari Cartridge Vectors ($BFF9-$BFFF) — AtariArchives.org
- atari800 emulator DOC/cart.txt — CAR format and cartridge type numbers — GitHub project authors
- MADS manual — OPT h- and f+ (raw single-block output for cartridges) — mads.atari8.info
