Mercurial > hg > index.cgi

comparison docs/manual/x568.html @ 565:fc072f6cde09

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update documentation to reflect includebin offset/length feature
author William Astle <lost@l-w.ca>
date Thu, 21 Dec 2023 22:16:12 -0700
parents
children
comparison
equal deleted inserted replaced
564:87f904e2b304 565:fc072f6cde09
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="c62.html"><LINK
15 REL="PREVIOUS"
16 TITLE="Assembler Directives"
17 HREF="x261.html"><LINK
18 REL="NEXT"
19 TITLE="Structures"
20 HREF="x591.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="x261.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="x591.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="AEN568"
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 a
86 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}"). The special expansion "\*"
89 translates to the exact parameter string, including all parameters, passed
90 to the macro. These parameter references are replaced with the verbatim text
91 of the parameter passed to the macro. A reference to a non-existent
92 parameter will be replaced by an empty string. Macro parameters are expanded
93 everywhere on each source line. That means the parameter to a macro could be
94 used as a symbol or it could even appear in a comment or could cause an
95 entire source line to be commented out when the macro is expanded. </P
96 ><P
97 >Parameters passed to a macro are separated by commas and the parameter list
98 is terminated by any whitespace. This means that neither a comma nor whitespace
99 may be included in a macro parameter.</P
100 ><P
101 >Macro expansion is done recursively. That is, within a macro, macros are
102 expanded. This can lead to infinite loops in macro expansion. If the assembler
103 hangs for a long time while assembling a file that uses macros, this may be
104 the reason.</P
105 ><P
106 >Each macro expansion receives its own local symbol context which is not
107 inherited by any macros called by it nor is it inherited from the context
108 the macro was instantiated in. That means it is possible to use local symbols
109 within macros without having them collide with symbols in other macros or
110 outside the macro itself. However, this also means that using a local symbol
111 as a parameter to a macro, while legal, will not do what it would seem to do
112 as it will result in looking up the local symbol in the macro's symbol context
113 rather than the enclosing context where it came from, likely yielding either
114 an undefined symbol error or bizarre assembly results.</P
115 ><P
116 >Note that there is no way to define a macro as local to a symbol context. All
117 macros are part of the global macro namespace. However, macros have a separate
118 namespace from symbols so it is possible to have a symbol with the same name
119 as a macro.</P
120 ><P
121 >Macros are defined only during the first pass. Macro expansion also
122 only occurs during the first pass. On the second pass, the macro
123 definition is simply ignored. Macros must be defined before they are used.</P
124 ><P
125 >The following directives are used when defining macros.</P
126 ><P
127 ></P
128 ><DIV
129 CLASS="VARIABLELIST"
130 ><DL
131 ><DT
132 ><CODE
133 CLASS="PARAMETER"
134 >macroname</CODE
135 > MACRO [NOEXPAND]</DT
136 ><DD
137 ><P
138 >This directive is used to being the definition of a macro called
139 <CODE
140 CLASS="PARAMETER"
141 >macroname</CODE
142 >. If <CODE
143 CLASS="PARAMETER"
144 >macroname</CODE
145 > already
146 exists, it is considered an error. Attempting to define a macro within a
147 macro is undefined. It may work and it may not so the behaviour should not
148 be relied upon.</P
149 ><P
150 >If NOEXPAND is specified, the macro will not be expanded in a program
151 listing. Instead, all bytes emitted by all instructions within the macro
152 will appear to be emitted on the line where the macro is invoked, starting
153 at the address of the line of the invokation. If the macro uses ORG or other
154 directives that define symbols or change the assembly address, these things
155 will also be hidden (except in the symbol table) and the output bytes will
156 appear with incorrect address attribution. Thus, NOEXPAND should only be
157 used for macros that do not mess with the assembly address or otherwise
158 define symbols that should be visible.</P
159 ></DD
160 ><DT
161 >ENDM</DT
162 ><DD
163 ><P
164 >This directive indicates the end of the macro currently being defined. It
165 causes the assembler to resume interpreting source lines as normal.</P
166 ></DD
167 ></DL
168 ></DIV
169 ></DIV
170 ><DIV
171 CLASS="NAVFOOTER"
172 ><HR
173 ALIGN="LEFT"
174 WIDTH="100%"><TABLE
175 SUMMARY="Footer navigation table"
176 WIDTH="100%"
177 BORDER="0"
178 CELLPADDING="0"
179 CELLSPACING="0"
180 ><TR
181 ><TD
182 WIDTH="33%"
183 ALIGN="left"
184 VALIGN="top"
185 ><A
186 HREF="x261.html"
187 ACCESSKEY="P"
188 >Prev</A
189 ></TD
190 ><TD
191 WIDTH="34%"
192 ALIGN="center"
193 VALIGN="top"
194 ><A
195 HREF="index.html"
196 ACCESSKEY="H"
197 >Home</A
198 ></TD
199 ><TD
200 WIDTH="33%"
201 ALIGN="right"
202 VALIGN="top"
203 ><A
204 HREF="x591.html"
205 ACCESSKEY="N"
206 >Next</A
207 ></TD
208 ></TR
209 ><TR
210 ><TD
211 WIDTH="33%"
212 ALIGN="left"
213 VALIGN="top"
214 >Assembler Directives</TD
215 ><TD
216 WIDTH="34%"
217 ALIGN="center"
218 VALIGN="top"
219 ><A
220 HREF="c62.html"
221 ACCESSKEY="U"
222 >Up</A
223 ></TD
224 ><TD
225 WIDTH="33%"
226 ALIGN="right"
227 VALIGN="top"
228 >Structures</TD
229 ></TR
230 ></TABLE
231 ></DIV
232 ></BODY
233 ></HTML
234 >