Calling Machine Language from Atari BASIC with USR

Atari BASIC is slow, but it has a clean escape hatch: the USR function jumps into a machine-language routine and comes back with a number. Its simple assembly interface is one of the language's strengths, and thousands of magazine programs relied on it for fast sound, scrolling, player movement and disk tricks. This guide explains exactly what happens during a USR call so you can write and use your own routines safely.

You will learn: the USR calling convention, how arguments arrive on the 6502 stack, how to return a value, safe places to put code, and three complete routines (with assembly source and BASIC DATA).

You need: Atari BASIC; basic familiarity with 6502 instructions helps. An assembler (MADS, ATASM, or a cartridge assembler) is useful but not required — every routine here is given as decimal DATA.

1. The calling convention

X=USR(address,arg1,arg2,...)

When BASIC executes this it:

  1. Converts each argument to a 16-bit integer (0–65535).
  2. Pushes the arguments onto the 6502 hardware stack, each as high byte then low byte when pulled, in left-to-right order.
  3. Pushes a single byte holding the number of arguments — even when there are none.
  4. Does a JSR-style call to address.

So the first thing every routine must do is PLA the argument count, then PLA each argument's high and low bytes in turn. The stack must be exactly balanced when your routine executes RTS — if you leave an argument on the stack, the RTS will pull it as a return address and the machine will crash. Carl Evans's SEEKER routine in Atari BASIC Faster and Better even checks the count and pulls off any unexpected arguments before reporting an error, which is good defensive practice.

When your routine returns, the value of the USR function is whatever 16-bit number you left in locations 212 and 213 ($D4/$D5, the start of floating-point register FR0), low byte first. If you store nothing there, USR returns the address of the routine itself.

2. Where to put the code

There are two classic methods:

Page six (1536–1791, $600–$6FF). 256 bytes the operating system never uses. POKE the routine in from DATA and call USR(1536). Two caveats: an INPUT of more than 128 characters overflows into 1536–1663, and some environments (BASIC A+, for instance, uses $600–$67F) claim part of the page.

Inside a string. Build the routine in a string with CHR$ and call USR(ADR(ML$)). The string moves around as your program grows, so the code must be relocatable: no JMPs or JSRs to its own labels, only relative branches. In return, it can never be overwritten by another routine.

For bigger routines, lower RAMTOP (location 106) by a few pages before a GRAPHICS call and use the space freed above it.

For zero-page pointers, locations 203–209 ($CB–$D1) are the only page-zero bytes "uncontestably" left free by BASIC. Locations 212 upwards belong to the floating-point package — fine to use briefly inside a USR routine (indeed you return results there), but never from an interrupt routine.

3. Routine one: set the border colour (one argument)

The simplest useful routine takes one argument and stores its low byte in COLOR4 (712), the border/background shadow register.

        PLA             ; argument count (1) - discard
        PLA             ; high byte of argument - discard
        PLA             ; low byte of argument
        STA $02C8       ; COLOR4 = 712
        RTS
10 FOR I=0 TO 6:READ B:POKE 1536+I,B:NEXT I
20 DATA 104,104,104,141,200,2,96
30 FOR C=0 TO 255 STEP 2
40 X=USR(1536,C)
50 FOR D=1 TO 20:NEXT D:NEXT C

104 is PLA, 141,200,2 is STA $02C8 and 96 is RTS. Run it and the border cycles through every colour.

4. Routine two: return a value (a 16-bit PEEK)

This routine reads a two-byte pointer from any address and returns it, replacing the common PEEK(A)+256*PEEK(A+1) with one call. It uses $CB/$CC as a zero-page pointer and returns the result through FR0.

        PLA             ; argument count - discard
        PLA             ; address high byte
        STA $CC
        PLA             ; address low byte
        STA $CB
        LDY #0
        LDA ($CB),Y     ; low byte at address
        STA $D4         ; FR0 low
        INY
        LDA ($CB),Y     ; high byte at address+1
        STA $D5         ; FR0 high
        RTS
10 FOR I=0 TO 18:READ B:POKE 1536+I,B:NEXT I
20 DATA 104,104,133,204,104,133,203,160,0,177,203
30 DATA 133,212,200,177,203,133,213,96
40 PRINT "DISPLAY LIST AT ";USR(1536,560)
50 PRINT "SCREEN MEMORY AT ";USR(1536,88)

Locations 560/561 hold the display-list address and 88/89 the screen address, so line 40 and 50 should print the same values as the long-hand PEEK formulas.

5. Routine three: a relocatable memory fill in a string

Here is a fill routine you can keep in a string. It takes three arguments — address, byte count (1–255, or 0 for 256) and fill value — and uses only zero-page addressing and a relative branch, so it runs wherever BASIC puts the string.

        PLA             ; argument count - discard
        PLA             ; address high
        STA $CC
        PLA             ; address low
        STA $CB
        PLA             ; count high - discard
        PLA             ; count low
        TAY
        PLA             ; value high - discard
        PLA             ; value low (stays in A)
LOOP    DEY
        STA ($CB),Y
        BNE LOOP        ; Z flag comes from DEY
        RTS
10 DIM F$(18)
20 FOR I=1 TO 18:READ B:F$(I,I)=CHR$(B):NEXT I
30 DATA 104,104,133,204,104,133,203,104,104,168
40 DATA 104,104,136,145,203,208,251,96
50 SC=PEEK(88)+PEEK(89)*256
60 X=USR(ADR(F$),SC,240,128)

Line 60 fills the first 240 bytes (six lines) of the GRAPHICS 0 screen with screen code 128 — an inverse space — at machine speed. The loop counts Y down from the count to zero, so byte 0 is written last and the BNE falls through when DEY reaches zero. A filler like this is the classic way to clear player/missile memory, which BASIC's FOR/POKE loops do painfully slowly.

6. The literal-string shortcut (and why to avoid it)

Very small routines can be typed directly as a string constant inside the USR call, as in X=USR(ADR("..."),16), saving the DATA statements entirely: ADR of a literal returns the address of that very string in the program line. It works, but the routine's bytes must be typed as ATASCII characters — many of them inverse or control graphics — and the bytes 34 (quote) and 155 (RETURN) cannot appear at all. Magazine listings that used this trick were notoriously hard to type correctly; DATA statements are kinder to readers.

7. A note on other BASICs

USR conventions are not universal. FastBasic, for example, does not push an argument count, so routines written for it must not start with the count-discarding PLA. Always check the documentation of the language you are targeting.

Troubleshooting

  • The machine locks up on the USR call: the stack is unbalanced. Count your PLAs: one for the count plus two per argument.
  • Wrong result: you stored the return value high byte first. FR0 wants low byte at 212, high at 213.
  • Works in page 6, crashes from a string: the routine contains an absolute JMP/JSR or reads a table by absolute address — it is not relocatable.
  • Routine suddenly corrupted: a long INPUT overwrote the start of page 6, or another utility (a DOS extension, BASIC A+) shares the area.
  • ERROR 3 on the USR line: an argument was negative or larger than 65535.

Further reading

  • Machine Language for Beginners — Richard Mansfield (Small System Services, 1983), and The Second Book of Machine Language (1984).
  • Atari Roots: A Guide to Atari Assembly Language (atariarchives.org edition).
  • Atari Assembly Language Programmer's Guide — Alan Moose and Marian Lorenz (Weber Systems, 1986).
  • Mapping the Atari — Ian Chadwick (Small System Services, 1983).

Credits