User manual

ST assembler ST Assembler-Linker
30/89 Doc ID 11392 Rev 4
4.5 Macros
Macros are assembly-time subroutines.
When you call an execution-time subroutine you have to go through several time-consuming
steps: loading registers with the arguments for the subroutine, having saved and emptied
out the old contents of the registers if necessary, pushing registers used by the subroutine
(with its attendant stack activity) and returning from the subroutine (more stack activity) then
popping off preserved registers and continuing.
Although macros don't get rid of all these problems, they can go a long way toward making
your program execute faster than using subroutines, at a cost. The cost is program size.
Each time you invoke a macro to do a particular job, the whole macro assembly code
is inserted into your source code.
This means there is no stacking for return addresses, your program just runs straight into
the code; but it is obviously not feasible to do this for subroutines above certain size.
The true use of macros is in small snippets of code that you use repeatedly, perhaps with
different arguments, which can be formalized into a 'template' for the macros' definition.
4.5.1 Defining macros
Macros are defined using three directives: MACRO, MEND and LOCAL.
The format is:
<macro-name>MACRO [parameter-1][, parameter-2 ...]
[LOCAL] <label-name>[, label-name ...]]
<body-of-macro>
MEND
For example:
add16 MACRO first,second,result
ld A,first
adc A,second
ld result,A
MEND
The piece of code of the example might be called by:
add16 index,offset,index
which would add the following statements to the source code at that point:
ld A,index
adc A,offset
ld index.X,A
Note: The formal parameters given in the definition have been replaced by the actual
parameters given on the calling line.
These new parameters may be expressions or strings as well as label names or constants.
Because they may be complex expressions, they are bracketed when there is any extra
numeric activity; this is to make sure they come out with the precedence correctly parsed.
Macros do not need to have any parameters. You may leave the MACRO argument field blank
(and, in this case, give no parameters on the calling line).