Mercurial > hg-old > index.cgi

comparison doc/manual/manual.html @ 153:ffef3ea07399 2.1 2.1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Preparing for release
author lost
date Fri, 30 Jan 2009 04:32:55 +0000
parents
children
comparison
equal deleted inserted replaced
152:6bd4755d224f 153:ffef3ea07399
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 >Object Files</A
81 ></DT
82 ></DL
83 ></DD
84 ><DT
85 >3. <A
86 HREF="#AEN35"
87 >LWASM</A
88 ></DT
89 ><DD
90 ><DL
91 ><DT
92 >3.1. <A
93 HREF="#AEN38"
94 >Command Line Options</A
95 ></DT
96 ><DT
97 >3.2. <A
98 HREF="#AEN121"
99 >Dialects</A
100 ></DT
101 ><DT
102 >3.3. <A
103 HREF="#AEN125"
104 >Source Format</A
105 ></DT
106 ><DT
107 >3.4. <A
108 HREF="#AEN133"
109 >Symbols</A
110 ></DT
111 ><DT
112 >3.5. <A
113 HREF="#AEN137"
114 >Numbers and Expressions</A
115 ></DT
116 ><DT
117 >3.6. <A
118 HREF="#AEN144"
119 >Assembler Directives</A
120 ></DT
121 ><DD
122 ><DL
123 ><DT
124 >3.6.1. <A
125 HREF="#AEN147"
126 >Data Directives</A
127 ></DT
128 ><DT
129 >3.6.2. <A
130 HREF="#AEN211"
131 >Address Definition</A
132 ></DT
133 ><DT
134 >3.6.3. <A
135 HREF="#AEN253"
136 >Conditional Assembly</A
137 ></DT
138 ><DT
139 >3.6.4. <A
140 HREF="#AEN317"
141 >Miscelaneous Directives</A
142 ></DT
143 ></DL
144 ></DD
145 ><DT
146 >3.7. <A
147 HREF="#AEN339"
148 >Macros</A
149 ></DT
150 ><DT
151 >3.8. <A
152 HREF="#AEN361"
153 >Object Files and Sections</A
154 ></DT
155 ><DT
156 >3.9. <A
157 HREF="#AEN407"
158 >Assembler Modes and Pragmas</A
159 ></DT
160 ></DL
161 ></DD
162 ><DT
163 >4. <A
164 HREF="#AEN436"
165 >LWLINK</A
166 ></DT
167 ><DD
168 ><DL
169 ><DT
170 >4.1. <A
171 HREF="#AEN439"
172 >Command Line Options</A
173 ></DT
174 ><DT
175 >4.2. <A
176 HREF="#AEN510"
177 >Linker Operation</A
178 ></DT
179 ><DT
180 >4.3. <A
181 HREF="#AEN524"
182 >Linking Scripts</A
183 ></DT
184 ></DL
185 ></DD
186 ><DT
187 >5. <A
188 HREF="#OBJCHAP"
189 >Object Files</A
190 ></DT
191 ></DL
192 ></DIV
193 ><DIV
194 CLASS="LOT"
195 ><DL
196 CLASS="LOT"
197 ><DT
198 ><B
199 >List of Tables</B
200 ></DT
201 ><DT
202 >5-1. <A
203 HREF="#AEN583"
204 >Object File Term Types</A
205 ></DT
206 ><DT
207 >5-2. <A
208 HREF="#AEN610"
209 >Object File Operator Numbers</A
210 ></DT
211 ></DL
212 ></DIV
213 ><DIV
214 CLASS="CHAPTER"
215 ><HR><H1
216 ><A
217 NAME="AEN10"
218 ></A
219 >Chapter 1. Introduction</H1
220 ><P
221 >The LW tool chain provides utilities for building binaries for MC6809 and
222 HD6309 CPUs. The tool chain includes a cross-assembler and a cross-linker
223 which support several styles of output.</P
224 ><DIV
225 CLASS="SECTION"
226 ><HR><H2
227 CLASS="SECTION"
228 ><A
229 NAME="AEN13"
230 >1.1. History</A
231 ></H2
232 ><P
233 >For a long time, I have had an interest in creating an operating system for
234 the Coco3. I finally started working on that project around the beginning of
235 2006. I had a number of assemblers I could choose from. Eventually, I settled
236 on one and started tinkering. After a while, I realized that assembler was not
237 going to be sufficient due to lack of macros and issues with forward references.
238 Then I tried another which handled forward references correctly but still did
239 not support macros. I looked around at other assemblers and they all lacked
240 one feature or another that I really wanted for creating my operating system.</P
241 ><P
242 >The solution seemed clear at that point. I am a fair programmer so I figured
243 I could write an assembler that would do everything I wanted an assembler to
244 do. Thus the LWASM probject was born. After more than two years of on and off
245 work, version 1.0 of LWASM was released in October of 2008.</P
246 ><P
247 >As the aforementioned operating system project progressed further, it became
248 clear that while assembling the whole project through a single file was doable,
249 it was not practical. When I found myself playing some fancy games with macros
250 in a bid to simulate sections, I realized I needed a means of assembling
251 source files separately and linking them later. This spawned a major development
252 effort to add an object file support to LWASM. It also spawned the LWLINK
253 project to provide a means to actually link the files.</P
254 ></DIV
255 ></DIV
256 ><DIV
257 CLASS="CHAPTER"
258 ><HR><H1
259 ><A
260 NAME="AEN18"
261 ></A
262 >Chapter 2. Output Formats</H1
263 ><P
264 >The LW tool chain supports multiple output formats. Each format has its
265 advantages and disadvantages. Each format is described below.</P
266 ><DIV
267 CLASS="SECTION"
268 ><HR><H2
269 CLASS="SECTION"
270 ><A
271 NAME="AEN21"
272 >2.1. Raw Binaries</A
273 ></H2
274 ><P
275 >A raw binary is simply a string of bytes. There are no headers or other
276 niceties. Both LWLINK and LWASM support generating raw binaries. ORG directives
277 in the source code only serve to set the addresses that will be used for
278 symbols but otherwise have no direct impact on the resulting binary.</P
279 ></DIV
280 ><DIV
281 CLASS="SECTION"
282 ><HR><H2
283 CLASS="SECTION"
284 ><A
285 NAME="AEN24"
286 >2.2. DECB Binaries</A
287 ></H2
288 ><P
289 >A DECB binary is compatible with the LOADM command in Disk Extended
290 Color Basic on the CoCo. They are also compatible with CLOADM from Extended
291 Color Basic. These binaries include the load address of the binary as well
292 as encoding an execution address. These binaries may contain multiple loadable
293 sections, each of which has its own load address.</P
294 ><P
295 >Each binary starts with a preamble. Each preamble is five bytes long. The
296 first byte is zero. The next two bytes specify the number of bytes to load
297 and the last two bytes specify the address to load the bytes at. Then, a
298 string of bytes follows. After this string of bytes, there may be another
299 preamble or a postamble. A postamble is also five bytes in length. The first
300 byte of the postamble is $FF, the next two are zero, and the last two are
301 the execution address for the binary.</P
302 ><P
303 >Both LWASM and LWLINK can output this format.</P
304 ></DIV
305 ><DIV
306 CLASS="SECTION"
307 ><HR><H2
308 CLASS="SECTION"
309 ><A
310 NAME="AEN29"
311 >2.3. Object Files</A
312 ></H2
313 ><P
314 >LWASM supports generating a proprietary object file format which is
315 described in <A
316 HREF="#OBJCHAP"
317 >Chapter 5</A
318 >. LWLINK is then used to link these
319 object files into a final binary in any of LWLINK's supported binary
320 formats.</P
321 ><P
322 >Object files are very flexible in that they allow references that are not
323 known at assembly time to be resolved at link time. However, because the
324 addresses of such references are not known, there is no way for the assembler
325 has to use sixteen bit addressing modes for these references. The linker
326 will always use sixteen bits when resolving a reference which means any
327 instruction that requires an eight bit operand cannot use external references.</P
328 ><P
329 >Object files also support the concept of sections which are not valid
330 for other output types. This allows related code from each object file
331 linked to be collapsed together in the final binary.</P
332 ></DIV
333 ></DIV
334 ><DIV
335 CLASS="CHAPTER"
336 ><HR><H1
337 ><A
338 NAME="AEN35"
339 ></A
340 >Chapter 3. LWASM</H1
341 ><P
342 >The LWTOOLS assembler is called LWASM. This chapter documents the various
343 features of the assembler. It is not, however, a tutorial on 6x09 assembly
344 language programming.</P
345 ><DIV
346 CLASS="SECTION"
347 ><HR><H2
348 CLASS="SECTION"
349 ><A
350 NAME="AEN38"
351 >3.1. Command Line Options</A
352 ></H2
353 ><P
354 >The binary for LWASM is called "lwasm". Note that the binary is in lower
355 case. lwasm takes the following command line arguments.</P
356 ><P
357 ></P
358 ><DIV
359 CLASS="VARIABLELIST"
360 ><DL
361 ><DT
362 ><CODE
363 CLASS="OPTION"
364 >--decb</CODE
365 >, <CODE
366 CLASS="OPTION"
367 >-b</CODE
368 ></DT
369 ><DD
370 ><P
371 >Select the DECB output format target. Equivalent to <CODE
372 CLASS="OPTION"
373 >--format=decb</CODE
374 >.</P
375 ></DD
376 ><DT
377 ><CODE
378 CLASS="OPTION"
379 >--format=type</CODE
380 >, <CODE
381 CLASS="OPTION"
382 >-f type</CODE
383 ></DT
384 ><DD
385 ><P
386 >Select the output format. Valid values are <CODE
387 CLASS="OPTION"
388 >obj</CODE
389 > for the object
390 file target, <CODE
391 CLASS="OPTION"
392 >decb</CODE
393 > for the DECB LOADM format, and <CODE
394 CLASS="OPTION"
395 >raw</CODE
396 >
397 for a raw binary.</P
398 ></DD
399 ><DT
400 ><CODE
401 CLASS="OPTION"
402 >--list[=file]</CODE
403 >, <CODE
404 CLASS="OPTION"
405 >-l[file]</CODE
406 ></DT
407 ><DD
408 ><P
409 >Cause LWASM to generate a listing. If <CODE
410 CLASS="OPTION"
411 >file</CODE
412 > is specified,
413 the listing will go to that file. Otherwise it will go to the standard output
414 stream. By default, no listing is generated.</P
415 ></DD
416 ><DT
417 ><CODE
418 CLASS="OPTION"
419 >--obj</CODE
420 ></DT
421 ><DD
422 ><P
423 >Select the proprietary object file format as the output target.</P
424 ></DD
425 ><DT
426 ><CODE
427 CLASS="OPTION"
428 >--output=FILE</CODE
429 >, <CODE
430 CLASS="OPTION"
431 >-o FILE</CODE
432 ></DT
433 ><DD
434 ><P
435 >This option specifies the name of the output file. If not specified, the
436 default is <CODE
437 CLASS="OPTION"
438 >a.out</CODE
439 >.</P
440 ></DD
441 ><DT
442 ><CODE
443 CLASS="OPTION"
444 >--pragma=pragma</CODE
445 >, <CODE
446 CLASS="OPTION"
447 >-p pragma</CODE
448 ></DT
449 ><DD
450 ><P
451 >Specify assembler pragmas. Multiple pragmas are separated by commas. The
452 pragmas accepted are the same as for the PRAGMA assembler directive described
453 below.</P
454 ></DD
455 ><DT
456 ><CODE
457 CLASS="OPTION"
458 >--raw</CODE
459 >, <CODE
460 CLASS="OPTION"
461 >-r</CODE
462 ></DT
463 ><DD
464 ><P
465 >Select raw binary as the output target.</P
466 ></DD
467 ><DT
468 ><CODE
469 CLASS="OPTION"
470 >--help</CODE
471 >, <CODE
472 CLASS="OPTION"
473 >-?</CODE
474 ></DT
475 ><DD
476 ><P
477 >Present a help screen describing the command line options.</P
478 ></DD
479 ><DT
480 ><CODE
481 CLASS="OPTION"
482 >--usage</CODE
483 ></DT
484 ><DD
485 ><P
486 >Provide a summary of the command line options.</P
487 ></DD
488 ><DT
489 ><CODE
490 CLASS="OPTION"
491 >--version</CODE
492 >, <CODE
493 CLASS="OPTION"
494 >-V</CODE
495 ></DT
496 ><DD
497 ><P
498 >Display the software version.</P
499 ></DD
500 ><DT
501 ><CODE
502 CLASS="OPTION"
503 >--debug</CODE
504 >, <CODE
505 CLASS="OPTION"
506 >-d</CODE
507 ></DT
508 ><DD
509 ><P
510 >Increase the debugging level. Only really useful to people hacking on the
511 LWASM source code itself.</P
512 ></DD
513 ></DL
514 ></DIV
515 ></DIV
516 ><DIV
517 CLASS="SECTION"
518 ><HR><H2
519 CLASS="SECTION"
520 ><A
521 NAME="AEN121"
522 >3.2. Dialects</A
523 ></H2
524 ><P
525 >LWASM supports all documented MC6809 instructions as defined by Motorola.
526 It also supports all known HD6309 instructions. There is some variation,
527 however, in the pneumonics used for the block transfer instructions. LWASM
528 uses TFM for all four of them as do several other assemblers. Others, such
529 as CCASM, use four separate opcodes for it (compare: copy+, copy-, implode,
530 and explode). There are advantages to both methods. However, it seems like
531 TFM has the most traction and thus, this is what LWASM supports. Support
532 for such variations may be added in the future.</P
533 ><P
534 >The standard addressing mode specifiers are supported. These are the
535 hash sign ("#") for immediate mode, the less than sign ("&lt;") for forced
536 eight bit modes, and the greater than sign ("&gt;") for forced sixteen bit modes.</P
537 ></DIV
538 ><DIV
539 CLASS="SECTION"
540 ><HR><H2
541 CLASS="SECTION"
542 ><A
543 NAME="AEN125"
544 >3.3. Source Format</A
545 ></H2
546 ><P
547 >LWASM accepts plain text files in a relatively free form. It can handle
548 lines terminated with CR, LF, CRLF, or LFCR which means it should be able
549 to assemble files on any platform on which it compiles.</P
550 ><P
551 >Each line may start with a symbol. If a symbol is present, there must not
552 be any whitespace preceding it. It is legal for a line to contain nothing
553 but a symbol.</P
554 ><P
555 >The op code is separated from the symbol by whitespace. If there is
556 no symbol, there must be at least one white space character preceding it.
557 If applicable, the operand follows separated by whitespace. Following the
558 opcode and operand is an optional comment.</P
559 ><P
560 >A comment can also be introduced with a * or a ;. The comment character is
561 optional for end of statement comments. However, if a symbol is the only
562 thing present on the line other than the comment, the comment character is
563 mandatory to prevent the assembler from interpreting the comment as an opcode.</P
564 ><P
565 >The opcode is not treated case sensitively. Neither are register names in
566 the operand fields. Symbols, however, are case sensitive.</P
567 ><P
568 >LWASM does not support line numbers in the file.</P
569 ></DIV
570 ><DIV
571 CLASS="SECTION"
572 ><HR><H2
573 CLASS="SECTION"
574 ><A
575 NAME="AEN133"
576 >3.4. Symbols</A
577 ></H2
578 ><P
579 >Symbols have no length restriction. They may contain letters, numbers, dots,
580 dollar signs, and underscores. They must start with a letter, dot, or
581 underscore.</P
582 ><P
583 >LWASM also supports the concept of a local symbol. A local symbol is one
584 which contains either a "?" or a "@", which can appear anywhere in the symbol.
585 The scope of a local symbol is determined by a number of factors. First,
586 each included file gets its own local symbol scope. A blank line will also
587 be considered a local scope barrier. Macros each have their own local symbol
588 scope as well (which has a side effect that you cannot use a local symbol
589 as an argument to a macro). There are other factors as well. In general,
590 a local symbol is restricted to the block of code it is defined within.</P
591 ></DIV
592 ><DIV
593 CLASS="SECTION"
594 ><HR><H2
595 CLASS="SECTION"
596 ><A
597 NAME="AEN137"
598 >3.5. Numbers and Expressions</A
599 ></H2
600 ><P
601 >Numbers can be expressed in binary, octal, decimal, or hexadecimal.
602 Binary numbers may be prefixed with a "%" symbol or suffixed with a
603 "b" or "B". Octal numbers may be prefixed with "@" or suffixed with
604 "Q", "q", "O", or "o". Hexadecimal numbers may be prefixed with "$" or
605 suffixed with "H". No prefix or suffix is required for decimal numbers but
606 they can be prefixed with "&amp;" if desired. Any constant which begins with
607 a letter must be expressed with the correct prefix base identifier or be
608 prefixed with a 0. Thus hexadecimal FF would have to be written either 0FFH
609 or $FF. Numbers are not case sensitive.</P
610 ><P
611 > A symbol may appear at any point where a number is acceptable. The
612 special symbol "*" can be used to represent the starting address of the
613 current source line within expressions. </P
614 ><P
615 >The ASCII value of a character can be included by prefixing it with a
616 single quote ('). The ASCII values of two characters can be included by
617 prefixing the characters with a quote (").</P
618 ><P
619 >LWASM supports the following basic binary operators: +, -, *, /, and %.
620 These represent addition, subtraction, multiplication, division, and modulus.
621 It also supports unary negation and unary 1's complement (- and ^ respectively).
622 For completeness, a unary positive (+) is supported though it is a no-op.</P
623 ><P
624 >Operator precedence follows the usual rules. multiplication, division,
625 and modulus take precedence over addition and subtraction. Unary operators
626 take precedence over binary operators. To force a specific order of evaluation,
627 parentheses can be used in the usual manner.</P
628 ></DIV
629 ><DIV
630 CLASS="SECTION"
631 ><HR><H2
632 CLASS="SECTION"
633 ><A
634 NAME="AEN144"
635 >3.6. Assembler Directives</A
636 ></H2
637 ><P
638 >Various directives can be used to control the behaviour of the
639 assembler or to include non-code/data in the resulting output. Those directives
640 that are not described in detail in other sections of this document are
641 described below.</P
642 ><DIV
643 CLASS="SECTION"
644 ><HR><H3
645 CLASS="SECTION"
646 ><A
647 NAME="AEN147"
648 >3.6.1. Data Directives</A
649 ></H3
650 ><P
651 ></P
652 ><DIV
653 CLASS="VARIABLELIST"
654 ><DL
655 ><DT
656 >FCB <CODE
657 CLASS="PARAMETER"
658 >expr[,...]</CODE
659 ></DT
660 ><DD
661 ><P
662 >Include one or more constant bytes (separated by commas) in the output.</P
663 ></DD
664 ><DT
665 >FDB <CODE
666 CLASS="PARAMETER"
667 >expr[,...]</CODE
668 ></DT
669 ><DD
670 ><P
671 >Include one or more words (separated by commas) in the output.</P
672 ></DD
673 ><DT
674 >FQB <CODE
675 CLASS="PARAMETER"
676 >expr[,...]</CODE
677 ></DT
678 ><DD
679 ><P
680 >Include one or more double words (separated by commas) in the output.</P
681 ></DD
682 ><DT
683 >FCC <CODE
684 CLASS="PARAMETER"
685 >string</CODE
686 ></DT
687 ><DD
688 ><P
689 >Include a string of text in the output. The first character of the operand
690 is the delimiter which must appear as the last character and cannot appear
691 within the string. The string is included with no modifications&#62;</P
692 ></DD
693 ><DT
694 >FCN <CODE
695 CLASS="PARAMETER"
696 >string</CODE
697 ></DT
698 ><DD
699 ><P
700 >Include a NUL terminated string of text in the output. The first character of
701 the operand is the delimiter which must appear as the last character and
702 cannot appear within the string. A NUL byte is automatically appended to
703 the string.</P
704 ></DD
705 ><DT
706 >FCS <CODE
707 CLASS="PARAMETER"
708 >string</CODE
709 ></DT
710 ><DD
711 ><P
712 >Include a string of text in the output with bit 7 of the final byte set. The
713 first character of the operand is the delimiter which must appear as the last
714 character and cannot appear within the string.</P
715 ></DD
716 ><DT
717 >ZMB <CODE
718 CLASS="PARAMETER"
719 >expr</CODE
720 ></DT
721 ><DD
722 ><P
723 >Include a number of NUL bytes in the output. The number must be fully resolvable
724 during pass 1 of assembly so no forward or external references are permitted.</P
725 ></DD
726 ><DT
727 >ZMD <CODE
728 CLASS="PARAMETER"
729 >expr</CODE
730 ></DT
731 ><DD
732 ><P
733 >Include a number of zero words in the output. The number must be fully
734 resolvable during pass 1 of assembly so no forward or external references are
735 permitted.</P
736 ></DD
737 ><DT
738 >ZMQ <CODE
739 CLASS="PARAMETER"
740 >expr<CODE
741 CLASS="PARAMETER"
742 ></CODE
743 ></CODE
744 ></DT
745 ><DD
746 ><P
747 >Include a number of zero double-words in the output. The number must be fully
748 resolvable during pass 1 of assembly so no forward or external references are
749 permitted.</P
750 ></DD
751 ><DT
752 >RMB <CODE
753 CLASS="PARAMETER"
754 >expr</CODE
755 ></DT
756 ><DD
757 ><P
758 >Reserve a number of bytes in the output. The number must be fully resolvable
759 during pass 1 of assembly so no forward or external references are permitted.
760 The value of the bytes is undefined.</P
761 ></DD
762 ><DT
763 >RMD <CODE
764 CLASS="PARAMETER"
765 >expr</CODE
766 ></DT
767 ><DD
768 ><P
769 >Reserve a number of words in the output. The number must be fully
770 resolvable during pass 1 of assembly so no forward or external references are
771 permitted. The value of the words is undefined.</P
772 ></DD
773 ><DT
774 >RMQ <CODE
775 CLASS="PARAMETER"
776 >expr</CODE
777 ></DT
778 ><DD
779 ><P
780 >Reserve a number of double-words in the output. The number must be fully
781 resolvable during pass 1 of assembly so no forward or external references are
782 permitted. The value of the double-words is undefined.</P
783 ></DD
784 ></DL
785 ></DIV
786 ></DIV
787 ><DIV
788 CLASS="SECTION"
789 ><HR><H3
790 CLASS="SECTION"
791 ><A
792 NAME="AEN211"
793 >3.6.2. Address Definition</A
794 ></H3
795 ><P
796 >The directives in this section all control the addresses of symbols
797 or the assembly process itself.</P
798 ><P
799 ></P
800 ><DIV
801 CLASS="VARIABLELIST"
802 ><DL
803 ><DT
804 >ORG <CODE
805 CLASS="PARAMETER"
806 >expr</CODE
807 ></DT
808 ><DD
809 ><P
810 >Set the assembly address. The address must be fully resolvable on the
811 first pass so no external or forward references are permitted. ORG is not
812 permitted within sections when outputting to object files. For the DECB
813 target, each ORG directive after which output is generated will cause
814 a new preamble to be output. ORG is only used to determine the addresses
815 of symbols when the raw target is used.</P
816 ></DD
817 ><DT
818 ><CODE
819 CLASS="PARAMETER"
820 >sym</CODE
821 > EQU <CODE
822 CLASS="PARAMETER"
823 >expr</CODE
824 >, <CODE
825 CLASS="PARAMETER"
826 >sym</CODE
827 > = <CODE
828 CLASS="PARAMETER"
829 >expr</CODE
830 ></DT
831 ><DD
832 ><P
833 >Define the value of <CODE
834 CLASS="PARAMETER"
835 >sym</CODE
836 > to be <CODE
837 CLASS="PARAMETER"
838 >expr</CODE
839 >.</P
840 ></DD
841 ><DT
842 ><CODE
843 CLASS="PARAMETER"
844 >sym</CODE
845 > SET <CODE
846 CLASS="PARAMETER"
847 >expr</CODE
848 ></DT
849 ><DD
850 ><P
851 >Define the value of <CODE
852 CLASS="PARAMETER"
853 >sym</CODE
854 > to be <CODE
855 CLASS="PARAMETER"
856 >expr</CODE
857 >.
858 Unlike EQU, SET permits symbols to be defined multiple times as long as SET
859 is used for all instances. Use of the symbol before the first SET statement
860 that sets its value is undefined.</P
861 ></DD
862 ><DT
863 >SETDP <CODE
864 CLASS="PARAMETER"
865 >expr</CODE
866 ></DT
867 ><DD
868 ><P
869 >Inform the assembler that it can assume the DP register contains
870 <CODE
871 CLASS="PARAMETER"
872 >expr</CODE
873 >. This directive is only advice to the assembler
874 to determine whether an address is in the direct page and has no effect
875 on the contents of the DP register. The value must be fully resolved during
876 the first assembly pass because it affects the sizes of subsequent instructions.</P
877 ><P
878 >This directive has no effect in the object file target.</P
879 ></DD
880 ><DT
881 >ALIGN <CODE
882 CLASS="PARAMETER"
883 >expr</CODE
884 ></DT
885 ><DD
886 ><P
887 >Force the current assembly address to be a multiple of <CODE
888 CLASS="PARAMETER"
889 >expr</CODE
890 >.
891 A series of NUL bytes is output to force the alignment, if required. The
892 alignment value must be fully resolved on the first pass because it affects
893 the addresses of subsquent instructions.</P
894 ><P
895 >This directive is not suitable for inclusion in the middle of actual
896 code. It is intended to appear where the bytes output will not be executed.</P
897 ></DD
898 ></DL
899 ></DIV
900 ></DIV
901 ><DIV
902 CLASS="SECTION"
903 ><HR><H3
904 CLASS="SECTION"
905 ><A
906 NAME="AEN253"
907 >3.6.3. Conditional Assembly</A
908 ></H3
909 ><P
910 >Portions of the source code can be excluded or included based on conditions
911 known at assembly time. Conditionals can be nested arbitrarily deeply. The
912 directives associated with conditional assembly are described in this section.</P
913 ><P
914 >All conditionals must be fully bracketed. That is, every conditional
915 statement must eventually be followed by an ENDC at the same level of nesting.</P
916 ><P
917 >Conditional expressions are only evaluated on the first assembly pass.
918 It is not possible to game the assembly process by having a conditional
919 change its value between assembly passes. Thus there is not and never will
920 be any equivalent of IFP1 or IFP2 as provided by other assemblers.</P
921 ><P
922 ></P
923 ><DIV
924 CLASS="VARIABLELIST"
925 ><DL
926 ><DT
927 >IFEQ <CODE
928 CLASS="PARAMETER"
929 >expr</CODE
930 ></DT
931 ><DD
932 ><P
933 >If <CODE
934 CLASS="PARAMETER"
935 >expr</CODE
936 > evaluates to zero, the conditional
937 will be considered true.</P
938 ></DD
939 ><DT
940 >IFNE <CODE
941 CLASS="PARAMETER"
942 >expr</CODE
943 >, IF <CODE
944 CLASS="PARAMETER"
945 >expr</CODE
946 ></DT
947 ><DD
948 ><P
949 >If <CODE
950 CLASS="PARAMETER"
951 >expr</CODE
952 > evaluates to a non-zero value, the conditional
953 will be considered true.</P
954 ></DD
955 ><DT
956 >IFGT <CODE
957 CLASS="PARAMETER"
958 >expr</CODE
959 ></DT
960 ><DD
961 ><P
962 >If <CODE
963 CLASS="PARAMETER"
964 >expr</CODE
965 > evaluates to a value greater than zero, the conditional
966 will be considered true.</P
967 ></DD
968 ><DT
969 >IFGE <CODE
970 CLASS="PARAMETER"
971 >expr</CODE
972 ></DT
973 ><DD
974 ><P
975 >If <CODE
976 CLASS="PARAMETER"
977 >expr</CODE
978 > evaluates to a value greater than or equal to zero, the conditional
979 will be considered true.</P
980 ></DD
981 ><DT
982 >IFLT <CODE
983 CLASS="PARAMETER"
984 >expr</CODE
985 ></DT
986 ><DD
987 ><P
988 >If <CODE
989 CLASS="PARAMETER"
990 >expr</CODE
991 > evaluates to a value less than zero, the conditional
992 will be considered true.</P
993 ></DD
994 ><DT
995 >IFLE <CODE
996 CLASS="PARAMETER"
997 >expr</CODE
998 ></DT
999 ><DD
1000 ><P
1001 >If <CODE
1002 CLASS="PARAMETER"
1003 >expr</CODE
1004 > evaluates to a value less than or equal to zero , the conditional
1005 will be considered true.</P
1006 ></DD
1007 ><DT
1008 >IFDEF <CODE
1009 CLASS="PARAMETER"
1010 >sym</CODE
1011 ></DT
1012 ><DD
1013 ><P
1014 >If <CODE
1015 CLASS="PARAMETER"
1016 >sym</CODE
1017 > is defined at this point in the assembly
1018 process, the conditional
1019 will be considered true.</P
1020 ></DD
1021 ><DT
1022 >IFNDEF <CODE
1023 CLASS="PARAMETER"
1024 >sym</CODE
1025 ></DT
1026 ><DD
1027 ><P
1028 >If <CODE
1029 CLASS="PARAMETER"
1030 >sym</CODE
1031 > is not defined at this point in the assembly
1032 process, the conditional
1033 will be considered true.</P
1034 ></DD
1035 ><DT
1036 >ELSE</DT
1037 ><DD
1038 ><P
1039 >If the preceding conditional at the same level of nesting was false, the
1040 statements following will be assembled. If the preceding conditional at
1041 the same level was true, the statements following will not be assembled.
1042 Note that the preceding conditional might have been another ELSE statement
1043 although this behaviour is not guaranteed to be supported in future versions
1044 of LWASM.</P
1045 ></DD
1046 ><DT
1047 >ENDC</DT
1048 ><DD
1049 ><P
1050 >This directive marks the end of a conditional construct. Every conditional
1051 construct must end with an ENDC directive.</P
1052 ></DD
1053 ></DL
1054 ></DIV
1055 ></DIV
1056 ><DIV
1057 CLASS="SECTION"
1058 ><HR><H3
1059 CLASS="SECTION"
1060 ><A
1061 NAME="AEN317"
1062 >3.6.4. Miscelaneous Directives</A
1063 ></H3
1064 ><P
1065 >This section includes directives that do not fit into the other
1066 categories.</P
1067 ><P
1068 ></P
1069 ><DIV
1070 CLASS="VARIABLELIST"
1071 ><DL
1072 ><DT
1073 >INCLUDE <CODE
1074 CLASS="PARAMETER"
1075 >filename</CODE
1076 ></DT
1077 ><DD
1078 ><P
1079 >Include the contents of <CODE
1080 CLASS="PARAMETER"
1081 >filename</CODE
1082 > at this point in
1083 the assembly as though it were a part of the file currently being processed.
1084 Note that whitespace cannot appear in the name of the file.</P
1085 ></DD
1086 ><DT
1087 >END <CODE
1088 CLASS="PARAMETER"
1089 >[expr]</CODE
1090 ></DT
1091 ><DD
1092 ><P
1093 >This directive causes the assembler to stop assembling immediately as though
1094 it ran out of input. For the DECB target only, <CODE
1095 CLASS="PARAMETER"
1096 >expr</CODE
1097 >
1098 can be used to set the execution address of the resulting binary. For all
1099 other targets, specifying <CODE
1100 CLASS="PARAMETER"
1101 >expr</CODE
1102 > will cause an error.</P
1103 ></DD
1104 ><DT
1105 >ERROR <CODE
1106 CLASS="PARAMETER"
1107 >string</CODE
1108 ></DT
1109 ><DD
1110 ><P
1111 >Causes a custom error message to be printed at this line. This will cause
1112 assembly to fail. This directive is most useful inside conditional constructs
1113 to cause assembly to fail if some condition that is known bad happens.</P
1114 ></DD
1115 ></DL
1116 ></DIV
1117 ></DIV
1118 ></DIV
1119 ><DIV
1120 CLASS="SECTION"
1121 ><HR><H2
1122 CLASS="SECTION"
1123 ><A
1124 NAME="AEN339"
1125 >3.7. Macros</A
1126 ></H2
1127 ><P
1128 >LWASM is a macro assembler. A macro is simply a name that stands in for a
1129 series of instructions. Once a macro is defined, it is used like any other
1130 assembler directive. Defining a macro can be considered equivalent to adding
1131 additional assembler directives.</P
1132 ><P
1133 >Macros my accept parameters. These parameters are referenced within
1134 a macro by the a backslash ("\") followed by a digit 1 through 9 for the first
1135 through ninth parameters. They may also be referenced by enclosing the
1136 decimal parameter number in braces ("{num}"). These parameter references
1137 are replaced with the verbatim text of the parameter passed to the macro. A
1138 reference to a non-existent parameter will be replaced by an empty string.
1139 Macro parameters are expanded everywhere on each source line. That means
1140 the parameter to a macro could be used as a symbol or it could even appear
1141 in a comment or could cause an entire source line to be commented out
1142 when the macro is expanded.</P
1143 ><P
1144 >Parameters passed to a macro are separated by commas and the parameter list
1145 is terminated by any whitespace. This means that neither a comma nor whitespace
1146 may be included in a macro parameter.</P
1147 ><P
1148 >Macro expansion is done recursively. That is, within a macro, macros are
1149 expanded. This can lead to infinite loops in macro expansion. If the assembler
1150 hangs for a long time while assembling a file that uses macros, this may be
1151 the reason.</P
1152 ><P
1153 >Each macro expansion receives its own local symbol context which is not
1154 inherited by any macros called by it nor is it inherited from the context
1155 the macro was instantiated in. That means it is possible to use local symbols
1156 within macros without having them collide with symbols in other macros or
1157 outside the macro itself. However, this also means that using a local symbol
1158 as a parameter to a macro, while legal, will not do what it would seem to do
1159 as it will result in looking up the local symbol in the macro's symbol context
1160 rather than the enclosing context where it came from, likely yielding either
1161 an undefined symbol error or bizarre assembly results.</P
1162 ><P
1163 >Note that there is no way to define a macro as local to a symbol context. All
1164 macros are part of the global macro namespace. However, macros have a separate
1165 namespace from symbols so it is possible to have a symbol with the same name
1166 as a macro.</P
1167 ><P
1168 >Macros are defined only during the first pass. Macro expansion also
1169 only occurs during the first pass. On the second pass, the macro
1170 definition is simply ignored. Macros must be defined before they are used.</P
1171 ><P
1172 >The following directives are used when defining macros.</P
1173 ><P
1174 ></P
1175 ><DIV
1176 CLASS="VARIABLELIST"
1177 ><DL
1178 ><DT
1179 ><CODE
1180 CLASS="PARAMETER"
1181 >macroname</CODE
1182 > MACRO</DT
1183 ><DD
1184 ><P
1185 >This directive is used to being the definition of a macro called
1186 <CODE
1187 CLASS="PARAMETER"
1188 >macroname</CODE
1189 >. If <CODE
1190 CLASS="PARAMETER"
1191 >macroname</CODE
1192 > already
1193 exists, it is considered an error. Attempting to define a macro within a
1194 macro is undefined. It may work and it may not so the behaviour should not
1195 be relied upon.</P
1196 ></DD
1197 ><DT
1198 >ENDM</DT
1199 ><DD
1200 ><P
1201 >This directive indicates the end of the macro currently being defined. It
1202 causes the assembler to resume interpreting source lines as normal.</P
1203 ></DD
1204 ></DL
1205 ></DIV
1206 ></DIV
1207 ><DIV
1208 CLASS="SECTION"
1209 ><HR><H2
1210 CLASS="SECTION"
1211 ><A
1212 NAME="AEN361"
1213 >3.8. Object Files and Sections</A
1214 ></H2
1215 ><P
1216 >The object file target is very useful for large project because it allows
1217 multiple files to be assembled independently and then linked into the final
1218 binary at a later time. It allows only the small portion of the project
1219 that was modified to be re-assembled rather than requiring the entire set
1220 of source code to be available to the assembler in a single assembly process.
1221 This can be particularly important if there are a large number of macros,
1222 symbol definitions, or other metadata that uses resources at assembly time.
1223 By far the largest benefit, however, is keeping the source files small enough
1224 for a mere mortal to find things in them.</P
1225 ><P
1226 >With multi-file projects, there needs to be a means of resolving references to
1227 symbols in other source files. These are known as external references. The
1228 addresses of these symbols cannot be known until the linker joins all the
1229 object files into a single binary. This means that the assembler must be
1230 able to output the object code without knowing the value of the symbol. This
1231 places some restrictions on the code generated by the assembler. For
1232 example, the assembler cannot generate direct page addressing for instructions
1233 that reference external symbols because the address of the symbol may not
1234 be in the direct page. Similarly, relative branches and PC relative addressing
1235 cannot be used in their eight bit forms. Everything that must be resolved
1236 by the linker must be assembled to use the largest address size possible to
1237 allow the linker to fill in the correct value at link time. Note that the
1238 same problem applies to absolute address references as well, even those in
1239 the same source file, because the address is not known until link time.</P
1240 ><P
1241 >It is often desired in multi-file projects to have code of various types grouped
1242 together in the final binary generated by the linker as well. The same applies
1243 to data. In order for the linker to do that, the bits that are to be grouped
1244 must be tagged in some manner. This is where the concept of sections comes in.
1245 Each chunk of code or data is part of a section in the object file. Then,
1246 when the linker reads all the object files, it coalesces all sections of the
1247 same name into a single section and then considers it as a unit.</P
1248 ><P
1249 >The existence of sections, however, raises a problem for symbols even
1250 within the same source file. Thus, the assembler must treat symbols from
1251 different sections within the same source file in the same manner as external
1252 symbols. That is, it must leave them for the linker to resolve at link time,
1253 with all the limitations that entails.</P
1254 ><P
1255 >In the object file target mode, LWASM requires all source lines that
1256 cause bytes to be output to be inside a section. Any directives that do
1257 not cause any bytes to be output can appear outside of a section. This includes
1258 such things as EQU or RMB. Even ORG can appear outside a section. ORG, however,
1259 makes no sense within a section because it is the linker that determines
1260 the starting address of the section's code, not the assembler.</P
1261 ><P
1262 >All symbols defined globally in the assembly process are local to the
1263 source file and cannot be exported. All symbols defined within a section are
1264 considered local to the source file unless otherwise explicitly exported.
1265 Symbols referenced from external source files must be declared external,
1266 either explicitly or by asking the assembler to assume that all undefined
1267 symbols are external.</P
1268 ><P
1269 >It is often handy to define a number of memory addresses that will be
1270 used for data at run-time but which need not be included in the binary file.
1271 These memory addresses are not initialized until run-time, either by the
1272 program itself or by the program loader, depending on the operating environment.
1273 Such sections are often known as BSS sections. LWASM supports generating
1274 sections with a BSS attribute set which causes the section definition including
1275 symbols exported from that section and those symbols required to resolve
1276 references from the local file, but with no actual code in the object file.
1277 It is illegal for any source lines within a BSS flagged section to cause any
1278 bytes to be output.</P
1279 ><P
1280 >The following directives apply to section handling.</P
1281 ><P
1282 ></P
1283 ><DIV
1284 CLASS="VARIABLELIST"
1285 ><DL
1286 ><DT
1287 >SECTION <CODE
1288 CLASS="PARAMETER"
1289 >name[,flags]</CODE
1290 >, SECT <CODE
1291 CLASS="PARAMETER"
1292 >name[,flags]</CODE
1293 ></DT
1294 ><DD
1295 ><P
1296 >Instructs the assembler that the code following this directive is to be
1297 considered part of the section <CODE
1298 CLASS="PARAMETER"
1299 >name</CODE
1300 >. A section name
1301 may appear multiple times in which case it is as though all the code from
1302 all the instances of that section appeared adjacent within the source file.
1303 However, <CODE
1304 CLASS="PARAMETER"
1305 >flags</CODE
1306 > may only be specified on the first
1307 instance of the section.</P
1308 ><P
1309 >There is a single flag supported in <CODE
1310 CLASS="PARAMETER"
1311 >flags</CODE
1312 >. The
1313 flag <CODE
1314 CLASS="PARAMETER"
1315 >bss</CODE
1316 > will cause the section to be treated as a BSS
1317 section and, thus, no code will be included in the object file nor will any
1318 bytes be permitted to be output.</P
1319 ><P
1320 >If assembly is already happening within a section, the section is implicitly
1321 ended and the new section started. This is not considered an error although
1322 it is recommended that all sections be explicitly closed.</P
1323 ></DD
1324 ><DT
1325 >ENDSECTION, ENDSECT, ENDS</DT
1326 ><DD
1327 ><P
1328 >This directive ends the current section. This puts assembly outside of any
1329 sections until the next SECTION directive.</P
1330 ></DD
1331 ><DT
1332 ><CODE
1333 CLASS="PARAMETER"
1334 >sym</CODE
1335 > EXTERN, <CODE
1336 CLASS="PARAMETER"
1337 >sym</CODE
1338 > EXTERNAL, <CODE
1339 CLASS="PARAMETER"
1340 >sym</CODE
1341 > IMPORT</DT
1342 ><DD
1343 ><P
1344 >This directive defines <CODE
1345 CLASS="PARAMETER"
1346 >sym</CODE
1347 > as an external symbol.
1348 This directive may occur at any point in the source code. EXTERN definitions
1349 are resolved on the first pass so an EXTERN definition anywhere in the
1350 source file is valid for the entire file. The use of this directive is
1351 optional when the assembler is instructed to assume that all undefined
1352 symbols are external. In fact, in that mode, if the symbol is referenced
1353 before the EXTERN directive, an error will occur.</P
1354 ></DD
1355 ><DT
1356 ><CODE
1357 CLASS="PARAMETER"
1358 >sym</CODE
1359 > EXPORT</DT
1360 ><DD
1361 ><P
1362 >This directive defines <CODE
1363 CLASS="PARAMETER"
1364 >sym</CODE
1365 > as an exported symbol.
1366 This directive may occur at any point in the source code, even before the
1367 definition of the exported symbol.</P
1368 ></DD
1369 ></DL
1370 ></DIV
1371 ></DIV
1372 ><DIV
1373 CLASS="SECTION"
1374 ><HR><H2
1375 CLASS="SECTION"
1376 ><A
1377 NAME="AEN407"
1378 >3.9. Assembler Modes and Pragmas</A
1379 ></H2
1380 ><P
1381 >There are a number of options that affect the way assembly is performed.
1382 Some of these options can only be specified on the command line because
1383 they determine something absolute about the assembly process. These include
1384 such things as the output target. Other things may be switchable during
1385 the assembly process. These are known as pragmas and are, by definition,
1386 not portable between assemblers.</P
1387 ><P
1388 >LWASM supports a number of pragmas that affect code generation or
1389 otherwise affect the behaviour of the assembler. These may be specified by
1390 way of a command line option or by assembler directives. The directives
1391 are as follows.</P
1392 ><P
1393 ></P
1394 ><DIV
1395 CLASS="VARIABLELIST"
1396 ><DL
1397 ><DT
1398 >PRAGMA <CODE
1399 CLASS="PARAMETER"
1400 >pragma[,...]</CODE
1401 ></DT
1402 ><DD
1403 ><P
1404 >Specifies that the assembler should bring into force all <CODE
1405 CLASS="PARAMETER"
1406 >pragma</CODE
1407 >s
1408 specified. Any unrecognized pragma will cause an assembly error. The new
1409 pragmas will take effect immediately. This directive should be used when
1410 the program will assemble incorrectly if the pragma is ignored or not supported.</P
1411 ></DD
1412 ><DT
1413 >*PRAGMA <CODE
1414 CLASS="PARAMETER"
1415 >pragma[,...]</CODE
1416 ></DT
1417 ><DD
1418 ><P
1419 >This is identical to the PRAGMA directive except no error will occur with
1420 unrecognized or unsupported pragmas. This directive, by virtue of starting
1421 with a comment character, will also be ignored by assemblers that do not
1422 support this directive. Use this variation if the pragma is not required
1423 for correct functioning of the code.</P
1424 ></DD
1425 ></DL
1426 ></DIV
1427 ><P
1428 >Each pragma supported has a positive version and a negative version.
1429 The positive version enables the pragma while the negative version disables
1430 it. The negatitve version is simply the positive version with "no" prefixed
1431 to it. For instance, "pragma" vs. "nopragma". Only the positive version is
1432 listed below.</P
1433 ><P
1434 >Pragmas are not case sensitive.</P
1435 ><P
1436 ></P
1437 ><DIV
1438 CLASS="VARIABLELIST"
1439 ><DL
1440 ><DT
1441 >index0tonone</DT
1442 ><DD
1443 ><P
1444 >When in force, this pragma enables an optimization affecting indexed addressing
1445 modes. When the offset expression in an indexed mode evaluates to zero but is
1446 not explicity written as 0, this will replace the operand with the equivalent
1447 no offset mode, thus creating slightly faster code. Because of the advantages
1448 of this optimization, it is enabled by default.</P
1449 ></DD
1450 ><DT
1451 >undefextern</DT
1452 ><DD
1453 ><P
1454 >This pragma is only valid for targets that support external references. When in
1455 force, if the assembler sees an undefined symbol on the second pass, it will
1456 automatically define it as an external symbol. This automatic definition will
1457 apply for the remainder of the assembly process, even if the pragma is
1458 subsequently turned off. Because this behaviour would be potentially surprising,
1459 this pragma defaults to off.</P
1460 ><P
1461 >The primary use for this pragma is for projects that share a large number of
1462 symbols between source files. In such cases, it is impractical to enumerate
1463 all the external references in every source file. This allows the assembler
1464 and linker to do the heavy lifting while not preventing a particular source
1465 module from defining a local symbol of the same name as an external symbol
1466 if it does not need the external symbol. (This pragma will not cause an
1467 automatic external definition if there is already a locally defined symbol.)</P
1468 ><P
1469 >This pragma will often be specified on the command line for large projects.
1470 However, depending on the specific dynamics of the project, it may be sufficient
1471 for one or two files to use this pragma internally.</P
1472 ></DD
1473 ></DL
1474 ></DIV
1475 ></DIV
1476 ></DIV
1477 ><DIV
1478 CLASS="CHAPTER"
1479 ><HR><H1
1480 ><A
1481 NAME="AEN436"
1482 ></A
1483 >Chapter 4. LWLINK</H1
1484 ><P
1485 >The LWTOOLS linker is called LWLINK. This chapter documents the various features
1486 of the linker.</P
1487 ><DIV
1488 CLASS="SECTION"
1489 ><HR><H2
1490 CLASS="SECTION"
1491 ><A
1492 NAME="AEN439"
1493 >4.1. Command Line Options</A
1494 ></H2
1495 ><P
1496 >The binary for LWLINK is called "lwlink". Note that the binary is in lower
1497 case. lwlink takes the following command line arguments.</P
1498 ><P
1499 ></P
1500 ><DIV
1501 CLASS="VARIABLELIST"
1502 ><DL
1503 ><DT
1504 ><CODE
1505 CLASS="OPTION"
1506 >--decb</CODE
1507 >, <CODE
1508 CLASS="OPTION"
1509 >-b</CODE
1510 ></DT
1511 ><DD
1512 ><P
1513 >Selects the DECB output format target. This is equivalent to <CODE
1514 CLASS="OPTION"
1515 >--format=decb</CODE
1516 ></P
1517 ></DD
1518 ><DT
1519 ><CODE
1520 CLASS="OPTION"
1521 >--output=FILE</CODE
1522 >, <CODE
1523 CLASS="OPTION"
1524 >-o FILE</CODE
1525 ></DT
1526 ><DD
1527 ><P
1528 >This option specifies the name of the output file. If not specified, the
1529 default is <CODE
1530 CLASS="OPTION"
1531 >a.out</CODE
1532 >.</P
1533 ></DD
1534 ><DT
1535 ><CODE
1536 CLASS="OPTION"
1537 >--format=TYPE</CODE
1538 >, <CODE
1539 CLASS="OPTION"
1540 >-f TYPE</CODE
1541 ></DT
1542 ><DD
1543 ><P
1544 >This option specifies the output format. Valid values are <CODE
1545 CLASS="OPTION"
1546 >decb</CODE
1547 >
1548 and <CODE
1549 CLASS="OPTION"
1550 >raw</CODE
1551 ></P
1552 ></DD
1553 ><DT
1554 ><CODE
1555 CLASS="OPTION"
1556 >--raw</CODE
1557 >, <CODE
1558 CLASS="OPTION"
1559 >-r</CODE
1560 ></DT
1561 ><DD
1562 ><P
1563 >This option specifies the raw output format.
1564 It is equivalent to <CODE
1565 CLASS="OPTION"
1566 >--format=raw</CODE
1567 >.
1568 and <CODE
1569 CLASS="OPTION"
1570 >raw</CODE
1571 ></P
1572 ></DD
1573 ><DT
1574 ><CODE
1575 CLASS="OPTION"
1576 >--script=FILE</CODE
1577 >, <CODE
1578 CLASS="OPTION"
1579 >-s</CODE
1580 ></DT
1581 ><DD
1582 ><P
1583 >This option allows specifying a linking script to override the linker's
1584 built in defaults.</P
1585 ></DD
1586 ><DT
1587 ><CODE
1588 CLASS="OPTION"
1589 >--debug</CODE
1590 >, <CODE
1591 CLASS="OPTION"
1592 >-d</CODE
1593 ></DT
1594 ><DD
1595 ><P
1596 >This option increases the debugging level. It is only useful for LWTOOLS
1597 developers.</P
1598 ></DD
1599 ><DT
1600 ><CODE
1601 CLASS="OPTION"
1602 >--help</CODE
1603 >, <CODE
1604 CLASS="OPTION"
1605 >-?</CODE
1606 ></DT
1607 ><DD
1608 ><P
1609 >This provides a listing of command line options and a brief description
1610 of each.</P
1611 ></DD
1612 ><DT
1613 ><CODE
1614 CLASS="OPTION"
1615 >--usage</CODE
1616 ></DT
1617 ><DD
1618 ><P
1619 >This will display a usage summary.
1620 of each.</P
1621 ></DD
1622 ><DT
1623 ><CODE
1624 CLASS="OPTION"
1625 >--version</CODE
1626 >, <CODE
1627 CLASS="OPTION"
1628 >-V</CODE
1629 ></DT
1630 ><DD
1631 ><P
1632 >This will display the version of LWLINK.
1633 of each.</P
1634 ></DD
1635 ></DL
1636 ></DIV
1637 ></DIV
1638 ><DIV
1639 CLASS="SECTION"
1640 ><HR><H2
1641 CLASS="SECTION"
1642 ><A
1643 NAME="AEN510"
1644 >4.2. Linker Operation</A
1645 ></H2
1646 ><P
1647 >LWLINK takes one or more files in the LWTOOLS object file format and links
1648 them into a single binary. While the precise method is slightly different,
1649 linking can be conceptualized as the following steps.</P
1650 ><P
1651 ></P
1652 ><OL
1653 TYPE="1"
1654 ><LI
1655 ><P
1656 >First, the linker loads a linking script. If no script is specified, it
1657 loads a built-in default script based on the output format selected. This
1658 script tells the linker how to lay out the various sections in the final
1659 binary.</P
1660 ></LI
1661 ><LI
1662 ><P
1663 >Next, the linker reads all the input files into memory. At this time, it
1664 flags any format errors in those files. It constructs a table of symbols
1665 for each object at this time.</P
1666 ></LI
1667 ><LI
1668 ><P
1669 >The linker then proceeds with organizing the sections loaded from each file
1670 according to the linking script. As it does so, it is able to assign addresses
1671 to each symbol defined in each object file. At this time, the linker may
1672 also collapse different instances of the same section name into a single
1673 section by appending the data from each subsequent instance of the section
1674 to the first instance of the section.</P
1675 ></LI
1676 ><LI
1677 ><P
1678 >Next, the linker looks through every object file for every incomplete reference.
1679 It then attempts to fully resolve that reference. If it cannot do so, it
1680 throws an error. Once a reference is resolved, the value is placed into
1681 the binary code at the specified section. It should be noted that an
1682 incomplete reference can reference either a symbol internal to the object
1683 file or an external symbol which is in the export list of another object
1684 file.</P
1685 ></LI
1686 ><LI
1687 ><P
1688 >If all of the above steps are successful, the linker opens the output file
1689 and actually constructs the binary.</P
1690 ></LI
1691 ></OL
1692 ></DIV
1693 ><DIV
1694 CLASS="SECTION"
1695 ><HR><H2
1696 CLASS="SECTION"
1697 ><A
1698 NAME="AEN524"
1699 >4.3. Linking Scripts</A
1700 ></H2
1701 ><P
1702 >A linker script is used to instruct the linker about how to assemble the
1703 various sections into a completed binary. It consists of a series of
1704 directives which are considered in the order they are encountered.</P
1705 ><P
1706 >The sections will appear in the resulting binary in the order they are
1707 specified in the script file. If a referenced section is not found, the linker will behave as though the
1708 section did exist but had a zero size, no relocations, and no exports.
1709 A section should only be referenced once. Any subsequent references will have
1710 an undefined effect.</P
1711 ><P
1712 >All numbers are in linking scripts are specified in hexadecimal. All directives
1713 are case sensitive although the hexadecimal numbers are not.</P
1714 ><P
1715 >A section name can be specified as a "*", then any section not
1716 already matched by the script will be matched. The "*" can be followed
1717 by a comma and a flag to narrow the section down slightly, also.
1718 If the flag is "!bss", then any section that is not flagged as a bss section
1719 will be matched. If the flag is "bss", then any section that is flagged as
1720 bss will be matched.</P
1721 ><P
1722 >The following directives are understood in a linker script.</P
1723 ><P
1724 ></P
1725 ><DIV
1726 CLASS="VARIABLELIST"
1727 ><DL
1728 ><DT
1729 >section <CODE
1730 CLASS="PARAMETER"
1731 >name</CODE
1732 > load <CODE
1733 CLASS="PARAMETER"
1734 >addr</CODE
1735 ></DT
1736 ><DD
1737 ><P
1738 >&#13;This causes the section <CODE
1739 CLASS="PARAMETER"
1740 >name</CODE
1741 > to load at
1742 <CODE
1743 CLASS="PARAMETER"
1744 >addr</CODE
1745 >. For the raw target, only one "load at" entry is
1746 allowed for non-bss sections and it must be the first one. For raw targets,
1747 it affects the addresses the linker assigns to symbols but has no other
1748 affect on the output. bss sections may all have separate load addresses but
1749 since they will not appear in the binary anyway, this is okay.</P
1750 ><P
1751 >For the decb target, each "load" entry will cause a new "block" to be
1752 output to the binary which will contain the load address. It is legal for
1753 sections to overlap in this manner - the linker assumes the loader will sort
1754 everything out.</P
1755 ></DD
1756 ><DT
1757 >section <CODE
1758 CLASS="PARAMETER"
1759 >name</CODE
1760 ></DT
1761 ><DD
1762 ><P
1763 >&#13;This will cause the section <CODE
1764 CLASS="PARAMETER"
1765 >name</CODE
1766 > to load after the previously listed
1767 section.</P
1768 ></DD
1769 ><DT
1770 >exec <CODE
1771 CLASS="PARAMETER"
1772 >addr or sym</CODE
1773 ></DT
1774 ><DD
1775 ><P
1776 >This will cause the execution address (entry point) to be the address
1777 specified (in hex) or the specified symbol name. The symbol name must
1778 match a symbol that is exported by one of the object files being linked.
1779 This has no effect for targets that do not encode the entry point into the
1780 resulting file. If not specified, the entry point is assumed to be address 0
1781 which is probably not what you want. The default link scripts for targets
1782 that support this directive automatically starts at the beginning of the
1783 first section (usually "init" or "code") that is emitted in the binary.</P
1784 ></DD
1785 ><DT
1786 >pad <CODE
1787 CLASS="PARAMETER"
1788 >size</CODE
1789 ></DT
1790 ><DD
1791 ><P
1792 >This will cause the output file to be padded with NUL bytes to be exactly
1793 <CODE
1794 CLASS="PARAMETER"
1795 >size</CODE
1796 > bytes in length. This only makes sense for a raw target.</P
1797 ></DD
1798 ></DL
1799 ></DIV
1800 ></DIV
1801 ></DIV
1802 ><DIV
1803 CLASS="CHAPTER"
1804 ><HR><H1
1805 ><A
1806 NAME="OBJCHAP"
1807 ></A
1808 >Chapter 5. Object Files</H1
1809 ><P
1810 >LWTOOLS uses a proprietary object file format. It is proprietary in the sense
1811 that it is specific to LWTOOLS, not that it is a hidden format. It would be
1812 hard to keep it hidden in an open source tool chain anyway. This chapter
1813 documents the object file format.</P
1814 ><P
1815 >An object file consists of a series of sections each of which contains a
1816 list of exported symbols, a list of incomplete references, and a list of
1817 "local" symbols which may be used in calculating incomplete references. Each
1818 section will obviously also contain the object code.</P
1819 ><P
1820 >Exported symbols must be completely resolved to an address within the
1821 section it is exported from. That is, an exported symbol must be a constant
1822 rather than defined in terms of other symbols.</P
1823 ><P
1824 >Each object file starts with a magic number and version number. The magic
1825 number is the string "LWOBJ16" for this 16 bit object file format. The only
1826 defined version number is currently 0. Thus, the first 8 bytes of the object
1827 file are <FONT
1828 COLOR="RED"
1829 >4C574F424A313600</FONT
1830 ></P
1831 ><P
1832 >Each section has the following items in order:</P
1833 ><P
1834 ></P
1835 ><UL
1836 ><LI
1837 ><P
1838 >section name</P
1839 ></LI
1840 ><LI
1841 ><P
1842 >flags</P
1843 ></LI
1844 ><LI
1845 ><P
1846 >list of local symbols (and addresses within the section)</P
1847 ></LI
1848 ><LI
1849 ><P
1850 >list of exported symbols (and addresses within the section)</P
1851 ></LI
1852 ><LI
1853 ><P
1854 >list of incomplete references along with the expressions to calculate them</P
1855 ></LI
1856 ><LI
1857 ><P
1858 >the actual object code (for non-BSS sections)</P
1859 ></LI
1860 ></UL
1861 ><P
1862 >The section starts with the name of the section with a NUL termination
1863 followed by a series of flag bytes terminated by NUL. There are only two
1864 flag bytes defined. A NUL (0) indicates no more flags and a value of 1
1865 indicates the section is a BSS section. For a BSS section, no actual
1866 code is included in the object file.</P
1867 ><P
1868 >Either a NULL section name or end of file indicate the presence of no more
1869 sections.</P
1870 ><P
1871 >Each entry in the exported and local symbols table consists of the symbol
1872 (NUL terminated) followed by two bytes which contain the value in big endian
1873 order. The end of a symbol table is indicated by a NULL symbol name.</P
1874 ><P
1875 >Each entry in the incomplete references table consists of an expression
1876 followed by a 16 bit offset where the reference goes. Expressions are
1877 defined as a series of terms up to an "end of expression" term. Each term
1878 consists of a single byte which identifies the type of term (see below)
1879 followed by any data required by the term. Then end of the list is flagged
1880 by a NULL expression (only an end of expression term).</P
1881 ><DIV
1882 CLASS="TABLE"
1883 ><A
1884 NAME="AEN583"
1885 ></A
1886 ><P
1887 ><B
1888 >Table 5-1. Object File Term Types</B
1889 ></P
1890 ><TABLE
1891 BORDER="1"
1892 FRAME="border"
1893 CLASS="CALSTABLE"
1894 ><COL><COL><THEAD
1895 ><TR
1896 ><TH
1897 >TERMTYPE</TH
1898 ><TH
1899 >Meaning</TH
1900 ></TR
1901 ></THEAD
1902 ><TBODY
1903 ><TR
1904 ><TD
1905 >00</TD
1906 ><TD
1907 >end of expression</TD
1908 ></TR
1909 ><TR
1910 ><TD
1911 >01</TD
1912 ><TD
1913 >integer (16 bit in big endian order follows)</TD
1914 ></TR
1915 ><TR
1916 ><TD
1917 >02</TD
1918 ><TD
1919 > external symbol reference (NUL terminated symbol name follows)</TD
1920 ></TR
1921 ><TR
1922 ><TD
1923 >03</TD
1924 ><TD
1925 >local symbol reference (NUL terminated symbol name follows)</TD
1926 ></TR
1927 ><TR
1928 ><TD
1929 >04</TD
1930 ><TD
1931 >operator (1 byte operator number)</TD
1932 ></TR
1933 ><TR
1934 ><TD
1935 >05</TD
1936 ><TD
1937 >section base address reference</TD
1938 ></TR
1939 ></TBODY
1940 ></TABLE
1941 ></DIV
1942 ><P
1943 >External references are resolved using other object files while local
1944 references are resolved using the local symbol table(s) from this file. This
1945 allows local symbols that are not exported to have the same names as
1946 exported symbols or external references.</P
1947 ><DIV
1948 CLASS="TABLE"
1949 ><A
1950 NAME="AEN610"
1951 ></A
1952 ><P
1953 ><B
1954 >Table 5-2. Object File Operator Numbers</B
1955 ></P
1956 ><TABLE
1957 BORDER="1"
1958 FRAME="border"
1959 CLASS="CALSTABLE"
1960 ><COL><COL><THEAD
1961 ><TR
1962 ><TH
1963 >Number</TH
1964 ><TH
1965 >Operator</TH
1966 ></TR
1967 ></THEAD
1968 ><TBODY
1969 ><TR
1970 ><TD
1971 >01</TD
1972 ><TD
1973 >addition (+)</TD
1974 ></TR
1975 ><TR
1976 ><TD
1977 >02</TD
1978 ><TD
1979 >subtraction (-)</TD
1980 ></TR
1981 ><TR
1982 ><TD
1983 >03</TD
1984 ><TD
1985 >multiplication (*)</TD
1986 ></TR
1987 ><TR
1988 ><TD
1989 >04</TD
1990 ><TD
1991 >division (/)</TD
1992 ></TR
1993 ><TR
1994 ><TD
1995 >05</TD
1996 ><TD
1997 >modulus (%)</TD
1998 ></TR
1999 ><TR
2000 ><TD
2001 >06</TD
2002 ><TD
2003 >integer division (\) (same as division)</TD
2004 ></TR
2005 ><TR
2006 ><TD
2007 >07</TD
2008 ><TD
2009 >bitwise and</TD
2010 ></TR
2011 ><TR
2012 ><TD
2013 >08</TD
2014 ><TD
2015 >bitwise or</TD
2016 ></TR
2017 ><TR
2018 ><TD
2019 >09</TD
2020 ><TD
2021 >bitwise xor</TD
2022 ></TR
2023 ><TR
2024 ><TD
2025 >0A</TD
2026 ><TD
2027 >boolean and</TD
2028 ></TR
2029 ><TR
2030 ><TD
2031 >0B</TD
2032 ><TD
2033 >boolean or</TD
2034 ></TR
2035 ><TR
2036 ><TD
2037 >0C</TD
2038 ><TD
2039 >unary negation, 2's complement (-)</TD
2040 ></TR
2041 ><TR
2042 ><TD
2043 >0D</TD
2044 ><TD
2045 >unary 1's complement (^)</TD
2046 ></TR
2047 ></TBODY
2048 ></TABLE
2049 ></DIV
2050 ><P
2051 >An expression is represented in a postfix manner with both operands for
2052 binary operators preceding the operator and the single operand for unary
2053 operators preceding the operator.</P
2054 ></DIV
2055 ></DIV
2056 ></BODY
2057 ></HTML
2058 >