MADS (Mad-Assembler): A Practical Guide for Atari Programmers

Horizontal rainbow colour bands filling the whole screen, produced by the rainbow.asm example

MADS, the Mad-Assembler written by Tebe of Madteam, is the assembler you'll meet most often in modern Atari 8-bit projects. Projects built with it include a Turbo-BASIC XL 1.5 disassembly, BW-DOS, an Infocom interpreter, and games such as Pang, Getris and Last Squadron. It is a multi-pass cross-assembler for the 6502 and 65816. It writes Atari DOS and SpartaDOS X executables, and it runs anywhere Free Pascal can compile it (Windows, Linux, macOS).

What you'll learn: the command line, how MADS builds executable segments, the built-in "macro commands" that save typing, scoped labels and procedures, and how to hand symbols to Altirra.

What you need: a MADS binary for your platform, or the source (mads.pas) plus Free Pascal. Build it with fpc -Mdelphi -vh -O3 mads.pas. You'll also want a text editor and an emulator.

1. Where MADS's syntax comes from

MADS is aimed at users of QA (Quick Assembler), XASM and FA (Fast Assembler). It took its basic syntax from QA and some macro commands from XASM. If you know MAC/65 or the Assembler Editor, the main differences are:

  • No line numbers. Labels go in column 1, instructions are indented (or use -f to allow instructions in column 1).
  • org instead of *=, and dta for data (.byte/.word also work).
  • Hex is $FF, binary is %1010, low and high bytes are <expr and >expr, and * is the current address.
  • Expressions can be grouped with () or []. XASM accepts only [].

2. The command line

From mads-usage.txt (abridged; -bc, -ml, -vu and -xp are also available):

Syntax: mads source [options]
-b:address      Generate binary file at specified address
-c              Activate case sensitivity for labels
-d:label=value  Define a label and set it to <value>
-f              Allow mnemonics at the first column of a line
-fv:value       Set raw binary fill byte to <value>
-hc[:filename]  Generate ".h" header file for CA65
-hm[:filename]  Generate ".hea" header file for MADS
-i:path         Use additional include directory (repeatable)
-l[:filename]   Generate ".lst" listing file
-m:filename     Include macro definitions from file
-o:filename     Set object file name
-p              Display fully qualified file names in listing and errors
-s              Suppress info messages
-t[:filename]   Generate ".lab" labels file
-u              Display warnings for unused labels
-x              Exclude unreferenced procedures from code generation

Switches can start with - or /, case doesn't matter, and they can be combined (mads -lpt source.asm). If you give no extension, .asm is assumed. The default output is source.obx, so pass -o: to get a .xex. MADS exits with code 2 on an assembly error and 3 on bad parameters, which is useful in makefiles. A typical build line:

mads game.asm -o:game.xex -l:game.lst -t:game.lab -i:include

3. Segments: ORG, RUN and INI

By default (opt h+) every org begins a new segment in an Atari DOS executable: the $FFFF header, then start and end addresses, then the data. Two pseudo-ops write the special vectors for you:

  • run addr adds a segment that loads RUNAD ($2E0). DOS jumps there after the whole file has loaded.
  • ini addr adds a segment that loads INITAD ($2E2). The loader calls that address as soon as the segment arrives and continues loading when your routine returns with RTS.

Here is the pattern from the MADS example file_header.asm:

        org $2000
part1   lda #$80
        sta 712          ; COLOR4 (border)
        rts
        ini part1        ; runs during loading

        org $3000
main    lda #$26
        sta 712
        rts
        run main         ; runs when loading is complete

Two opt switches matter for non-DOS output:

Option Effect
opt h- No DOS headers at all: raw bytes, for boot sectors, cartridges or data files.
opt f+ Write everything as one block (gaps filled), useful for cartridge images.
opt l+ / opt l- Turn the listing on or off from that line onward.
opt c+ Enable 65816 instructions.
opt r+ Let mva/mwa and similar commands skip redundant loads.

org can also write a custom header. org [a($FFFA)],adr produces a SpartaDOS X fixed-address block, for example. The MADS documentation's example of a single-header file is:

        opt h-f+
        org [a(start), a(over-1)],$2000
start   nop
        .ds 128
        nop
over

4. Macro commands: built-in shorthands

MADS knows a family of multi-instruction "macro commands" without any include file:

        mva #$00 712        ; lda #$00 / sta 712
        mwa #dlist $230     ; 16-bit move: SDLSTL/SDLSTH
        adw ptr #40         ; 16-bit add (clc / adc / sta pairs)
        inw counter         ; 16-bit increment
        dew counter         ; 16-bit decrement
        cpw x1 x2           ; 16-bit compare
        jne far_label       ; long branch: BNE if in range, else BEQ over a JMP

