User manual

MPLAB
®
XC8 C Compiler User’s Guide
DS52053B-page 262  2012 Microchip Technology Inc.
6.4.9.13 MACRO AND ENDM
These directives provide for the definition of assembly macros, optionally with argu-
ments. See Section 6.4.9.5 “EQU” for simple association of a value with an identifier,
or Section 5.14.1 “C Language Comments” 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
;args: arg1 - the literal value to load
; arg2 - the NAME of the source variable
;descr: Move a literal value into a nominated file register
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.
A comment may 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 > may 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 may 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 Section 6.4.9.14 “LOCAL” 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 control, see Section 6.4.10.3 “EXPAND”.