MADS (Mad-Assembler): A Practical Guide for Atari Programmers
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
-fto allow instructions in column 1). orginstead of*=, anddtafor data (.byte/.wordalso work).- Hex is
$FF, binary is%1010, low and high bytes are<exprand>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 addradds a segment that loads RUNAD ($2E0). DOS jumps there after the whole file has loaded.ini addradds a segment that loads INITAD ($2E2). The loader calls that address as soon as the segment arrives and continues loading when your routine returns withRTS.
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 … .endlor.macro … .endmis 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 (unlessopt ?+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 labelon 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. Usemain.labelfrom outside, or:labelto reach a global of the same name from inside. - Branch out of range. Use
jne/jeqetc., 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
.printdirective can show segment end addresses during assembly. - Your editor jumps to the wrong file on errors. Add
-pso MADS prints fully qualified file names.
Further reading
- The full MADS manual (
doc/mads_eng.htmlin the repository) covers SpartaDOS X relocatable blocks,.struct,.var/.zpvar, virtual memory banks, 65816 support and the.laband.lstfile formats. - The repository's
examples/folder has small, readable examples:hscroll.asm,Boot.asm(a custom boot loader),detect_cpu.asm,file_loader.asmand complete games. - Mapping the Atari, Ian Chadwick (COMPUTE! Books, 1983), for every equate you'll write.
Credits
- Picture: rainbow.asm: a VCOUNT-plus-frame-counter colour per scan line, with the playfield switched off. — Program authors; screenshot by the site
- MADS documentation (English translation of Mad-Assembler 1.9.5 manual) — JAC; mads.atari8.info
- MADS command-line usage — GitHub project authors
- Mad-Assembler repository README and examples (file_header.asm, Boot.asm) — GitHub project authors
- Altirra help — source-level debugging (MADS symbol support) — Screenshot from Avery Lee's Altirra page, virtualdub.org
- Fast Assembler 1.8 manual (MADS supports FA syntax) — GitHub project authors
- AtariAge — Visual Studio Code (MADS/ATasm build tasks) — AtariAge forum members
- Mapping the Atari — memory map — AtariArchives.org
