Bank-Switched Cartridges: Programming XEGS and Atarimax Carts

Two Atari screens side by side: one reads THIS TEXT IS IN XEGS BANK 0, 1 and 2; the other reads BANK 0 RUNS THE SHOW, GREETINGS FROM BANK 5 and GREETINGS FROM BANK F

A standard Atari cartridge gives you 8K at $A000–$BFFF, or 16K at $8000–$BFFF. Games such as the later XEGS releases, and today's big homebrew titles and flash-cart menus, need far more. They get it by bank switching: a larger ROM is cut into 8K pieces, and a write to the cartridge's control area chooses which piece appears in the address window. This guide explains the two schemes you are most likely to use, with tested example cartridges for each.

What you'll learn: the cartridge control area and its dangers, the XEGS layout with a fixed bank, the Atarimax layout with one switchable window, why every bank needs startup code, running code from RAM while banks change, and how to pack a .CAR file.

What you need: MADS, Python (or any tool that can concatenate binary files) and an emulator. Read Programming Your Own Atari Cartridge first: everything about the $BFFA header still applies. Both examples here were assembled and run in atari800.

1. The cartridge control area: $D500–$D5FF

The cartridge slot can see three address ranges: the left-cartridge window $A000–$BFFF, the right-cartridge window $8000–$9FFF, and a 256-byte cartridge control area at $D500–$D5FF (CCTL). The computer does nothing with CCTL itself. Bank-switching cartridges watch it and change banks when it is accessed.

There is an important trap. Many cartridges switch banks on a read as well as a write, and the 6502 makes extra "false" reads with indexed addressing. An instruction such as LDA $D5FF,X meant for another device can trip a bank switch through a stray read of $D5xx. A runaway display list that makes ANTIC fetch from $D5D5 can do the same. Touch $D5xx only deliberately.

2. The XEGS scheme: a fixed top bank

Atari's XEGS cartridges (and the many homebrews that copy the design) come in 32K, 64K, 128K and larger sizes. The layout:

  • The ROM is divided into 8K banks: 4 for 32K, 8 for 64K, 16 for 128K.
  • The last bank is always mapped at $A000–$BFFF. It holds the cartridge header and your main code.
  • Any of the banks can be switched into $8000–$9FFF by writing its number to $D500–$D5FF. A 32K cart uses the two lowest bits of the value written, 64K three bits, and 128K four bits.

This is convenient: your program runs in the fixed bank and pulls data or code into the lower window as needed, without ever switching itself out.

; XEGS 32K bank-switched cartridge: fixed bank 3 at $A000-$BFFF
; banks 0-2 appear at $8000-$9FFF after a write of the bank number to $D500
        opt h-f+            ; raw output, fill gaps
SAVMSC  = $58
PTR     = $CB
BANKREG = $D500

        org $A000
start   ldx #0              ; for bank 0, 1, 2:
nextb   stx BANKREG         ; select the bank in $8000-$9FFF
        stx bank
        txa                 ; screen row = 2 + bank*2
        asl
        clc
        adc #2
        tay
        lda SAVMSC
        sta PTR
        lda SAVMSC+1
        sta PTR+1
rowl    dey
        bmi rowok
        clc
        lda PTR
        adc #40
        sta PTR
        bcc rowl
        inc PTR+1
        bne rowl
rowok   ldy #0
copy    lda $8000,y         ; the message stored at the start of the bank
        cmp #$FF            ; $FF marks the end
        beq done
        sta (PTR),y
        iny
        bne copy
done    ldx bank
        inx
        cpx #3
        bne nextb
loop    jmp loop
init    rts                 ; cartridge init: nothing to do
bank    = $CD

        org $BFFA           ; cartridge header (left cartridge)
        dta a(start)        ; run address
        dta 0               ; $BFFC: 0 = cartridge present
        dta 4               ; $BFFD: flags (bit 2: run the cartridge)
        dta a(init)         ; init address

opt h-f+ makes MADS write a raw 8K image with no binary-load headers, filling gaps, so the result is exactly the fixed bank. Banks 0–2 here hold only data: a line of text in screen (internal) code at the start of each bank, ending in $FF. The program selects each bank in turn, copies its text to the screen, and the result is three different lines from three banks, as in the screenshot.

3. The Atarimax scheme: one window, no fixed bank

Atarimax flash cartridges (the MaxFlash family, used for many modern releases and multicarts) work differently:

  • 1Mbit (128K): 16 banks of 8K, all appearing at $A000–$BFFF. Any read or write access to $D500–$D51F selects a bank: address bits 0–3 choose the bank, and bit 4 set ($D510–$D51F) turns the cartridge off.
  • 8Mbit (1MB): 128 banks at $A000–$BFFF, selected by an access to $D500–$D5FF. Address bits 0–6 choose the bank, and bit 7 turns the cartridge off.
  • The data value is ignored. The address is the bank number, so STA $D500,X with X = bank works.

There is no fixed bank, so two problems appear:

  1. Switching banks swaps out the code doing the switching. The instruction after STA $D505 is fetched from bank 5. Keep switching routines in RAM, or put identical code at the same address in every bank.
  2. The bank at power-up isn't guaranteed. Cartridges without reset circuitry can start in any bank, and that cartridges can't see the RESET key. So every bank must contain a valid header and a little startup code that selects the main bank.

The example handles both. It is assembled 16 times with a different BANK value, and every copy gets the same reset stub at $BFE0:

