Mercurial > hg > index.cgi

comparison docs/manual/x676.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 >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="c62.html"><LINK
15 REL="PREVIOUS"
16 TITLE="Object Files and Sections"
17 HREF="x612.html"><LINK
18 REL="NEXT"
19 TITLE="Convenience Instructions"
20 HREF="x827.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="x612.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="x827.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="AEN676"
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". When only one version is
153 listed below, its opposite can be obtained by prepending "no" if it is not
154 present or removing "no" from the beginning if it is present.</P
155 ><P
156 >Pragmas are not case sensitive.</P
157 ><P
158 ></P
159 ><DIV
160 CLASS="VARIABLELIST"
161 ><DL
162 ><DT
163 >6800compat</DT
164 ><DD
165 ><P
166 >When in force, this pragma enables recognition of various
167 compatibility instructions useful when assembling 6800 code. These
168 compatibility instructions are assembled into equivalent 6809 instructions.
169 This mode also includes several analogous instructions which are not
170 strictly 6800 instructions but allow the similar style to be applied to 6809
171 specific features.</P
172 ><P
173 >Technically, a compliant 6809 assembler must recognize these
174 instructions by default since Motorola advertised the 6809 as being source
175 compatible with the 6800. However, most source code does not require this
176 compatibility and LWASM itself did not support these instructions prior to
177 version 4.11 so this mode is disabled by default.</P
178 ></DD
179 ><DT
180 >6809</DT
181 ><DD
182 ><P
183 >This pragma allows you to mark a section of code as 6809-only. In ths mode,
184 the assembler will throw an error if any 6309 instructions are used.</P
185 ></DD
186 ><DT
187 >6309</DT
188 ><DD
189 ><P
190 >This pragma enables the use of 6309 instructions and disables any 6809 specific
191 instructions. It also changes the cycle count listing output (if selected)
192 to display 6309 timings.</P
193 ></DD
194 ><DT
195 >6809conv, 6309conv</DT
196 ><DD
197 ><P
198 >These pragmas enable convenience instructions extending the 6809 and 6309
199 instruction sets respectively. For more information, see
200 <A
201 HREF="x827.html"
202 >Section 3.11</A
203 >.</P
204 ></DD
205 ><DT
206 >index0tonone</DT
207 ><DD
208 ><P
209 >When in force, this pragma enables an optimization affecting indexed addressing
210 modes. When the offset expression in an indexed mode evaluates to zero but is
211 not explicity written as 0, this will replace the operand with the equivalent
212 no offset mode, thus creating slightly faster code. Because of the advantages
213 of this optimization, it is enabled by default.</P
214 ></DD
215 ><DT
216 >cescapes</DT
217 ><DD
218 ><P
219 >This pragma will cause strings in the FCC, FCS, and FCN pseudo operations to
220 have C-style escape sequences interpreted. The one departure from the official
221 spec is that unrecognized escape sequences will return either the character
222 immediately following the backslash or some undefined value. Do not rely
223 on the behaviour of undefined escape sequences.</P
224 ></DD
225 ><DT
226 >importundefexport</DT
227 ><DD
228 ><P
229 >This pragma is only valid for targets that support external references. When
230 in force, it will cause the EXPORT directive to act as IMPORT if the symbol
231 to be exported is not defined. This is provided for compatibility with the
232 output of gcc6809 and should not be used in hand written code. Because of
233 the confusion this pragma can cause, it is disabled by default.</P
234 ></DD
235 ><DT
236 >undefextern</DT
237 ><DD
238 ><P
239 >This pragma is only valid for targets that support external references. When in
240 force, if the assembler sees an undefined symbol on the second pass, it will
241 automatically define it as an external symbol. This automatic definition will
242 apply for the remainder of the assembly process, even if the pragma is
243 subsequently turned off. Because this behaviour would be potentially surprising,
244 this pragma defaults to off.</P
245 ><P
246 >The primary use for this pragma is for projects that share a large number of
247 symbols between source files. In such cases, it is impractical to enumerate
248 all the external references in every source file. This allows the assembler
249 and linker to do the heavy lifting while not preventing a particular source
250 module from defining a local symbol of the same name as an external symbol
251 if it does not need the external symbol. (This pragma will not cause an
252 automatic external definition if there is already a locally defined symbol.)</P
253 ><P
254 >This pragma will often be specified on the command line for large projects.
255 However, depending on the specific dynamics of the project, it may be sufficient
256 for one or two files to use this pragma internally.</P
257 ></DD
258 ><DT
259 >export</DT
260 ><DD
261 ><P
262 >This pragma causes all symbols to be added to the export list
263 automatically. This is useful when a large number of symbols need to be
264 exported but you do not wish to include an EXPORT directive for all of them.
265 This is often useful on the command line but might be useful even inline
266 with the PRAGMA directive if a large number of symbols in a row are to be
267 exported.</P
268 ></DD
269 ><DT
270 >dollarlocal</DT
271 ><DD
272 ><P
273 >When set, a "$" in a symbol makes it local. When not set, "$" does not
274 cause a symbol to be local. It is set by default except when using the OS9
275 target.</P
276 ></DD
277 ><DT
278 >dollarnotlocal</DT
279 ><DD
280 ><P
281 > This is the same as the "dollarlocal" pragma except its sense is
282 reversed. That is, "dollarlocal" and "nodollarnotlocal" are equivalent and
283 "nodollarlocal" and "dollarnotlocal" are equivalent. </P
284 ></DD
285 ><DT
286 >pcaspcr</DT
287 ><DD
288 ><P
289 > Normally, LWASM makes a distinction between PC and PCR in program
290 counter relative addressing. In particular, the use of PC means an absolute
291 offset from PC while PCR causes the assembler to calculate the offset to the
292 specified operand and use that as the offset from PC. By setting this
293 pragma, you can have PC treated the same as PCR. </P
294 ></DD
295 ><DT
296 >shadow</DT
297 ><DD
298 ><P
299 >When this pragma is in effect, it becomes possible to define a macro
300 that matches an internal operation code. Thus, it makes it possible to
301 redefine either CPU instructions or pseudo operations. Because this feature
302 is of dubious utility, it is disabled by default.</P
303 ></DD
304 ><DT
305 >nolist</DT
306 ><DD
307 ><P
308 >Lines where this pragma is in effect will not appear in the assembly
309 listing. Also, any symbols defined under this pragma will not show up in
310 the symbol list. This is most useful in include files to avoid spamming the
311 assembly listing with dozens, hundreds, or thousands of irrelevant
312 symbols. It is important to note that this pragma will not hide lines that
313 generate output to the binary.</P
314 ></DD
315 ><DT
316 >nolistcode</DT
317 ><DD
318 ><P
319 >Lines where this pragma is in effect will not appear in the assembly
320 listing. Also, any symbols defined under this pragma will not show up in
321 the symbol list. This is most useful in include files to avoid spamming the
322 assembly listing with dozens, hundreds, or thousands of irrelevant
323 symbols. Unlike "nolist", this pragma will hide lines that generate output
324 to the binary.</P
325 ></DD
326 ><DT
327 >autobranchlength</DT
328 ><DD
329 ><P
330 >One of the perennial annoyances for 6809 programmers is that the
331 mneumonics for the short and long branch instructions are different (bxx vs.
332 lbxx), which is at odds with the rest of the instruction set. This pragma
333 is a solution to those annoying byte overflow errors that short branch
334 instructions tend to aquire.</P
335 ><P
336 >When this pragma is in effect, which is not the default, whenever any
337 relative branch instruction is used, its size will be automatically
338 determined based on the actual distance to the destination. In other words,
339 one can write code with long or short branches everywhere and the assembler
340 will choose a size for the branch.</P
341 ><P
342 >Also, while this pragma is in effect, the &#62; and &#60; symbols can be used
343 to force the branch size, analogous to their use for other instructions with
344 &#60; forcing 8 bit offsets and &#62; forcing 16 bit offets.</P
345 ><P
346 >Because this pragma leads to source that is incompatible with other
347 assemblers, it is strongly recommended that it be invoked using the PRAGMA
348 directive within the source code rather than on the command line or via the
349 *PRAGMA directive. This way, an error will be raised if someone tries to
350 assemble the code under a different assembler.</P
351 ><P
352 >Note that if the "forwardrefmax" pragma is ineffect, as is the current
353 default, this pragma will not behave as expected.</P
354 ></DD
355 ><DT
356 >nosymbolcase, symbolnocase</DT
357 ><DD
358 ><P
359 >Any symbol defined while this pragma is in force will be treated as
360 case insensitive, regardless whether the pragma is in force when the symbol
361 is referenced.</P
362 ><P
363 >It is important to note that this pragma will not work as expected in
364 all cases when using the object file assembly target. It is intended for
365 use only when the assembler will be producing the final binary.</P
366 ></DD
367 ><DT
368 >condundefzero</DT
369 ><DD
370 ><P
371 >This pragma will cause the assembler to change the way it handles
372 symbols in conditional expressions. Ordinarily, any symbol that is not
373 defined prior to the conditional will throw an undefined symbol error. With
374 this pragma in effect, symbols that are not yet defined at the point the
375 conditional is encountered will be treated as zero.</P
376 ><P
377 >This is not the default because it encourages poor code design. One
378 should use the "IFDEF" or "IFNDEF" conditionals to test for the presence of
379 a symbol.</P
380 ><P
381 >It is important to note that if a symbol is defined but it does not
382 yet evaluate to a constant value at the point where the conditional appears,
383 the assembler will still complain about a non constant condition.</P
384 ></DD
385 ><DT
386 >forwardrefmax</DT
387 ><DD
388 ><P
389 >This pragma will disable forward reference optimization completely.
390 However, many source files, especially
391 those not using the PCR relative addressing modes, this optimization is
392 pointless since the assembler will almost certainly settle on a 16 bit
393 offset or address. If all variables in the direct page are defined before
394 the main body of the code, the benefit of forward reference optimization
395 almost certainly vanishes completely. However, the cost of doing that
396 optimization remains and can result in a very long assembly time. Because
397 of this, "forwardrefmax" has been the default setting since version 4.14 of
398 LWTOOLS. To turn it off, use "noforwardrefmax".</P
399 ><P
400 >Enabling this pragma will cause all forward references to use the
401 maximum offset or address size, much the same has EDTASM and other pure
402 two pass assemblers do. The side effect is that all line lengths and
403 symbol values are fully resolved after the initial parsing pass and the
404 amount of work to resolve everything becomes almost nil.</P
405 ><P
406 >While this pragma can be applied selectively to sections of source
407 code (use *PRAGMA if doing so and compatibility with other assemblers
408 is desired), it is likely more useful when provided as a command line
409 pragma.</P
410 ><P
411 >It should be noted that the presence or absence of this pragma
412 will not change the correctness of the generated code unless cycle counts
413 or byte counts are critical (which they usually are not). It also will
414 not override the operand size override prefixes (&lt; and &gt;). It only
415 applies when the assembler is left to guess what the operand size is.</P
416 ></DD
417 ><DT
418 >operandsizewarning</DT
419 ><DD
420 ><P
421 >Enabling this pragma will cause LWASM to show a warning when it
422 detects that a smaller addressing mode could be used for an instruction.
423 This is particularly useful for finding places where long branches are used
424 where short branches could be used instead. It will also show the warnings
425 for indexing offsets (regardless of whether the operand size is
426 forced).</P
427 ><P
428 >As of LWASM 4.16, no other checks are performed.</P
429 ></DD
430 ><DT
431 >qrts</DT
432 ><DD
433 ><P
434 >&#13;Enables the use of the ?RTS branch target. ?RTS is implemented to maintain
435 compatibility with the MACRO-80c assembler. It works by searching backward
436 in the code for an RTS instruction. If none is found, it inverts the branch
437 logic and inserts an RTS following the branch instruction. Below you can
438 see how a BMI (2B xx) has been assembled as a BPL *+1 (2A 01) to skip over an
439 inserted RTS (39).</P
440 ><PRE
441 CLASS="PROGRAMLISTING"
442 >1D1E 7D1D1D TST WHICH1
443 1D21 2A0139 BMI ?RTS
444 1D24 BD1D65 JSR INV</PRE
445 ></DD
446 ><DT
447 >m80ext</DT
448 ><DD
449 ><P
450 >&#13;This pragma (along with pragma qrts) enables some uncommon behaviors to
451 accomodate The Micro Works MACRO-80c assembler from 1982. This assembler
452 was used by a number of notable TRS-80 Color Computer applications and the
453 goal of this pragma is to allow them to build identical binaries from
454 unmodified, vintage source code.</P
455 ><P
456 >&#13;In m80ext mode, the handling of the "END" pseudo-op changes when used inside
457 an include file. Instead of terminating all assembly, it merely stops
458 processing of the current include file (this behavior matches the original
459 Motorola 6809 assembler). In addition, loading an ASCII value with a single
460 quote (e.g., LDA #'N) is extended to 16-bit registers (e.g., LDD #'NO).
461 LWASM normally supports this via double quote and that is the proper use in
462 modern code. Finally, the FCC pseudo-op is extended to handle FCB-like
463 behavior after the closing delimiter:</P
464 ><PRE
465 CLASS="PROGRAMLISTING"
466 > FCC "Greetings from 1982",13,0</PRE
467 ></DD
468 ><DT
469 >testmode</DT
470 ><DD
471 ><P
472 >&#13;This pragma is intended for internal testing purposes. In testmode, the
473 assembler searches for a specially-formatted comment starting with a
474 semicolon followed by a period. Immediately afterward are a list of hex
475 bytes that the assembler is expected to generate. Likewise, if the
476 assembler is expected to throw an error or warning on a given line, you can
477 check by specifying "E:" followed by the error number. In this case the
478 error is ignored and the assembler continues ignoring the line in question.&#13;</P
479 ><PRE
480 CLASS="PROGRAMLISTING"
481 >1D1E 7D1D1D TST WHICH1 ;.7d1d1d
482 1D21 2A0139 BMI ?RTS ;.2a0139
483 1D24 1D24 FDB * ;.1d24
484 1D26 xyz INV ;.E:32 (Error 32 is "Bad opcode")</PRE
485 ></DD
486 ><DT
487 >emuext</DT
488 ><DD
489 ><P
490 >&#13;This pragma enables two instructions useful when running code in compatible
491 emulators. Break breaks into the debugger. Log writes printf-style
492 output to the debug window&#13;</P
493 ><PRE
494 CLASS="PROGRAMLISTING"
495 > LOG ; log output
496 FDB FSTR ; pointer to format string
497 FDB PX1 ; 16 bit pointer to 16 bit value
498 FDB PY1 ; 16 bit pointer to 8 bit value (see format string!)
499 FDB PX2 ; 16 bit pointer to 16 bit value
500 FDB PY2 ; 16 bit pointer to 8 bit value
501 ; execution continues here ...
502 RTS
503
504 ; format string
505 FSTR FCC "%hu,%hhu - %hu,%hhu"
506 FCB 10,0</PRE
507 ></DD
508 ></DL
509 ></DIV
510 ><P
511 >As a convenience, each input file has a pragma state stack. This
512 allows, through the use of *PRAGMAPUSH and *PRAGMAPOP, a file to change a
513 pragma state and then restore it to the precise state it had previously.
514 If, at the end of an input file, all pragma states have not been popped,
515 they will be removed from the stack. Thus, it is critical to employ
516 *PRAGMAPOP correctly. Because each input file has its own pragma stack,
517 using *PRAGMAPUSH in one file and *PRAGMAPOP in another file will not
518 work.</P
519 ><P
520 >Pragma stacks are more useful in include files, in particular in
521 conjunction with the nolist pragma. One can push the state of the nolist
522 pragma, engage the nolist pragma, and then pop the state of the nolist
523 pragma at the end of the include file. This will cause the entire include
524 file to operate under the nolist pragma. However, if the file is included
525 while nolist is already engaged, it will not undo that state.</P
526 ></DIV
527 ><DIV
528 CLASS="NAVFOOTER"
529 ><HR
530 ALIGN="LEFT"
531 WIDTH="100%"><TABLE
532 SUMMARY="Footer navigation table"
533 WIDTH="100%"
534 BORDER="0"
535 CELLPADDING="0"
536 CELLSPACING="0"
537 ><TR
538 ><TD
539 WIDTH="33%"
540 ALIGN="left"
541 VALIGN="top"
542 ><A
543 HREF="x612.html"
544 ACCESSKEY="P"
545 >Prev</A
546 ></TD
547 ><TD
548 WIDTH="34%"
549 ALIGN="center"
550 VALIGN="top"
551 ><A
552 HREF="index.html"
553 ACCESSKEY="H"
554 >Home</A
555 ></TD
556 ><TD
557 WIDTH="33%"
558 ALIGN="right"
559 VALIGN="top"
560 ><A
561 HREF="x827.html"
562 ACCESSKEY="N"
563 >Next</A
564 ></TD
565 ></TR
566 ><TR
567 ><TD
568 WIDTH="33%"
569 ALIGN="left"
570 VALIGN="top"
571 >Object Files and Sections</TD
572 ><TD
573 WIDTH="34%"
574 ALIGN="center"
575 VALIGN="top"
576 ><A
577 HREF="c62.html"
578 ACCESSKEY="U"
579 >Up</A
580 ></TD
581 ><TD
582 WIDTH="33%"
583 ALIGN="right"
584 VALIGN="top"
585 >Convenience Instructions</TD
586 ></TR
587 ></TABLE
588 ></DIV
589 ></BODY
590 ></HTML
591 >