Mercurial > hg-old > index.cgi

comparison doc/manual/manual.html @ 272:d5392bb5da3c 2.5

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