Assembler Macros

The WinAPE assembler provides Macros to allow complex or repeated code to be generated easily by defining custom directives which can optionally include parameters.

Macro definition

Macros are defined using the format:

macro name [parameter{,parameter...}]

A macro can contain any valid code, including labels and local labels (prefixed with @).

The macro name and all parameters must be defined using valid symbol characters ('A'..'Z', 'a'..'z', '_', '0'..'9').

Each parameter passed is substituted literally into the code inside the macro when it is encountered as a whole word. For this reason, it is preferable to use parameter names which are not normally used in either text strings or as register names. The example below shows a bad macro definition since it uses register names:

macro test a, b, c
  print a
  print "hello a bc"
  print 'c'
  db a, b, c
  db a + b, c + 'a'
  LD H,A

testit 1, '2', 3

The output produced by this would be:

hello 1 bc
000010  0000  01 32 03        db 1, '2', 3
000010  0003  33 34           db 1 + '2', 3 + '1'
000010  0005  26 01           LD H,1

Notice that the value 1 has been substituted for all A words in the macro definition, including the a inside the string "hello a bc" which has been converted to "hello 1 bc", the 'a' inside quotes in the second db a + b, c + 'a' which has been converted to db 1 + '2', 3 + '1' and also the valid Z80 instruction LD H,A which has been converted to LD H,1. The bc inside the second print is not substituted since there is no parameter called bc.

Overriding Reserved Words

A macro can redefine standard directives or even Z80 instructions. At any time in the assembler, in order to use the standard version simply precede it with an exclamation mark. For example:

macro ld dest,src
  if "dest" = "de"
    if "src" = "bc"
      !ld d,b
      !ld e,c
    elseif "src" = "hl"
      !ld d,h
      !ld e,l
      !ld dest,src
    !ld dest,src

As a general rule it is not advisable to redefine the function of standard directives or Z80 instructions as it can make your code very hard to maintain.

Local Labels

If a macro contains a label and it is used more than once the assembler will attempt to redefine the same symbol, which will cause an error. For example:

macro decnz_bad
  or a
  jr z,silly1
  dec a

decnz_bad  ;; <- This line will cause a Duplicate Definition error

By using a local label (a symbol prefixed with an @ character) the assembler will scope the label to the current macro only. So a correct definition for a macro to decrement A if it's not zero could be:

macro decnz_a
  or a
  jr z,@leave
  dec a


The output of the above decnz_a two lines would be:

000008  0000                decnz_a
000008  0000  B7              or a
000008  0001  28 01           jr z,@leave
000008  0003  3D              dec a
000008  0004                  @leave
000009  0004                decnz_a
000009  0004  B7              or a
000009  0005  28 01           jr z,@leave
000009  0007  3D              dec a
000009  0008                  @leave

Curly Brackets

Curly brackets allow parameters to be included in the middle of another word. For example, consider the following macro:

macro curly param
  print "H{param}o"

curly ell

The assembler would print out the word Hello.

Nested Macros

Macros can use previously defined macros internally. For example:

macro swap reg1, reg2
  ld a,reg1
  ld reg1,reg2
  ld reg2,a

macro swap_bcde
  swap b,c
  swap d,e


The assembler output for the swap_bcde line is:

000012  0000                swap_bcde
000012  0000                  swap b,c
000012  0000  78              ld a,b
000012  0001  41              ld b,c
000012  0002  4F              ld c,a
000012  0003                  swap d,e
000012  0003  7A              ld a,d
000012  0004  53              ld d,e
000012  0005  5F              ld e,a

Combining Macros with the LET directive

Since let allows a symbol to be redefined, global symbols can be shared between multiple macros. For example:

macro pixel_address x, y
  @y7 equ y and 7 * #800
  @addr equ y / 8 * #50 + #c000 + @y7
  let pix_addr = x / 8 + @addr
  let pix_mask = #80
  repeat x and 7
    let pix_mask = pix_mask / 2

macro get_pixel_address addr_reg, mask_reg, x_pos, y_pos
  pixel_address x_pos,y_pos
  ld addr_reg,pix_addr
  ld mask_reg,pix_mask

get_pixel_address hl,e,233,36

The assembler output for the get_pixel_address hl,e,233,36 line of code is:

000017  0000                get_pixel_address hl,e,235,36
000017  0000                  pixel_address 235,36
000017  0000  (2000)          @y7 equ 36 and 7 * #800
000017  0000  (E140)          @addr equ 36 / 8 * #50 + #c000 + @y7
000017  0000  (E15D)          let pix_addr = 235 / 8 + @addr
000017  0000  (0080)          let pix_mask = #80
000017  0000                  repeat 235 and 7
000017  0000                    let pix_mask = pix_mask / 2
000017  0000                  rend
000017  0000  (0040)            let pix_mask = pix_mask / 2
000017  0000  (0020)            let pix_mask = pix_mask / 2
000017  0000  (0010)            let pix_mask = pix_mask / 2
000017  0000  21 5D E1        ld hl,pix_addr
000017  0003  1E 10           ld e,pix_mask
000019  0005                end

That's the equivalent of ld hl,#e15d:ld e,#10 but the assembler works out the address and mask rather than you doing it manually. Unfortunately, the above code won't cope with expressions being passed in as parameters (eg. pixel_address left + 10, top + 20) because the assembler expression evaluation is always performed left-to-right with no support for parenthesis. This is as a result of maintaining Maxam source compatibility, so we would have to modify the macro definition using more local symbols or let to re-assign. For example:

macro pixel_address x, y
  @y1 equ y
  @y7 equ @y1 and 7 * #800
  @addr equ @y1 / 8 * #50 + #c000 + @y7
  let pix_addr = x;
  let pix_addr = pix_addr / 8 + @addr
  let pix_mask = #80
  repeat x and 7
    let pix_mask = pix_mask / 2

Note that repeat and while are also treated as macros and have their own local symbols. It is not currently possible to access the local symbols of the parent macro, so it would not be possible to modify @y1, @y7 or @addr inside the repeat loop.

String Comparisons

The WinAPE assembler has basic string comparison support, allowing conditional compilation by comparing macro parameters to string values. For example:

macro get_edge_address edge
  if "edge" = "left"
    ld hl,#c050
  elseif "edge" = "top"
    ld hl,#c028
  elseif "edge" = "right"
    ld hl,#c09e
    ld hl,#c0c8

get_edge_address right