Mercurial > hg > index.cgi

comparison docs/manual/x584.html @ 168:1e0a0e6cd918

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documentation updates
author lost@l-w.ca
date Mon, 29 Aug 2011 19:15:50 -0600
parents
children
comparison
equal deleted inserted replaced
167:872fa82680e1 168:1e0a0e6cd918
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 >Assembler Modes and Pragmas</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="c45.html"><LINK
15 REL="PREVIOUS"
16 TITLE="Object Files and Sections"
17 HREF="x520.html"><LINK
18 REL="NEXT"
19 TITLE="LWLINK"
20 HREF="c662.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="x520.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="c662.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="AEN584"
77 >3.10. Assembler Modes and Pragmas</A
78 ></H1
79 ><P
80 >There are a number of options that affect the way assembly is performed.
81 Some of these options can only be specified on the command line because
82 they determine something absolute about the assembly process. These include
83 such things as the output target. Other things may be switchable during
84 the assembly process. These are known as pragmas and are, by definition,
85 not portable between assemblers.</P
86 ><P
87 >LWASM supports a number of pragmas that affect code generation or
88 otherwise affect the behaviour of the assembler. These may be specified by
89 way of a command line option or by assembler directives. The directives
90 are as follows.</P
91 ><P
92 ></P
93 ><DIV
94 CLASS="VARIABLELIST"
95 ><DL
96 ><DT
97 >PRAGMA <CODE
98 CLASS="PARAMETER"
99 >pragma[,...]</CODE
100 ></DT
101 ><DD
102 ><P
103 >Specifies that the assembler should bring into force all <CODE
104 CLASS="PARAMETER"
105 >pragma</CODE
106 >s
107 specified. Any unrecognized pragma will cause an assembly error. The new
108 pragmas will take effect immediately. This directive should be used when
109 the program will assemble incorrectly if the pragma is ignored or not supported.</P
110 ></DD
111 ><DT
112 >*PRAGMA <CODE
113 CLASS="PARAMETER"
114 >pragma[,...]</CODE
115 ></DT
116 ><DD
117 ><P
118 >This is identical to the PRAGMA directive except no error will occur with
119 unrecognized or unsupported pragmas. This directive, by virtue of starting
120 with a comment character, will also be ignored by assemblers that do not
121 support this directive. Use this variation if the pragma is not required
122 for correct functioning of the code.</P
123 ></DD
124 ><DT
125 >*PRAGMAPUSH <CODE
126 CLASS="PARAMETER"
127 >pragma[,...]</CODE
128 ></DT
129 ><DD
130 ><P
131 >This directive saves the current state of the specified pragma(s) for later retrieval. See discussion below for more information.</P
132 ><P
133 >This directive will not throw any errors for any reason.</P
134 ></DD
135 ><DT
136 >*PRAGMAPOP <CODE
137 CLASS="PARAMETER"
138 >pragma[,...]</CODE
139 ></DT
140 ><DD
141 ><P
142 >This directive restores the previously saved state of the specified pragma(s). See discussion below for more information.</P
143 ><P
144 >This directive will not throw any errors for any reason.</P
145 ></DD
146 ></DL
147 ></DIV
148 ><P
149 >Each pragma supported has a positive version and a negative version.
150 The positive version enables the pragma while the negative version disables
151 it. The negatitve version is simply the positive version with "no" prefixed
152 to it. For instance, "pragma" vs. "nopragma". Only the positive version is
153 listed below.</P
154 ><P
155 >Pragmas are not case sensitive.</P
156 ><P
157 ></P
158 ><DIV
159 CLASS="VARIABLELIST"
160 ><DL
161 ><DT
162 >index0tonone</DT
163 ><DD
164 ><P
165 >When in force, this pragma enables an optimization affecting indexed addressing
166 modes. When the offset expression in an indexed mode evaluates to zero but is
167 not explicity written as 0, this will replace the operand with the equivalent
168 no offset mode, thus creating slightly faster code. Because of the advantages
169 of this optimization, it is enabled by default.</P
170 ></DD
171 ><DT
172 >cescapes</DT
173 ><DD
174 ><P
175 >This pragma will cause strings in the FCC, FCS, and FCN pseudo operations to
176 have C-style escape sequences interpreted. The one departure from the official
177 spec is that unrecognized escape sequences will return either the character
178 immediately following the backslash or some undefined value. Do not rely
179 on the behaviour of undefined escape sequences.</P
180 ></DD
181 ><DT
182 >importundefexport</DT
183 ><DD
184 ><P
185 >This pragma is only valid for targets that support external references. When
186 in force, it will cause the EXPORT directive to act as IMPORT if the symbol
187 to be exported is not defined. This is provided for compatibility with the
188 output of gcc6809 and should not be used in hand written code. Because of
189 the confusion this pragma can cause, it is disabled by default.</P
190 ></DD
191 ><DT
192 >undefextern</DT
193 ><DD
194 ><P
195 >This pragma is only valid for targets that support external references. When in
196 force, if the assembler sees an undefined symbol on the second pass, it will
197 automatically define it as an external symbol. This automatic definition will
198 apply for the remainder of the assembly process, even if the pragma is
199 subsequently turned off. Because this behaviour would be potentially surprising,
200 this pragma defaults to off.</P
201 ><P
202 >The primary use for this pragma is for projects that share a large number of
203 symbols between source files. In such cases, it is impractical to enumerate
204 all the external references in every source file. This allows the assembler
205 and linker to do the heavy lifting while not preventing a particular source
206 module from defining a local symbol of the same name as an external symbol
207 if it does not need the external symbol. (This pragma will not cause an
208 automatic external definition if there is already a locally defined symbol.)</P
209 ><P
210 >This pragma will often be specified on the command line for large projects.
211 However, depending on the specific dynamics of the project, it may be sufficient
212 for one or two files to use this pragma internally.</P
213 ></DD
214 ><DT
215 >dollarlocal</DT
216 ><DD
217 ><P
218 >When set, a "$" in a symbol makes it local. When not set, "$" does not
219 cause a symbol to be local. It is set by default except when using the OS9
220 target.</P
221 ></DD
222 ><DT
223 >dollarnotlocal</DT
224 ><DD
225 ><P
226 > This is the same as the "dollarlocal" pragma except its sense is
227 reversed. That is, "dollarlocal" and "nodollarnotlocal" are equivalent and
228 "nodollarlocal" and "dollarnotlocal" are equivalent. </P
229 ></DD
230 ><DT
231 >pcaspcr</DT
232 ><DD
233 ><P
234 > Normally, LWASM makes a distinction between PC and PCR in program
235 counter relative addressing. In particular, the use of PC means an absolute
236 offset from PC while PCR causes the assembler to calculate the offset to the
237 specified operand and use that as the offset from PC. By setting this
238 pragma, you can have PC treated the same as PCR. </P
239 ></DD
240 ><DT
241 >shadow</DT
242 ><DD
243 ><P
244 >When this pragma is in effect, it becomes possible to define a macro
245 that matches an internal operation code. Thus, it makes it possible to
246 redefine either CPU instructions or pseudo operations. Because this feature
247 is of dubious utility, it is disabled by default.</P
248 ></DD
249 ><DT
250 >nolist</DT
251 ><DD
252 ><P
253 >Lines where this pragma is in effect will not appear in the assembly
254 listing. Also, any symbols defined under this pragma will not show up in
255 the symbol list. This is most useful in include files to avoid spamming the
256 assembly listing with dozens, hundreds, or thousands of irrelevant
257 symbols.</P
258 ></DD
259 ><DT
260 >autobranchlength</DT
261 ><DD
262 ><P
263 >One of the perennial annoyances for 6809 programmers is that the
264 mneumonics for the short and long branch instructions are different (bxx vs.
265 lbxx), which is at odds with the rest of the instruction set. This pragma
266 is a solution to those annoying byte overflow errors that short branch
267 instructions tend to aquire.</P
268 ><P
269 >When this pragma is in effect, which is not the default, whenever any
270 relative branch instruction is used, its size will be automatically
271 determined based on the actual distance to the destination. In other words,
272 one can write code with long or short branches everywhere and the assembler
273 will choose a size for the branch.</P
274 ><P
275 >Also, while this pragma is in effect, the &#62; and &#60; symbols can be used
276 to force the branch size, analogous to their use for other instructions with
277 &#60; forcing 8 bit offsets and &#62; forcing 16 bit offets.</P
278 ><P
279 >Because this pragma leads to source that is incompatible with other
280 assemblers, it is strongly recommended that it be invoked using the PRAGMA
281 directive within the source code rather than on the command line or via the
282 *PRAGMA directive. This way, an error will be raised if someone tries to
283 * assemble the code under a different assembler.</P
284 ></DD
285 ></DL
286 ></DIV
287 ><P
288 >As a convenience, each input file has a pragma state stack. This
289 allows, through the use of *PRAGMAPUSH and *PRAGMAPOP, a file to change a
290 pragma state and then restore it to the precise state it had previously.
291 If, at the end of an input file, all pragma states have not been popped,
292 they will be removed from the stack. Thus, it is critical to employ
293 *PRAGMAPOP correctly. Because each input file has its own pragma stack,
294 using *PRAGMAPUSH in one file and *PRAGMAPOP in another file will not
295 work.</P
296 ><P
297 >Pragma stacks are more useful in include files, in particular in
298 conjunction with the nolist pragma. One can push the state of the nolist
299 pragma, engage the nolist pragma, and then pop the state of the nolist
300 pragma at the end of the include file. This will cause the entire include
301 file to operate under the nolist pragma. However, if the file is included
302 while nolist is already engaged, it will not undo that state.</P
303 ></DIV
304 ><DIV
305 CLASS="NAVFOOTER"
306 ><HR
307 ALIGN="LEFT"
308 WIDTH="100%"><TABLE
309 SUMMARY="Footer navigation table"
310 WIDTH="100%"
311 BORDER="0"
312 CELLPADDING="0"
313 CELLSPACING="0"
314 ><TR
315 ><TD
316 WIDTH="33%"
317 ALIGN="left"
318 VALIGN="top"
319 ><A
320 HREF="x520.html"
321 ACCESSKEY="P"
322 >Prev</A
323 ></TD
324 ><TD
325 WIDTH="34%"
326 ALIGN="center"
327 VALIGN="top"
328 ><A
329 HREF="index.html"
330 ACCESSKEY="H"
331 >Home</A
332 ></TD
333 ><TD
334 WIDTH="33%"
335 ALIGN="right"
336 VALIGN="top"
337 ><A
338 HREF="c662.html"
339 ACCESSKEY="N"
340 >Next</A
341 ></TD
342 ></TR
343 ><TR
344 ><TD
345 WIDTH="33%"
346 ALIGN="left"
347 VALIGN="top"
348 >Object Files and Sections</TD
349 ><TD
350 WIDTH="34%"
351 ALIGN="center"
352 VALIGN="top"
353 ><A
354 HREF="c45.html"
355 ACCESSKEY="U"
356 >Up</A
357 ></TD
358 ><TD
359 WIDTH="33%"
360 ALIGN="right"
361 VALIGN="top"
362 >LWLINK</TD
363 ></TR
364 ></TABLE
365 ></DIV
366 ></BODY
367 ></HTML
368 >