Getting Started with 6502 Assembly on the Atari 8-bit

The hello.asm example running: the message printed through CIO on a recoloured GRAPHICS 0 screen

Assembly language is the step that turns an Atari 400/800/XL/XE from a BASIC machine into one where you control ANTIC, GTIA and POKEY directly. In his Antic lessons, Chris Crawford wrote that machine code typically ran about ten times faster than BASIC, and on some operations up to a thousand times faster. It also gives you things BASIC can't do at all, interrupts above all. This guide takes you from nothing to a working program you can load and run.

What you'll learn: how an Atari machine-language program is laid out in memory, how to assemble one with a modern cross-assembler, how to print text through the operating system's CIO routines, how to read the keyboard, and how to load the result in an emulator or on real hardware.

What you need:

  • A PC (Windows, macOS or Linux) with MADS, the Mad-Assembler. It is a free multi-pass cross-assembler for 6502 and 65816 that writes Atari DOS and SpartaDOS X executables. ATasm or ca65 would also do; there are separate guides for those.
  • Altirra (or atari800) to run and debug the program.
  • Optional but strongly recommended: Mapping the Atari for addresses, and De Re Atari for the hardware.

1. Three ideas you need first

Registers. The 6502 has an 8-bit accumulator (A), two 8-bit index registers (X and Y), a stack pointer (S), a status register (P) that holds the carry/zero/negative/overflow flags, and a 16-bit program counter. Almost everything is done by loading a value into A, X or Y, working on it, and storing it back to memory.

Memory is the hardware. Atari's chips appear as memory locations. If you store a byte at $D018 you have written a GTIA colour register. The OS also keeps RAM shadow copies of many registers and copies them into the chips once per frame during vertical blank. COLOR2 at 710 ($2C6) is the shadow of $D018, for example. Write to the shadow and your change stays put. Write to the hardware register and the OS overwrites it on the next frame.

Low byte first. Every 16-bit address is stored as two bytes, low byte then high byte. Assemblers give you <label and >label to pull out the low and high halves.

2. Where can my program live?

Choose a load address that DOS doesn't use and that sits below screen memory. Some landmarks:

Area Use
$00–$FF (page zero) Fast addressing. Mostly owned by the OS, BASIC and the floating-point package. Only $CB–$D1 (203–209) are "uncontestably left free by BASIC". $D4–$FF are free only if you never call the FP routines.
$0600–$06FF (page six) 256 bytes the OS never touches. Classic home for small routines called from BASIC.
$2000 upwards A common start for DOS programs. It's the default for cc65's atari target. ANALOG's Matthew Ratcliff recommended $3400 to keep clear of every DOS of the day.
MEMTOP ($2E5/$2E6) Top of free RAM. The display list and screen sit above it.

For a first program, $2000 works with DOS 2.5, with an emulator's direct loader, and with most modern loaders.

3. The program

Save this as hello.asm. In MADS a label must start in column 1, and instructions must be indented (the -f switch relaxes this).

; hello.asm - first Atari program (MADS syntax)
; build: mads hello.asm -o:hello.xex -l:hello.lst -t:hello.lab

ICCOM   = $0342     ; IOCB #0 command byte
ICBAL   = $0344     ; IOCB #0 buffer address (lo, hi at +1)
ICBLL   = $0348     ; IOCB #0 buffer length  (lo, hi at +1)
CIOV    = $E456     ; Central I/O entry point
PUTREC  = $09       ; CIO command: put record (text line)
COLOR2  = $02C6     ; shadow of COLPF2: GR.0 background
COLOR4  = $02C8     ; shadow of COLBK: border
CH      = $02FC     ; last key code, $FF = no key

        org $2000

start   lda #$00
        sta COLOR4          ; border: hue 0, luminance 0 (black)
        lda #$84
        sta COLOR2          ; background: hue 8, luminance 4

        ldx #$00            ; X = channel * 16 (IOCB 0 = screen editor E:)
        lda #PUTREC
        sta ICCOM,x
        lda #<message
        sta ICBAL,x
        lda #>message
        sta ICBAL+1,x
        lda #<msglen
        sta ICBLL,x
        lda #>msglen
        sta ICBLL+1,x
        jsr CIOV            ; print the line

        lda #$FF
        sta CH              ; forget any earlier key press
wait    lda CH
        cmp #$FF
        beq wait            ; loop until a key is pressed
        lda #$FF
        sta CH              ; swallow the key
        rts                 ; back to whoever loaded us

message dta c'HELLO FROM 6502 ASSEMBLY'
        dta $9B             ; ATASCII end-of-line
msglen  = *-message

        run start           ; write RUNAD so the loader jumps to START

