Mercurial > hg > index.cgi

comparison docs/manual/manual.html.orig @ 455:cad5937314cb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add operandsizewarning pragma Add operandsizewarning pragma that will raise warnings for certain operands if the operand size could be smaller. (Long branch used instead of short branch, for instance.)
author William Astle <lost@l-w.ca>
date Fri, 16 Feb 2018 22:53:46 -0700
parents
children
comparison
equal deleted inserted replaced
454:ffdef8994f13 455:cad5937314cb
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 >LW Tool Chain</TITLE
6 ><META
7 NAME="GENERATOR"
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"></HEAD
9 ><BODY
10 CLASS="BOOK"
11 BGCOLOR="#FFFFFF"
12 TEXT="#000000"
13 LINK="#0000FF"
14 VLINK="#840084"
15 ALINK="#0000FF"
16 ><DIV
17 CLASS="BOOK"
18 ><A
19 NAME="AEN1"
20 ></A
21 ><DIV
22 CLASS="TITLEPAGE"
23 ><H1
24 CLASS="TITLE"
25 ><A
26 NAME="AEN2"
27 >LW Tool Chain</A
28 ></H1
29 ><H3
30 CLASS="AUTHOR"
31 ><A
32 NAME="AEN4"
33 ></A
34 >William Astle</H3
35 ><H3
36 CLASS="AUTHOR"
37 ><A
38 NAME="AEN7"
39 ></A
40 >LWTools Contributors </H3
41 ><P
42 CLASS="COPYRIGHT"
43 >Copyright &copy; 2009-2015 William Astle and LWTools contributors</P
44 ><HR></DIV
45 ><DIV
46 CLASS="TOC"
47 ><DL
48 ><DT
49 ><B
50 >Table of Contents</B
51 ></DT
52 ><DT
53 >1. <A
54 HREF="#AEN13"
55 >Introduction</A
56 ></DT
57 ><DD
58 ><DL
59 ><DT
60 >1.1. <A
61 HREF="#AEN16"
62 >History</A
63 ></DT
64 ></DL
65 ></DD
66 ><DT
67 >2. <A
68 HREF="#AEN21"
69 >Output Formats</A
70 ></DT
71 ><DD
72 ><DL
73 ><DT
74 >2.1. <A
75 HREF="#AEN24"
76 >Raw Binaries</A
77 ></DT
78 ><DT
79 >2.2. <A
80 HREF="#AEN27"
81 >DECB Binaries</A
82 ></DT
83 ><DT
84 >2.3. <A
85 HREF="#AEN32"
86 >ASCII Hexadecimal</A
87 ></DT
88 ><DT
89 >2.4. <A
90 HREF="#AEN36"
91 >Motorola S-Record</A
92 ></DT
93 ><DT
94 >2.5. <A
95 HREF="#AEN41"
96 >Intel Hex</A
97 ></DT
98 ><DT
99 >2.6. <A
100 HREF="#AEN46"
101 >OS9 Modules</A
102 ></DT
103 ><DT
104 >2.7. <A
105 HREF="#AEN54"
106 >Object Files</A
107 ></DT
108 ></DL
109 ></DD
110 ><DT
111 >3. <A
112 HREF="#AEN62"
113 >LWASM</A
114 ></DT
115 ><DD
116 ><DL
117 ><DT
118 >3.1. <A
119 HREF="#AEN65"
120 >Command Line Options</A
121 ></DT
122 ><DT
123 >3.2. <A
124 HREF="#AEN218"
125 >Dialects</A
126 ></DT
127 ><DT
128 >3.3. <A
129 HREF="#AEN227"
130 >Source Format</A
131 ></DT
132 ><DT
133 >3.4. <A
134 HREF="#AEN237"
135 >Symbols</A
136 ></DT
137 ><DT
138 >3.5. <A
139 HREF="#AEN242"
140 >Numbers and Expressions</A
141 ></DT
142 ><DT
143 >3.6. <A
144 HREF="#AEN250"
145 >Assembler Directives</A
146 ></DT
147 ><DD
148 ><DL
149 ><DT
150 >3.6.1. <A
151 HREF="#AEN253"
152 >Data Directives</A
153 ></DT
154 ><DT
155 >3.6.2. <A
156 HREF="#AEN364"
157 >Address Definition</A
158 ></DT
159 ><DT
160 >3.6.3. <A
161 HREF="#AEN415"
162 >Conditional Assembly</A
163 ></DT
164 ><DT
165 >3.6.4. <A
166 HREF="#AEN486"
167 >OS9 Target Directives</A
168 ></DT
169 ><DT
170 >3.6.5. <A
171 HREF="#AEN511"
172 >Miscelaneous Directives</A
173 ></DT
174 ></DL
175 ></DD
176 ><DT
177 >3.7. <A
178 HREF="#AEN551"
179 >Macros</A
180 ></DT
181 ><DT
182 >3.8. <A
183 HREF="#AEN574"
184 >Structures</A
185 ></DT
186 ><DT
187 >3.9. <A
188 HREF="#AEN595"
189 >Object Files and Sections</A
190 ></DT
191 ><DT
192 >3.10. <A
193 HREF="#AEN659"
194 >Assembler Modes and Pragmas</A
195 ></DT
196 ><DT
197 >3.11. <A
198 HREF="#CONVINST"
199 >Convenience Instructions</A
200 ></DT
201 ><DT
202 >3.12. <A
203 HREF="#AEN805"
204 >Cycle Counts</A
205 ></DT
206 ></DL
207 ></DD
208 ><DT
209 >4. <A
210 HREF="#AEN811"
211 >LWLINK</A
212 ></DT
213 ><DD
214 ><DL
215 ><DT
216 >4.1. <A
217 HREF="#AEN814"
218 >Command Line Options</A
219 ></DT
220 ><DT
221 >4.2. <A
222 HREF="#AEN911"
223 >Linker Operation</A
224 ></DT
225 ><DT
226 >4.3. <A
227 HREF="#AEN925"
228 >Linking Scripts</A
229 ></DT
230 ><DT
231 >4.4. <A
232 HREF="#AEN991"
233 >Format Specific Linking Notes</A
234 ></DT
235 ><DD
236 ><DL
237 ><DT
238 >4.4.1. <A
239 HREF="#AEN994"
240 >OS9 Modules</A
241 ></DT
242 ></DL
243 ></DD
244 ></DL
245 ></DD
246 ><DT
247 >5. <A
248 HREF="#AEN1006"
249 >Libraries and LWAR</A
250 ></DT
251 ><DD
252 ><DL
253 ><DT
254 >5.1. <A
255 HREF="#AEN1010"
256 >Command Line Options</A
257 ></DT
258 ></DL
259 ></DD
260 ><DT
261 >6. <A
262 HREF="#OBJCHAP"
263 >Object Files</A
264 ></DT
265 ></DL
266 ></DIV
267 ><DIV
268 CLASS="LOT"
269 ><DL
270 CLASS="LOT"
271 ><DT
272 ><B
273 >List of Tables</B
274 ></DT
275 ><DT
276 >6-1. <A
277 HREF="#AEN1093"
278 >Object File Term Types</A
279 ></DT
280 ><DT
281 >6-2. <A
282 HREF="#AEN1123"
283 >Object File Operator Numbers</A
284 ></DT
285 ></DL
286 ></DIV
287 ><DIV
288 CLASS="CHAPTER"
289 ><HR><H1
290 ><A
291 NAME="AEN13"
292 ></A
293 >Chapter 1. Introduction</H1
294 ><P
295 >The LW tool chain provides utilities for building binaries for MC6809 and
296 HD6309 CPUs. The tool chain includes a cross-assembler and a cross-linker
297 which support several styles of output.</P
298 ><DIV
299 CLASS="SECTION"
300 ><HR><H2
301 CLASS="SECTION"
302 ><A
303 NAME="AEN16"
304 >1.1. History</A
305 ></H2
306 ><P
307 >For a long time, I have had an interest in creating an operating system for
308 the Coco3. I finally started working on that project around the beginning of
309 2006. I had a number of assemblers I could choose from. Eventually, I settled
310 on one and started tinkering. After a while, I realized that assembler was not
311 going to be sufficient due to lack of macros and issues with forward references.
312 Then I tried another which handled forward references correctly but still did
313 not support macros. I looked around at other assemblers and they all lacked
314 one feature or another that I really wanted for creating my operating system.</P
315 ><P
316 >The solution seemed clear at that point. I am a fair programmer so I figured
317 I could write an assembler that would do everything I wanted an assembler to
318 do. Thus the LWASM probject was born. After more than two years of on and off
319 work, version 1.0 of LWASM was released in October of 2008.</P
320 ><P
321 >As the aforementioned operating system project progressed further, it became
322 clear that while assembling the whole project through a single file was doable,
323 it was not practical. When I found myself playing some fancy games with macros
324 in a bid to simulate sections, I realized I needed a means of assembling
325 source files separately and linking them later. This spawned a major development
326 effort to add an object file support to LWASM. It also spawned the LWLINK
327 project to provide a means to actually link the files.</P
328 ></DIV
329 ></DIV
330 ><DIV
331 CLASS="CHAPTER"
332 ><HR><H1
333 ><A
334 NAME="AEN21"
335 ></A
336 >Chapter 2. Output Formats</H1
337 ><P
338 >The LW tool chain supports multiple output formats. Each format has its
339 advantages and disadvantages. Each format is described below.</P
340 ><DIV
341 CLASS="SECTION"
342 ><HR><H2
343 CLASS="SECTION"
344 ><A
345 NAME="AEN24"
346 >2.1. Raw Binaries</A
347 ></H2
348 ><P
349 >A raw binary is simply a string of bytes. There are no headers or other
350 niceties. Both LWLINK and LWASM support generating raw binaries. ORG directives
351 in the source code only serve to set the addresses that will be used for
352 symbols but otherwise have no direct impact on the resulting binary.</P
353 ></DIV
354 ><DIV
355 CLASS="SECTION"
356 ><HR><H2
357 CLASS="SECTION"
358 ><A
359 NAME="AEN27"
360 >2.2. DECB Binaries</A
361 ></H2
362 ><P
363 >A DECB binary is compatible with the LOADM command in Disk Extended
364 Color Basic on the CoCo. They are also compatible with CLOADM from Extended
365 Color Basic. These binaries include the load address of the binary as well
366 as encoding an execution address. These binaries may contain multiple loadable
367 sections, each of which has its own load address.</P
368 ><P
369 >Each binary starts with a preamble. Each preamble is five bytes long. The
370 first byte is zero. The next two bytes specify the number of bytes to load
371 and the last two bytes specify the address to load the bytes at. Then, a
372 string of bytes follows. After this string of bytes, there may be another
373 preamble or a postamble. A postamble is also five bytes in length. The first
374 byte of the postamble is $FF, the next two are zero, and the last two are
375 the execution address for the binary.</P
376 ><P
377 >Both LWASM and LWLINK can output this format.</P
378 ></DIV
379 ><DIV
380 CLASS="SECTION"
381 ><HR><H2
382 CLASS="SECTION"
383 ><A
384 NAME="AEN32"
385 >2.3. ASCII Hexadecimal</A
386 ></H2
387 ><P
388 >This human-readable ASCII hexadecimal format consists of CR+LF terminated
389 lines of ASCII text. Each line has the following structure: a zero-padded
390 four-digit ASCII hex address, a colon separator, and one or more zero-padded
391 two-digit hex values separated by commas. ASCII Hexadecimal format favors
392 paragraph-aligned addresses (i.e. a least significant address nybble value
393 of zero). During output, the number of hex values on each line are adjusted
394 to align the address of the next line on a paragraph boundary. The sequence
395 of addresses in the ASCII Hexadecimal file directly follows that of the source
396 file; multiple ORG directives in the source code may result in out-of-sequence
397 addresses in the ASCII Hexadecimal output.</P
398 ><P
399 >LWASM can output this format since version 4.10.</P
400 ></DIV
401 ><DIV
402 CLASS="SECTION"
403 ><HR><H2
404 CLASS="SECTION"
405 ><A
406 NAME="AEN36"
407 >2.4. Motorola S-Record</A
408 ></H2
409 ><P
410 >This ASCII format consists of a series of CR+LF terminated "records" of ASCII
411 text. Each record has the following structure: a start-of-record character
412 "S", an ASCII record type digit (0-9), a two-digit ASCII hex byte count, a
413 four-digit ASCII hex address, an optional sequence of two-digit ASCII hex data
414 values, and a two-digit ASCII hex checksum. The LW tool chain issues only S0,
415 S1, S5 and S9 record types. S1 records are limited to maximum of 16 data bytes
416 in length, and paragraph alignment of addresses is favored. The address
417 sequence of the S-Records directly follows that of the source file; multiple
418 ORG directives in the source code may result in out-of-sequence addresses in
419 the S-Record output. </P
420 ><P
421 >Motorola S-Record format is a standard ASCII format accepted by most memory
422 device programming equipment. It is particularly useful when the assembled
423 code output is destined to reside within an EPROM or Flash memory device,
424 for example.</P
425 ><P
426 >LWASM can output this format since version 4.10. LWLINK can output this format
427 since version 4.11.</P
428 ></DIV
429 ><DIV
430 CLASS="SECTION"
431 ><HR><H2
432 CLASS="SECTION"
433 ><A
434 NAME="AEN41"
435 >2.5. Intel Hex</A
436 ></H2
437 ><P
438 >This ASCII format consists of a series of CR+LF terminated "records" of ASCII
439 text. Each record has the following structure: a start-of-record character
440 ":", a two-digit ASCII hex byte count, a four-digit ASCII hex address, a two-
441 digit ASCII hex record type, an optional sequence of two-digit ASCII hex data
442 values, and a two-digit ASCII hex checksum. The LW tool chain issues only 00,
443 and 01 Intel Hex record types. Data records are limited to maximum of 16
444 data bytes in length, and paragraph alignment of addresses is favored. The
445 address sequence of the Intel hex records directly follows that of the source
446 file; multiple ORG directives in the source code may result in out-of-sequence
447 addresses in the Intel Hex output. </P
448 ><P
449 >Intel Hex format is the other standard ASCII format accepted by most memory
450 device programming equipment, it and the Motorola S-Record format are used for
451 similar purposes.</P
452 ><P
453 >LWASM can output this format since version 4.10.</P
454 ></DIV
455 ><DIV
456 CLASS="SECTION"
457 ><HR><H2
458 CLASS="SECTION"
459 ><A
460 NAME="AEN46"
461 >2.6. OS9 Modules</A
462 ></H2
463 ><P
464 >&#13;Since version 2.5, LWASM is able to generate OS9 modules. The syntax is
465 basically the same as for other assemblers. A module starts with the MOD
466 directive and ends with the EMOD directive. The OS9 directive is provided
467 as a shortcut for writing system calls.&#13;</P
468 ><P
469 >&#13;LWASM does NOT provide an OS9Defs file. You must provide your own. Also note
470 that the common practice of using "ifp1" around the inclusion of the OS9Defs
471 file is discouraged as it is pointless and can lead to unintentional
472 problems and phasing errors. Because LWASM reads each file exactly once,
473 there is no benefit to restricting the inclusion to the first assembly pass.&#13;</P
474 ><P
475 >&#13;As of version 4.5, LWASM also implements the standard data/code address
476 streams for OS9 modules. That means that between MOD and EMOD, any RMB,
477 RMD, RMQ, or equivalent directives will move the data address ahead and
478 leave the code address unmodified. Outside of an actual module, both the
479 code and data addresses are moved ahead equally. That last bit is critical
480 to understand because it means any directives that follow an EMOD directive
481 may have different results than other assemblers.&#13;</P
482 ><P
483 >&#13;Additionally, within a module body, the ORG directive sets only the data
484 address, not the code address. However, outside a module body, ORG sets both
485 addresses.&#13;</P
486 ><P
487 >Both code and data addresses are reset to 0 by the MOD directive.</P
488 ><P
489 >&#13;As of version 4.5, LWLINK also supports creation of OS9 modules.&#13;</P
490 ></DIV
491 ><DIV
492 CLASS="SECTION"
493 ><HR><H2
494 CLASS="SECTION"
495 ><A
496 NAME="AEN54"
497 >2.7. Object Files</A
498 ></H2
499 ><P
500 >LWASM supports generating a proprietary object file format which is
501 described in <A
502 HREF="#OBJCHAP"
503 >Chapter 6</A
504 >. LWLINK is then used to link these
505 object files into a final binary in any of LWLINK's supported binary
506 formats.</P
507 ><P
508 >Object files also support the concept of sections which are not valid
509 for other output types. This allows related code from each object file
510 linked to be collapsed together in the final binary.</P
511 ><P
512 >Object files are very flexible in that they allow references that are not
513 known at assembly time to be resolved at link time. However, because the
514 addresses of such references are not known at assembly time, there is no way
515 for the assembler to deduce that an eight bit addressing mode is possible.
516 That means the assember will default to using sixteen bit addressing
517 whenever an external or cross-section reference is used.</P
518 ><P
519 >As of LWASM 2.4, it is possible to force direct page addressing for an
520 external reference. Care must be taken to ensure the resulting addresses
521 are really in the direct page since the linker does not know what the direct
522 page is supposed to be and does not emit errors for byte overflows.</P
523 ><P
524 >It is also possible to use external references in an eight bit immediate
525 mode instruction. In this case, only the low order eight bits will be used.
526 Again, no byte overflows will be flagged.</P
527 ></DIV
528 ></DIV
529 ><DIV
530 CLASS="CHAPTER"
531 ><HR><H1
532 ><A
533 NAME="AEN62"
534 ></A
535 >Chapter 3. LWASM</H1
536 ><P
537 >The LWTOOLS assembler is called LWASM. This chapter documents the various
538 features of the assembler. It is not, however, a tutorial on 6x09 assembly
539 language programming.</P
540 ><DIV
541 CLASS="SECTION"
542 ><HR><H2
543 CLASS="SECTION"
544 ><A
545 NAME="AEN65"
546 >3.1. Command Line Options</A
547 ></H2
548 ><P
549 >The binary for LWASM is called "lwasm". Note that the binary is in lower
550 case. lwasm takes the following command line arguments.</P
551 ><P
552 ></P
553 ><DIV
554 CLASS="VARIABLELIST"
555 ><DL
556 ><DT
557 ><CODE
558 CLASS="OPTION"
559 >--6309</CODE
560 >, <CODE
561 CLASS="OPTION"
562 >-3</CODE
563 ></DT
564 ><DD
565 ><P
566 >This will cause the assembler to accept the additional instructions available
567 on the 6309 processor. This is the default mode; this option is provided for
568 completeness and to override preset command arguments.</P
569 ><P
570 >This option is the same as if the first line of the source code is "PRAGMA 6309".</P
571 ></DD
572 ><DT
573 ><CODE
574 CLASS="OPTION"
575 >--6800compat</CODE
576 ></DT
577 ><DD
578 ><P
579 >This is equivalent to <CODE
580 CLASS="OPTION"
581 >--pragma=6800compat</CODE
582 >.</P
583 ><P
584 >This will enable recognition of 6800 compatibility instructions.</P
585 ></DD
586 ><DT
587 ><CODE
588 CLASS="OPTION"
589 >--6809</CODE
590 >, <CODE
591 CLASS="OPTION"
592 >-9</CODE
593 ></DT
594 ><DD
595 ><P
596 >This will cause the assembler to reject instructions that are only available
597 on the 6309 processor. This actually has the effect of starting the assembler
598 as though the first line of the source is "PRAGMA 6809".</P
599 ></DD
600 ><DT
601 ><CODE
602 CLASS="OPTION"
603 >--decb</CODE
604 >, <CODE
605 CLASS="OPTION"
606 >-b</CODE
607 ></DT
608 ><DD
609 ><P
610 >Select the DECB output format target. Equivalent to <CODE
611 CLASS="OPTION"
612 >--format=decb</CODE
613 >.</P
614 ><P
615 >While this is the default output format currently, it is not safe to rely
616 on that fact. Future versions may have different defaults. It is also trivial
617 to modify the source code to change the default. Thus, it is recommended to specify
618 this option if you need DECB output.</P
619 ></DD
620 ><DT
621 ><CODE
622 CLASS="OPTION"
623 >--format=type</CODE
624 >, <CODE
625 CLASS="OPTION"
626 >-f type</CODE
627 ></DT
628 ><DD
629 ><P
630 >Select the output format. Valid values are <CODE
631 CLASS="OPTION"
632 >obj</CODE
633 > for the
634 object file target, <CODE
635 CLASS="OPTION"
636 >decb</CODE
637 > for the DECB LOADM format,
638 <CODE
639 CLASS="OPTION"
640 >os9</CODE
641 > for creating OS9 modules, <CODE
642 CLASS="OPTION"
643 >raw</CODE
644 > for
645 a raw binary, <CODE
646 CLASS="OPTION"
647 >hex</CODE
648 > for ASCII hexadecminal format,
649 <CODE
650 CLASS="OPTION"
651 >srec</CODE
652 > for Motorola S-Record format, and <CODE
653 CLASS="OPTION"
654 >ihex</CODE
655 >
656 for Intel Hex format.</P
657 ></DD
658 ><DT
659 ><CODE
660 CLASS="OPTION"
661 >--list[=file]</CODE
662 >, <CODE
663 CLASS="OPTION"
664 >-l[file]</CODE
665 ></DT
666 ><DD
667 ><P
668 >Cause LWASM to generate a listing. If <CODE
669 CLASS="OPTION"
670 >file</CODE
671 > is specified,
672 the listing will go to that file. Otherwise it will go to the standard output
673 stream. By default, no listing is generated. Unless <CODE
674 CLASS="OPTION"
675 >--symbols</CODE
676 >
677 is specified, the list will not include the symbol table.</P
678 ></DD
679 ><DT
680 ><CODE
681 CLASS="OPTION"
682 >--symbols</CODE
683 >, <CODE
684 CLASS="OPTION"
685 >-s</CODE
686 ></DT
687 ><DD
688 ><P
689 >Causes LWASM to generate a list of symbols when generating a listing.
690 It has no effect unless a listing is being generated.</P
691 ></DD
692 ><DT
693 ><CODE
694 CLASS="OPTION"
695 >--symbols-nolocals</CODE
696 ></DT
697 ><DD
698 ><P
699 >Behaves just like <CODE
700 CLASS="OPTION"
701 >--symbols</CODE
702 > but with local labels omitted.</P
703 ></DD
704 ><DT
705 ><CODE
706 CLASS="OPTION"
707 >--map=FILE</CODE
708 ></DT
709 ><DD
710 ><P
711 >&#13;This option generates a map file which can be used by debuggers and monitors to provide symbol information. A map file may be created independent of a listing file. (Patches are pending for MAME and exec09.)&#13;</P
712 ></DD
713 ><DT
714 ><CODE
715 CLASS="OPTION"
716 >--obj</CODE
717 ></DT
718 ><DD
719 ><P
720 >Select the proprietary object file format as the output target.</P
721 ></DD
722 ><DT
723 ><CODE
724 CLASS="OPTION"
725 >--output=FILE</CODE
726 >, <CODE
727 CLASS="OPTION"
728 >-o FILE</CODE
729 ></DT
730 ><DD
731 ><P
732 >This option specifies the name of the output file. If not specified, the
733 default is <CODE
734 CLASS="OPTION"
735 >a.out</CODE
736 >.</P
737 ></DD
738 ><DT
739 ><CODE
740 CLASS="OPTION"
741 >--pragma=pragma</CODE
742 >, <CODE
743 CLASS="OPTION"
744 >-p pragma</CODE
745 ></DT
746 ><DD
747 ><P
748 >Specify assembler pragmas. Multiple pragmas are separated by commas. The
749 pragmas accepted are the same as for the PRAGMA assembler directive described
750 below.</P
751 ></DD
752 ><DT
753 ><CODE
754 CLASS="OPTION"
755 >--raw</CODE
756 >, <CODE
757 CLASS="OPTION"
758 >-r</CODE
759 ></DT
760 ><DD
761 ><P
762 >Select raw binary as the output target.</P
763 ></DD
764 ><DT
765 ><CODE
766 CLASS="OPTION"
767 >--includedir=path</CODE
768 >, <CODE
769 CLASS="OPTION"
770 >-I path</CODE
771 ></DT
772 ><DD
773 ><P
774 >Add <CODE
775 CLASS="OPTION"
776 >path</CODE
777 > to the end of the include path.</P
778 ></DD
779 ><DT
780 ><CODE
781 CLASS="OPTION"
782 >--define=SYM[=VAL]</CODE
783 >, <CODE
784 CLASS="OPTION"
785 >-D SYM[=VAL]</CODE
786 ></DT
787 ><DD
788 ><P
789 >Pre-defines the symbol SYM as either the specified VAL. If VAL is omitted,
790 the symbol is defined as 1. The symbol will be defined as though it were
791 defined using the SET directive in the assembly source. That means it can
792 be overridden by a SET directive within the source code. Attempting to
793 redefine SYM using EQU will result in a multiply defined symbol error.</P
794 ></DD
795 ><DT
796 ><CODE
797 CLASS="OPTION"
798 >-t WIDTH</CODE
799 >, <CODE
800 CLASS="OPTION"
801 >--tabs=WIDTH</CODE
802 ></DT
803 ><DD
804 ><P
805 >Specifies the handling of tabs in listing files. <CODE
806 CLASS="OPTION"
807 >--tabs=0</CODE
808 >
809 disables tab expansion. <CODE
810 CLASS="OPTION"
811 >--tabs=8</CODE
812 > is the default setting.</P
813 ></DD
814 ><DT
815 ><CODE
816 CLASS="OPTION"
817 >--help</CODE
818 >, <CODE
819 CLASS="OPTION"
820 >-?</CODE
821 ></DT
822 ><DD
823 ><P
824 >Present a help screen describing the command line options.</P
825 ></DD
826 ><DT
827 ><CODE
828 CLASS="OPTION"
829 >--usage</CODE
830 ></DT
831 ><DD
832 ><P
833 >Provide a summary of the command line options.</P
834 ></DD
835 ><DT
836 ><CODE
837 CLASS="OPTION"
838 >--version</CODE
839 >, <CODE
840 CLASS="OPTION"
841 >-V</CODE
842 ></DT
843 ><DD
844 ><P
845 >Display the software version.</P
846 ></DD
847 ><DT
848 ><CODE
849 CLASS="OPTION"
850 >--debug</CODE
851 >, <CODE
852 CLASS="OPTION"
853 >-d</CODE
854 ></DT
855 ><DD
856 ><P
857 >Increase the debugging level. Only really useful to people hacking on the
858 LWASM source code itself.</P
859 ></DD
860 ></DL
861 ></DIV
862 ></DIV
863 ><DIV
864 CLASS="SECTION"
865 ><HR><H2
866 CLASS="SECTION"
867 ><A
868 NAME="AEN218"
869 >3.2. Dialects</A
870 ></H2
871 ><P
872 > LWASM supports all documented MC6809 instructions as defined by
873 Motorola. By default, this does not include any MC6800 compatibility
874 instructions. As of LWASM 4.11, those compatibility instructions can be
875 enabled using the <CODE
876 CLASS="PARAMETER"
877 >--6800compat</CODE
878 > option or the
879 <CODE
880 CLASS="PARAMETER"
881 >6800compat</CODE
882 > pragma. It also supports all known HD6309
883 instructions. While there is general agreement on the pneumonics for most
884 of the 6309 instructions, there is some variance with the block transfer
885 instructions. TFM for all four variations seems to have gained the most
886 traction and, thus, this is the form that is recommended for LWASM.
887 However, it also supports COPY, COPY-, IMP, EXP, TFRP, TFRM, TFRS, and TFRR.
888 It further adds COPY+ as a synomym for COPY, IMPLODE for IMP, and EXPAND for
889 EXP. </P
890 ><P
891 >By default, LWASM accepts 6309 instructions. However, using the
892 <CODE
893 CLASS="PARAMETER"
894 >--6809</CODE
895 > parameter, you can cause it to throw errors on
896 6309 instructions instead.</P
897 ><P
898 >The standard addressing mode specifiers are supported. These are the
899 hash sign ("#") for immediate mode, the less than sign ("&lt;") for forced
900 eight bit modes, and the greater than sign ("&gt;") for forced sixteen bit modes.</P
901 ><P
902 >Additionally, LWASM supports using the asterisk ("*") to indicate
903 base page addressing. This should not be used in hand-written source code,
904 however, because it is non-standard and may or may not be present in future
905 versions of LWASM.</P
906 ></DIV
907 ><DIV
908 CLASS="SECTION"
909 ><HR><H2
910 CLASS="SECTION"
911 ><A
912 NAME="AEN227"
913 >3.3. Source Format</A
914 ></H2
915 ><P
916 >LWASM accepts plain text files in a relatively free form. It can handle
917 lines terminated with CR, LF, CRLF, or LFCR which means it should be able
918 to assemble files on any platform on which it compiles.</P
919 ><P
920 >Each line may start with a symbol. If a symbol is present, there must not
921 be any whitespace preceding it. It is legal for a line to contain nothing
922 but a symbol.</P
923 ><P
924 >The op code is separated from the symbol by whitespace. If there is
925 no symbol, there must be at least one white space character preceding it.
926 If applicable, the operand follows separated by whitespace. Following the
927 opcode and operand is an optional comment.</P
928 ><P
929 > It is important to note that operands cannot contain any whitespace
930 except in the case of delimited strings. This is because the first
931 whitespace character will be interpreted as the separator between the
932 operand column and the comment. This behaviour is required for approximate
933 source compatibility with other 6x09 assemblers. </P
934 ><P
935 >A comment can also be introduced with a * or a ;. The comment character is
936 optional for end of statement comments. However, if a symbol is the only
937 thing present on the line other than the comment, the comment character is
938 mandatory to prevent the assembler from interpreting the comment as an opcode.</P
939 ><P
940 >For compatibility with the output generated by some C preprocessors, LWASM
941 will also ignore lines that begin with a #. This should not be used as a general
942 comment character, however.</P
943 ><P
944 >The opcode is not treated case sensitively. Neither are register names in
945 the operand fields. Symbols, however, are case sensitive.</P
946 ><P
947 > As of version 2.6, LWASM supports files with line numbers. If line
948 numbers are present, the line must start with a digit. The line number
949 itself must consist only of digits. The line number must then be followed
950 by either the end of the line or exactly one white space character. After
951 that white space character, the lines are interpreted exactly as above. </P
952 ></DIV
953 ><DIV
954 CLASS="SECTION"
955 ><HR><H2
956 CLASS="SECTION"
957 ><A
958 NAME="AEN237"
959 >3.4. Symbols</A
960 ></H2
961 ><P
962 >Symbols have no length restriction. They may contain letters, numbers, dots,
963 dollar signs, and underscores. They must start with a letter, dot, or
964 underscore.</P
965 ><P
966 >LWASM also supports the concept of a local symbol. A local symbol is one
967 which contains either a "?" or a "@", which can appear anywhere in the symbol.
968 The scope of a local symbol is determined by a number of factors. First,
969 each included file gets its own local symbol scope. A blank line will also
970 be considered a local scope barrier. Macros each have their own local symbol
971 scope as well (which has a side effect that you cannot use a local symbol
972 as an argument to a macro). There are other factors as well. In general,
973 a local symbol is restricted to the block of code it is defined within.</P
974 ><P
975 >By default, unless assembling to the os9 target, a "$" in the symbol will
976 also make it local. This can be controlled by the "dollarlocal" and
977 "nodollarlocal" pragmas. In the absence of a pragma to the contrary, for
978 the os9 target, a "$" in the symbol will not make it considered local while
979 for all other targets it will.</P
980 ></DIV
981 ><DIV
982 CLASS="SECTION"
983 ><HR><H2
984 CLASS="SECTION"
985 ><A
986 NAME="AEN242"
987 >3.5. Numbers and Expressions</A
988 ></H2
989 ><P
990 >&#13;Numbers can be expressed in binary, octal, decimal, or hexadecimal. Binary
991 numbers may be prefixed with a "%" symbol or suffixed with a "b" or "B".
992 Octal numbers may be prefixed with "@" or suffixed with "Q", "q", "O", or
993 "o". Hexadecimal numbers may be prefixed with "$", "0x" or "0X", or suffixed
994 with "H". No prefix or suffix is required for decimal numbers but they can
995 be prefixed with "&amp;" if desired. Any constant which begins with a letter
996 must be expressed with the correct prefix base identifier or be prefixed
997 with a 0. Thus hexadecimal FF would have to be written either 0FFH or $FF.
998 Numbers are not case sensitive.&#13;</P
999 ><P
1000 > A symbol may appear at any point where a number is acceptable. The
1001 special symbol "*" can be used to represent the starting address of the
1002 current source line within expressions. </P
1003 ><P
1004 >The ASCII value of a character can be included by prefixing it with a
1005 single quote ('). The ASCII values of two characters can be included by
1006 prefixing the characters with a quote (").</P
1007 ><P
1008 >&#13;LWASM supports the following basic binary operators: +, -, *, /, and %.
1009 These represent addition, subtraction, multiplication, division, and
1010 modulus. It also supports unary negation and unary 1's complement (- and ^
1011 respectively). It is also possible to use ~ for the unary 1's complement
1012 operator. For completeness, a unary positive (+) is supported though it is
1013 a no-op. LWASM also supports using |, &#38;, and ^ for bitwise or, bitwise and,
1014 and bitwise exclusive or respectively.&#13;</P
1015 ><P
1016 >&#13;Operator precedence follows the usual rules. Multiplication, division, and
1017 modulus take precedence over addition and subtraction. Unary operators take
1018 precedence over binary operators. Bitwise operators are lower precdence
1019 than addition and subtraction. To force a specific order of evaluation,
1020 parentheses can be used in the usual manner.&#13;</P
1021 ><P
1022 >&#13;As of LWASM 2.5, the operators &#38;&#38; and || are recognized for boolean and and
1023 boolean or respectively. They will return either 0 or 1 (false or true).
1024 They have the lowest precedence of all the binary operators.&#13;</P
1025 ></DIV
1026 ><DIV
1027 CLASS="SECTION"
1028 ><HR><H2
1029 CLASS="SECTION"
1030 ><A
1031 NAME="AEN250"
1032 >3.6. Assembler Directives</A
1033 ></H2
1034 ><P
1035 >Various directives can be used to control the behaviour of the
1036 assembler or to include non-code/data in the resulting output. Those directives
1037 that are not described in detail in other sections of this document are
1038 described below.</P
1039 ><DIV
1040 CLASS="SECTION"
1041 ><HR><H3
1042 CLASS="SECTION"
1043 ><A
1044 NAME="AEN253"
1045 >3.6.1. Data Directives</A
1046 ></H3
1047 ><P
1048 ></P
1049 ><DIV
1050 CLASS="VARIABLELIST"
1051 ><DL
1052 ><DT
1053 >FCB <CODE
1054 CLASS="PARAMETER"
1055 >expr[,...]</CODE
1056 >, .DB <CODE
1057 CLASS="PARAMETER"
1058 >expr[,...]</CODE
1059 >, .BYTE <CODE
1060 CLASS="PARAMETER"
1061 >expr[,...]</CODE
1062 ></DT
1063 ><DD
1064 ><P
1065 >Include one or more constant bytes (separated by commas) in the output.</P
1066 ></DD
1067 ><DT
1068 >FDB <CODE
1069 CLASS="PARAMETER"
1070 >expr[,...]</CODE
1071 >, .DW <CODE
1072 CLASS="PARAMETER"
1073 >expr[,...]</CODE
1074 >, .WORD <CODE
1075 CLASS="PARAMETER"
1076 >expr[,...]</CODE
1077 ></DT
1078 ><DD
1079 ><P
1080 >Include one or more words (separated by commas) in the output.</P
1081 ></DD
1082 ><DT
1083 >FQB <CODE
1084 CLASS="PARAMETER"
1085 >expr[,...]</CODE
1086 >, .QUAD <CODE
1087 CLASS="PARAMETER"
1088 >expr[,...]</CODE
1089 >, .4BYTE <CODE
1090 CLASS="PARAMETER"
1091 >expr[,...]</CODE
1092 ></DT
1093 ><DD
1094 ><P
1095 >Include one or more double words (separated by commas) in the output.</P
1096 ></DD
1097 ><DT
1098 >FCC <CODE
1099 CLASS="PARAMETER"
1100 >string</CODE
1101 >, .ASCII <CODE
1102 CLASS="PARAMETER"
1103 >string</CODE
1104 >, .STR <CODE
1105 CLASS="PARAMETER"
1106 >string</CODE
1107 ></DT
1108 ><DD
1109 ><P
1110 >Include a string of text in the output. The first character of the operand
1111 is the delimiter which must appear as the last character and cannot appear
1112 within the string. The string is included with no modifications&#62;</P
1113 ></DD
1114 ><DT
1115 >FCN <CODE
1116 CLASS="PARAMETER"
1117 >string</CODE
1118 >, .ASCIZ <CODE
1119 CLASS="PARAMETER"
1120 >string</CODE
1121 >, .STRZ <CODE
1122 CLASS="PARAMETER"
1123 >string</CODE
1124 ></DT
1125 ><DD
1126 ><P
1127 >Include a NUL terminated string of text in the output. The first character of
1128 the operand is the delimiter which must appear as the last character and
1129 cannot appear within the string. A NUL byte is automatically appended to
1130 the string.</P
1131 ></DD
1132 ><DT
1133 >FCS <CODE
1134 CLASS="PARAMETER"
1135 >string</CODE
1136 >, .ASCIS <CODE
1137 CLASS="PARAMETER"
1138 >string</CODE
1139 >, .STRS <CODE
1140 CLASS="PARAMETER"
1141 >string</CODE
1142 ></DT
1143 ><DD
1144 ><P
1145 >Include a string of text in the output with bit 7 of the final byte set. The
1146 first character of the operand is the delimiter which must appear as the last
1147 character and cannot appear within the string.</P
1148 ></DD
1149 ><DT
1150 >ZMB <CODE
1151 CLASS="PARAMETER"
1152 >expr</CODE
1153 ></DT
1154 ><DD
1155 ><P
1156 >Include a number of NUL bytes in the output. The number must be fully resolvable
1157 during pass 1 of assembly so no forward or external references are permitted.</P
1158 ></DD
1159 ><DT
1160 >ZMD <CODE
1161 CLASS="PARAMETER"
1162 >expr</CODE
1163 ></DT
1164 ><DD
1165 ><P
1166 >Include a number of zero words in the output. The number must be fully
1167 resolvable during pass 1 of assembly so no forward or external references are
1168 permitted.</P
1169 ></DD
1170 ><DT
1171 >ZMQ <CODE
1172 CLASS="PARAMETER"
1173 >expr<CODE
1174 CLASS="PARAMETER"
1175 ></CODE
1176 ></CODE
1177 ></DT
1178 ><DD
1179 ><P
1180 >Include a number of zero double-words in the output. The number must be fully
1181 resolvable during pass 1 of assembly so no forward or external references are
1182 permitted.</P
1183 ></DD
1184 ><DT
1185 >RMB <CODE
1186 CLASS="PARAMETER"
1187 >expr</CODE
1188 >, .BLKB <CODE
1189 CLASS="PARAMETER"
1190 >expr</CODE
1191 >, .DS <CODE
1192 CLASS="PARAMETER"
1193 >expr</CODE
1194 >, .RS <CODE
1195 CLASS="PARAMETER"
1196 >expr</CODE
1197 ></DT
1198 ><DD
1199 ><P
1200 >Reserve a number of bytes in the output. The number must be fully resolvable
1201 during pass 1 of assembly so no forward or external references are permitted.
1202 The value of the bytes is undefined.</P
1203 ></DD
1204 ><DT
1205 >RMD <CODE
1206 CLASS="PARAMETER"
1207 >expr</CODE
1208 ></DT
1209 ><DD
1210 ><P
1211 >Reserve a number of words in the output. The number must be fully
1212 resolvable during pass 1 of assembly so no forward or external references are
1213 permitted. The value of the words is undefined.</P
1214 ></DD
1215 ><DT
1216 >RMQ <CODE
1217 CLASS="PARAMETER"
1218 >expr</CODE
1219 ></DT
1220 ><DD
1221 ><P
1222 >Reserve a number of double-words in the output. The number must be fully
1223 resolvable during pass 1 of assembly so no forward or external references are
1224 permitted. The value of the double-words is undefined.</P
1225 ></DD
1226 ><DT
1227 >INCLUDEBIN <CODE
1228 CLASS="PARAMETER"
1229 >filename</CODE
1230 ></DT
1231 ><DD
1232 ><P
1233 >Treat the contents of <CODE
1234 CLASS="PARAMETER"
1235 >filename</CODE
1236 > as a string of bytes to
1237 be included literally at the current assembly point. This has the same effect
1238 as converting the file contents to a series of FCB statements and including
1239 those at the current assembly point.</P
1240 ><P
1241 > If <CODE
1242 CLASS="PARAMETER"
1243 >filename</CODE
1244 > beings with a /, the file name
1245 will be taken as absolute. Otherwise, the current directory will be
1246 searched followed by the search path in the order specified.</P
1247 ><P
1248 > Please note that absolute path detection including drive letters will
1249 not function correctly on Windows platforms. Non-absolute inclusion will
1250 work, however.</P
1251 ></DD
1252 ><DT
1253 >FILL <CODE
1254 CLASS="PARAMETER"
1255 >byte</CODE
1256 >,<CODE
1257 CLASS="PARAMETER"
1258 >size</CODE
1259 ></DT
1260 ><DD
1261 ><P
1262 >Insert <CODE
1263 CLASS="PARAMETER"
1264 >size</CODE
1265 > bytes of <CODE
1266 CLASS="PARAMETER"
1267 >byte</CODE
1268 >.</P
1269 ></DD
1270 ></DL
1271 ></DIV
1272 ></DIV
1273 ><DIV
1274 CLASS="SECTION"
1275 ><HR><H3
1276 CLASS="SECTION"
1277 ><A
1278 NAME="AEN364"
1279 >3.6.2. Address Definition</A
1280 ></H3
1281 ><P
1282 >The directives in this section all control the addresses of symbols
1283 or the assembly process itself.</P
1284 ><P
1285 ></P
1286 ><DIV
1287 CLASS="VARIABLELIST"
1288 ><DL
1289 ><DT
1290 >ORG <CODE
1291 CLASS="PARAMETER"
1292 >expr</CODE
1293 ></DT
1294 ><DD
1295 ><P
1296 >Set the assembly address. The address must be fully resolvable on the
1297 first pass so no external or forward references are permitted. ORG is not
1298 permitted within sections when outputting to object files. For target formats
1299 that include address information (decb, hex, srec, and ihex), an ORG
1300 directive will re-start the address sequence within the output. When using
1301 the raw target format, ORG is used only to determine the addresses of symbols.</P
1302 ></DD
1303 ><DT
1304 >REORG</DT
1305 ><DD
1306 ><P
1307 >Sets the assembly address to the value it had immediately prior to the
1308 previous ORG statement. It is used to continue assembly after some
1309 specification that required an additional ORG. This directive is primarily
1310 intended for MACRO-80c compatibility. Consider using alternatives in
1311 modern code.</P
1312 ></DD
1313 ><DT
1314 ><CODE
1315 CLASS="PARAMETER"
1316 >sym</CODE
1317 > EQU <CODE
1318 CLASS="PARAMETER"
1319 >expr</CODE
1320 >, <CODE
1321 CLASS="PARAMETER"
1322 >sym</CODE
1323 > = <CODE
1324 CLASS="PARAMETER"
1325 >expr</CODE
1326 ></DT
1327 ><DD
1328 ><P
1329 >Define the value of <CODE
1330 CLASS="PARAMETER"
1331 >sym</CODE
1332 > to be <CODE
1333 CLASS="PARAMETER"
1334 >expr</CODE
1335 >.</P
1336 ></DD
1337 ><DT
1338 ><CODE
1339 CLASS="PARAMETER"
1340 >sym</CODE
1341 > SET <CODE
1342 CLASS="PARAMETER"
1343 >expr</CODE
1344 ></DT
1345 ><DD
1346 ><P
1347 >Define the value of <CODE
1348 CLASS="PARAMETER"
1349 >sym</CODE
1350 > to be <CODE
1351 CLASS="PARAMETER"
1352 >expr</CODE
1353 >.
1354 Unlike EQU, SET permits symbols to be defined multiple times as long as SET
1355 is used for all instances. Use of the symbol before the first SET statement
1356 that sets its value is undefined.</P
1357 ></DD
1358 ><DT
1359 >SETDP <CODE
1360 CLASS="PARAMETER"
1361 >expr</CODE
1362 ></DT
1363 ><DD
1364 ><P
1365 >Inform the assembler that it can assume the DP register contains
1366 <CODE
1367 CLASS="PARAMETER"
1368 >expr</CODE
1369 >. This directive is only advice to the assembler
1370 to determine whether an address is in the direct page and has no effect
1371 on the contents of the DP register. The value must be fully resolved during
1372 the first assembly pass because it affects the sizes of subsequent instructions.</P
1373 ><P
1374 >This directive has no effect in the object file target.</P
1375 ></DD
1376 ><DT
1377 >ALIGN <CODE
1378 CLASS="PARAMETER"
1379 >expr</CODE
1380 >[,<CODE
1381 CLASS="PARAMETER"
1382 >value</CODE
1383 >]</DT
1384 ><DD
1385 ><P
1386 >Force the current assembly address to be a multiple of
1387 <CODE
1388 CLASS="PARAMETER"
1389 >expr</CODE
1390 >. If <CODE
1391 CLASS="PARAMETER"
1392 >value</CODE
1393 > is not
1394 specified, a series of NUL bytes is output to force the alignment, if
1395 required. Otherwise, the low order 8 bits of <CODE
1396 CLASS="PARAMETER"
1397 >value</CODE
1398 >
1399 will be used as the fill. The alignment value must be fully resolved on the
1400 first pass because it affects the addresses of subsquent instructions.
1401 However, <CODE
1402 CLASS="PARAMETER"
1403 >value</CODE
1404 > may include forward references; as
1405 long as it resolves to a constant for the second pass, the value will be
1406 accepted.</P
1407 ><P
1408 >Unless <CODE
1409 CLASS="PARAMETER"
1410 >value</CODE
1411 > is specified as something like $12,
1412 this directive is not suitable for inclusion in the middle of actual code.
1413 The default padding value is $00 which is intended to be used within data
1414 blocks. </P
1415 ></DD
1416 ></DL
1417 ></DIV
1418 ></DIV
1419 ><DIV
1420 CLASS="SECTION"
1421 ><HR><H3
1422 CLASS="SECTION"
1423 ><A
1424 NAME="AEN415"
1425 >3.6.3. Conditional Assembly</A
1426 ></H3
1427 ><P
1428 >Portions of the source code can be excluded or included based on conditions
1429 known at assembly time. Conditionals can be nested arbitrarily deeply. The
1430 directives associated with conditional assembly are described in this section.</P
1431 ><P
1432 >All conditionals must be fully bracketed. That is, every conditional
1433 statement must eventually be followed by an ENDC at the same level of nesting.</P
1434 ><P
1435 >Conditional expressions are only evaluated on the first assembly pass.
1436 It is not possible to game the assembly process by having a conditional
1437 change its value between assembly passes. Due to the underlying architecture
1438 of LWASM, there is no possible utility to IFP1 and IFP2, nor can they, as of LWASM 3.0, actually
1439 be implemented meaningfully. Thus there is not and never will
1440 be any equivalent of IFP1 or IFP2 as provided by other assemblers. Use of those opcodes
1441 will throw a warning and be ignored.</P
1442 ><P
1443 >It is important to note that if a conditional does not resolve to a constant
1444 during the first parsing pass, an error will be thrown. This is unavoidable because the assembler
1445 must make a decision about which source to include and which source to exclude at this stage.
1446 Thus, expressions that work normally elsewhere will not work for conditions.</P
1447 ><P
1448 ></P
1449 ><DIV
1450 CLASS="VARIABLELIST"
1451 ><DL
1452 ><DT
1453 >IFEQ <CODE
1454 CLASS="PARAMETER"
1455 >expr</CODE
1456 ></DT
1457 ><DD
1458 ><P
1459 >If <CODE
1460 CLASS="PARAMETER"
1461 >expr</CODE
1462 > evaluates to zero, the conditional
1463 will be considered true.</P
1464 ></DD
1465 ><DT
1466 >IFNE <CODE
1467 CLASS="PARAMETER"
1468 >expr</CODE
1469 >, IF <CODE
1470 CLASS="PARAMETER"
1471 >expr</CODE
1472 ></DT
1473 ><DD
1474 ><P
1475 >If <CODE
1476 CLASS="PARAMETER"
1477 >expr</CODE
1478 > evaluates to a non-zero value, the conditional
1479 will be considered true.</P
1480 ></DD
1481 ><DT
1482 >IFGT <CODE
1483 CLASS="PARAMETER"
1484 >expr</CODE
1485 ></DT
1486 ><DD
1487 ><P
1488 >If <CODE
1489 CLASS="PARAMETER"
1490 >expr</CODE
1491 > evaluates to a value greater than zero, the conditional
1492 will be considered true.</P
1493 ></DD
1494 ><DT
1495 >IFGE <CODE
1496 CLASS="PARAMETER"
1497 >expr</CODE
1498 ></DT
1499 ><DD
1500 ><P
1501 >If <CODE
1502 CLASS="PARAMETER"
1503 >expr</CODE
1504 > evaluates to a value greater than or equal to zero, the conditional
1505 will be considered true.</P
1506 ></DD
1507 ><DT
1508 >IFLT <CODE
1509 CLASS="PARAMETER"
1510 >expr</CODE
1511 ></DT
1512 ><DD
1513 ><P
1514 >If <CODE
1515 CLASS="PARAMETER"
1516 >expr</CODE
1517 > evaluates to a value less than zero, the conditional
1518 will be considered true.</P
1519 ></DD
1520 ><DT
1521 >IFLE <CODE
1522 CLASS="PARAMETER"
1523 >expr</CODE
1524 ></DT
1525 ><DD
1526 ><P
1527 >If <CODE
1528 CLASS="PARAMETER"
1529 >expr</CODE
1530 > evaluates to a value less than or equal to zero , the conditional
1531 will be considered true.</P
1532 ></DD
1533 ><DT
1534 >IFDEF <CODE
1535 CLASS="PARAMETER"
1536 >sym</CODE
1537 ></DT
1538 ><DD
1539 ><P
1540 >If <CODE
1541 CLASS="PARAMETER"
1542 >sym</CODE
1543 > is defined at this point in the assembly
1544 process, the conditional
1545 will be considered true.</P
1546 ></DD
1547 ><DT
1548 >IFPRAGMA <CODE
1549 CLASS="PARAMETER"
1550 >pragma</CODE
1551 ></DT
1552 ><DD
1553 ><P
1554 >If <CODE
1555 CLASS="PARAMETER"
1556 >pragma</CODE
1557 > is in effect, the condition will be considered true.</P
1558 ></DD
1559 ><DT
1560 >IFNDEF <CODE
1561 CLASS="PARAMETER"
1562 >sym</CODE
1563 ></DT
1564 ><DD
1565 ><P
1566 >If <CODE
1567 CLASS="PARAMETER"
1568 >sym</CODE
1569 > is not defined at this point in the assembly
1570 process, the conditional
1571 will be considered true.</P
1572 ></DD
1573 ><DT
1574 >ELSE</DT
1575 ><DD
1576 ><P
1577 >If the preceding conditional at the same level of nesting was false, the
1578 statements following will be assembled. If the preceding conditional at
1579 the same level was true, the statements following will not be assembled.
1580 Note that the preceding conditional might have been another ELSE statement
1581 although this behaviour is not guaranteed to be supported in future versions
1582 of LWASM.</P
1583 ></DD
1584 ><DT
1585 >ENDC</DT
1586 ><DD
1587 ><P
1588 >This directive marks the end of a conditional construct. Every conditional
1589 construct must end with an ENDC directive.</P
1590 ></DD
1591 ></DL
1592 ></DIV
1593 ></DIV
1594 ><DIV
1595 CLASS="SECTION"
1596 ><HR><H3
1597 CLASS="SECTION"
1598 ><A
1599 NAME="AEN486"
1600 >3.6.4. OS9 Target Directives</A
1601 ></H3
1602 ><P
1603 >This section includes directives that apply solely to the OS9
1604 target.</P
1605 ><P
1606 ></P
1607 ><DIV
1608 CLASS="VARIABLELIST"
1609 ><DL
1610 ><DT
1611 >OS9 <CODE
1612 CLASS="PARAMETER"
1613 >syscall</CODE
1614 ></DT
1615 ><DD
1616 ><P
1617 >&#13;This directive generates a call to the specified system call. <CODE
1618 CLASS="PARAMETER"
1619 >syscall</CODE
1620 > may be an arbitrary expression.&#13;</P
1621 ></DD
1622 ><DT
1623 >MOD <CODE
1624 CLASS="PARAMETER"
1625 >size</CODE
1626 >,<CODE
1627 CLASS="PARAMETER"
1628 >name</CODE
1629 >,<CODE
1630 CLASS="PARAMETER"
1631 >type</CODE
1632 >,<CODE
1633 CLASS="PARAMETER"
1634 >flags</CODE
1635 >,<CODE
1636 CLASS="PARAMETER"
1637 >execoff</CODE
1638 >,<CODE
1639 CLASS="PARAMETER"
1640 >datasize</CODE
1641 ></DT
1642 ><DD
1643 ><P
1644 >&#13;This tells LWASM that the beginning of the actual module is here. It will
1645 generate a module header based on the parameters specified. It will also
1646 begin calcuating the module CRC.&#13;</P
1647 ><P
1648 >&#13;The precise meaning of the various parameters is beyond the scope of this
1649 document since it is not a tutorial on OS9 module programming.&#13;</P
1650 ></DD
1651 ><DT
1652 >EMOD</DT
1653 ><DD
1654 ><P
1655 >&#13;This marks the end of a module and causes LWASM to emit the calculated CRC
1656 for the module.&#13;</P
1657 ></DD
1658 ></DL
1659 ></DIV
1660 ></DIV
1661 ><DIV
1662 CLASS="SECTION"
1663 ><HR><H3
1664 CLASS="SECTION"
1665 ><A
1666 NAME="AEN511"
1667 >3.6.5. Miscelaneous Directives</A
1668 ></H3
1669 ><P
1670 >This section includes directives that do not fit into the other
1671 categories.</P
1672 ><P
1673 ></P
1674 ><DIV
1675 CLASS="VARIABLELIST"
1676 ><DL
1677 ><DT
1678 >INCLUDE <CODE
1679 CLASS="PARAMETER"
1680 >filename</CODE
1681 >, USE <CODE
1682 CLASS="PARAMETER"
1683 >filename</CODE
1684 ></DT
1685 ><DD
1686 ><P
1687 > Include the contents of <CODE
1688 CLASS="PARAMETER"
1689 >filename</CODE
1690 > at
1691 this point in the assembly as though it were a part of the file currently
1692 being processed. Note that if whitespace appears in the name of the file,
1693 you must enclose <CODE
1694 CLASS="PARAMETER"
1695 >filename</CODE
1696 > in quotes.</P
1697 ><P
1698 >Note that the USE variation is provided only for compatibility with other
1699 assemblers. It is recommended to use the INCLUDE variation.</P
1700 ><P
1701 >If <CODE
1702 CLASS="PARAMETER"
1703 >filename</CODE
1704 > begins with a &quot;/&quot;, it is
1705 interpreted as an absolute path. If it does not, the search path will be used
1706 to find the file. First, the directory containing the file that contains this
1707 directive. (Includes within an included file are relative to the included file,
1708 not the file that included it.) If the file is not found there, the include path
1709 is searched. If it is still not found, an error will be thrown. Note that the
1710 current directory as understood by your shell or operating system is not searched.</P
1711 ></DD
1712 ><DT
1713 >END <CODE
1714 CLASS="PARAMETER"
1715 >[expr]</CODE
1716 ></DT
1717 ><DD
1718 ><P
1719 >This directive causes the assembler to stop assembling immediately as though
1720 it ran out of input. For the DECB target only, <CODE
1721 CLASS="PARAMETER"
1722 >expr</CODE
1723 >
1724 can be used to set the execution address of the resulting binary. For all
1725 other targets, specifying <CODE
1726 CLASS="PARAMETER"
1727 >expr</CODE
1728 > will cause an error.</P
1729 ></DD
1730 ><DT
1731 >ERROR <CODE
1732 CLASS="PARAMETER"
1733 >string</CODE
1734 ></DT
1735 ><DD
1736 ><P
1737 >Causes a custom error message to be printed at this line. This will cause
1738 assembly to fail. This directive is most useful inside conditional constructs
1739 to cause assembly to fail if some condition that is known bad happens. Everything
1740 from the directive to the end of the line is considered the error message.</P
1741 ></DD
1742 ><DT
1743 >WARNING <CODE
1744 CLASS="PARAMETER"
1745 >string</CODE
1746 ></DT
1747 ><DD
1748 ><P
1749 >Causes a custom warning message to be printed at this line. This will not cause
1750 assembly to fail. This directive is most useful inside conditional constructs
1751 or include files to alert the programmer to a deprecated feature being used
1752 or some other condition that may cause trouble later, but which may, in fact,
1753 not cause any trouble.</P
1754 ></DD
1755 ><DT
1756 >.MODULE <CODE
1757 CLASS="PARAMETER"
1758 >string</CODE
1759 ></DT
1760 ><DD
1761 ><P
1762 >This directive is ignored for most output targets. If the output target
1763 supports encoding a module name into it, <CODE
1764 CLASS="PARAMETER"
1765 >string</CODE
1766 >
1767 will be used as the module name.</P
1768 ><P
1769 >As of version 3.0, no supported output targets support this directive.</P
1770 ></DD
1771 ></DL
1772 ></DIV
1773 ></DIV
1774 ></DIV
1775 ><DIV
1776 CLASS="SECTION"
1777 ><HR><H2
1778 CLASS="SECTION"
1779 ><A
1780 NAME="AEN551"
1781 >3.7. Macros</A
1782 ></H2
1783 ><P
1784 >LWASM is a macro assembler. A macro is simply a name that stands in for a
1785 series of instructions. Once a macro is defined, it is used like any other
1786 assembler directive. Defining a macro can be considered equivalent to adding
1787 additional assembler directives.</P
1788 ><P
1789 >Macros may accept parameters. These parameters are referenced within a
1790 macro by the a backslash ("\") followed by a digit 1 through 9 for the first
1791 through ninth parameters. They may also be referenced by enclosing the
1792 decimal parameter number in braces ("{num}"). The special expansion "\*"
1793 translates to the exact parameter string, including all parameters, passed
1794 to the macro. These parameter references are replaced with the verbatim text
1795 of the parameter passed to the macro. A reference to a non-existent
1796 parameter will be replaced by an empty string. Macro parameters are expanded
1797 everywhere on each source line. That means the parameter to a macro could be
1798 used as a symbol or it could even appear in a comment or could cause an
1799 entire source line to be commented out when the macro is expanded. </P
1800 ><P
1801 >Parameters passed to a macro are separated by commas and the parameter list
1802 is terminated by any whitespace. This means that neither a comma nor whitespace
1803 may be included in a macro parameter.</P
1804 ><P
1805 >Macro expansion is done recursively. That is, within a macro, macros are
1806 expanded. This can lead to infinite loops in macro expansion. If the assembler
1807 hangs for a long time while assembling a file that uses macros, this may be
1808 the reason.</P
1809 ><P
1810 >Each macro expansion receives its own local symbol context which is not
1811 inherited by any macros called by it nor is it inherited from the context
1812 the macro was instantiated in. That means it is possible to use local symbols
1813 within macros without having them collide with symbols in other macros or
1814 outside the macro itself. However, this also means that using a local symbol
1815 as a parameter to a macro, while legal, will not do what it would seem to do
1816 as it will result in looking up the local symbol in the macro's symbol context
1817 rather than the enclosing context where it came from, likely yielding either
1818 an undefined symbol error or bizarre assembly results.</P
1819 ><P
1820 >Note that there is no way to define a macro as local to a symbol context. All
1821 macros are part of the global macro namespace. However, macros have a separate
1822 namespace from symbols so it is possible to have a symbol with the same name
1823 as a macro.</P
1824 ><P
1825 >Macros are defined only during the first pass. Macro expansion also
1826 only occurs during the first pass. On the second pass, the macro
1827 definition is simply ignored. Macros must be defined before they are used.</P
1828 ><P
1829 >The following directives are used when defining macros.</P
1830 ><P
1831 ></P
1832 ><DIV
1833 CLASS="VARIABLELIST"
1834 ><DL
1835 ><DT
1836 ><CODE
1837 CLASS="PARAMETER"
1838 >macroname</CODE
1839 > MACRO [NOEXPAND]</DT
1840 ><DD
1841 ><P
1842 >This directive is used to being the definition of a macro called
1843 <CODE
1844 CLASS="PARAMETER"
1845 >macroname</CODE
1846 >. If <CODE
1847 CLASS="PARAMETER"
1848 >macroname</CODE
1849 > already
1850 exists, it is considered an error. Attempting to define a macro within a
1851 macro is undefined. It may work and it may not so the behaviour should not
1852 be relied upon.</P
1853 ><P
1854 >If NOEXPAND is specified, the macro will not be expanded in a program
1855 listing. Instead, all bytes emitted by all instructions within the macro
1856 will appear to be emitted on the line where the macro is invoked, starting
1857 at the address of the line of the invokation. If the macro uses ORG or other
1858 directives that define symbols or change the assembly address, these things
1859 will also be hidden (except in the symbol table) and the output bytes will
1860 appear with incorrect address attribution. Thus, NOEXPAND should only be
1861 used for macros that do not mess with the assembly address or otherwise
1862 define symbols that should be visible.</P
1863 ></DD
1864 ><DT
1865 >ENDM</DT
1866 ><DD
1867 ><P
1868 >This directive indicates the end of the macro currently being defined. It
1869 causes the assembler to resume interpreting source lines as normal.</P
1870 ></DD
1871 ></DL
1872 ></DIV
1873 ></DIV
1874 ><DIV
1875 CLASS="SECTION"
1876 ><HR><H2
1877 CLASS="SECTION"
1878 ><A
1879 NAME="AEN574"
1880 >3.8. Structures</A
1881 ></H2
1882 ><P
1883 >&#13;Structures are used to group related data in a fixed structure. A structure
1884 consists a number of fields, defined in sequential order and which take up
1885 specified size. The assembler does not enforce any means of access within a
1886 structure; it assumes that whatever you are doing, you intended to do.
1887 There are two pseudo ops that are used for defining structures.&#13;</P
1888 ><P
1889 ></P
1890 ><DIV
1891 CLASS="VARIABLELIST"
1892 ><DL
1893 ><DT
1894 ><CODE
1895 CLASS="PARAMETER"
1896 >structname</CODE
1897 > STRUCT</DT
1898 ><DD
1899 ><P
1900 >&#13;This directive is used to begin the definition of a structure with name
1901 <CODE
1902 CLASS="PARAMETER"
1903 >structname</CODE
1904 >. Subsequent statements all form part of
1905 the structure definition until the end of the structure is declared.&#13;</P
1906 ></DD
1907 ><DT
1908 >ENDSTRUCT, ENDS</DT
1909 ><DD
1910 ><P
1911 >This directive ends the definition of the structure. ENDSTRUCT is the
1912 preferred form. Prior to version 3.0 of LWASM, ENDS was used to end a
1913 section instead of a structure.</P
1914 ></DD
1915 ></DL
1916 ></DIV
1917 ><P
1918 >&#13;Within a structure definition, only reservation pseudo ops are permitted.
1919 Anything else will cause an assembly error.</P
1920 ><P
1921 > Once a structure is defined, you can reserve an area of memory in the
1922 same structure by using the structure name as the opcode. Structures can
1923 also contain fields that are themselves structures. See the example
1924 below.</P
1925 ><PRE
1926 CLASS="PROGRAMLISTING"
1927 >tstruct2 STRUCT
1928 f1 rmb 1
1929 f2 rmb 1
1930 ENDSTRUCT
1931
1932 tstruct STRUCT
1933 field1 rmb 2
1934 field2 rmb 3
1935 field3 tstruct2
1936 ENDSTRUCT
1937
1938 ORG $2000
1939 var1 tstruct
1940 var2 tstruct2</PRE
1941 ><P
1942 >Fields are referenced using a dot (.) as a separator. To refer to the
1943 generic offset within a structure, use the structure name to the left of the
1944 dot. If referring to a field within an actual variable, use the variable's
1945 symbol name to the left of the dot.</P
1946 ><P
1947 >You can also refer to the actual size of a structure (or a variable
1948 declared as a structure) using the special symbol sizeof{structname} where
1949 structname will be the name of the structure or the name of the
1950 variable.</P
1951 ><P
1952 >Essentially, structures are a shortcut for defining a vast number of
1953 symbols. When a structure is defined, the assembler creates symbols for the
1954 various fields in the form structname.fieldname as well as the appropriate
1955 sizeof{structname} symbol. When a variable is declared as a structure, the
1956 assembler does the same thing using the name of the variable. You will see
1957 these symbols in the symbol table when the assembler is instructed to
1958 provide a listing. For instance, the above listing will create the
1959 following symbols (symbol values in parentheses): tstruct2.f1 (0),
1960 tstruct2.f2 (1), sizeof{tstruct2} (2), tstruct.field1 (0), tstruct.field2
1961 (2), tstruct.field3 (5), tstruct.field3.f1 (5), tstruct.field3.f2 (6),
1962 sizeof{tstruct.field3} (2), sizeof{tstruct} (7), var1 {$2000}, var1.field1
1963 {$2000}, var1.field2 {$2002}, var1.field3 {$2005}, var1.field3.f1 {$2005},
1964 var1.field3.f2 {$2006}, sizeof(var1.field3} (2), sizeof{var1} (7), var2
1965 ($2007), var2.f1 ($2007), var2.f2 ($2008), sizeof{var2} (2). </P
1966 ></DIV
1967 ><DIV
1968 CLASS="SECTION"
1969 ><HR><H2
1970 CLASS="SECTION"
1971 ><A
1972 NAME="AEN595"
1973 >3.9. Object Files and Sections</A
1974 ></H2
1975 ><P
1976 >The object file target is very useful for large project because it allows
1977 multiple files to be assembled independently and then linked into the final
1978 binary at a later time. It allows only the small portion of the project
1979 that was modified to be re-assembled rather than requiring the entire set
1980 of source code to be available to the assembler in a single assembly process.
1981 This can be particularly important if there are a large number of macros,
1982 symbol definitions, or other metadata that uses resources at assembly time.
1983 By far the largest benefit, however, is keeping the source files small enough
1984 for a mere mortal to find things in them.</P
1985 ><P
1986 >With multi-file projects, there needs to be a means of resolving references to
1987 symbols in other source files. These are known as external references. The
1988 addresses of these symbols cannot be known until the linker joins all the
1989 object files into a single binary. This means that the assembler must be
1990 able to output the object code without knowing the value of the symbol. This
1991 places some restrictions on the code generated by the assembler. For
1992 example, the assembler cannot generate direct page addressing for instructions
1993 that reference external symbols because the address of the symbol may not
1994 be in the direct page. Similarly, relative branches and PC relative addressing
1995 cannot be used in their eight bit forms. Everything that must be resolved
1996 by the linker must be assembled to use the largest address size possible to
1997 allow the linker to fill in the correct value at link time. Note that the
1998 same problem applies to absolute address references as well, even those in
1999 the same source file, because the address is not known until link time.</P
2000 ><P
2001 >It is often desired in multi-file projects to have code of various types grouped
2002 together in the final binary generated by the linker as well. The same applies
2003 to data. In order for the linker to do that, the bits that are to be grouped
2004 must be tagged in some manner. This is where the concept of sections comes in.
2005 Each chunk of code or data is part of a section in the object file. Then,
2006 when the linker reads all the object files, it coalesces all sections of the
2007 same name into a single section and then considers it as a unit.</P
2008 ><P
2009 >The existence of sections, however, raises a problem for symbols even
2010 within the same source file. Thus, the assembler must treat symbols from
2011 different sections within the same source file in the same manner as external
2012 symbols. That is, it must leave them for the linker to resolve at link time,
2013 with all the limitations that entails.</P
2014 ><P
2015 >In the object file target mode, LWASM requires all source lines that
2016 cause bytes to be output to be inside a section. Any directives that do
2017 not cause any bytes to be output can appear outside of a section. This includes
2018 such things as EQU or RMB. Even ORG can appear outside a section. ORG, however,
2019 makes no sense within a section because it is the linker that determines
2020 the starting address of the section's code, not the assembler.</P
2021 ><P
2022 >All symbols defined globally in the assembly process are local to the
2023 source file and cannot be exported. All symbols defined within a section are
2024 considered local to the source file unless otherwise explicitly exported.
2025 Symbols referenced from external source files must be declared external,
2026 either explicitly or by asking the assembler to assume that all undefined
2027 symbols are external.</P
2028 ><P
2029 >It is often handy to define a number of memory addresses that will be
2030 used for data at run-time but which need not be included in the binary file.
2031 These memory addresses are not initialized until run-time, either by the
2032 program itself or by the program loader, depending on the operating environment.
2033 Such sections are often known as BSS sections. LWASM supports generating
2034 sections with a BSS attribute set which causes the section definition including
2035 symbols exported from that section and those symbols required to resolve
2036 references from the local file, but with no actual code in the object file.
2037 It is illegal for any source lines within a BSS flagged section to cause any
2038 bytes to be output.</P
2039 ><P
2040 >The following directives apply to section handling.</P
2041 ><P
2042 ></P
2043 ><DIV
2044 CLASS="VARIABLELIST"
2045 ><DL
2046 ><DT
2047 >SECTION <CODE
2048 CLASS="PARAMETER"
2049 >name[,flags]</CODE
2050 >, SECT <CODE
2051 CLASS="PARAMETER"
2052 >name[,flags]</CODE
2053 >, .AREA <CODE
2054 CLASS="PARAMETER"
2055 >name[,flags]</CODE
2056 ></DT
2057 ><DD
2058 ><P
2059 >Instructs the assembler that the code following this directive is to be
2060 considered part of the section <CODE
2061 CLASS="PARAMETER"
2062 >name</CODE
2063 >. A section name
2064 may appear multiple times in which case it is as though all the code from
2065 all the instances of that section appeared adjacent within the source file.
2066 However, <CODE
2067 CLASS="PARAMETER"
2068 >flags</CODE
2069 > may only be specified on the first
2070 instance of the section.</P
2071 ><P
2072 ><CODE
2073 CLASS="PARAMETER"
2074 >flags</CODE
2075 > is a comma separated list of flags. If a
2076 flag is "bss", the section will be treated as a BSS section and no
2077 statements that generate output are permitted.</P
2078 ><P
2079 >If the flag is "constant",
2080 the same restrictions apply as for BSS sections. Additionally, all symbols
2081 defined in a constant section define absolute values and will not be
2082 adjusted by the linker at link time. Constant sections cannot define
2083 complex expressions for symbols; the value must be fully defined at assembly
2084 time. Additionally, multiple instances of a constant section do not
2085 coalesce into a single addressing unit; each instance starts again at offset
2086 0.</P
2087 ><P
2088 >If the section name is "bss" or ".bss" in any combination of upper and
2089 lower case, the section is assumed to be a BSS section. In that case,
2090 the flag <CODE
2091 CLASS="PARAMETER"
2092 >!bss</CODE
2093 > can be used to override this assumption.</P
2094 ><P
2095 > If the section name is "_constants" or "_constant", in any
2096 combination of upper and lower case, the section is assumed to be a constant
2097 section. This assumption can be overridden with the "!constant"
2098 flag.</P
2099 ><P
2100 >If assembly is already happening within a section, the section is implicitly
2101 ended and the new section started. This is not considered an error although
2102 it is recommended that all sections be explicitly closed.</P
2103 ></DD
2104 ><DT
2105 >ENDSECTION, ENDSECT</DT
2106 ><DD
2107 ><P
2108 >This directive ends the current section. This puts assembly outside of any
2109 sections until the next SECTION directive. ENDSECTION is the preferred form.
2110 Prior to version 3.0 of LWASM, ENDS could also be used to end a section but
2111 as of version 3.0, it is now an alias for ENDSTRUCT instead.</P
2112 ></DD
2113 ><DT
2114 ><CODE
2115 CLASS="PARAMETER"
2116 >sym</CODE
2117 > EXTERN, <CODE
2118 CLASS="PARAMETER"
2119 >sym</CODE
2120 > EXTERNAL, <CODE
2121 CLASS="PARAMETER"
2122 >sym</CODE
2123 > IMPORT</DT
2124 ><DD
2125 ><P
2126 >This directive defines <CODE
2127 CLASS="PARAMETER"
2128 >sym</CODE
2129 > as an external symbol.
2130 This directive may occur at any point in the source code. EXTERN definitions
2131 are resolved on the first pass so an EXTERN definition anywhere in the
2132 source file is valid for the entire file. The use of this directive is
2133 optional when the assembler is instructed to assume that all undefined
2134 symbols are external. In fact, in that mode, if the symbol is referenced
2135 before the EXTERN directive, an error will occur.</P
2136 ></DD
2137 ><DT
2138 ><CODE
2139 CLASS="PARAMETER"
2140 >sym</CODE
2141 > EXPORT, <CODE
2142 CLASS="PARAMETER"
2143 >sym</CODE
2144 > .GLOBL, EXPORT <CODE
2145 CLASS="PARAMETER"
2146 >sym</CODE
2147 >, .GLOBL <CODE
2148 CLASS="PARAMETER"
2149 >sym</CODE
2150 ></DT
2151 ><DD
2152 ><P
2153 >This directive defines <CODE
2154 CLASS="PARAMETER"
2155 >sym</CODE
2156 > as an exported symbol.
2157 This directive may occur at any point in the source code, even before the
2158 definition of the exported symbol.</P
2159 ><P
2160 >Note that <CODE
2161 CLASS="PARAMETER"
2162 >sym</CODE
2163 > may appear as the operand or as the
2164 statement's symbol. If there is a symbol on the statement, that will
2165 take precedence over any operand that is present.</P
2166 ></DD
2167 ><DT
2168 ><CODE
2169 CLASS="PARAMETER"
2170 >sym</CODE
2171 > EXTDEP</DT
2172 ><DD
2173 ><P
2174 >This directive forces an external dependency on
2175 <CODE
2176 CLASS="PARAMETER"
2177 >sym</CODE
2178 >, even if it is never referenced anywhere else in
2179 this file.</P
2180 ></DD
2181 ></DL
2182 ></DIV
2183 ></DIV
2184 ><DIV
2185 CLASS="SECTION"
2186 ><HR><H2
2187 CLASS="SECTION"
2188 ><A
2189 NAME="AEN659"
2190 >3.10. Assembler Modes and Pragmas</A
2191 ></H2
2192 ><P
2193 >There are a number of options that affect the way assembly is performed.
2194 Some of these options can only be specified on the command line because
2195 they determine something absolute about the assembly process. These include
2196 such things as the output target. Other things may be switchable during
2197 the assembly process. These are known as pragmas and are, by definition,
2198 not portable between assemblers.</P
2199 ><P
2200 >LWASM supports a number of pragmas that affect code generation or
2201 otherwise affect the behaviour of the assembler. These may be specified by
2202 way of a command line option or by assembler directives. The directives
2203 are as follows.</P
2204 ><P
2205 ></P
2206 ><DIV
2207 CLASS="VARIABLELIST"
2208 ><DL
2209 ><DT
2210 >PRAGMA <CODE
2211 CLASS="PARAMETER"
2212 >pragma[,...]</CODE
2213 ></DT
2214 ><DD
2215 ><P
2216 >Specifies that the assembler should bring into force all <CODE
2217 CLASS="PARAMETER"
2218 >pragma</CODE
2219 >s
2220 specified. Any unrecognized pragma will cause an assembly error. The new
2221 pragmas will take effect immediately. This directive should be used when
2222 the program will assemble incorrectly if the pragma is ignored or not supported.</P
2223 ></DD
2224 ><DT
2225 >*PRAGMA <CODE
2226 CLASS="PARAMETER"
2227 >pragma[,...]</CODE
2228 ></DT
2229 ><DD
2230 ><P
2231 >This is identical to the PRAGMA directive except no error will occur with
2232 unrecognized or unsupported pragmas. This directive, by virtue of starting
2233 with a comment character, will also be ignored by assemblers that do not
2234 support this directive. Use this variation if the pragma is not required
2235 for correct functioning of the code.</P
2236 ></DD
2237 ><DT
2238 >*PRAGMAPUSH <CODE
2239 CLASS="PARAMETER"
2240 >pragma[,...]</CODE
2241 ></DT
2242 ><DD
2243 ><P
2244 >This directive saves the current state of the specified pragma(s) for later retrieval. See discussion below for more information.</P
2245 ><P
2246 >This directive will not throw any errors for any reason.</P
2247 ></DD
2248 ><DT
2249 >*PRAGMAPOP <CODE
2250 CLASS="PARAMETER"
2251 >pragma[,...]</CODE
2252 ></DT
2253 ><DD
2254 ><P
2255 >This directive restores the previously saved state of the specified pragma(s). See discussion below for more information.</P
2256 ><P
2257 >This directive will not throw any errors for any reason.</P
2258 ></DD
2259 ></DL
2260 ></DIV
2261 ><P
2262 >Each pragma supported has a positive version and a negative version.
2263 The positive version enables the pragma while the negative version disables
2264 it. The negatitve version is simply the positive version with "no" prefixed
2265 to it. For instance, "pragma" vs. "nopragma". When only one version is
2266 listed below, its opposite can be obtained by prepending "no" if it is not
2267 present or removing "no" from the beginning if it is present.</P
2268 ><P
2269 >Pragmas are not case sensitive.</P
2270 ><P
2271 ></P
2272 ><DIV
2273 CLASS="VARIABLELIST"
2274 ><DL
2275 ><DT
2276 >6800compat</DT
2277 ><DD
2278 ><P
2279 >When in force, this pragma enables recognition of various
2280 compatibility instructions useful when assembling 6800 code. These
2281 compatibility instructions are assembled into equivalent 6809 instructions.
2282 This mode also includes several analogous instructions which are not
2283 strictly 6800 instructions but allow the similar style to be applied to 6809
2284 specific features.</P
2285 ><P
2286 >Technically, a compliant 6809 assembler must recognize these
2287 instructions by default since Motorola advertised the 6809 as being source
2288 compatible with the 6800. However, most source code does not require this
2289 compatibility and LWASM itself did not support these instructions prior to
2290 version 4.11 so this mode is disabled by default.</P
2291 ></DD
2292 ><DT
2293 >6809</DT
2294 ><DD
2295 ><P
2296 >This pragma allows you to mark a section of code as 6809-only. In ths mode,
2297 the assembler will throw an error if any 6309 instructions are used.</P
2298 ></DD
2299 ><DT
2300 >6309</DT
2301 ><DD
2302 ><P
2303 >This pragma enables the use of 6309 instructions and disables any 6809 specific
2304 instructions. It also changes the cycle count listing output (if selected)
2305 to display 6309 timings.</P
2306 ></DD
2307 ><DT
2308 >6809conv, 6309conv</DT
2309 ><DD
2310 ><P
2311 >These pragmas enable convenience instructions extending the 6809 and 6309
2312 instruction sets respectively. For more information, see
2313 <A
2314 HREF="#CONVINST"
2315 >Section 3.11</A
2316 >.</P
2317 ></DD
2318 ><DT
2319 >index0tonone</DT
2320 ><DD
2321 ><P
2322 >When in force, this pragma enables an optimization affecting indexed addressing
2323 modes. When the offset expression in an indexed mode evaluates to zero but is
2324 not explicity written as 0, this will replace the operand with the equivalent
2325 no offset mode, thus creating slightly faster code. Because of the advantages
2326 of this optimization, it is enabled by default.</P
2327 ></DD
2328 ><DT
2329 >cescapes</DT
2330 ><DD
2331 ><P
2332 >This pragma will cause strings in the FCC, FCS, and FCN pseudo operations to
2333 have C-style escape sequences interpreted. The one departure from the official
2334 spec is that unrecognized escape sequences will return either the character
2335 immediately following the backslash or some undefined value. Do not rely
2336 on the behaviour of undefined escape sequences.</P
2337 ></DD
2338 ><DT
2339 >importundefexport</DT
2340 ><DD
2341 ><P
2342 >This pragma is only valid for targets that support external references. When
2343 in force, it will cause the EXPORT directive to act as IMPORT if the symbol
2344 to be exported is not defined. This is provided for compatibility with the
2345 output of gcc6809 and should not be used in hand written code. Because of
2346 the confusion this pragma can cause, it is disabled by default.</P
2347 ></DD
2348 ><DT
2349 >undefextern</DT
2350 ><DD
2351 ><P
2352 >This pragma is only valid for targets that support external references. When in
2353 force, if the assembler sees an undefined symbol on the second pass, it will
2354 automatically define it as an external symbol. This automatic definition will
2355 apply for the remainder of the assembly process, even if the pragma is
2356 subsequently turned off. Because this behaviour would be potentially surprising,
2357 this pragma defaults to off.</P
2358 ><P
2359 >The primary use for this pragma is for projects that share a large number of
2360 symbols between source files. In such cases, it is impractical to enumerate
2361 all the external references in every source file. This allows the assembler
2362 and linker to do the heavy lifting while not preventing a particular source
2363 module from defining a local symbol of the same name as an external symbol
2364 if it does not need the external symbol. (This pragma will not cause an
2365 automatic external definition if there is already a locally defined symbol.)</P
2366 ><P
2367 >This pragma will often be specified on the command line for large projects.
2368 However, depending on the specific dynamics of the project, it may be sufficient
2369 for one or two files to use this pragma internally.</P
2370 ></DD
2371 ><DT
2372 >export</DT
2373 ><DD
2374 ><P
2375 >This pragma causes all symbols to be added to the export list
2376 automatically. This is useful when a large number of symbols need to be
2377 exported but you do not wish to include an EXPORT directive for all of them.
2378 This is often useful on the command line but might be useful even inline
2379 with the PRAGMA directive if a large number of symbols in a row are to be
2380 exported.</P
2381 ></DD
2382 ><DT
2383 >dollarlocal</DT
2384 ><DD
2385 ><P
2386 >When set, a "$" in a symbol makes it local. When not set, "$" does not
2387 cause a symbol to be local. It is set by default except when using the OS9
2388 target.</P
2389 ></DD
2390 ><DT
2391 >dollarnotlocal</DT
2392 ><DD
2393 ><P
2394 > This is the same as the "dollarlocal" pragma except its sense is
2395 reversed. That is, "dollarlocal" and "nodollarnotlocal" are equivalent and
2396 "nodollarlocal" and "dollarnotlocal" are equivalent. </P
2397 ></DD
2398 ><DT
2399 >pcaspcr</DT
2400 ><DD
2401 ><P
2402 > Normally, LWASM makes a distinction between PC and PCR in program
2403 counter relative addressing. In particular, the use of PC means an absolute
2404 offset from PC while PCR causes the assembler to calculate the offset to the
2405 specified operand and use that as the offset from PC. By setting this
2406 pragma, you can have PC treated the same as PCR. </P
2407 ></DD
2408 ><DT
2409 >shadow</DT
2410 ><DD
2411 ><P
2412 >When this pragma is in effect, it becomes possible to define a macro
2413 that matches an internal operation code. Thus, it makes it possible to
2414 redefine either CPU instructions or pseudo operations. Because this feature
2415 is of dubious utility, it is disabled by default.</P
2416 ></DD
2417 ><DT
2418 >nolist</DT
2419 ><DD
2420 ><P
2421 >Lines where this pragma is in effect will not appear in the assembly
2422 listing. Also, any symbols defined under this pragma will not show up in
2423 the symbol list. This is most useful in include files to avoid spamming the
2424 assembly listing with dozens, hundreds, or thousands of irrelevant
2425 symbols.</P
2426 ></DD
2427 ><DT
2428 >autobranchlength</DT
2429 ><DD
2430 ><P
2431 >One of the perennial annoyances for 6809 programmers is that the
2432 mneumonics for the short and long branch instructions are different (bxx vs.
2433 lbxx), which is at odds with the rest of the instruction set. This pragma
2434 is a solution to those annoying byte overflow errors that short branch
2435 instructions tend to aquire.</P
2436 ><P
2437 >When this pragma is in effect, which is not the default, whenever any
2438 relative branch instruction is used, its size will be automatically
2439 determined based on the actual distance to the destination. In other words,
2440 one can write code with long or short branches everywhere and the assembler
2441 will choose a size for the branch.</P
2442 ><P
2443 >Also, while this pragma is in effect, the &#62; and &#60; symbols can be used
2444 to force the branch size, analogous to their use for other instructions with
2445 &#60; forcing 8 bit offsets and &#62; forcing 16 bit offets.</P
2446 ><P
2447 >Because this pragma leads to source that is incompatible with other
2448 assemblers, it is strongly recommended that it be invoked using the PRAGMA
2449 directive within the source code rather than on the command line or via the
2450 *PRAGMA directive. This way, an error will be raised if someone tries to
2451 assemble the code under a different assembler.</P
2452 ></DD
2453 ><DT
2454 >nosymbolcase, symbolnocase</DT
2455 ><DD
2456 ><P
2457 >Any symbol defined while this pragma is in force will be treated as
2458 case insensitive, regardless whether the pragma is in force when the symbol
2459 is referenced.</P
2460 ><P
2461 >It is important to note that this pragma will not work as expected in
2462 all cases when using the object file assembly target. It is intended for
2463 use only when the assembler will be producing the final binary.</P
2464 ></DD
2465 ><DT
2466 >condundefzero</DT
2467 ><DD
2468 ><P
2469 >This pragma will cause the assembler to change the way it handles
2470 symbols in conditional expressions. Ordinarily, any symbol that is not
2471 defined prior to the conditional will throw an undefined symbol error. With
2472 this pragma in effect, symbols that are not yet defined at the point the
2473 conditional is encountered will be treated as zero.</P
2474 ><P
2475 >This is not the default because it encourages poor code design. One
2476 should use the "IFDEF" or "IFNDEF" conditionals to test for the presence of
2477 a symbol.</P
2478 ><P
2479 >It is important to note that if a symbol is defined but it does not
2480 yet evaluate to a constant value at the point where the conditional appears,
2481 the assembler will still complain about a non constant condition.</P
2482 ></DD
2483 ><DT
2484 >forwardrefmax</DT
2485 ><DD
2486 ><P
2487 >This pragma will disable forward reference optimization completely.
2488 Ordinarily, LWASM will attempt to select the shortest possible addressing
2489 mode for forward references. However, in many source files, especially
2490 those not using the PCR relative addressing modes, this optimization is
2491 pointless since the assembler will almost certainly settle on a 16 bit
2492 offset or address. If all variables in the direct page are defined before
2493 the main body of the code, the benefit of forward reference optimization
2494 almost certainly vanishes completely. However, the cost of doing that
2495 optimization remains and can result in a very long assembly time.</P
2496 ><P
2497 >Enabling this pragma will cause all forward references to use the
2498 maximum offset or address size, much the same has EDTASM and other pure
2499 two pass assemblers do. The side effect is that all line lengths and
2500 symbol values are fully resolved after the initial parsing pass and the
2501 amount of work to resolve everything becomes almost nil.</P
2502 ><P
2503 >While this pragma can be applied selectively to sections of source
2504 code (use *PRAGMA if doing so and compatibility with other assemblers
2505 is desired), it is likely more useful when provided as a command line
2506 pragma.</P
2507 ><P
2508 >It should be noted that the presence or absence of this pragma
2509 will not change the correctness of the generated code unless cycle counts
2510 or byte counts are critical (which they usually are not). It also will
2511 not override the operand size override prefixes (&lt; and &gt;). It only
2512 applies when the assembler is left to guess what the operand size is.</P
2513 ></DD
2514 ><DT
2515 >operandsizewarning</DT
2516 ><DD
2517 ><P
2518 >Enabling this pragma will cause LWASM to show a warning when it
2519 detects that a smaller addressing mode could be used for an instruction.
2520 This is particularly useful for finding places where long branches are used
2521 where short branches could be used instead. It will also show the warnings
2522 for indexing offsets (regardless of whether the operand size is
2523 forced).</P
2524 ><P
2525 >As of LWASM 4.16, no other checks are performed.</P
2526 ></DD
2527 ><DT
2528 >qrts</DT
2529 ><DD
2530 ><P
2531 >&#13;Enables the use of the ?RTS branch target. ?RTS is implemented to maintain
2532 compatibility with the MACRO-80c assembler. It works by searching backward
2533 in the code for an RTS instruction. If none is found, it inverts the branch
2534 logic and inserts an RTS following the branch instruction. Below you can
2535 see how a BMI (2B xx) has been assembled as a BPL *+1 (2A 01) to skip over an
2536 inserted RTS (39).</P
2537 ><PRE
2538 CLASS="PROGRAMLISTING"
2539 >1D1E 7D1D1D TST WHICH1
2540 1D21 2A0139 BMI ?RTS
2541 1D24 BD1D65 JSR INV</PRE
2542 ></DD
2543 ><DT
2544 >m80ext</DT
2545 ><DD
2546 ><P
2547 >&#13;This pragma (along with pragma qrts) enables some uncommon behaviors to
2548 accomodate The Micro Works MACRO-80c assembler from 1982. This assembler
2549 was used by a number of notable TRS-80 Color Computer applications and the
2550 goal of this pragma is to allow them to build identical binaries from
2551 unmodified, vintage source code.</P
2552 ><P
2553 >&#13;In m80ext mode, the handling of the "END" pseudo-op changes when used inside
2554 an include file. Instead of terminating all assembly, it merely stops
2555 processing of the current include file (this behavior matches the original
2556 Motorola 6809 assembler). In addition, loading an ASCII value with a single
2557 quote (e.g., LDA #'N) is extended to 16-bit registers (e.g., LDD #'NO).
2558 LWASM normally supports this via double quote and that is the proper use in
2559 modern code. Finally, the FCC pseudo-op is extended to handle FCB-like
2560 behavior after the closing delimiter:</P
2561 ><PRE
2562 CLASS="PROGRAMLISTING"
2563 > FCC "Greetings from 1982",13,0</PRE
2564 ></DD
2565 ><DT
2566 >testmode</DT
2567 ><DD
2568 ><P
2569 >&#13;This pragma is intended for internal testing purposes. In testmode, the
2570 assembler searches for a specially-formatted comment starting with a
2571 semicolon followed by a period. Immediately afterward are a list of hex
2572 bytes that the assembler is expected to generate. Likewise, if the
2573 assembler is expected to throw an error or warning on a given line, you can
2574 check by specifying "E:" followed by the error number. In this case the
2575 error is ignored and the assembler continues ignoring the line in question.&#13;</P
2576 ><PRE
2577 CLASS="PROGRAMLISTING"
2578 >1D1E 7D1D1D TST WHICH1 ;.7d1d1d
2579 1D21 2A0139 BMI ?RTS ;.2a0139
2580 1D24 1D24 FDB * ;.1d24
2581 1D26 xyz INV ;.E:32 (Error 32 is "Bad opcode")</PRE
2582 ></DD
2583 ></DL
2584 ></DIV
2585 ><P
2586 >As a convenience, each input file has a pragma state stack. This
2587 allows, through the use of *PRAGMAPUSH and *PRAGMAPOP, a file to change a
2588 pragma state and then restore it to the precise state it had previously.
2589 If, at the end of an input file, all pragma states have not been popped,
2590 they will be removed from the stack. Thus, it is critical to employ
2591 *PRAGMAPOP correctly. Because each input file has its own pragma stack,
2592 using *PRAGMAPUSH in one file and *PRAGMAPOP in another file will not
2593 work.</P
2594 ><P
2595 >Pragma stacks are more useful in include files, in particular in
2596 conjunction with the nolist pragma. One can push the state of the nolist
2597 pragma, engage the nolist pragma, and then pop the state of the nolist
2598 pragma at the end of the include file. This will cause the entire include
2599 file to operate under the nolist pragma. However, if the file is included
2600 while nolist is already engaged, it will not undo that state.</P
2601 ></DIV
2602 ><DIV
2603 CLASS="SECTION"
2604 ><HR><H2
2605 CLASS="SECTION"
2606 ><A
2607 NAME="CONVINST"
2608 >3.11. Convenience Instructions</A
2609 ></H2
2610 ><P
2611 >&#13;Similar to the 6800 compatibility instructions (pragma 6800compat) these
2612 pragma 6809conv and pragma 6309conv enable convenience extensions to the
2613 6809 and 6309 instruction set. Originally intended for compatibility with
2614 the MACRO-80c assembler, these have proven useful in large codebases that
2615 target both the 6809 and the 6309.</P
2616 ><P
2617 >&#13;The 6809 extensions are straightforward with the exception of "TSTD" which
2618 assembles as "STD -2,S". A benefit of using these is they will "just work"
2619 and take on their 6309 equivalent when you enable 6309 assembly mode.
2620 Supported instructions: ASRD, CLRD, COMD, LSLD, LSRD, NEGD, TSTD.</P
2621 ><P
2622 >&#13;6309 extensions are based on common patterns described by Chris Burke and
2623 Darren Atkinson in their 6309 documentation and include the following
2624 instructions: ASRQ, CLRQ, COMQ, LSLE, LSLF, LSLQ, LSRQ, NEGE,
2625 NEGF, NEGW, NEGQ, TSTQ.</P
2626 ></DIV
2627 ><DIV
2628 CLASS="SECTION"
2629 ><HR><H2
2630 CLASS="SECTION"
2631 ><A
2632 NAME="AEN805"
2633 >3.12. Cycle Counts</A
2634 ></H2
2635 ><P
2636 >&#13;The following options for displaying cycle counts in listings are provided.
2637 These options are enabled from pragmas on the command line or in the
2638 assembly files themselves. For compatibility with other assemblers you can
2639 use the "OPT" keyword in addition to "PRAGMA."</P
2640 ><PRE
2641 CLASS="PROGRAMLISTING"
2642 >opt c - enable cycle counts: [8]
2643 opt cd - enable detailed cycle counts breaking down addressing modes: [5+3]
2644 opt ct - show a running subtotal of cycles
2645 opt cc - clear the running subtotal</PRE
2646 ><P
2647 >&#13;The assembler supports both 6809 as well as native-mode 6309 cycle counts.
2648 In 6309 mode the counts are displayed in parenthesis instead of brackets.
2649 In addition, some operations have a variable cycle count. In this case a
2650 "+?" is displayed to alert the reader. Sample output is shown below.</P
2651 ><PRE
2652 CLASS="PROGRAMLISTING"
2653 >266f 7d25e2 (window.asm):00313 [7] 7 move tst putflg
2654 2672 2602 (window.asm):00314 [5] 12 bne a@
2655 2674 1e13 (window.asm):00315 [8] 20 exg x,u
2656 2676 0dd6 (window.asm):00316 [6] 26 a@ tst is6309
2657 2678 2618 (window.asm):00317 [5] 31 bne exit@
2658 (window.asm):00318 opt 6309
2659 267a 10860085 (window.asm):00319 (4) 35 b@ ldw #133
2660 267e 113813 (window.asm):00320 (6+?) 41 tfm x+,u+
2661 2681 30881b (window.asm):00321 (4+1) 46 leax 27,x
2662 2684 33c81b (window.asm):00322 (4+1) 51 leau 27,u
2663 2687 4a (window.asm):00323 (1) 52 deca
2664 2688 26f0 (window.asm):00324 (5) 57 bne b@</PRE
2665 ></DIV
2666 ></DIV
2667 ><DIV
2668 CLASS="CHAPTER"
2669 ><HR><H1
2670 ><A
2671 NAME="AEN811"
2672 ></A
2673 >Chapter 4. LWLINK</H1
2674 ><P
2675 >The LWTOOLS linker is called LWLINK. This chapter documents the various features
2676 of the linker.</P
2677 ><DIV
2678 CLASS="SECTION"
2679 ><HR><H2
2680 CLASS="SECTION"
2681 ><A
2682 NAME="AEN814"
2683 >4.1. Command Line Options</A
2684 ></H2
2685 ><P
2686 >The binary for LWLINK is called "lwlink". Note that the binary is in lower
2687 case. lwlink takes the following command line arguments.</P
2688 ><P
2689 ></P
2690 ><DIV
2691 CLASS="VARIABLELIST"
2692 ><DL
2693 ><DT
2694 ><CODE
2695 CLASS="OPTION"
2696 >--decb</CODE
2697 >, <CODE
2698 CLASS="OPTION"
2699 >-b</CODE
2700 ></DT
2701 ><DD
2702 ><P
2703 >Selects the DECB output format target. This is equivalent to <CODE
2704 CLASS="OPTION"
2705 >--format=decb</CODE
2706 ></P
2707 ></DD
2708 ><DT
2709 ><CODE
2710 CLASS="OPTION"
2711 >--output=FILE</CODE
2712 >, <CODE
2713 CLASS="OPTION"
2714 >-o FILE</CODE
2715 ></DT
2716 ><DD
2717 ><P
2718 >This option specifies the name of the output file. If not specified, the
2719 default is <CODE
2720 CLASS="OPTION"
2721 >a.out</CODE
2722 >.</P
2723 ></DD
2724 ><DT
2725 ><CODE
2726 CLASS="OPTION"
2727 >--format=TYPE</CODE
2728 >, <CODE
2729 CLASS="OPTION"
2730 >-f TYPE</CODE
2731 ></DT
2732 ><DD
2733 ><P
2734 >This option specifies the output format. Valid values are <CODE
2735 CLASS="OPTION"
2736 >decb</CODE
2737 >
2738 and <CODE
2739 CLASS="OPTION"
2740 >raw</CODE
2741 ></P
2742 ></DD
2743 ><DT
2744 ><CODE
2745 CLASS="OPTION"
2746 >--raw</CODE
2747 >, <CODE
2748 CLASS="OPTION"
2749 >-r</CODE
2750 ></DT
2751 ><DD
2752 ><P
2753 >This option specifies the raw output format.
2754 It is equivalent to <CODE
2755 CLASS="OPTION"
2756 >--format=raw</CODE
2757 >
2758 and <CODE
2759 CLASS="OPTION"
2760 >-f raw</CODE
2761 ></P
2762 ></DD
2763 ><DT
2764 ><CODE
2765 CLASS="OPTION"
2766 >--script=FILE</CODE
2767 >, <CODE
2768 CLASS="OPTION"
2769 >-s</CODE
2770 ></DT
2771 ><DD
2772 ><P
2773 >This option allows specifying a linking script to override the linker's
2774 built in defaults.</P
2775 ></DD
2776 ><DT
2777 ><CODE
2778 CLASS="OPTION"
2779 >--section-base=SECT=BASE</CODE
2780 ></DT
2781 ><DD
2782 ><P
2783 >Cause section SECT to load at base address BASE. This will be prepended
2784 to the built-in link script. It is ignored if a link script is provided.</P
2785 ></DD
2786 ><DT
2787 ><CODE
2788 CLASS="OPTION"
2789 >--map=FILE</CODE
2790 >, <CODE
2791 CLASS="OPTION"
2792 >-m FILE</CODE
2793 ></DT
2794 ><DD
2795 ><P
2796 >This will output a description of the link result to FILE.</P
2797 ></DD
2798 ><DT
2799 ><CODE
2800 CLASS="OPTION"
2801 >--library=LIBSPEC</CODE
2802 >, <CODE
2803 CLASS="OPTION"
2804 >-l LIBSPEC</CODE
2805 ></DT
2806 ><DD
2807 ><P
2808 >Load a library using the library search path. If LIBSPEC is prefixed with a
2809 colon (":"), then LIBSPEC is the precise filename to be searched for in the
2810 library path. Otherwise, LIBSPEC will have "lib" prepended and ".a" appended.</P
2811 ></DD
2812 ><DT
2813 ><CODE
2814 CLASS="OPTION"
2815 >--library-path=DIR</CODE
2816 >, <CODE
2817 CLASS="OPTION"
2818 >-L DIR</CODE
2819 ></DT
2820 ><DD
2821 ><P
2822 >Add DIR to the library search path.</P
2823 ></DD
2824 ><DT
2825 ><CODE
2826 CLASS="OPTION"
2827 >--debug</CODE
2828 >, <CODE
2829 CLASS="OPTION"
2830 >-d</CODE
2831 ></DT
2832 ><DD
2833 ><P
2834 >This option increases the debugging level. It is only useful for LWTOOLS
2835 developers.</P
2836 ></DD
2837 ><DT
2838 ><CODE
2839 CLASS="OPTION"
2840 >--help</CODE
2841 >, <CODE
2842 CLASS="OPTION"
2843 >-?</CODE
2844 ></DT
2845 ><DD
2846 ><P
2847 >This provides a listing of command line options and a brief description
2848 of each.</P
2849 ></DD
2850 ><DT
2851 ><CODE
2852 CLASS="OPTION"
2853 >--usage</CODE
2854 ></DT
2855 ><DD
2856 ><P
2857 >This will display a usage summary
2858 of each command line option.</P
2859 ></DD
2860 ><DT
2861 ><CODE
2862 CLASS="OPTION"
2863 >--version</CODE
2864 >, <CODE
2865 CLASS="OPTION"
2866 >-V</CODE
2867 ></DT
2868 ><DD
2869 ><P
2870 >This will display the version of LWLINK.</P
2871 ></DD
2872 ></DL
2873 ></DIV
2874 ></DIV
2875 ><DIV
2876 CLASS="SECTION"
2877 ><HR><H2
2878 CLASS="SECTION"
2879 ><A
2880 NAME="AEN911"
2881 >4.2. Linker Operation</A
2882 ></H2
2883 ><P
2884 >&#13;LWLINK takes one or more files in supported input formats and links them
2885 into a single binary. Currently supported formats are the LWTOOLS object
2886 file format and the archive format used by LWAR. While the precise method is
2887 slightly different, linking can be conceptualized as the following steps.&#13;</P
2888 ><P
2889 ></P
2890 ><OL
2891 TYPE="1"
2892 ><LI
2893 ><P
2894 >First, the linker loads a linking script. If no script is specified, it
2895 loads a built-in default script based on the output format selected. This
2896 script tells the linker how to lay out the various sections in the final
2897 binary.</P
2898 ></LI
2899 ><LI
2900 ><P
2901 >Next, the linker reads all the input files into memory. At this time, it
2902 flags any format errors in those files. It constructs a table of symbols
2903 for each object at this time.</P
2904 ></LI
2905 ><LI
2906 ><P
2907 >The linker then proceeds with organizing the sections loaded from each file
2908 according to the linking script. As it does so, it is able to assign addresses
2909 to each symbol defined in each object file. At this time, the linker may
2910 also collapse different instances of the same section name into a single
2911 section by appending the data from each subsequent instance of the section
2912 to the first instance of the section.</P
2913 ></LI
2914 ><LI
2915 ><P
2916 >Next, the linker looks through every object file for every incomplete reference.
2917 It then attempts to fully resolve that reference. If it cannot do so, it
2918 throws an error. Once a reference is resolved, the value is placed into
2919 the binary code at the specified section. It should be noted that an
2920 incomplete reference can reference either a symbol internal to the object
2921 file or an external symbol which is in the export list of another object
2922 file.</P
2923 ></LI
2924 ><LI
2925 ><P
2926 >If all of the above steps are successful, the linker opens the output file
2927 and actually constructs the binary.</P
2928 ></LI
2929 ></OL
2930 ></DIV
2931 ><DIV
2932 CLASS="SECTION"
2933 ><HR><H2
2934 CLASS="SECTION"
2935 ><A
2936 NAME="AEN925"
2937 >4.3. Linking Scripts</A
2938 ></H2
2939 ><P
2940 >A linker script is used to instruct the linker about how to assemble the
2941 various sections into a completed binary. It consists of a series of
2942 directives which are considered in the order they are encountered.</P
2943 ><P
2944 >The sections will appear in the resulting binary in the order they are
2945 specified in the script file. If a referenced section is not found, the linker will behave as though the
2946 section did exist but had a zero size, no relocations, and no exports.
2947 A section should only be referenced once. Any subsequent references will have
2948 an undefined effect.</P
2949 ><P
2950 >All numbers are in linking scripts are specified in hexadecimal. All directives
2951 are case sensitive although the hexadecimal numbers are not.</P
2952 ><P
2953 >A section name can be specified as a "*", then any section not
2954 already matched by the script will be matched. The "*" can be followed
2955 by a comma and a flag to narrow the section down slightly, also.
2956 If the flag is "!bss", then any section that is not flagged as a bss section
2957 will be matched. If the flag is "bss", then any section that is flagged as
2958 bss will be matched.</P
2959 ><P
2960 >The following directives are understood in a linker script.</P
2961 ><P
2962 ></P
2963 ><DIV
2964 CLASS="VARIABLELIST"
2965 ><DL
2966 ><DT
2967 >sectopt <CODE
2968 CLASS="PARAMETER"
2969 >section</CODE
2970 > padafter <CODE
2971 CLASS="PARAMETER"
2972 >byte,...</CODE
2973 ></DT
2974 ><DD
2975 ><P
2976 >&#13;This will cause the linker to append the specified list of byte values
2977 (specified in hexadecimal separated by commas) to the end of the named
2978 section. This is done once all instances of the specified section are
2979 collected together. This has no effect if the specified section does not
2980 appear anywhere in any of the objects specified for linking. &#13;</P
2981 ><P
2982 >&#13;If code depends on the presence of this padding somewhere, it is sufficient
2983 to include an empty section of the specified name in the object that depends
2984 on it.&#13;</P
2985 ></DD
2986 ><DT
2987 >define basesympat <CODE
2988 CLASS="PARAMETER"
2989 >string</CODE
2990 ></DT
2991 ><DD
2992 ><P
2993 >&#13;This causes the linker to define a symbol for the ultimate base address of
2994 each section using the pattern specified by <CODE
2995 CLASS="PARAMETER"
2996 >string</CODE
2997 >.
2998 In the string, %s can appear exactly once and will be replaced with the
2999 section name. The base address is calculated after all instances of each
3000 section have been collapsed together.&#13;</P
3001 ><P
3002 >&#13;It should be noted that if none of the objects to be linked contains a
3003 particular section name, there will be no base symbol defined for it, even
3004 if it is listed explicitly in the link script. If code depends on the
3005 presence of these symbols, it is sufficient to include an empty section of
3006 the specified name in the object that depends on it.&#13;</P
3007 ><P
3008 > If the pattern resolves to the same string for multiple
3009 sections, the results are undefined.&#13;</P
3010 ></DD
3011 ><DT
3012 >define lensympat <CODE
3013 CLASS="PARAMETER"
3014 >string</CODE
3015 ></DT
3016 ><DD
3017 ><P
3018 >&#13;This causes the linker to define a symbol for the ultimate length of each
3019 section using the pattern specified by <CODE
3020 CLASS="PARAMETER"
3021 >string</CODE
3022 >. In
3023 the string, %s can appear exactly once and will be replaced with the section
3024 name. The length is calculated after all instances of a section have been
3025 collapsed together.&#13;</P
3026 ><P
3027 >&#13;It should be noted that if none of the objects to be linked contains a
3028 particular section name, there will be no length symbol defined for it, even
3029 if it is listed explicitly in the link script. If code depends on the
3030 presence of these symbols, it is sufficient to include an empty section of
3031 the specified name in the object that depends on it.&#13;</P
3032 ><P
3033 >If the pattern resolves to the same string for multiple
3034 sections, the results are undefined.&#13;</P
3035 ></DD
3036 ><DT
3037 >section <CODE
3038 CLASS="PARAMETER"
3039 >name</CODE
3040 > load <CODE
3041 CLASS="PARAMETER"
3042 >addr</CODE
3043 ></DT
3044 ><DD
3045 ><P
3046 >&#13;This causes the section <CODE
3047 CLASS="PARAMETER"
3048 >name</CODE
3049 > to load at
3050 <CODE
3051 CLASS="PARAMETER"
3052 >addr</CODE
3053 >. For the raw target, only one "load at" entry is
3054 allowed for non-bss sections and it must be the first one. For raw targets,
3055 it affects the addresses the linker assigns to symbols but has no other
3056 affect on the output. bss sections may all have separate load addresses but
3057 since they will not appear in the binary anyway, this is okay.</P
3058 ><P
3059 >For the decb target, each "load" entry will cause a new "block" to be
3060 output to the binary which will contain the load address. It is legal for
3061 sections to overlap in this manner - the linker assumes the loader will sort
3062 everything out.</P
3063 ></DD
3064 ><DT
3065 >section <CODE
3066 CLASS="PARAMETER"
3067 >name</CODE
3068 > high <CODE
3069 CLASS="PARAMETER"
3070 >addr</CODE
3071 ></DT
3072 ><DD
3073 ><P
3074 >&#13;This causes the section <CODE
3075 CLASS="PARAMETER"
3076 >name</CODE
3077 > to load with its end
3078 address just below <CODE
3079 CLASS="PARAMETER"
3080 >addr</CODE
3081 >. Subsequent sections are
3082 loaded at progressively lower addresses. This may lead to inefficient file
3083 encoding for some targets. As of this writing, it will also almost
3084 certainly do the wrong thing for a raw target.&#13;</P
3085 ><P
3086 >&#13;This is useful for aligning a block of code with high memory. As an
3087 example, if the total size of a section is $100 bytes and a high address of
3088 $FE00 is specified, the section will actually load at $FD00.&#13;</P
3089 ></DD
3090 ><DT
3091 >section <CODE
3092 CLASS="PARAMETER"
3093 >name</CODE
3094 ></DT
3095 ><DD
3096 ><P
3097 >&#13;This will cause the section <CODE
3098 CLASS="PARAMETER"
3099 >name</CODE
3100 > to load after the previously listed
3101 section.</P
3102 ></DD
3103 ><DT
3104 >entry <CODE
3105 CLASS="PARAMETER"
3106 >addr or sym</CODE
3107 ></DT
3108 ><DD
3109 ><P
3110 >This will cause the execution address (entry point) to be the address
3111 specified (in hex) or the specified symbol name. The symbol name must
3112 match a symbol that is exported by one of the object files being linked.
3113 This has no effect for targets that do not encode the entry point into the
3114 resulting file. If not specified, the entry point is assumed to be address 0
3115 which is probably not what you want. The default link scripts for targets
3116 that support this directive automatically starts at the beginning of the
3117 first section (usually "init" or "code") that is emitted in the binary.</P
3118 ></DD
3119 ><DT
3120 >pad <CODE
3121 CLASS="PARAMETER"
3122 >size</CODE
3123 ></DT
3124 ><DD
3125 ><P
3126 >This will cause the output file to be padded with NUL bytes to be exactly
3127 <CODE
3128 CLASS="PARAMETER"
3129 >size</CODE
3130 > bytes in length. This only makes sense for a raw target.</P
3131 ></DD
3132 ></DL
3133 ></DIV
3134 ></DIV
3135 ><DIV
3136 CLASS="SECTION"
3137 ><HR><H2
3138 CLASS="SECTION"
3139 ><A
3140 NAME="AEN991"
3141 >4.4. Format Specific Linking Notes</A
3142 ></H2
3143 ><P
3144 >Some formats require special information to be able to generate actual
3145 binaries. If the specific format you are interested in is not listed in
3146 this section, then there is nothing special you need to know about to create
3147 a final binary.</P
3148 ><DIV
3149 CLASS="SECTION"
3150 ><HR><H3
3151 CLASS="SECTION"
3152 ><A
3153 NAME="AEN994"
3154 >4.4.1. OS9 Modules</A
3155 ></H3
3156 ><P
3157 >OS9 modules need to embed several items into the module header. These
3158 items are the type of module, the langauge of the module, the module
3159 attributes, the module revision number, the data size (bss), and the
3160 execution offset. These are all either calculated or default to reasonable
3161 values.</P
3162 ><P
3163 >The data size is calcuated as the sum of all sections named "bss" or
3164 ".bss" in all object files that are linked together.</P
3165 ><P
3166 >The execution offset is calculated from the address of the special
3167 symbol "__start" which must be an exported (external) symbol in one of the
3168 objects to be linked.</P
3169 ><P
3170 >The type defaults to "Prgrm" or "Program module". The language
3171 defaults to "Objct" or "6809 object code". Attributes default to enabling
3172 the re-entrant flag. And finally, the revision defaults to zero.</P
3173 ><P
3174 >The embedded module name is the output filename. If the output
3175 filename includes more than just the filename, this will probably not be
3176 what you want.</P
3177 ><P
3178 >The type, language, attributes, revision, and module name can all be
3179 overridden by providing a special section in exactly one of the object files
3180 to be linked. This section is called "__os9" (note the two underscores).
3181 To override the type, language, attributes, or revision values, define a
3182 non-exported symbol in this section called "type", "lang", "attr", or "rev"
3183 respectively. Any other symbols defined are ignored. To override the
3184 module name, include as the only actual code in the section a NUL terminated
3185 string (the FCN directive is useful for this). If there is no code in the
3186 section or it beings with a NUL, the default name will be used. Any of the
3187 preceeding that are not defined in the special section will retain their
3188 default values.</P
3189 ><P
3190 >The built-in link script for OS9 modules will place the following
3191 sections, in order, in the module: "code", ".text", "data", ".data". It
3192 will merge all sections with the name "bss" or ".bss" into the "data"
3193 section. All other section names are ignored. What this means is that you
3194 must define your data variables in the a section called "bss" or ".bss" even
3195 though you will be refencing them all as offsets from U. This does have the
3196 unpleasant side effect that all BSS references will end up being 16 bit
3197 offsets because the assembler cannot know what the offset will be once the
3198 linker is finished its work. Thus, if the tightest possible code is
3199 required, having LWASM directly output the module is a better choice.</P
3200 ><P
3201 >While the built-in link script is probably sufficient for most
3202 purposes, you can provide your own script. If you provide a custom link
3203 script, you must start your code and data sections at location 000D to
3204 accommodate the module header. Otherwise, you will have an incorrect
3205 location for the execution offset. You must use the ENTRY directive in the
3206 script to define the entry point for the module.</P
3207 ><P
3208 >It should also be obvious from the above that you cannot mix the bss
3209 (rmb) definitions with the module code when linking separately. Those
3210 familiar with typical module creation will probably find this an unpleasant
3211 difference but it is unavoidable.</P
3212 ><P
3213 >It should also be noted that direct page references should also be
3214 avoided because you cannot know ahead of time whether the linker is going to
3215 end up putting a particular variable in the first 256 bytes of the module's
3216 data space. If, however, you know for certain you will have less than 256
3217 bytes of defined data space across all of the object files that will be
3218 linked, you can instead use forced DP addressing for your data addresses
3219 instead of the ,u notation. When linking with 3rd party libraries, this
3220 practice should be avoided. Also, when creating libraries, always use the
3221 offset from U technique.</P
3222 ></DIV
3223 ></DIV
3224 ></DIV
3225 ><DIV
3226 CLASS="CHAPTER"
3227 ><HR><H1
3228 ><A
3229 NAME="AEN1006"
3230 ></A
3231 >Chapter 5. Libraries and LWAR</H1
3232 ><P
3233 >LWTOOLS also includes a tool for managing libraries. These are analogous to
3234 the static libraries created with the "ar" tool on POSIX systems. Each library
3235 file contains one or more object files. The linker will treat the object
3236 files within a library as though they had been specified individually on
3237 the command line except when resolving external references. External references
3238 are looked up first within the object files within the library and then, if
3239 not found, the usual lookup based on the order the files are specified on
3240 the command line occurs.</P
3241 ><P
3242 >The tool for creating these libary files is called LWAR.</P
3243 ><DIV
3244 CLASS="SECTION"
3245 ><HR><H2
3246 CLASS="SECTION"
3247 ><A
3248 NAME="AEN1010"
3249 >5.1. Command Line Options</A
3250 ></H2
3251 ><P
3252 >The binary for LWAR is called "lwar". Note that the binary is in lower
3253 case. The options lwar understands are listed below. For archive manipulation
3254 options, the first non-option argument is the name of the archive. All other
3255 non-option arguments are the names of files to operate on.</P
3256 ><P
3257 ></P
3258 ><DIV
3259 CLASS="VARIABLELIST"
3260 ><DL
3261 ><DT
3262 ><CODE
3263 CLASS="OPTION"
3264 >--add</CODE
3265 >, <CODE
3266 CLASS="OPTION"
3267 >-a</CODE
3268 ></DT
3269 ><DD
3270 ><P
3271 >This option specifies that an archive is going to have files added to it.
3272 If the archive does not already exist, it is created. New files are added
3273 to the end of the archive.</P
3274 ></DD
3275 ><DT
3276 ><CODE
3277 CLASS="OPTION"
3278 >--create</CODE
3279 >, <CODE
3280 CLASS="OPTION"
3281 >-c</CODE
3282 ></DT
3283 ><DD
3284 ><P
3285 >This option specifies that an archive is going to be created and have files
3286 added to it. If the archive already exists, it is truncated.</P
3287 ></DD
3288 ><DT
3289 ><CODE
3290 CLASS="OPTION"
3291 >--merge</CODE
3292 >, <CODE
3293 CLASS="OPTION"
3294 >-m</CODE
3295 ></DT
3296 ><DD
3297 ><P
3298 >If specified, any files specified to be added to an archive will be checked
3299 to see if they are archives themselves. If so, their constituent members are
3300 added to the archive. This is useful for avoiding archives containing archives.</P
3301 ></DD
3302 ><DT
3303 ><CODE
3304 CLASS="OPTION"
3305 >--list</CODE
3306 >, <CODE
3307 CLASS="OPTION"
3308 >-l</CODE
3309 ></DT
3310 ><DD
3311 ><P
3312 >This will display a list of the files contained in the archive.</P
3313 ></DD
3314 ><DT
3315 ><CODE
3316 CLASS="OPTION"
3317 >--debug</CODE
3318 >, <CODE
3319 CLASS="OPTION"
3320 >-d</CODE
3321 ></DT
3322 ><DD
3323 ><P
3324 >This option increases the debugging level. It is only useful for LWTOOLS
3325 developers.</P
3326 ></DD
3327 ><DT
3328 ><CODE
3329 CLASS="OPTION"
3330 >--help</CODE
3331 >, <CODE
3332 CLASS="OPTION"
3333 >-?</CODE
3334 ></DT
3335 ><DD
3336 ><P
3337 >This provides a listing of command line options and a brief description
3338 of each.</P
3339 ></DD
3340 ><DT
3341 ><CODE
3342 CLASS="OPTION"
3343 >--usage</CODE
3344 ></DT
3345 ><DD
3346 ><P
3347 >This will display a usage summary
3348 of each command line option.</P
3349 ></DD
3350 ><DT
3351 ><CODE
3352 CLASS="OPTION"
3353 >--version</CODE
3354 >, <CODE
3355 CLASS="OPTION"
3356 >-V</CODE
3357 ></DT
3358 ><DD
3359 ><P
3360 >This will display the version of LWLINK.
3361 of each.</P
3362 ></DD
3363 ></DL
3364 ></DIV
3365 ></DIV
3366 ></DIV
3367 ><DIV
3368 CLASS="CHAPTER"
3369 ><HR><H1
3370 ><A
3371 NAME="OBJCHAP"
3372 ></A
3373 >Chapter 6. Object Files</H1
3374 ><P
3375 >LWTOOLS uses a proprietary object file format. It is proprietary in the sense
3376 that it is specific to LWTOOLS, not that it is a hidden format. It would be
3377 hard to keep it hidden in an open source tool chain anyway. This chapter
3378 documents the object file format.</P
3379 ><P
3380 >An object file consists of a series of sections each of which contains a
3381 list of exported symbols, a list of incomplete references, and a list of
3382 "local" symbols which may be used in calculating incomplete references. Each
3383 section will obviously also contain the object code.</P
3384 ><P
3385 >Exported symbols must be completely resolved to an address within the
3386 section it is exported from. That is, an exported symbol must be a constant
3387 rather than defined in terms of other symbols.</P
3388 ><P
3389 >Each object file starts with a magic number and version number. The magic
3390 number is the string "LWOBJ16" for this 16 bit object file format. The only
3391 defined version number is currently 0. Thus, the first 8 bytes of the object
3392 file are <FONT
3393 COLOR="RED"
3394 >4C574F424A313600</FONT
3395 ></P
3396 ><P
3397 >Each section has the following items in order:</P
3398 ><P
3399 ></P
3400 ><UL
3401 ><LI
3402 ><P
3403 >section name</P
3404 ></LI
3405 ><LI
3406 ><P
3407 >flags</P
3408 ></LI
3409 ><LI
3410 ><P
3411 >list of local symbols (and addresses within the section)</P
3412 ></LI
3413 ><LI
3414 ><P
3415 >list of exported symbols (and addresses within the section)</P
3416 ></LI
3417 ><LI
3418 ><P
3419 >list of incomplete references along with the expressions to calculate them</P
3420 ></LI
3421 ><LI
3422 ><P
3423 >the actual object code (for non-BSS sections)</P
3424 ></LI
3425 ></UL
3426 ><P
3427 >The section starts with the name of the section with a NUL termination
3428 followed by a series of flag bytes terminated by NUL. There are only two
3429 flag bytes defined. A NUL (0) indicates no more flags and a value of 1
3430 indicates the section is a BSS section. For a BSS section, no actual
3431 code is included in the object file.</P
3432 ><P
3433 >Either a NULL section name or end of file indicate the presence of no more
3434 sections.</P
3435 ><P
3436 >Each entry in the exported and local symbols table consists of the symbol
3437 (NUL terminated) followed by two bytes which contain the value in big endian
3438 order. The end of a symbol table is indicated by a NULL symbol name.</P
3439 ><P
3440 >Each entry in the incomplete references table consists of an expression
3441 followed by a 16 bit offset where the reference goes. Expressions are
3442 defined as a series of terms up to an "end of expression" term. Each term
3443 consists of a single byte which identifies the type of term (see below)
3444 followed by any data required by the term. Then end of the list is flagged
3445 by a NULL expression (only an end of expression term).</P
3446 ><DIV
3447 CLASS="TABLE"
3448 ><A
3449 NAME="AEN1093"
3450 ></A
3451 ><P
3452 ><B
3453 >Table 6-1. Object File Term Types</B
3454 ></P
3455 ><TABLE
3456 BORDER="1"
3457 FRAME="border"
3458 CLASS="CALSTABLE"
3459 ><COL><COL><THEAD
3460 ><TR
3461 ><TH
3462 >TERMTYPE</TH
3463 ><TH
3464 >Meaning</TH
3465 ></TR
3466 ></THEAD
3467 ><TBODY
3468 ><TR
3469 ><TD
3470 >00</TD
3471 ><TD
3472 >end of expression</TD
3473 ></TR
3474 ><TR
3475 ><TD
3476 >01</TD
3477 ><TD
3478 >integer (16 bit in big endian order follows)</TD
3479 ></TR
3480 ><TR
3481 ><TD
3482 >02</TD
3483 ><TD
3484 > external symbol reference (NUL terminated symbol name follows)</TD
3485 ></TR
3486 ><TR
3487 ><TD
3488 >03</TD
3489 ><TD
3490 >local symbol reference (NUL terminated symbol name follows)</TD
3491 ></TR
3492 ><TR
3493 ><TD
3494 >04</TD
3495 ><TD
3496 >operator (1 byte operator number)</TD
3497 ></TR
3498 ><TR
3499 ><TD
3500 >05</TD
3501 ><TD
3502 >section base address reference</TD
3503 ></TR
3504 ><TR
3505 ><TD
3506 >FF</TD
3507 ><TD
3508 >This term will set flags for the expression. Each one of these terms will set a single flag. All of them should be specified first in an expression. If they are not, the behaviour is undefined. The byte following is the flag. Flag 01 indicates an 8 bit relocation. Flag 02 indicates a zero-width relocation (see the EXTDEP pseudo op in LWASM).</TD
3509 ></TR
3510 ></TBODY
3511 ></TABLE
3512 ></DIV
3513 ><P
3514 >External references are resolved using other object files while local
3515 references are resolved using the local symbol table(s) from this file. This
3516 allows local symbols that are not exported to have the same names as
3517 exported symbols or external references.</P
3518 ><DIV
3519 CLASS="TABLE"
3520 ><A
3521 NAME="AEN1123"
3522 ></A
3523 ><P
3524 ><B
3525 >Table 6-2. Object File Operator Numbers</B
3526 ></P
3527 ><TABLE
3528 BORDER="1"
3529 FRAME="border"
3530 CLASS="CALSTABLE"
3531 ><COL><COL><THEAD
3532 ><TR
3533 ><TH
3534 >Number</TH
3535 ><TH
3536 >Operator</TH
3537 ></TR
3538 ></THEAD
3539 ><TBODY
3540 ><TR
3541 ><TD
3542 >01</TD
3543 ><TD
3544 >addition (+)</TD
3545 ></TR
3546 ><TR
3547 ><TD
3548 >02</TD
3549 ><TD
3550 >subtraction (-)</TD
3551 ></TR
3552 ><TR
3553 ><TD
3554 >03</TD
3555 ><TD
3556 >multiplication (*)</TD
3557 ></TR
3558 ><TR
3559 ><TD
3560 >04</TD
3561 ><TD
3562 >division (/)</TD
3563 ></TR
3564 ><TR
3565 ><TD
3566 >05</TD
3567 ><TD
3568 >modulus (%)</TD
3569 ></TR
3570 ><TR
3571 ><TD
3572 >06</TD
3573 ><TD
3574 >integer division (\) (same as division)</TD
3575 ></TR
3576 ><TR
3577 ><TD
3578 >07</TD
3579 ><TD
3580 >bitwise and</TD
3581 ></TR
3582 ><TR
3583 ><TD
3584 >08</TD
3585 ><TD
3586 >bitwise or</TD
3587 ></TR
3588 ><TR
3589 ><TD
3590 >09</TD
3591 ><TD
3592 >bitwise xor</TD
3593 ></TR
3594 ><TR
3595 ><TD
3596 >0A</TD
3597 ><TD
3598 >boolean and</TD
3599 ></TR
3600 ><TR
3601 ><TD
3602 >0B</TD
3603 ><TD
3604 >boolean or</TD
3605 ></TR
3606 ><TR
3607 ><TD
3608 >0C</TD
3609 ><TD
3610 >unary negation, 2's complement (-)</TD
3611 ></TR
3612 ><TR
3613 ><TD
3614 >0D</TD
3615 ><TD
3616 >unary 1's complement (^)</TD
3617 ></TR
3618 ></TBODY
3619 ></TABLE
3620 ></DIV
3621 ><P
3622 >An expression is represented in a postfix manner with both operands for
3623 binary operators preceding the operator and the single operand for unary
3624 operators preceding the operator.</P
3625 ></DIV
3626 ></DIV
3627 ></BODY
3628 ></HTML
3629 >