|
421
|
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
|
|
|
2 <HTML
|
|
|
3 ><HEAD
|
|
|
4 ><TITLE
|
|
|
5 >Macros</TITLE
|
|
|
6 ><META
|
|
|
7 NAME="GENERATOR"
|
|
|
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
|
|
|
9 REL="HOME"
|
|
|
10 TITLE="LW Tool Chain"
|
|
|
11 HREF="index.html"><LINK
|
|
|
12 REL="UP"
|
|
|
13 TITLE="LWASM"
|
|
|
14 HREF="c43.html"><LINK
|
|
|
15 REL="PREVIOUS"
|
|
|
16 TITLE="Assembler Directives"
|
|
|
17 HREF="x190.html"><LINK
|
|
|
18 REL="NEXT"
|
|
|
19 TITLE="Structures"
|
|
|
20 HREF="x495.html"></HEAD
|
|
|
21 ><BODY
|
|
|
22 CLASS="SECTION"
|
|
|
23 BGCOLOR="#FFFFFF"
|
|
|
24 TEXT="#000000"
|
|
|
25 LINK="#0000FF"
|
|
|
26 VLINK="#840084"
|
|
|
27 ALINK="#0000FF"
|
|
|
28 ><DIV
|
|
|
29 CLASS="NAVHEADER"
|
|
|
30 ><TABLE
|
|
|
31 SUMMARY="Header navigation table"
|
|
|
32 WIDTH="100%"
|
|
|
33 BORDER="0"
|
|
|
34 CELLPADDING="0"
|
|
|
35 CELLSPACING="0"
|
|
|
36 ><TR
|
|
|
37 ><TH
|
|
|
38 COLSPAN="3"
|
|
|
39 ALIGN="center"
|
|
|
40 >LW Tool Chain</TH
|
|
|
41 ></TR
|
|
|
42 ><TR
|
|
|
43 ><TD
|
|
|
44 WIDTH="10%"
|
|
|
45 ALIGN="left"
|
|
|
46 VALIGN="bottom"
|
|
|
47 ><A
|
|
|
48 HREF="x190.html"
|
|
|
49 ACCESSKEY="P"
|
|
|
50 >Prev</A
|
|
|
51 ></TD
|
|
|
52 ><TD
|
|
|
53 WIDTH="80%"
|
|
|
54 ALIGN="center"
|
|
|
55 VALIGN="bottom"
|
|
|
56 >Chapter 3. LWASM</TD
|
|
|
57 ><TD
|
|
|
58 WIDTH="10%"
|
|
|
59 ALIGN="right"
|
|
|
60 VALIGN="bottom"
|
|
|
61 ><A
|
|
|
62 HREF="x495.html"
|
|
|
63 ACCESSKEY="N"
|
|
|
64 >Next</A
|
|
|
65 ></TD
|
|
|
66 ></TR
|
|
|
67 ></TABLE
|
|
|
68 ><HR
|
|
|
69 ALIGN="LEFT"
|
|
|
70 WIDTH="100%"></DIV
|
|
|
71 ><DIV
|
|
|
72 CLASS="SECTION"
|
|
|
73 ><H1
|
|
|
74 CLASS="SECTION"
|
|
|
75 ><A
|
|
|
76 NAME="AEN473"
|
|
|
77 >3.7. Macros</A
|
|
|
78 ></H1
|
|
|
79 ><P
|
|
|
80 >LWASM is a macro assembler. A macro is simply a name that stands in for a
|
|
|
81 series of instructions. Once a macro is defined, it is used like any other
|
|
|
82 assembler directive. Defining a macro can be considered equivalent to adding
|
|
|
83 additional assembler directives.</P
|
|
|
84 ><P
|
|
|
85 >Macros may accept parameters. These parameters are referenced within
|
|
|
86 a macro by the a backslash ("\") followed by a digit 1 through 9 for the first
|
|
|
87 through ninth parameters. They may also be referenced by enclosing the
|
|
|
88 decimal parameter number in braces ("{num}"). These parameter references
|
|
|
89 are replaced with the verbatim text of the parameter passed to the macro. A
|
|
|
90 reference to a non-existent parameter will be replaced by an empty string.
|
|
|
91 Macro parameters are expanded everywhere on each source line. That means
|
|
|
92 the parameter to a macro could be used as a symbol or it could even appear
|
|
|
93 in a comment or could cause an entire source line to be commented out
|
|
|
94 when the macro is expanded.</P
|
|
|
95 ><P
|
|
|
96 >Parameters passed to a macro are separated by commas and the parameter list
|
|
|
97 is terminated by any whitespace. This means that neither a comma nor whitespace
|
|
|
98 may be included in a macro parameter.</P
|
|
|
99 ><P
|
|
|
100 >Macro expansion is done recursively. That is, within a macro, macros are
|
|
|
101 expanded. This can lead to infinite loops in macro expansion. If the assembler
|
|
|
102 hangs for a long time while assembling a file that uses macros, this may be
|
|
|
103 the reason.</P
|
|
|
104 ><P
|
|
|
105 >Each macro expansion receives its own local symbol context which is not
|
|
|
106 inherited by any macros called by it nor is it inherited from the context
|
|
|
107 the macro was instantiated in. That means it is possible to use local symbols
|
|
|
108 within macros without having them collide with symbols in other macros or
|
|
|
109 outside the macro itself. However, this also means that using a local symbol
|
|
|
110 as a parameter to a macro, while legal, will not do what it would seem to do
|
|
|
111 as it will result in looking up the local symbol in the macro's symbol context
|
|
|
112 rather than the enclosing context where it came from, likely yielding either
|
|
|
113 an undefined symbol error or bizarre assembly results.</P
|
|
|
114 ><P
|
|
|
115 >Note that there is no way to define a macro as local to a symbol context. All
|
|
|
116 macros are part of the global macro namespace. However, macros have a separate
|
|
|
117 namespace from symbols so it is possible to have a symbol with the same name
|
|
|
118 as a macro.</P
|
|
|
119 ><P
|
|
|
120 >Macros are defined only during the first pass. Macro expansion also
|
|
|
121 only occurs during the first pass. On the second pass, the macro
|
|
|
122 definition is simply ignored. Macros must be defined before they are used.</P
|
|
|
123 ><P
|
|
|
124 >The following directives are used when defining macros.</P
|
|
|
125 ><P
|
|
|
126 ></P
|
|
|
127 ><DIV
|
|
|
128 CLASS="VARIABLELIST"
|
|
|
129 ><DL
|
|
|
130 ><DT
|
|
|
131 ><CODE
|
|
|
132 CLASS="PARAMETER"
|
|
|
133 >macroname</CODE
|
|
|
134 > MACRO</DT
|
|
|
135 ><DD
|
|
|
136 ><P
|
|
|
137 >This directive is used to being the definition of a macro called
|
|
|
138 <CODE
|
|
|
139 CLASS="PARAMETER"
|
|
|
140 >macroname</CODE
|
|
|
141 >. If <CODE
|
|
|
142 CLASS="PARAMETER"
|
|
|
143 >macroname</CODE
|
|
|
144 > already
|
|
|
145 exists, it is considered an error. Attempting to define a macro within a
|
|
|
146 macro is undefined. It may work and it may not so the behaviour should not
|
|
|
147 be relied upon.</P
|
|
|
148 ></DD
|
|
|
149 ><DT
|
|
|
150 >ENDM</DT
|
|
|
151 ><DD
|
|
|
152 ><P
|
|
|
153 >This directive indicates the end of the macro currently being defined. It
|
|
|
154 causes the assembler to resume interpreting source lines as normal.</P
|
|
|
155 ></DD
|
|
|
156 ></DL
|
|
|
157 ></DIV
|
|
|
158 ></DIV
|
|
|
159 ><DIV
|
|
|
160 CLASS="NAVFOOTER"
|
|
|
161 ><HR
|
|
|
162 ALIGN="LEFT"
|
|
|
163 WIDTH="100%"><TABLE
|
|
|
164 SUMMARY="Footer navigation table"
|
|
|
165 WIDTH="100%"
|
|
|
166 BORDER="0"
|
|
|
167 CELLPADDING="0"
|
|
|
168 CELLSPACING="0"
|
|
|
169 ><TR
|
|
|
170 ><TD
|
|
|
171 WIDTH="33%"
|
|
|
172 ALIGN="left"
|
|
|
173 VALIGN="top"
|
|
|
174 ><A
|
|
|
175 HREF="x190.html"
|
|
|
176 ACCESSKEY="P"
|
|
|
177 >Prev</A
|
|
|
178 ></TD
|
|
|
179 ><TD
|
|
|
180 WIDTH="34%"
|
|
|
181 ALIGN="center"
|
|
|
182 VALIGN="top"
|
|
|
183 ><A
|
|
|
184 HREF="index.html"
|
|
|
185 ACCESSKEY="H"
|
|
|
186 >Home</A
|
|
|
187 ></TD
|
|
|
188 ><TD
|
|
|
189 WIDTH="33%"
|
|
|
190 ALIGN="right"
|
|
|
191 VALIGN="top"
|
|
|
192 ><A
|
|
|
193 HREF="x495.html"
|
|
|
194 ACCESSKEY="N"
|
|
|
195 >Next</A
|
|
|
196 ></TD
|
|
|
197 ></TR
|
|
|
198 ><TR
|
|
|
199 ><TD
|
|
|
200 WIDTH="33%"
|
|
|
201 ALIGN="left"
|
|
|
202 VALIGN="top"
|
|
|
203 >Assembler Directives</TD
|
|
|
204 ><TD
|
|
|
205 WIDTH="34%"
|
|
|
206 ALIGN="center"
|
|
|
207 VALIGN="top"
|
|
|
208 ><A
|
|
|
209 HREF="c43.html"
|
|
|
210 ACCESSKEY="U"
|
|
|
211 >Up</A
|
|
|
212 ></TD
|
|
|
213 ><TD
|
|
|
214 WIDTH="33%"
|
|
|
215 ALIGN="right"
|
|
|
216 VALIGN="top"
|
|
|
217 >Structures</TD
|
|
|
218 ></TR
|
|
|
219 ></TABLE
|
|
|
220 ></DIV
|
|
|
221 ></BODY
|
|
|
222 ></HTML
|
|
|
223 > |
