Mercurial > hg-old > index.cgi

comparison doc/manual/manual.html @ 434:b8bf63962a99 3.0

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