The structure of a macro definition consists of a name, some optional arguments, the body of the macro and a termination keyword. The syntax you use to define a macro is:
name MACRO arg1
, arg2
, ... ,
argn
macro-body
ENDMACRO | ENDM
The name of the macro has the same requirements as a label name (in particular it must start in column one). The arguments are a comma-separated list of identifiers. The body of the macro can have arbitrary assembly language text including other macro definitions and invocations, conditional and file inclusion directives. A macro is instantiated by using its name together with optional actual argument values. A macro instantiation has to occur on its own line—it cannot be used within an expression or as an argument to an assembly code mnemonic or directive. The syntax you use invoke a macro is
name actual1 , actual2 , ... , actualn // comment
When a macro is instantiated the macro body is inserted into the assembly text with the actual values replacing the arguments that were in the body of the macro definition.
When labels are used in macros they must be unique for each instantiation to avoid duplicate label definition errors. The assembler provides a label generation mechanism for situations where the label name isn’t significant and a mechanism for constructing specific label names.
If a macro definition contains a jump to other instructions in the macro definition it is likely that the actual name of the label isn’t important. To facilitate this a label of the form name? can be used.
There are situations when a macro invocation should result in the definition of a label. In the simplest case the label can be passed as an argument to the macro, however there are cases when the label name should be constructed from other tokens. The macro definition facility provides two constructs to enable this:
If multiple definitions are required a loop structure can be used. This can be achieved either by a recursive macro definitions or by the use of the LOOP directive.
P2TAB MACRO N IF N P2TAB N-1 ENDIF DW 1<<N ENDMACRO
POWERS: POWER2TAB 10
This creates a table of ten powers of 2, that is 1, 2, 4, 8, and so on, up to 1024.
If the loop counter is a large number then a recursive macro may consume considerable machine resources. To avoid this you can use the LOOP directive, which is an iterative rather than recursive solution.
LOOP expression
loop-body
ENDLOOP
The loop control expression must be a compile time constant. The loop body can contain any assembly text (including further loop constructs) except macro definitions (since it would result in multiple definitions of the same macro). The above recursive definition can be recast in an iterative style:
POWERS: x SET 0 LOOP x <= 10 DC.W 1<<x x SET x+1 ENDLOOP
Note that the label naming capabilities using ?, $$, and ## are not available within the body of a loop. If the loop body is to declare labels then a recursive macro definition should be used or a combination of using macro invocation to define the labels and the loops to define the text of the label.