MADS Macros in Practice: Building Your Own Checked Macro Library
MADS, the Mad-Assembler that most modern Atari 8-bit projects are built with, ships with dozens of ready-made "macro commands" such as MVA and ADW, which MADS (Mad-Assembler): A Practical Guide for Atari Programmers introduces. The real power comes when you write your own. A good macro reads like a statement of a higher-level language, checks its arguments while the program is assembled, and picks the best instructions for the values it is given. This guide builds a small library of four such macros and a program that uses them, and shows the MADS features that make it possible.
What you'll learn: declaring macros with named parameters, how labels inside macros stay local, choosing code with .IF inside a macro, catching mistakes at assembly time with :0 and .ERROR, and using .REPT with its # counter for tables.
What you need: MADS and an emulator. Every macro below was assembled with MADS and the program was run in atari800. The error messages quoted are the ones MADS actually printed.
1. Declaring a macro
A macro is declared with .macro name parameters and ended with .endm. Parameters can be referred to by name (:msg) or by number (:1, :2 …). Names make a library much easier to read:
.macro print row, msg
lda #<:msg
ldx #>:msg
ldy #:row
jsr printz
.endm
Calling it is just print 2, msg1. MADS substitutes the text of each argument for its parameter, so #:row becomes #2. A macro is only kept in memory while the program is assembled; it generates code only where it is used.
Two cautions: a macro can't have the same name as an instruction or a pseudo-command (MADS reports a reserved word), and < and > in an argument are evaluated before the value is passed in.
2. Local labels
Any label defined inside a macro is local to that expansion. That is what makes a macro containing a loop usable more than once:
.macro wait frames
ldx #:frames
nextf lda RTCLOK+2
same cmp RTCLOK+2
beq same
dex
bne nextf
.endm
The example program calls wait 30 twice. The listing shows nextf and same at two different addresses, and MADS raised no "label declared twice" error. If a macro needs a label from the main program with the same name as a local one, prefix it with : to reach the global label.
3. Choosing code at assembly time
Because the arguments are known when the program is assembled, a macro can use .if … .else … .endif to generate different code for different values. This one adds a constant to a byte, and uses INC when the constant is 1:
.macro addb dst, val
.if :val=1
inc :dst
.else
clc
lda :dst
adc #:val
sta :dst
.endif
.endm
In the listing, addb count, 1 produced the single instruction INC COUNT (3 bytes) and addb count, 16 produced CLC, LDA, ADC #16, STA (8 bytes). The program then printed $11, the correct 0 + 1 + 16. Note that INC and the long form differ in their side effects: INC leaves A and the carry alone. A macro that switches between instruction sequences should say so in its comment.
4. Catching mistakes while assembling
Parameter :0 holds the number of arguments actually passed, and .error "text" stops assembly with a message. Together they turn wrong macro calls into clear errors instead of strange code:
.macro print row, msg
.if :0<>2
.error "print needs a row and a message"
.endif
...
Assembling a file with the call print 2 gave:
bad2.asm (4) ERROR: print needs a row and a message
The same idea checks ranges. This macro behaves like BASIC's SETCOLOR, and refuses impossible values:
.macro setcolor reg, hue, lum
.if :reg>4 .or :hue>15 .or :lum>15
.error "setcolor: register 0-4, hue and luminance 0-15"
.endif
lda #:hue*16+:lum
sta COLOR0+:reg
.endm
A call with hue 16 stopped with ERROR: setcolor: register 0-4, hue and luminance 0-15. The checks cost nothing in the finished program, because .if and .error are evaluated by the assembler and generate no code. The manual also notes that missing parameters are given the value −1 ($FFFFFFFF), but checking :0 is simpler.
5. Repeating with .REPT and
.rept n … .endr repeats a block, and inside it # is the pass number, starting at 0. That builds the row address tables used by the print routine:
rowlo .rept 24
dta <[#*40]
.endr
For one line, the short form :24 dta <[#*40] does the same. When a repeated block contains several lines that all use #, use .rept. The one-line form rejects a second # with "'#' is allowed only in repeated lines".
6. The complete program
; A small MADS macro library, and a program that uses it.
RTCLOK = $12
SAVMSC = $58
COLOR0 = $02C4
src = $CB ; zero-page pointers
dst = $CD
; print text (screen codes, ended by $FF) at the start of a row
.macro print row, msg
.if :0<>2
.error "print needs a row and a message"
.endif
lda #<:msg
ldx #>:msg
ldy #:row
jsr printz
.endm
; wait a number of frames; the labels inside are local to each use
.macro wait frames
ldx #:frames
nextf lda RTCLOK+2
same cmp RTCLOK+2
beq same
dex
bne nextf
.endm
; like BASIC's SETCOLOR register,hue,luminance - checked at assembly time
.macro setcolor reg, hue, lum
.if :reg>4 .or :hue>15 .or :lum>15
.error "setcolor: register 0-4, hue and luminance 0-15"
.endif
lda #:hue*16+:lum
sta COLOR0+:reg
.endm
; add an 8-bit constant to a byte: INC when the constant is 1
.macro addb dst, val
.if :val=1
inc :dst
.else
clc
lda :dst
adc #:val
sta :dst
.endif
.endm
org $3000
start setcolor 2, 9, 2 ; dark blue background
setcolor 1, 15, 12 ; light text
print 2, msg1
wait 30
print 4, msg2
wait 30
addb count, 1 ; expands to INC
addb count, 16 ; expands to CLC/LDA/ADC/STA
lda count ; 0 + 1 + 16 = 17 = $11
ldy #6
jsr showhex
print 6, msg3
jmp *
printz sta src ; A/X = text address, Y = row
stx src+1
lda rowlo,y
clc
adc SAVMSC
sta dst
lda rowhi,y
adc SAVMSC+1
sta dst+1
ldy #0
pz1 lda (src),y
cmp #$FF ; end marker (0 is a space in screen code)
beq pz2
sta (dst),y
iny
bne pz1
pz2 rts
showhex pha ; A in hex at column 32 of row Y
lda rowlo,y
clc
adc SAVMSC
sta dst
lda rowhi,y
adc SAVMSC+1
sta dst+1
pla
pha
lsr
lsr
lsr
lsr
tax
lda hexd,x
ldy #32
sta (dst),y
pla
and #$0F
tax
lda hexd,x
iny
sta (dst),y
rts
count dta 0
hexd dta d'0123456789ABCDEF'
rowlo .rept 24
dta <[#*40]
.endr
rowhi .rept 24
dta >[#*40]
.endr
msg1 dta d'PRINTED BY THE PRINT MACRO',$FF
msg2 dta d'AFTER WAIT 30 (HALF A SECOND)',$FF
msg3 dta d'ADDB COUNT,1 + ADDB COUNT,16 = $',$FF
run start
One detail in printz: the messages are in screen code (d'…'), where a space is code 0, so they end with $FF instead of the usual 0. Our first version used 0 and printed only the first word of each message.
7. Building a library
- Keep macros in their own file and include it with
icl 'macros.asm'at the top of each program. Because unused macros generate no code, a large library costs nothing. - Name macros for what they do (
print,wait), and don't reuse instruction or MADS directive names. - Check every argument you can: counts with
:0, ranges with.if, and stop with.error. Errors at assembly time are far cheaper than crashes on the Atari. - Document side effects: which registers and flags a macro changes. A caller can't see the expansion without looking at the listing.
- Read the listing (
-l:file.lst) when a macro misbehaves: MADS shows each expansion line by line, marked with the macro's name. - Know the built-ins: MVA, MWA, ADW, INW, CPW and the rest cover many everyday needs already. Your own macros fill the gaps for your project.
Troubleshooting
- Reserved word error at the macro name: the name matches an instruction or directive. Rename it.
- A macro generates wrong immediate values: remember that
<and>are evaluated before the call. Check the expansion in the listing. - "'#' is allowed only in repeated lines": use
.reptfor a multi-line repeat. - The wrong branch of an
.ifis assembled: look at the expansion in the listing to see what text the argument became.
Further reading
- The MADS manual: the chapters on macros (declaration, parameters,
:0, separators, local labels),.IF/.ERRORand.REPT, plus the exampleMACRO.ASMin the MADS distribution. - On this site: MADS (Mad-Assembler): A Practical Guide for Atari Programmers, Fast Memory Fills and Block Moves in 6502 Assembly, A Modern Cross-Development Workflow for the Atari 8-bit.
Credits
- Picture: The example program, built entirely from four home-made macros: colours, text, delays and an addition that picks its own instructions. — Program authors; screenshot by the site
- MADS manual (English) — MACROS chapter (.MACRO/.ENDM, named and numbered parameters, :0 count, missing parameters = -1, '<' '>' evaluated first, local labels, ':' prefix for global labels, reserved-word names), MACRO COMMANDS list, .IF/.ERROR, .REPT with '#' — GitHub project authors