How it works

  • The = lines are equates. They give names to addresses. All are standard OS locations, listed in Mapping the Atari: IOCB #0 begins at 832 ($340) with the command byte at $342, the buffer address at $344/$345 and the length at $348/$349. CIOV is 58454 ($E456), CH is 764 ($2FC), COLOR2 is 710 and COLOR4 is 712. The same names appear in cc65's atari.inc, which makes a handy cross-check.
  • CIO (Central Input/Output) is the OS's device-independent I/O system. There are eight IOCBs, 16 bytes apart. You put the IOCB number times 16 in X, fill in the command, buffer and length, and JSR CIOV. IOCB 0 is already open to the screen editor E: when your program starts, so you can print straight away. On return, the Y register holds the status (1 means success), and the negative flag is set if there was an error.
  • Colour values pack hue into the high nibble and luminance into the low nibble. $84 means hue 8, luminance 4. Try other values.
  • The keyboard is read by watching CH. The OS stores a hardware key code there and leaves $FF when no key is waiting.
  • dta c'...' is MADS for ATASCII text. msglen = *-message uses *, the current assembly address, to work out the length.
  • run start is a MADS pseudo-op. It adds a small segment that loads the address of start into RUNAD ($2E0). That tells DOS to jump to your code once loading has finished. The executable-file guide explains the details.

4. Assemble it

mads hello.asm -o:hello.xex -l:hello.lst -t:hello.lab

-o: names the executable. Without it MADS writes hello.obx. -l writes a listing showing every address and the bytes generated, and -t writes a label table. Make a habit of reading the listing: it shows exactly what the assembler did with each line. MADS returns exit code 2 on an assembly error, which matters if you run it from a build script.

5. Run it

In Altirra, use File > Boot Image… and pick hello.xex. Altirra loads Atari executables directly, without needing a DOS disk. It also automatically loads symbol files that have the same base name as the program (.lst, .lab and others). That's why the build line above names them hello.lst and hello.lab. You'll see the message and the new colours. Press a key and the program returns.

To debug it, choose Debug > Enable Debugger, then type bp start in the command line before booting. When the breakpoint fires, press F11 (Step Into) to execute one instruction at a time and watch A, X and Y change. See the Altirra debugger guide for more.

On a real machine, copy hello.xex onto a DOS 2.5 disk image (or serve it with an SIO2PC tool, FujiNet or an SD-card device) and use DOS menu option L. BINARY LOAD.

6. Next steps that build on this program

  1. Direct screen writes. Read the screen address from SAVMSC ($58/$59) into two free zero-page bytes, such as $CB/$CC, and store screen codes with sta ($CB),y. That's indirect indexed addressing, the 6502's most useful mode.
  2. A raster effect. Read VCOUNT ($D40B), store it to WSYNC ($D40A) to wait for the end of the scan line, then write it to a colour register. You get a rainbow, the "hello world" of Atari demo coding.
  3. A routine called from BASIC. Put a routine in page six, end it with RTS, and call it with X=USR(1536). A BASIC USR call pushes the argument count on the stack, so your routine must PLA it off first.
  4. Interrupts. Display-list and vertical-blank interrupts are where assembly really earns its keep. De Re Atari chapters 5 and 8 and the DLI/VBI guides on this site go further.

Troubleshooting

  • "Undeclared label" or a mnemonic taken as a label. In MADS an instruction in column 1 is read as a label. Indent instructions, or assemble with -f.
  • The program loads but nothing happens. Check that the RUNAD segment exists. Look for the run line, or for $E0 $02 $E1 $02 near the end of the file in a hex viewer.
  • Crash on load. Your load address may overlap DOS, your own source buffer (with on-machine assemblers), or screen memory. Move the origin up, or check MEMLO ($2E7/$2E8) and MEMTOP.
  • Colours flicker back. You wrote a hardware register ($D0xx) instead of its shadow. Write the shadow in page two, or turn the OS's per-frame copy off.
  • Strange characters on screen. Text printed through CIO is ATASCII. Bytes written directly to screen memory must be internal screen codes. MADS writes those with dta d'...'.

Further reading

  • Mapping the Atari, Ian Chadwick (COMPUTE! Books / Small System Services, 1983; revised XL edition later). The address bible.
  • De Re Atari, Chris Crawford and others (Atari, Inc., 1982). Hardware and OS internals.
  • Assembly Language Programming for the Atari Computers, Mark Chasin (McGraw-Hill, 1984). Chapter 6 compares the period assemblers, and chapter 9 covers CIO in depth.
  • Atari Roots: A Guide to Atari Assembly Language, Mark Andrews (Datamost, 1984).
  • Machine Language for Beginners (1983) and The Second Book of Machine Language (1984), Richard Mansfield (COMPUTE! Books).
  • ANALOG Computing's Boot Camp column by Tom Hudson (1983–86), continued by Karl Wiegers (1986–89). An index is on KSquiggle's site, along with Chris Crawford's eight-lesson Antic assembly course.

Credits