|
168
|
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 > and < symbols can be used
|
|
|
276 to force the branch size, analogous to their use for other instructions with
|
|
|
277 < forcing 8 bit offsets and > 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 > |
