Mercurial > hg-old > index.cgi

comparison doc/manual/manual.html @ 421:3c2e1f24cc7d 3.0-beta2

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