MVX/MVY and MWX/MWY do the same job through X or Y. The Jcc forms (JEQ, JNE, JCC…) get around the 6502's ±127-byte branch limit, and the Rcc/Scc forms branch to the previous or next instruction. Look at the listing at first so you know exactly what code each one produces.

5. Labels: global, local, anonymous, temporary

  • Global labels are what you'd expect.
  • Local scope: anything defined inside .proc … .endp, .local … .endl or .macro … .endm is local to that block. Reach a global label of the same name with a : prefix (lda :lp) and a nested one with dot notation (main.loop).
  • Anonymous labels: a line labelled @ can be reached with @+ (forward) or @- (backward), optionally with a count (@-1). They work only for conditional branches no more than ten anonymous labels away.
@       dex
        bne @+        ; forward to the next @
        stx $80
@       lda #0
        bne @-        ; back to the previous @
  • Temporary labels start with ? and can be redefined during assembly (unless opt ?+ switches on MAE-style locals).

6. Procedures and macros

.proc gives you a named scope and an optional parameter-passing convention. With .reg the parameters come in through CPU registers:

.proc   setborder (.byte a) .reg
        sta 712
        rts
.endp

Ordinary macros take numbered parameters (:1, :2) or named ones:

.macro SetColor val,reg
        lda :val
        sta :reg
.endm

        SetColor #$34, 712

.rept n … .endr repeats a block, and # inside gives the loop counter. Handy for tables:

rowlo
        .rept 24
        dta l(screen+#*40)
        .endr
rowhi
        .rept 24
        dta h(screen+#*40)
        .endr

Other directives worth knowing: icl 'file.asm' (include source), ins 'font.fnt' (include binary, with optional offset and length), .align $400 (for character sets and display lists), .if/.elseif/.else/.endif, .ifdef, .print (show a value during assembly), and -d:DEBUG=1 on the command line to drive conditional code.

7. A complete example

This short demo blanks the playfield and draws a scrolling rainbow until you press START. All the addresses are standard OS and hardware locations.

; rainbow.asm   mads rainbow.asm -o:rainbow.xex -l:rainbow.lst -t:rainbow.lab
RTCLOK  = $12           ; 3-byte frame clock; RTCLOK+2 changes every frame
SDMCTL  = $022F         ; shadow of DMACTL
COLBK   = $D01A         ; GTIA background/border colour
CONSOL  = $D01F         ; console keys: bit 0 = START, 0 when pressed
WSYNC   = $D40A         ; any write halts the CPU until end of scan line
VCOUNT  = $D40B         ; current scan line / 2

        org $2000

.proc   main
        lda SDMCTL
        pha             ; remember the DMA setting
        mva #0 SDMCTL   ; no playfield: COLBK fills the screen
        mva #8 CONSOL   ; clear the console key register

loop    lda VCOUNT
        clc
        adc RTCLOK+2    ; scroll the bands one step per frame
        sta WSYNC
        sta COLBK
        lda CONSOL
        and #1
        bne loop        ; START not pressed yet

        pla
        sta SDMCTL      ; restore the display
        rts
.endp

        run main

Check the listing: you'll see mva expand to LDA #/STA pairs, and main.loop in the label file.

8. Debugging with Altirra

With MADS, Altirra supports full label translation, listing-level and source-level debugging: use -t for labels and -l for the listing. If the files share the executable's base name (rainbow.xex, rainbow.lab, rainbow.lst), Altirra loads them automatically when you boot the program. You can then type bp main.loop, open the source with Debug > Open Source File…, and step line by line.

9. Editor integration

MADS has no IDE of its own, and you don't need one. The WUDSN IDE plug-in for Eclipse has supported it for years. In Visual Studio Code, a simple tasks.json can run mads ${fileBasename} -l -o:${fileBasenameNoExtension}.com as a build task. There are also MADS syntax-highlighting and "Atasm Altirra Bridge" extensions. See the cross-development workflow guide.

Troubleshooting

  • ERROR: Undeclared label on what is clearly an instruction. It's in column 1. Indent it or use -f.
  • Labels "not found" after adding .proc. The label is now local. Use main.label from outside, or :label to reach a global of the same name from inside.
  • Branch out of range. Use jne/jeq etc., or restructure the code.
  • The program crashes only when it's large. Check that segments don't run into the screen at MEMTOP or overwrite DOS. The .print directive can show segment end addresses during assembly.
  • Your editor jumps to the wrong file on errors. Add -p so MADS prints fully qualified file names.

Further reading

  • The full MADS manual (doc/mads_eng.html in the repository) covers SpartaDOS X relocatable blocks, .struct, .var/.zpvar, virtual memory banks, 65816 support and the .lab and .lst file formats.
  • The repository's examples/ folder has small, readable examples: hscroll.asm, Boot.asm (a custom boot loader), detect_cpu.asm, file_loader.asm and complete games.
  • Mapping the Atari, Ian Chadwick (COMPUTE! Books, 1983), for every equate you'll write.

Credits