6.1.9.28 Macro And Endm Directives

The MACRO … ENDM directives provide for the definition of assembly macros, optionally with arguments. See 6.1.9.16 Equ Directive for simple association of a value with an identifier, or 5.14.1 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

See 6.1.9.27 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 6.1.9.18 Expand Directive).