Mercurial > hg > index.cgi

comparison docs/manual/manual.html @ 153:83b7b4ce3bbd

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