; Atarimax 128K flash cartridge: 16 banks of 8K, all at $A000-$BFFF.
; Bank n is selected by any access to $D500+n; $D510 turns the cartridge off.
; Assembled once per bank with BANK set on the command line (-d:BANK=n).
        opt h-f+
SAVMSC  = $58
PTR     = $CB
RAMCODE = $0600

        org $A000
msg     .if BANK=0
        dta d'BANK 0 RUNS THE SHOW'
        .else
        dta d'GREETINGS FROM BANK '
        .if BANK<10
        dta BANK+$10        ; digit 0-9 (internal code)
        .else
        dta BANK-10+$21     ; letter A-F
        .endif
        .endif
        dta $FF

        .if BANK=0
        org $A100           ; bank 0's program
start   ldx #rcend-rcode-1  ; copy the bank-reading routine to RAM
cp      lda rcode,x
        sta RAMCODE,x
        dex
        bpl cp
        lda SAVMSC          ; PTR = screen row 2
        clc
        adc #80
        sta PTR
        lda SAVMSC+1
        adc #0
        sta PTR+1
        ldx #0              ; banks 0, 5 and 15
        jsr RAMCODE
        ldx #5
        jsr RAMCODE
        ldx #15
        jsr RAMCODE
loop    jmp loop

; runs from RAM: show bank X's message, then switch back to bank 0
rcode   sta $D500,x         ; select bank X (the write itself switches)
        ldy #0
rc1     lda msg,y
        cmp #$FF
        beq rc2
        sta (PTR),y
        iny
        bne rc1
rc2     sta $D500           ; back to bank 0 (our code)
        clc
        lda PTR
        adc #80
        sta PTR
        bcc rc3
        inc PTR+1
rc3     rts
rcend
        .endif

        org $BFE0           ; every bank: switch to bank 0 and start
reset   sta $D500           ; after this the same address is in bank 0
        jmp $A100           ; bank 0's program
init    rts

        org $BFFA
        dta a(reset)
        dta 0
        dta 4
        dta a(init)

The key trick is in the reset stub. Whatever bank the machine starts in, the OS runs reset at $BFE0. STA $D500 selects bank 0, and the next instruction, JMP $A100, is fetched from bank 0, where the same stub sits at the same address. The routine copied to $0600 can then switch to any bank, read from $A000 and switch back, because it doesn't live in the cartridge at all. The program showed the messages of banks 0, 5 and 15 (F), as in the screenshot.

4. Building the .CAR files

Emulators need to know the banking type, which is what the .CAR format adds: the four bytes CART, a 4-byte big-endian type number, a 4-byte checksum (the sum of all data bytes), four zero bytes, then the raw ROM. Type 12 is XEGS 32K and type 41 is Atarimax 128K (13 and 14 are XEGS 64K and 128K, and 42 is Atarimax 1MB). We built both images with a few lines of Python:

import struct
def car(path, cart_type, data):
    hdr = b'CART' + struct.pack('>I', cart_type) + struct.pack('>I', sum(data) & 0xFFFFFFFF) + bytes(4)
    open(path, 'wb').write(hdr + data)

# Atarimax 128K: 16 banks assembled with  mads maxbank.asm -d:BANK=n -o:mbn.bin
car('max.car', 41, b''.join(open(f'mb{n}.bin', 'rb').read() for n in range(16)))

For the XEGS image, concatenate the three data banks (8,192 bytes each) followed by the fixed bank from xegs.asm. Order matters: the file holds banks 0, 1, 2… in order, and for XEGS the last 8K is the fixed one. In atari800, run a CAR file with atari800 -cart xegs.car. Altirra attaches it from the File menu. Real flash carts are programmed with their makers' tools.

5. Practical tips

  • Keep the bank-switch code in one place, ideally in the fixed bank (XEGS) or in RAM (Atarimax), and keep a variable with the current bank number, so that a routine that borrows another bank can switch back afterwards.
  • Interrupts: a VBI or DLI routine that lives in a switched bank will crash when another bank is selected. Keep interrupt code in the fixed bank or in RAM.
  • Data, not just code: levels, graphics and music are natural candidates for switched banks. Copy what you need into RAM, or read it while its bank is selected.
  • Turning the cartridge off (Atarimax $D510, or the disable bit in other schemes) lets the computer's own RAM at $A000–$BFFF show through on a 48K or larger machine, once your program has copied itself to RAM.

Troubleshooting

  • Crashes the moment a bank is switched: the code doing the switch was in the bank that disappeared. Run it from RAM or the fixed bank.
  • Works in the emulator, not on hardware (or vice versa): the cartridge powered up in a different bank. Add the reset stub to every bank.
  • Random bank changes: an indexed read or ANTIC fetch touched $D5xx. Check display lists and any abs,X near $D500.
  • Emulator shows garbage or asks for a type: the .CAR type number is wrong, or the image size doesn't match the type.

Further reading

  • Avery Lee, Altirra Hardware Reference Manual, chapter 8 (cartridges): the CCTL area, power-on behaviour, and Atarimax MaxFlash banking.
  • The atari800 emulator's cartridge documentation, which lists every numbered .CAR type with its banking rules.
  • AtariAge forum, "Atari 8bit bank switching" thread, for a discussion of the cartridge types.
  • On this site: Programming Your Own Atari Cartridge, SD-Card Drives, IDE Carts and Flash Multicarts, Atari 8-bit File Formats Explained.

Credits