Macro And Endm Directives

The MACRO … ENDM directives provide for the definition of assembly macros, optionally with arguments. See Equ Directive for simple association of a value with an identifier, or Preprocessor Directives for the preprocessor’s #define macro directive, which can also work with arguments.

The MACRO directive should be preceded by the macro name and optionally followed by a comma-separated list of formal arguments. When the macro is used, the macro name should be used in the same manner as a machine opcode, followed by a list of arguments to be substituted for the formal parameters.

For example:

;macro: movlf - Move a literal value into a nominated file register
;args:  arg1 - the literal value to load
;       arg2 - the NAME of the source variable
movlf   MACRO   arg1,arg2
  movlw arg1
  movwf arg2 mod 080h
ENDM

When used, this macro will expand to the 2 instructions in the body of the macro, with the formal parameters substituted by the arguments. Thus:

movlf 2,tempvar

expands to:

movlw 2
movwf tempvar mod 080h

The & character can be used to permit the concatenation of macro arguments with other text, but is removed in the actual expansion. For example:

loadPort MACRO port, value
  movlw value
  movwf PORT&port
ENDM

will load PORTA if port is A when called, etc. The special meaning of the & token in macros implies that you can not use the bitwise AND operator, (also represented by &), in assembly macros; use the and form of this operator instead.

A comment can be suppressed within the expansion of a macro (thus saving space in the macro storage) by opening the comment with a double semicolon, ;;.

When invoking a macro, the argument list must be comma-separated. If it is desired to include a comma (or other delimiter such as a space) in an argument then angle brackets < and > can be used to quote

If an argument is preceded by a percent sign, %, that argument will be evaluated as an expression and passed as a decimal number, rather than as a string. This is useful if evaluation of the argument inside the macro body would yield a different result.

The nul operator can be used within a macro to test a macro argument, for example:

IF nul     arg3  ;argument was not supplied.
...
ELSE             ;argument was supplied
...
ENDIF

See Local Directive for use of unique local labels within macros.

By default, the assembly list file will show macro in an unexpanded format; i.e., as the macro was invoked. Expansion of the macro in the listing file can be shown by using the EXPAND assembler directive (see Expand Directive).