MADS Macros in Practice: Building Your Own Checked Macro Library

Dark blue Atari screen with three lines of light text: PRINTED BY THE PRINT MACRO, AFTER WAIT 30 (HALF A SECOND), and ADDB COUNT,1 + ADDB COUNT,16 = $11

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 .rept for a multi-line repeat.
  • The wrong branch of an .if is 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/.ERROR and .REPT, plus the example MACRO.ASM in 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