Mercurial > hg-old > index.cgi

comparison doc/manual/manual.html @ 398:7987ee447833 3.0-beta1

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