Mercurial > hg-old > index.cgi

comparison doc/manual/x473.html @ 421:3c2e1f24cc7d 3.0-beta2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added generated files for release
author lost@l-w.ca
date Sun, 19 Sep 2010 01:33:24 -0600
parents
children
comparison
equal deleted inserted replaced
420:7366deedfa85 421:3c2e1f24cc7d
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 >