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