|
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>
|
|
|
6 <copyright><year>2009</year><holder>William Astle</holder></copyright>
|
|
|
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
|
|
|
446 "nodollarlocal" pragmas. In the absence of a pragma to the contrary, For
|
|
|
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
|
|
|
763 change its value between assembly passes. Thus there is not and never will
|
|
|
764 be any equivalent of IFP1 or IFP2 as provided by other assemblers.</para>
|
|
|
765
|
|
|
766 <variablelist>
|
|
|
767 <varlistentry>
|
|
|
768 <term>IFEQ <parameter>expr</parameter></term>
|
|
|
769 <listitem>
|
|
|
770 <para>If <parameter>expr</parameter> evaluates to zero, the conditional
|
|
|
771 will be considered true.
|
|
|
772 </para>
|
|
|
773 </listitem>
|
|
|
774 </varlistentry>
|
|
|
775
|
|
|
776 <varlistentry>
|
|
|
777 <term>IFNE <parameter>expr</parameter></term>
|
|
|
778 <term>IF <parameter>expr</parameter></term>
|
|
|
779 <listitem>
|
|
|
780 <para>If <parameter>expr</parameter> evaluates to a non-zero value, the conditional
|
|
|
781 will be considered true.
|
|
|
782 </para>
|
|
|
783 </listitem>
|
|
|
784 </varlistentry>
|
|
|
785
|
|
|
786 <varlistentry>
|
|
|
787 <term>IFGT <parameter>expr</parameter></term>
|
|
|
788 <listitem>
|
|
|
789 <para>If <parameter>expr</parameter> evaluates to a value greater than zero, the conditional
|
|
|
790 will be considered true.
|
|
|
791 </para>
|
|
|
792 </listitem>
|
|
|
793 </varlistentry>
|
|
|
794
|
|
|
795 <varlistentry>
|
|
|
796 <term>IFGE <parameter>expr</parameter></term>
|
|
|
797 <listitem>
|
|
|
798 <para>If <parameter>expr</parameter> evaluates to a value greater than or equal to zero, the conditional
|
|
|
799 will be considered true.
|
|
|
800 </para>
|
|
|
801 </listitem>
|
|
|
802 </varlistentry>
|
|
|
803
|
|
|
804 <varlistentry>
|
|
|
805 <term>IFLT <parameter>expr</parameter></term>
|
|
|
806 <listitem>
|
|
|
807 <para>If <parameter>expr</parameter> evaluates to a value less than zero, the conditional
|
|
|
808 will be considered true.
|
|
|
809 </para>
|
|
|
810 </listitem>
|
|
|
811 </varlistentry>
|
|
|
812
|
|
|
813 <varlistentry>
|
|
|
814 <term>IFLE <parameter>expr</parameter></term>
|
|
|
815 <listitem>
|
|
|
816 <para>If <parameter>expr</parameter> evaluates to a value less than or equal to zero , the conditional
|
|
|
817 will be considered true.
|
|
|
818 </para>
|
|
|
819 </listitem>
|
|
|
820 </varlistentry>
|
|
|
821
|
|
|
822 <varlistentry>
|
|
|
823 <term>IFDEF <parameter>sym</parameter></term>
|
|
|
824 <listitem>
|
|
|
825 <para>If <parameter>sym</parameter> is defined at this point in the assembly
|
|
|
826 process, the conditional
|
|
|
827 will be considered true.
|
|
|
828 </para>
|
|
|
829 </listitem>
|
|
|
830 </varlistentry>
|
|
|
831
|
|
|
832 <varlistentry>
|
|
|
833 <term>IFNDEF <parameter>sym</parameter></term>
|
|
|
834 <listitem>
|
|
|
835 <para>If <parameter>sym</parameter> is not defined at this point in the assembly
|
|
|
836 process, the conditional
|
|
|
837 will be considered true.
|
|
|
838 </para>
|
|
|
839 </listitem>
|
|
|
840 </varlistentry>
|
|
|
841
|
|
|
842 <varlistentry>
|
|
|
843 <term>ELSE</term>
|
|
|
844 <listitem>
|
|
|
845 <para>
|
|
|
846 If the preceding conditional at the same level of nesting was false, the
|
|
|
847 statements following will be assembled. If the preceding conditional at
|
|
|
848 the same level was true, the statements following will not be assembled.
|
|
|
849 Note that the preceding conditional might have been another ELSE statement
|
|
|
850 although this behaviour is not guaranteed to be supported in future versions
|
|
|
851 of LWASM.
|
|
|
852 </para>
|
|
|
853 </listitem>
|
|
|
854
|
|
|
855 <varlistentry>
|
|
|
856 <term>ENDC</term>
|
|
|
857 <listitem>
|
|
|
858 <para>
|
|
|
859 This directive marks the end of a conditional construct. Every conditional
|
|
|
860 construct must end with an ENDC directive.
|
|
|
861 </para>
|
|
|
862 </listitem>
|
|
|
863 </varlistentry>
|
|
|
864
|
|
|
865 </variablelist>
|
|
|
866 </section>
|
|
|
867
|
|
|
868 <section>
|
|
|
869 <title>OS9 Target Directives</title>
|
|
|
870
|
|
|
871 <para>This section includes directives that apply solely to the OS9
|
|
|
872 target.</para>
|
|
|
873
|
|
|
874 <variablelist>
|
|
|
875
|
|
|
876 <varlistentry>
|
|
|
877 <term>OS9 <parameter>syscall</parameter></term>
|
|
|
878 <listitem>
|
|
|
879 <para>
|
|
|
880
|
|
|
881 This directive generates a call to the specified system call. <parameter>syscall</parameter> may be an arbitrary expression.
|
|
|
882
|
|
|
883 </para>
|
|
|
884 </listitem>
|
|
|
885 </varlistentry>
|
|
|
886
|
|
|
887 <varlistentry>
|
|
|
888 <term>MOD <parameter>size</parameter>,<parameter>name</parameter>,<parameter>type</parameter>,<parameter>flags</parameter>,<parameter>execoff</parameter>,<parameter>datasize</parameter></term>
|
|
|
889 <listitem>
|
|
|
890 <para>
|
|
|
891
|
|
|
892 This tells LWASM that the beginning of the actual module is here. It will
|
|
|
893 generate a module header based on the parameters specified. It will also
|
|
|
894 begin calcuating the module CRC.
|
|
|
895
|
|
|
896 </para>
|
|
|
897
|
|
|
898 <para>
|
|
|
899
|
|
|
900 The precise meaning of the various parameters is beyond the scope of this
|
|
|
901 document since it is not a tutorial on OS9 module programming.
|
|
|
902
|
|
|
903 </para>
|
|
|
904
|
|
|
905 </listitem>
|
|
|
906 </varlistentry>
|
|
|
907
|
|
|
908 <varlistentry>
|
|
|
909 <term>EMOD</term>
|
|
|
910 <listitem>
|
|
|
911 <para>
|
|
|
912
|
|
|
913 This marks the end of a module and causes LWASM to emit the calculated CRC
|
|
|
914 for the module.
|
|
|
915
|
|
|
916 </para>
|
|
|
917 </varlistentry>
|
|
|
918
|
|
|
919 </variablelist>
|
|
|
920 </section>
|
|
|
921
|
|
|
922 <section>
|
|
|
923 <title>Miscelaneous Directives</title>
|
|
|
924
|
|
|
925 <para>This section includes directives that do not fit into the other
|
|
|
926 categories.</para>
|
|
|
927
|
|
|
928 <variablelist>
|
|
|
929
|
|
|
930 <varlistentry>
|
|
|
931 <term>INCLUDE <parameter>filename</parameter></term>
|
|
|
932 <term>USE <parameter>filename</parameter></term>
|
|
|
933
|
|
|
934 <listitem> <para> Include the contents of <parameter>filename</parameter> at
|
|
|
935 this point in the assembly as though it were a part of the file currently
|
|
|
936 being processed. Note that if whitespace appears in the name of the file,
|
|
|
937 you must enclose <parameter>filename</parameter> in quotes.
|
|
|
938 </para>
|
|
|
939
|
|
|
940 <para>
|
|
|
941 Note that the USE variation is provided only for compatibility with other
|
|
|
942 assemblers. It is recommended to use the INCLUDE variation.</para>
|
|
|
943
|
|
|
944 </listitem>
|
|
|
945 </varlistentry>
|
|
|
946
|
|
|
947 <varlistentry>
|
|
|
948 <term>END <parameter>[expr]</parameter></term>
|
|
|
949 <listitem>
|
|
|
950 <para>
|
|
|
951 This directive causes the assembler to stop assembling immediately as though
|
|
|
952 it ran out of input. For the DECB target only, <parameter>expr</parameter>
|
|
|
953 can be used to set the execution address of the resulting binary. For all
|
|
|
954 other targets, specifying <parameter>expr</parameter> will cause an error.
|
|
|
955 </para>
|
|
|
956 </listitem>
|
|
|
957 </varlistentry>
|
|
|
958
|
|
|
959 <varlistentry>
|
|
|
960 <term>ERROR <parameter>string</parameter></term>
|
|
|
961 <listitem>
|
|
|
962 <para>
|
|
|
963 Causes a custom error message to be printed at this line. This will cause
|
|
|
964 assembly to fail. This directive is most useful inside conditional constructs
|
|
|
965 to cause assembly to fail if some condition that is known bad happens.
|
|
|
966 </para>
|
|
|
967 </listitem>
|
|
|
968 </varlistentry>
|
|
|
969
|
|
|
970 <varlistentry>
|
|
|
971 <term>.MODULE <parameter>string</parameter></term>
|
|
|
972 <listitem>
|
|
|
973 <para>
|
|
|
974 This directive is ignored for most output targets. If the output target
|
|
|
975 supports encoding a module name into it, <parameter>string</parameter>
|
|
|
976 will be used as the module name.
|
|
|
977 </para>
|
|
|
978 <para>
|
|
|
979 As of version 2.2, no supported output targets support this directive.
|
|
|
980 </para>
|
|
|
981 </listitem>
|
|
|
982 </varlistentry>
|
|
|
983
|
|
|
984 </variablelist>
|
|
|
985 </section>
|
|
|
986
|
|
|
987 </section>
|
|
|
988
|
|
|
989 <section>
|
|
|
990 <title>Macros</title>
|
|
|
991 <para>
|
|
|
992 LWASM is a macro assembler. A macro is simply a name that stands in for a
|
|
|
993 series of instructions. Once a macro is defined, it is used like any other
|
|
|
994 assembler directive. Defining a macro can be considered equivalent to adding
|
|
|
995 additional assembler directives.
|
|
|
996 </para>
|
|
|
997 <para>Macros may accept parameters. These parameters are referenced within
|
|
|
998 a macro by the a backslash ("\") followed by a digit 1 through 9 for the first
|
|
|
999 through ninth parameters. They may also be referenced by enclosing the
|
|
|
1000 decimal parameter number in braces ("{num}"). These parameter references
|
|
|
1001 are replaced with the verbatim text of the parameter passed to the macro. A
|
|
|
1002 reference to a non-existent parameter will be replaced by an empty string.
|
|
|
1003 Macro parameters are expanded everywhere on each source line. That means
|
|
|
1004 the parameter to a macro could be used as a symbol or it could even appear
|
|
|
1005 in a comment or could cause an entire source line to be commented out
|
|
|
1006 when the macro is expanded.
|
|
|
1007 </para>
|
|
|
1008 <para>
|
|
|
1009 Parameters passed to a macro are separated by commas and the parameter list
|
|
|
1010 is terminated by any whitespace. This means that neither a comma nor whitespace
|
|
|
1011 may be included in a macro parameter.
|
|
|
1012 </para>
|
|
|
1013 <para>
|
|
|
1014 Macro expansion is done recursively. That is, within a macro, macros are
|
|
|
1015 expanded. This can lead to infinite loops in macro expansion. If the assembler
|
|
|
1016 hangs for a long time while assembling a file that uses macros, this may be
|
|
|
1017 the reason.</para>
|
|
|
1018
|
|
|
1019 <para>Each macro expansion receives its own local symbol context which is not
|
|
|
1020 inherited by any macros called by it nor is it inherited from the context
|
|
|
1021 the macro was instantiated in. That means it is possible to use local symbols
|
|
|
1022 within macros without having them collide with symbols in other macros or
|
|
|
1023 outside the macro itself. However, this also means that using a local symbol
|
|
|
1024 as a parameter to a macro, while legal, will not do what it would seem to do
|
|
|
1025 as it will result in looking up the local symbol in the macro's symbol context
|
|
|
1026 rather than the enclosing context where it came from, likely yielding either
|
|
|
1027 an undefined symbol error or bizarre assembly results.
|
|
|
1028 </para>
|
|
|
1029 <para>
|
|
|
1030 Note that there is no way to define a macro as local to a symbol context. All
|
|
|
1031 macros are part of the global macro namespace. However, macros have a separate
|
|
|
1032 namespace from symbols so it is possible to have a symbol with the same name
|
|
|
1033 as a macro.
|
|
|
1034 </para>
|
|
|
1035
|
|
|
1036 <para>
|
|
|
1037 Macros are defined only during the first pass. Macro expansion also
|
|
|
1038 only occurs during the first pass. On the second pass, the macro
|
|
|
1039 definition is simply ignored. Macros must be defined before they are used.
|
|
|
1040 </para>
|
|
|
1041
|
|
|
1042 <para>The following directives are used when defining macros.</para>
|
|
|
1043
|
|
|
1044 <variablelist>
|
|
|
1045 <varlistentry>
|
|
|
1046 <term><parameter>macroname</parameter> MACRO</term>
|
|
|
1047 <listitem>
|
|
|
1048 <para>This directive is used to being the definition of a macro called
|
|
|
1049 <parameter>macroname</parameter>. If <parameter>macroname</parameter> already
|
|
|
1050 exists, it is considered an error. Attempting to define a macro within a
|
|
|
1051 macro is undefined. It may work and it may not so the behaviour should not
|
|
|
1052 be relied upon.
|
|
|
1053 </para>
|
|
|
1054 </listitem>
|
|
|
1055 </varlistentry>
|
|
|
1056
|
|
|
1057 <varlistentry>
|
|
|
1058 <term>ENDM</term>
|
|
|
1059 <listitem>
|
|
|
1060 <para>
|
|
|
1061 This directive indicates the end of the macro currently being defined. It
|
|
|
1062 causes the assembler to resume interpreting source lines as normal.
|
|
|
1063 </para>
|
|
|
1064 </listitem>
|
|
|
1065 </variablelist>
|
|
|
1066
|
|
|
1067 </section>
|
|
|
1068
|
|
|
1069 <section>
|
|
|
1070 <title>Structures</title>
|
|
|
1071 <para>
|
|
|
1072
|
|
|
1073 Structures are used to group related data in a fixed structure. A structure
|
|
|
1074 consists a number of fields, defined in sequential order and which take up
|
|
|
1075 specified size. The assembler does not enforce any means of access within a
|
|
|
1076 structure; it assumes that whatever you are doing, you intended to do.
|
|
|
1077 There are two pseudo ops that are used for defining structures.
|
|
|
1078
|
|
|
1079 </para>
|
|
|
1080
|
|
|
1081 <variablelist>
|
|
|
1082 <varlistentry>
|
|
|
1083 <term><parameter>structname</parameter> STRUCT</term>
|
|
|
1084 <listitem>
|
|
|
1085 <para>
|
|
|
1086
|
|
|
1087 This directive is used to begin the definition of a structure with name
|
|
|
1088 <parameter>structname</parameter>. Subsequent statements all form part of
|
|
|
1089 the structure definition until the end of the structure is declared.
|
|
|
1090
|
|
|
1091 </para>
|
|
|
1092 </listitem>
|
|
|
1093 </varlistentry>
|
|
|
1094 <varlistentry>
|
|
|
1095 <term>ENDSTRUCT</term>
|
|
|
1096 <listitem>
|
|
|
1097 <para>
|
|
|
1098 This directive ends the definition of the structure.
|
|
|
1099 </para>
|
|
|
1100 </listitem>
|
|
|
1101 </varlistentry>
|
|
|
1102 </variablelist>
|
|
|
1103
|
|
|
1104 <para>
|
|
|
1105
|
|
|
1106 Within a structure definition, only reservation pseudo ops are permitted.
|
|
|
1107 Anything else will cause an assembly error.
|
|
|
1108 </para>
|
|
|
1109
|
|
|
1110 <para> Once a structure is defined, you can reserve an area of memory in the
|
|
|
1111 same structure by using the structure name as the opcode. Structures can
|
|
|
1112 also contain fields that are themselves structures. See the example
|
|
|
1113 below.</para>
|
|
|
1114
|
|
|
1115 <programlisting>
|
|
|
1116 tstruct2 STRUCT
|
|
|
1117 f1 rmb 1
|
|
|
1118 f2 rmb 1
|
|
|
1119 ENDSTRUCT
|
|
|
1120
|
|
|
1121 tstruct STRUCT
|
|
|
1122 field1 rmb 2
|
|
|
1123 field2 rmb 3
|
|
|
1124 field3 tstruct2
|
|
|
1125 ENDSTRUCT
|
|
|
1126
|
|
|
1127 ORG $2000
|
|
|
1128 var1 tstruct
|
|
|
1129 var2 tstruct2
|
|
|
1130 </programlisting>
|
|
|
1131
|
|
|
1132 <para>Fields are referenced using a dot (.) as a separator. To refer to the
|
|
|
1133 generic offset within a structure, use the structure name to the left of the
|
|
|
1134 dot. If referring to a field within an actual variable, use the variable's
|
|
|
1135 symbol name to the left of the dot.</para>
|
|
|
1136
|
|
|
1137 <para>You can also refer to the actual size of a structure (or a variable
|
|
|
1138 declared as a structure) using the special symbol sizeof{structname} where
|
|
|
1139 structname will be the name of the structure or the name of the
|
|
|
1140 variable.</para>
|
|
|
1141
|
|
|
1142 <para>Essentially, structures are a shortcut for defining a vast number of
|
|
|
1143 symbols. When a structure is defined, the assembler creates symbols for the
|
|
|
1144 various fields in the form structname.fieldname as well as the appropriate
|
|
|
1145 sizeof{structname} symbol. When a variable is declared as a structure, the
|
|
|
1146 assembler does the same thing using the name of the variable. You will see
|
|
|
1147 these symbols in the symbol table when the assembler is instructed to
|
|
|
1148 provide a listing. For instance, the above listing will create the
|
|
|
1149 following symbols (symbol values in parentheses): tstruct2.f1 (0),
|
|
|
1150 tstruct2.f2 (1), sizeof{tstruct2} (2), tstruct.field1 (0), tstruct.field2
|
|
|
1151 (2), tstruct.field3 (5), tstruct.field3.f1 (5), tstruct.field3.f2 (6),
|
|
|
1152 sizeof{tstruct.field3} (2), sizeof{tstruct} (7), var1 {$2000}, var1.field1
|
|
|
1153 {$2000}, var1.field2 {$2002}, var1.field3 {$2005}, var1.field3.f1 {$2005},
|
|
|
1154 var1.field3.f2 {$2006}, sizeof(var1.field3} (2), sizeof{var1} (7), var2
|
|
|
1155 ($2007), var2.f1 ($2007), var2.f2 ($2008), sizeof{var2} (2). </para>
|
|
|
1156
|
|
|
1157 </section>
|
|
|
1158
|
|
|
1159 <section>
|
|
|
1160 <title>Object Files and Sections</title>
|
|
|
1161 <para>
|
|
|
1162 The object file target is very useful for large project because it allows
|
|
|
1163 multiple files to be assembled independently and then linked into the final
|
|
|
1164 binary at a later time. It allows only the small portion of the project
|
|
|
1165 that was modified to be re-assembled rather than requiring the entire set
|
|
|
1166 of source code to be available to the assembler in a single assembly process.
|
|
|
1167 This can be particularly important if there are a large number of macros,
|
|
|
1168 symbol definitions, or other metadata that uses resources at assembly time.
|
|
|
1169 By far the largest benefit, however, is keeping the source files small enough
|
|
|
1170 for a mere mortal to find things in them.
|
|
|
1171 </para>
|
|
|
1172
|
|
|
1173 <para>
|
|
|
1174 With multi-file projects, there needs to be a means of resolving references to
|
|
|
1175 symbols in other source files. These are known as external references. The
|
|
|
1176 addresses of these symbols cannot be known until the linker joins all the
|
|
|
1177 object files into a single binary. This means that the assembler must be
|
|
|
1178 able to output the object code without knowing the value of the symbol. This
|
|
|
1179 places some restrictions on the code generated by the assembler. For
|
|
|
1180 example, the assembler cannot generate direct page addressing for instructions
|
|
|
1181 that reference external symbols because the address of the symbol may not
|
|
|
1182 be in the direct page. Similarly, relative branches and PC relative addressing
|
|
|
1183 cannot be used in their eight bit forms. Everything that must be resolved
|
|
|
1184 by the linker must be assembled to use the largest address size possible to
|
|
|
1185 allow the linker to fill in the correct value at link time. Note that the
|
|
|
1186 same problem applies to absolute address references as well, even those in
|
|
|
1187 the same source file, because the address is not known until link time.
|
|
|
1188 </para>
|
|
|
1189
|
|
|
1190 <para>
|
|
|
1191 It is often desired in multi-file projects to have code of various types grouped
|
|
|
1192 together in the final binary generated by the linker as well. The same applies
|
|
|
1193 to data. In order for the linker to do that, the bits that are to be grouped
|
|
|
1194 must be tagged in some manner. This is where the concept of sections comes in.
|
|
|
1195 Each chunk of code or data is part of a section in the object file. Then,
|
|
|
1196 when the linker reads all the object files, it coalesces all sections of the
|
|
|
1197 same name into a single section and then considers it as a unit.
|
|
|
1198 </para>
|
|
|
1199
|
|
|
1200 <para>
|
|
|
1201 The existence of sections, however, raises a problem for symbols even
|
|
|
1202 within the same source file. Thus, the assembler must treat symbols from
|
|
|
1203 different sections within the same source file in the same manner as external
|
|
|
1204 symbols. That is, it must leave them for the linker to resolve at link time,
|
|
|
1205 with all the limitations that entails.
|
|
|
1206 </para>
|
|
|
1207
|
|
|
1208 <para>
|
|
|
1209 In the object file target mode, LWASM requires all source lines that
|
|
|
1210 cause bytes to be output to be inside a section. Any directives that do
|
|
|
1211 not cause any bytes to be output can appear outside of a section. This includes
|
|
|
1212 such things as EQU or RMB. Even ORG can appear outside a section. ORG, however,
|
|
|
1213 makes no sense within a section because it is the linker that determines
|
|
|
1214 the starting address of the section's code, not the assembler.
|
|
|
1215 </para>
|
|
|
1216
|
|
|
1217 <para>
|
|
|
1218 All symbols defined globally in the assembly process are local to the
|
|
|
1219 source file and cannot be exported. All symbols defined within a section are
|
|
|
1220 considered local to the source file unless otherwise explicitly exported.
|
|
|
1221 Symbols referenced from external source files must be declared external,
|
|
|
1222 either explicitly or by asking the assembler to assume that all undefined
|
|
|
1223 symbols are external.
|
|
|
1224 </para>
|
|
|
1225
|
|
|
1226 <para>
|
|
|
1227 It is often handy to define a number of memory addresses that will be
|
|
|
1228 used for data at run-time but which need not be included in the binary file.
|
|
|
1229 These memory addresses are not initialized until run-time, either by the
|
|
|
1230 program itself or by the program loader, depending on the operating environment.
|
|
|
1231 Such sections are often known as BSS sections. LWASM supports generating
|
|
|
1232 sections with a BSS attribute set which causes the section definition including
|
|
|
1233 symbols exported from that section and those symbols required to resolve
|
|
|
1234 references from the local file, but with no actual code in the object file.
|
|
|
1235 It is illegal for any source lines within a BSS flagged section to cause any
|
|
|
1236 bytes to be output.
|
|
|
1237 </para>
|
|
|
1238
|
|
|
1239 <para>The following directives apply to section handling.</para>
|
|
|
1240
|
|
|
1241 <variablelist>
|
|
|
1242 <varlistentry>
|
|
|
1243 <term>SECTION <parameter>name[,flags]</parameter></term>
|
|
|
1244 <term>SECT <parameter>name[,flags]</parameter></term>
|
|
|
1245 <term>.AREA <parameter>name[,flags]</parameter></term>
|
|
|
1246 <listitem>
|
|
|
1247 <para>
|
|
|
1248 Instructs the assembler that the code following this directive is to be
|
|
|
1249 considered part of the section <parameter>name</parameter>. A section name
|
|
|
1250 may appear multiple times in which case it is as though all the code from
|
|
|
1251 all the instances of that section appeared adjacent within the source file.
|
|
|
1252 However, <parameter>flags</parameter> may only be specified on the first
|
|
|
1253 instance of the section.
|
|
|
1254 </para>
|
|
|
1255 <para>There is a single flag supported in <parameter>flags</parameter>. The
|
|
|
1256 flag <parameter>bss</parameter> will cause the section to be treated as a BSS
|
|
|
1257 section and, thus, no code will be included in the object file nor will any
|
|
|
1258 bytes be permitted to be output.</para>
|
|
|
1259 <para>
|
|
|
1260 If the section name is "bss" or ".bss" in any combination of upper and
|
|
|
1261 lower case, the section is assumed to be a BSS section. In that case,
|
|
|
1262 the flag <parameter>!bss</parameter> can be used to override this assumption.
|
|
|
1263 </para>
|
|
|
1264 <para>
|
|
|
1265 If assembly is already happening within a section, the section is implicitly
|
|
|
1266 ended and the new section started. This is not considered an error although
|
|
|
1267 it is recommended that all sections be explicitly closed.
|
|
|
1268 </para>
|
|
|
1269 </listitem>
|
|
|
1270 </varlistentry>
|
|
|
1271
|
|
|
1272 <varlistentry>
|
|
|
1273 <term>ENDSECTION</term>
|
|
|
1274 <term>ENDSECT</term>
|
|
|
1275 <term>ENDS</term>
|
|
|
1276 <listitem>
|
|
|
1277 <para>
|
|
|
1278 This directive ends the current section. This puts assembly outside of any
|
|
|
1279 sections until the next SECTION directive.
|
|
|
1280 </listitem>
|
|
|
1281 </varlistentry>
|
|
|
1282
|
|
|
1283 <varlistentry>
|
|
|
1284 <term><parameter>sym</parameter> EXTERN</term>
|
|
|
1285 <term><parameter>sym</parameter> EXTERNAL</term>
|
|
|
1286 <term><parameter>sym</parameter> IMPORT</term>
|
|
|
1287 <listitem>
|
|
|
1288 <para>
|
|
|
1289 This directive defines <parameter>sym</parameter> as an external symbol.
|
|
|
1290 This directive may occur at any point in the source code. EXTERN definitions
|
|
|
1291 are resolved on the first pass so an EXTERN definition anywhere in the
|
|
|
1292 source file is valid for the entire file. The use of this directive is
|
|
|
1293 optional when the assembler is instructed to assume that all undefined
|
|
|
1294 symbols are external. In fact, in that mode, if the symbol is referenced
|
|
|
1295 before the EXTERN directive, an error will occur.
|
|
|
1296 </para>
|
|
|
1297 </listitem>
|
|
|
1298 </varlistentry>
|
|
|
1299
|
|
|
1300 <varlistentry>
|
|
|
1301 <term><parameter>sym</parameter> EXPORT</term>
|
|
|
1302 <term><parameter>sym</parameter> .GLOBL</term>
|
|
|
1303
|
|
|
1304 <term>EXPORT <parameter>sym</parameter></term>
|
|
|
1305 <term>.GLOBL <parameter>sym</parameter></term>
|
|
|
1306
|
|
|
1307 <listitem>
|
|
|
1308 <para>
|
|
|
1309 This directive defines <parameter>sym</parameter> as an exported symbol.
|
|
|
1310 This directive may occur at any point in the source code, even before the
|
|
|
1311 definition of the exported symbol.
|
|
|
1312 </para>
|
|
|
1313 <para>
|
|
|
1314 Note that <parameter>sym</parameter> may appear as the operand or as the
|
|
|
1315 statement's symbol. If there is a symbol on the statement, that will
|
|
|
1316 take precedence over any operand that is present.
|
|
|
1317 </para>
|
|
|
1318 </listitem>
|
|
|
1319
|
|
|
1320 </varlistentry>
|
|
|
1321
|
|
|
1322 <varlistentry>
|
|
|
1323 <term><parameter>sym</parameter>EXTDEP</term>
|
|
|
1324 <listitem>
|
|
|
1325
|
|
|
1326 <para>This directive forces an external dependency on
|
|
|
1327 <parameter>sym</parameter>, even if it is never referenced anywhere else in
|
|
|
1328 this file.</para>
|
|
|
1329
|
|
|
1330 </listitem>
|
|
|
1331 </varlistentry>
|
|
|
1332 </variablelist>
|
|
|
1333
|
|
|
1334 </section>
|
|
|
1335
|
|
|
1336 <section>
|
|
|
1337 <title>Assembler Modes and Pragmas</title>
|
|
|
1338 <para>
|
|
|
1339 There are a number of options that affect the way assembly is performed.
|
|
|
1340 Some of these options can only be specified on the command line because
|
|
|
1341 they determine something absolute about the assembly process. These include
|
|
|
1342 such things as the output target. Other things may be switchable during
|
|
|
1343 the assembly process. These are known as pragmas and are, by definition,
|
|
|
1344 not portable between assemblers.
|
|
|
1345 </para>
|
|
|
1346
|
|
|
1347 <para>LWASM supports a number of pragmas that affect code generation or
|
|
|
1348 otherwise affect the behaviour of the assembler. These may be specified by
|
|
|
1349 way of a command line option or by assembler directives. The directives
|
|
|
1350 are as follows.
|
|
|
1351 </para>
|
|
|
1352
|
|
|
1353 <variablelist>
|
|
|
1354 <varlistentry>
|
|
|
1355 <term>PRAGMA <parameter>pragma[,...]</parameter></term>
|
|
|
1356 <listitem>
|
|
|
1357 <para>
|
|
|
1358 Specifies that the assembler should bring into force all <parameter>pragma</parameter>s
|
|
|
1359 specified. Any unrecognized pragma will cause an assembly error. The new
|
|
|
1360 pragmas will take effect immediately. This directive should be used when
|
|
|
1361 the program will assemble incorrectly if the pragma is ignored or not supported.
|
|
|
1362 </para>
|
|
|
1363 </listitem>
|
|
|
1364 </varlistentry>
|
|
|
1365
|
|
|
1366 <varlistentry>
|
|
|
1367 <term>*PRAGMA <parameter>pragma[,...]</parameter></term>
|
|
|
1368 <listitem>
|
|
|
1369 <para>
|
|
|
1370 This is identical to the PRAGMA directive except no error will occur with
|
|
|
1371 unrecognized or unsupported pragmas. This directive, by virtue of starting
|
|
|
1372 with a comment character, will also be ignored by assemblers that do not
|
|
|
1373 support this directive. Use this variation if the pragma is not required
|
|
|
1374 for correct functioning of the code.
|
|
|
1375 </para>
|
|
|
1376 </listitem>
|
|
|
1377 </varlistentry>
|
|
|
1378 </variablelist>
|
|
|
1379
|
|
|
1380 <para>Each pragma supported has a positive version and a negative version.
|
|
|
1381 The positive version enables the pragma while the negative version disables
|
|
|
1382 it. The negatitve version is simply the positive version with "no" prefixed
|
|
|
1383 to it. For instance, "pragma" vs. "nopragma". Only the positive version is
|
|
|
1384 listed below.</para>
|
|
|
1385
|
|
|
1386 <para>Pragmas are not case sensitive.</para>
|
|
|
1387
|
|
|
1388 <variablelist>
|
|
|
1389 <varlistentry>
|
|
|
1390 <term>index0tonone</term>
|
|
|
1391 <listitem>
|
|
|
1392 <para>
|
|
|
1393 When in force, this pragma enables an optimization affecting indexed addressing
|
|
|
1394 modes. When the offset expression in an indexed mode evaluates to zero but is
|
|
|
1395 not explicity written as 0, this will replace the operand with the equivalent
|
|
|
1396 no offset mode, thus creating slightly faster code. Because of the advantages
|
|
|
1397 of this optimization, it is enabled by default.
|
|
|
1398 </para>
|
|
|
1399 </listitem>
|
|
|
1400 </varlistentry>
|
|
|
1401
|
|
|
1402 <varlistentry>
|
|
|
1403 <term>cescapes</term>
|
|
|
1404 <listitem>
|
|
|
1405 <para>
|
|
|
1406 This pragma will cause strings in the FCC, FCS, and FCN pseudo operations to
|
|
|
1407 have C-style escape sequences interpreted. The one departure from the official
|
|
|
1408 spec is that unrecognized escape sequences will return either the character
|
|
|
1409 immediately following the backslash or some undefined value. Do not rely
|
|
|
1410 on the behaviour of undefined escape sequences.
|
|
|
1411 </para>
|
|
|
1412 </listitem>
|
|
|
1413 </varlistentry>
|
|
|
1414
|
|
|
1415 <varlistentry>
|
|
|
1416 <term>importundefexport</term>
|
|
|
1417 <listitem>
|
|
|
1418 <para>
|
|
|
1419 This pragma is only valid for targets that support external references. When
|
|
|
1420 in force, it will cause the EXPORT directive to act as IMPORT if the symbol
|
|
|
1421 to be exported is not defined. This is provided for compatibility with the
|
|
|
1422 output of gcc6809 and should not be used in hand written code. Because of
|
|
|
1423 the confusion this pragma can cause, it is disabled by default.
|
|
|
1424 </para>
|
|
|
1425 </listitem>
|
|
|
1426 </varlistentry>
|
|
|
1427
|
|
|
1428 <varlistentry>
|
|
|
1429 <term>undefextern</term>
|
|
|
1430 <listitem>
|
|
|
1431 <para>
|
|
|
1432 This pragma is only valid for targets that support external references. When in
|
|
|
1433 force, if the assembler sees an undefined symbol on the second pass, it will
|
|
|
1434 automatically define it as an external symbol. This automatic definition will
|
|
|
1435 apply for the remainder of the assembly process, even if the pragma is
|
|
|
1436 subsequently turned off. Because this behaviour would be potentially surprising,
|
|
|
1437 this pragma defaults to off.
|
|
|
1438 </para>
|
|
|
1439 <para>
|
|
|
1440 The primary use for this pragma is for projects that share a large number of
|
|
|
1441 symbols between source files. In such cases, it is impractical to enumerate
|
|
|
1442 all the external references in every source file. This allows the assembler
|
|
|
1443 and linker to do the heavy lifting while not preventing a particular source
|
|
|
1444 module from defining a local symbol of the same name as an external symbol
|
|
|
1445 if it does not need the external symbol. (This pragma will not cause an
|
|
|
1446 automatic external definition if there is already a locally defined symbol.)
|
|
|
1447 </para>
|
|
|
1448 <para>
|
|
|
1449 This pragma will often be specified on the command line for large projects.
|
|
|
1450 However, depending on the specific dynamics of the project, it may be sufficient
|
|
|
1451 for one or two files to use this pragma internally.
|
|
|
1452 </para>
|
|
|
1453 </listitem>
|
|
|
1454 </varlistentry>
|
|
|
1455
|
|
|
1456 <varlistentry>
|
|
|
1457 <term>dollarlocal</term>
|
|
|
1458 <listitem>
|
|
|
1459
|
|
|
1460 <para>When set, a "$" in a symbol makes it local. When not set, "$" does not
|
|
|
1461 cause a symbol to be local. It is set by default except when using the OS9
|
|
|
1462 target.</para>
|
|
|
1463
|
|
|
1464 </listitem>
|
|
|
1465 </varlistentry>
|
|
|
1466
|
|
|
1467 <varlistentry>
|
|
|
1468 <term>dollarnotlocal</term>
|
|
|
1469 <listitem>
|
|
|
1470
|
|
|
1471 <para> This is the same as the "dollarlocal" pragma except its sense is
|
|
|
1472 reversed. That is, "dollarlocal" and "nodollarnotlocal" are equivalent and
|
|
|
1473 "nodollarlocal" and "dollarnotlocal" are equivalent. </para>
|
|
|
1474
|
|
|
1475 </listitem>
|
|
|
1476 </varlistentry>
|
|
|
1477
|
|
|
1478 </variablelist>
|
|
|
1479
|
|
|
1480 </section>
|
|
|
1481
|
|
|
1482 </chapter>
|
|
|
1483
|
|
|
1484 <chapter>
|
|
|
1485 <title>LWLINK</title>
|
|
|
1486 <para>
|
|
|
1487 The LWTOOLS linker is called LWLINK. This chapter documents the various features
|
|
|
1488 of the linker.
|
|
|
1489 </para>
|
|
|
1490
|
|
|
1491 <section>
|
|
|
1492 <title>Command Line Options</title>
|
|
|
1493 <para>
|
|
|
1494 The binary for LWLINK is called "lwlink". Note that the binary is in lower
|
|
|
1495 case. lwlink takes the following command line arguments.
|
|
|
1496 </para>
|
|
|
1497 <variablelist>
|
|
|
1498 <varlistentry>
|
|
|
1499 <term><option>--decb</option></term>
|
|
|
1500 <term><option>-b</option></term>
|
|
|
1501 <listitem>
|
|
|
1502 <para>
|
|
|
1503 Selects the DECB output format target. This is equivalent to <option>--format=decb</option>
|
|
|
1504 </para>
|
|
|
1505 </listitem>
|
|
|
1506 </varlistentry>
|
|
|
1507
|
|
|
1508 <varlistentry>
|
|
|
1509 <term><option>--output=FILE</option></term>
|
|
|
1510 <term><option>-o FILE</option></term>
|
|
|
1511 <listitem>
|
|
|
1512 <para>
|
|
|
1513 This option specifies the name of the output file. If not specified, the
|
|
|
1514 default is <option>a.out</option>.
|
|
|
1515 </para>
|
|
|
1516 </listitem>
|
|
|
1517 </varlistentry>
|
|
|
1518
|
|
|
1519 <varlistentry>
|
|
|
1520 <term><option>--format=TYPE</option></term>
|
|
|
1521 <term><option>-f TYPE</option></term>
|
|
|
1522 <listitem>
|
|
|
1523 <para>
|
|
|
1524 This option specifies the output format. Valid values are <option>decb</option>
|
|
|
1525 and <option>raw</option>
|
|
|
1526 </para>
|
|
|
1527 </listitem>
|
|
|
1528 </varlistentry>
|
|
|
1529
|
|
|
1530 <varlistentry>
|
|
|
1531 <term><option>--raw</option></term>
|
|
|
1532 <term><option>-r</option></term>
|
|
|
1533 <listitem>
|
|
|
1534 <para>
|
|
|
1535 This option specifies the raw output format.
|
|
|
1536 It is equivalent to <option>--format=raw</option>
|
|
|
1537 and <option>-f raw</option>
|
|
|
1538 </para>
|
|
|
1539 </listitem>
|
|
|
1540 </varlistentry>
|
|
|
1541
|
|
|
1542 <varlistentry>
|
|
|
1543 <term><option>--script=FILE</option></term>
|
|
|
1544 <term><option>-s</option></term>
|
|
|
1545 <listitem>
|
|
|
1546 <para>
|
|
|
1547 This option allows specifying a linking script to override the linker's
|
|
|
1548 built in defaults.
|
|
|
1549 </para>
|
|
|
1550 </listitem>
|
|
|
1551 </varlistentry>
|
|
|
1552
|
|
|
1553 <varlistentry>
|
|
|
1554 <term><option>--section-base=SECT=BASE</option></term>
|
|
|
1555 <listitem>
|
|
|
1556 <para>
|
|
|
1557 Cause section SECT to load at base address BASE. This will be prepended
|
|
|
1558 to the built-in link script. It is ignored if a link script is provided.
|
|
|
1559 </para>
|
|
|
1560 </listitem>
|
|
|
1561 </varlistentry>
|
|
|
1562
|
|
|
1563 <varlistentry>
|
|
|
1564 <term><option>--map=FILE</option></term>
|
|
|
1565 <term><option>-m FILE</option></term>
|
|
|
1566 <listitem>
|
|
|
1567 <para>
|
|
|
1568 This will output a description of the link result to FILE.
|
|
|
1569 </para>
|
|
|
1570 </listitem>
|
|
|
1571 </varlistentry>
|
|
|
1572
|
|
|
1573 <varlistentry>
|
|
|
1574 <term><option>--library=LIBSPEC</option></term>
|
|
|
1575 <term><option>-l LIBSPEC</option></term>
|
|
|
1576 <listitem>
|
|
|
1577 <para>
|
|
|
1578 Load a library using the library search path. LIBSPEC will have "lib" prepended
|
|
|
1579 and ".a" appended.
|
|
|
1580 </para>
|
|
|
1581 </listitem>
|
|
|
1582 </varlistentry>
|
|
|
1583
|
|
|
1584 <varlistentry>
|
|
|
1585 <term><option>--library-path=DIR</option></term>
|
|
|
1586 <term><option>-L DIR</option></term>
|
|
|
1587 <listitem>
|
|
|
1588 <para>
|
|
|
1589 Add DIR to the library search path.
|
|
|
1590 </para>
|
|
|
1591 </listitem>
|
|
|
1592 </varlistentry>
|
|
|
1593
|
|
|
1594 <varlistentry>
|
|
|
1595 <term><option>--debug</option></term>
|
|
|
1596 <term><option>-d</option></term>
|
|
|
1597 <listitem>
|
|
|
1598 <para>
|
|
|
1599 This option increases the debugging level. It is only useful for LWTOOLS
|
|
|
1600 developers.
|
|
|
1601 </para>
|
|
|
1602 </listitem>
|
|
|
1603 </varlistentry>
|
|
|
1604
|
|
|
1605 <varlistentry>
|
|
|
1606 <term><option>--help</option></term>
|
|
|
1607 <term><option>-?</option></term>
|
|
|
1608 <listitem>
|
|
|
1609 <para>
|
|
|
1610 This provides a listing of command line options and a brief description
|
|
|
1611 of each.
|
|
|
1612 </para>
|
|
|
1613 </listitem>
|
|
|
1614 </varlistentry>
|
|
|
1615
|
|
|
1616 <varlistentry>
|
|
|
1617 <term><option>--usage</option></term>
|
|
|
1618 <listitem>
|
|
|
1619 <para>
|
|
|
1620 This will display a usage summary
|
|
|
1621 of each command line option.
|
|
|
1622 </para>
|
|
|
1623 </listitem>
|
|
|
1624 </varlistentry>
|
|
|
1625
|
|
|
1626
|
|
|
1627 <varlistentry>
|
|
|
1628 <term><option>--version</option></term>
|
|
|
1629 <term><option>-V</option></term>
|
|
|
1630 <listitem>
|
|
|
1631 <para>
|
|
|
1632 This will display the version of LWLINK.
|
|
|
1633 </para>
|
|
|
1634 </listitem>
|
|
|
1635 </varlistentry>
|
|
|
1636
|
|
|
1637 </section>
|
|
|
1638
|
|
|
1639 <section>
|
|
|
1640 <title>Linker Operation</title>
|
|
|
1641
|
|
|
1642 <para>
|
|
|
1643
|
|
|
1644 LWLINK takes one or more files in supported input formats and links them
|
|
|
1645 into a single binary. Currently supported formats are the LWTOOLS object
|
|
|
1646 file format and the archive format used by LWAR. While the precise method is
|
|
|
1647 slightly different, linking can be conceptualized as the following steps.
|
|
|
1648
|
|
|
1649 </para>
|
|
|
1650
|
|
|
1651 <orderedlist>
|
|
|
1652 <listitem>
|
|
|
1653 <para>
|
|
|
1654 First, the linker loads a linking script. If no script is specified, it
|
|
|
1655 loads a built-in default script based on the output format selected. This
|
|
|
1656 script tells the linker how to lay out the various sections in the final
|
|
|
1657 binary.
|
|
|
1658 </para>
|
|
|
1659 </listitem>
|
|
|
1660
|
|
|
1661 <listitem>
|
|
|
1662 <para>
|
|
|
1663 Next, the linker reads all the input files into memory. At this time, it
|
|
|
1664 flags any format errors in those files. It constructs a table of symbols
|
|
|
1665 for each object at this time.
|
|
|
1666 </para>
|
|
|
1667 </listitem>
|
|
|
1668
|
|
|
1669 <listitem>
|
|
|
1670 <para>
|
|
|
1671 The linker then proceeds with organizing the sections loaded from each file
|
|
|
1672 according to the linking script. As it does so, it is able to assign addresses
|
|
|
1673 to each symbol defined in each object file. At this time, the linker may
|
|
|
1674 also collapse different instances of the same section name into a single
|
|
|
1675 section by appending the data from each subsequent instance of the section
|
|
|
1676 to the first instance of the section.
|
|
|
1677 </para>
|
|
|
1678 </listitem>
|
|
|
1679
|
|
|
1680 <listitem>
|
|
|
1681 <para>
|
|
|
1682 Next, the linker looks through every object file for every incomplete reference.
|
|
|
1683 It then attempts to fully resolve that reference. If it cannot do so, it
|
|
|
1684 throws an error. Once a reference is resolved, the value is placed into
|
|
|
1685 the binary code at the specified section. It should be noted that an
|
|
|
1686 incomplete reference can reference either a symbol internal to the object
|
|
|
1687 file or an external symbol which is in the export list of another object
|
|
|
1688 file.
|
|
|
1689 </para>
|
|
|
1690 </listitem>
|
|
|
1691
|
|
|
1692 <listitem>
|
|
|
1693 <para>
|
|
|
1694 If all of the above steps are successful, the linker opens the output file
|
|
|
1695 and actually constructs the binary.
|
|
|
1696 </para>
|
|
|
1697 </listitem>
|
|
|
1698 </orderedlist>
|
|
|
1699
|
|
|
1700 </section>
|
|
|
1701
|
|
|
1702 <section
|
|
|
1703 <title>Linking Scripts</title>
|
|
|
1704 <para>
|
|
|
1705 A linker script is used to instruct the linker about how to assemble the
|
|
|
1706 various sections into a completed binary. It consists of a series of
|
|
|
1707 directives which are considered in the order they are encountered.
|
|
|
1708 </para>
|
|
|
1709 <para>
|
|
|
1710 The sections will appear in the resulting binary in the order they are
|
|
|
1711 specified in the script file. If a referenced section is not found, the linker will behave as though the
|
|
|
1712 section did exist but had a zero size, no relocations, and no exports.
|
|
|
1713 A section should only be referenced once. Any subsequent references will have
|
|
|
1714 an undefined effect.
|
|
|
1715 </para>
|
|
|
1716
|
|
|
1717 <para>
|
|
|
1718 All numbers are in linking scripts are specified in hexadecimal. All directives
|
|
|
1719 are case sensitive although the hexadecimal numbers are not.
|
|
|
1720 </para>
|
|
|
1721
|
|
|
1722 <para>A section name can be specified as a "*", then any section not
|
|
|
1723 already matched by the script will be matched. The "*" can be followed
|
|
|
1724 by a comma and a flag to narrow the section down slightly, also.
|
|
|
1725 If the flag is "!bss", then any section that is not flagged as a bss section
|
|
|
1726 will be matched. If the flag is "bss", then any section that is flagged as
|
|
|
1727 bss will be matched.
|
|
|
1728 </para>
|
|
|
1729
|
|
|
1730 <para>The following directives are understood in a linker script.</para>
|
|
|
1731 <variablelist>
|
|
|
1732 <varlistentry>
|
|
|
1733 <term>section <parameter>name</parameter> load <parameter>addr</parameter></term>
|
|
|
1734 <listitem><para>
|
|
|
1735
|
|
|
1736 This causes the section <parameter>name</parameter> to load at
|
|
|
1737 <parameter>addr</parameter>. For the raw target, only one "load at" entry is
|
|
|
1738 allowed for non-bss sections and it must be the first one. For raw targets,
|
|
|
1739 it affects the addresses the linker assigns to symbols but has no other
|
|
|
1740 affect on the output. bss sections may all have separate load addresses but
|
|
|
1741 since they will not appear in the binary anyway, this is okay.
|
|
|
1742 </para><para>
|
|
|
1743 For the decb target, each "load" entry will cause a new "block" to be
|
|
|
1744 output to the binary which will contain the load address. It is legal for
|
|
|
1745 sections to overlap in this manner - the linker assumes the loader will sort
|
|
|
1746 everything out.
|
|
|
1747 </para></listitem>
|
|
|
1748 </varlistentry>
|
|
|
1749
|
|
|
1750 <varlistentry>
|
|
|
1751 <term>section <parameter>name</parameter></term>
|
|
|
1752 <listitem><para>
|
|
|
1753
|
|
|
1754 This will cause the section <parameter>name</parameter> to load after the previously listed
|
|
|
1755 section.
|
|
|
1756 </para></listitem></varlistentry>
|
|
|
1757 <varlistentry>
|
|
|
1758 <term>exec <parameter>addr or sym</parameter></term>
|
|
|
1759 <listitem>
|
|
|
1760 <para>
|
|
|
1761 This will cause the execution address (entry point) to be the address
|
|
|
1762 specified (in hex) or the specified symbol name. The symbol name must
|
|
|
1763 match a symbol that is exported by one of the object files being linked.
|
|
|
1764 This has no effect for targets that do not encode the entry point into the
|
|
|
1765 resulting file. If not specified, the entry point is assumed to be address 0
|
|
|
1766 which is probably not what you want. The default link scripts for targets
|
|
|
1767 that support this directive automatically starts at the beginning of the
|
|
|
1768 first section (usually "init" or "code") that is emitted in the binary.
|
|
|
1769 </para>
|
|
|
1770 </listitem>
|
|
|
1771 </varlistentry>
|
|
|
1772
|
|
|
1773 <varlistentry>
|
|
|
1774 <term>pad <parameter>size</parameter></term>
|
|
|
1775 <listitem><para>
|
|
|
1776 This will cause the output file to be padded with NUL bytes to be exactly
|
|
|
1777 <parameter>size</parameter> bytes in length. This only makes sense for a raw target.
|
|
|
1778 </para>
|
|
|
1779 </listitem>
|
|
|
1780 </varlistentry>
|
|
|
1781 </variablelist>
|
|
|
1782
|
|
|
1783
|
|
|
1784
|
|
|
1785 </section>
|
|
|
1786
|
|
|
1787 </chapter>
|
|
|
1788
|
|
|
1789 <chapter>
|
|
|
1790 <title>Libraries and LWAR</title>
|
|
|
1791
|
|
|
1792 <para>
|
|
|
1793 LWTOOLS also includes a tool for managing libraries. These are analogous to
|
|
|
1794 the static libraries created with the "ar" tool on POSIX systems. Each library
|
|
|
1795 file contains one or more object files. The linker will treat the object
|
|
|
1796 files within a library as though they had been specified individually on
|
|
|
1797 the command line except when resolving external references. External references
|
|
|
1798 are looked up first within the object files within the library and then, if
|
|
|
1799 not found, the usual lookup based on the order the files are specified on
|
|
|
1800 the command line occurs.
|
|
|
1801 </para>
|
|
|
1802
|
|
|
1803 <para>
|
|
|
1804 The tool for creating these libary files is called LWAR.
|
|
|
1805 </para>
|
|
|
1806
|
|
|
1807 <section>
|
|
|
1808 <title>Command Line Options</title>
|
|
|
1809 <para>
|
|
|
1810 The binary for LWAR is called "lwar". Note that the binary is in lower
|
|
|
1811 case. The options lwar understands are listed below. For archive manipulation
|
|
|
1812 options, the first non-option argument is the name of the archive. All other
|
|
|
1813 non-option arguments are the names of files to operate on.
|
|
|
1814 </para>
|
|
|
1815
|
|
|
1816 <variablelist>
|
|
|
1817 <varlistentry>
|
|
|
1818 <term><option>--add</option></term>
|
|
|
1819 <term><option>-a</option></term>
|
|
|
1820 <listitem>
|
|
|
1821 <para>
|
|
|
1822 This option specifies that an archive is going to have files added to it.
|
|
|
1823 If the archive does not already exist, it is created. New files are added
|
|
|
1824 to the end of the archive.
|
|
|
1825 </para>
|
|
|
1826 </listitem>
|
|
|
1827 </varlistentry>
|
|
|
1828
|
|
|
1829 <varlistentry>
|
|
|
1830 <term><option>--create</option></term>
|
|
|
1831 <term><option>-c</option></term>
|
|
|
1832 <listitem>
|
|
|
1833 <para>
|
|
|
1834 This option specifies that an archive is going to be created and have files
|
|
|
1835 added to it. If the archive already exists, it is truncated.
|
|
|
1836 </para>
|
|
|
1837 </listitem>
|
|
|
1838 </varlistentry>
|
|
|
1839
|
|
|
1840 <varlistentry>
|
|
|
1841 <term><option>--merge</option></term>
|
|
|
1842 <term><option>-m</option></term>
|
|
|
1843 <listitem>
|
|
|
1844 <para>
|
|
|
1845 If specified, any files specified to be added to an archive will be checked
|
|
|
1846 to see if they are archives themselves. If so, their constituent members are
|
|
|
1847 added to the archive. This is useful for avoiding archives containing archives.
|
|
|
1848 </para>
|
|
|
1849 </listitem>
|
|
|
1850 </varlistentry>
|
|
|
1851
|
|
|
1852 <varlistentry>
|
|
|
1853 <term><option>--list</option></term>
|
|
|
1854 <term><option>-l</option></term>
|
|
|
1855 <listitem>
|
|
|
1856 <para>
|
|
|
1857 This will display a list of the files contained in the archive.
|
|
|
1858 </para>
|
|
|
1859 </listitem>
|
|
|
1860 </varlistentry>
|
|
|
1861
|
|
|
1862 <varlistentry>
|
|
|
1863 <term><option>--debug</option></term>
|
|
|
1864 <term><option>-d</option></term>
|
|
|
1865 <listitem>
|
|
|
1866 <para>
|
|
|
1867 This option increases the debugging level. It is only useful for LWTOOLS
|
|
|
1868 developers.
|
|
|
1869 </para>
|
|
|
1870 </listitem>
|
|
|
1871 </varlistentry>
|
|
|
1872
|
|
|
1873 <varlistentry>
|
|
|
1874 <term><option>--help</option></term>
|
|
|
1875 <term><option>-?</option></term>
|
|
|
1876 <listitem>
|
|
|
1877 <para>
|
|
|
1878 This provides a listing of command line options and a brief description
|
|
|
1879 of each.
|
|
|
1880 </para>
|
|
|
1881 </listitem>
|
|
|
1882 </varlistentry>
|
|
|
1883
|
|
|
1884 <varlistentry>
|
|
|
1885 <term><option>--usage</option></term>
|
|
|
1886 <listitem>
|
|
|
1887 <para>
|
|
|
1888 This will display a usage summary
|
|
|
1889 of each command line option.
|
|
|
1890 </para>
|
|
|
1891 </listitem>
|
|
|
1892 </varlistentry>
|
|
|
1893
|
|
|
1894
|
|
|
1895 <varlistentry>
|
|
|
1896 <term><option>--version</option></term>
|
|
|
1897 <term><option>-V</option></term>
|
|
|
1898 <listitem>
|
|
|
1899 <para>
|
|
|
1900 This will display the version of LWLINK.
|
|
|
1901 of each.
|
|
|
1902 </para>
|
|
|
1903 </listitem>
|
|
|
1904 </varlistentry>
|
|
|
1905
|
|
|
1906 </section>
|
|
|
1907
|
|
|
1908 </chapter>
|
|
|
1909
|
|
|
1910 <chapter id="objchap">
|
|
|
1911 <title>Object Files</title>
|
|
|
1912 <para>
|
|
|
1913 LWTOOLS uses a proprietary object file format. It is proprietary in the sense
|
|
|
1914 that it is specific to LWTOOLS, not that it is a hidden format. It would be
|
|
|
1915 hard to keep it hidden in an open source tool chain anyway. This chapter
|
|
|
1916 documents the object file format.
|
|
|
1917 </para>
|
|
|
1918
|
|
|
1919 <para>
|
|
|
1920 An object file consists of a series of sections each of which contains a
|
|
|
1921 list of exported symbols, a list of incomplete references, and a list of
|
|
|
1922 "local" symbols which may be used in calculating incomplete references. Each
|
|
|
1923 section will obviously also contain the object code.
|
|
|
1924 </para>
|
|
|
1925
|
|
|
1926 <para>
|
|
|
1927 Exported symbols must be completely resolved to an address within the
|
|
|
1928 section it is exported from. That is, an exported symbol must be a constant
|
|
|
1929 rather than defined in terms of other symbols.</para>
|
|
|
1930
|
|
|
1931 <para>
|
|
|
1932 Each object file starts with a magic number and version number. The magic
|
|
|
1933 number is the string "LWOBJ16" for this 16 bit object file format. The only
|
|
|
1934 defined version number is currently 0. Thus, the first 8 bytes of the object
|
|
|
1935 file are <code>4C574F424A313600</code>
|
|
|
1936 </para>
|
|
|
1937
|
|
|
1938 <para>
|
|
|
1939 Each section has the following items in order:
|
|
|
1940 </para>
|
|
|
1941
|
|
|
1942 <itemizedlist>
|
|
|
1943 <listitem><para>section name</para></listitem>
|
|
|
1944 <listitem><para>flags</para></listitem>
|
|
|
1945 <listitem><para>list of local symbols (and addresses within the section)</para></listitem>
|
|
|
1946 <listitem><para>list of exported symbols (and addresses within the section)</para></listitem>
|
|
|
1947 <listitem><para>list of incomplete references along with the expressions to calculate them</para></listitem>
|
|
|
1948 <listitem><para>the actual object code (for non-BSS sections)</para></listitem>
|
|
|
1949 </itemizedlist>
|
|
|
1950
|
|
|
1951 <para>
|
|
|
1952 The section starts with the name of the section with a NUL termination
|
|
|
1953 followed by a series of flag bytes terminated by NUL. There are only two
|
|
|
1954 flag bytes defined. A NUL (0) indicates no more flags and a value of 1
|
|
|
1955 indicates the section is a BSS section. For a BSS section, no actual
|
|
|
1956 code is included in the object file.
|
|
|
1957 </para>
|
|
|
1958
|
|
|
1959 <para>
|
|
|
1960 Either a NULL section name or end of file indicate the presence of no more
|
|
|
1961 sections.
|
|
|
1962 </para>
|
|
|
1963
|
|
|
1964 <para>
|
|
|
1965 Each entry in the exported and local symbols table consists of the symbol
|
|
|
1966 (NUL terminated) followed by two bytes which contain the value in big endian
|
|
|
1967 order. The end of a symbol table is indicated by a NULL symbol name.
|
|
|
1968 </para>
|
|
|
1969
|
|
|
1970 <para>
|
|
|
1971 Each entry in the incomplete references table consists of an expression
|
|
|
1972 followed by a 16 bit offset where the reference goes. Expressions are
|
|
|
1973 defined as a series of terms up to an "end of expression" term. Each term
|
|
|
1974 consists of a single byte which identifies the type of term (see below)
|
|
|
1975 followed by any data required by the term. Then end of the list is flagged
|
|
|
1976 by a NULL expression (only an end of expression term).
|
|
|
1977 </para>
|
|
|
1978
|
|
|
1979 <table frame="all"><title>Object File Term Types</title>
|
|
|
1980 <tgroup cols="2">
|
|
|
1981 <thead>
|
|
|
1982 <row>
|
|
|
1983 <entry>TERMTYPE</entry>
|
|
|
1984 <entry>Meaning</entry>
|
|
|
1985 </row>
|
|
|
1986 </thead>
|
|
|
1987 <tbody>
|
|
|
1988 <row>
|
|
|
1989 <entry>00</entry>
|
|
|
1990 <entry>end of expression</entry>
|
|
|
1991 </row>
|
|
|
1992
|
|
|
1993 <row>
|
|
|
1994 <entry>01</entry>
|
|
|
1995 <entry>integer (16 bit in big endian order follows)</entry>
|
|
|
1996 </row>
|
|
|
1997 <row>
|
|
|
1998 <entry>02</entry>
|
|
|
1999 <entry> external symbol reference (NUL terminated symbol name follows)</entry>
|
|
|
2000 </row>
|
|
|
2001
|
|
|
2002 <row>
|
|
|
2003 <entry>03</entry>
|
|
|
2004 <entry>local symbol reference (NUL terminated symbol name follows)</entry>
|
|
|
2005 </row>
|
|
|
2006
|
|
|
2007 <row>
|
|
|
2008 <entry>04</entry>
|
|
|
2009 <entry>operator (1 byte operator number)</entry>
|
|
|
2010 </row>
|
|
|
2011 <row>
|
|
|
2012 <entry>05</entry>
|
|
|
2013 <entry>section base address reference</entry>
|
|
|
2014 </row>
|
|
|
2015
|
|
|
2016 <row>
|
|
|
2017 <entry>FF</entry>
|
|
|
2018 <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>
|
|
|
2019 </row>
|
|
|
2020 </tbody>
|
|
|
2021 </tgroup>
|
|
|
2022 </table>
|
|
|
2023
|
|
|
2024
|
|
|
2025 <para>
|
|
|
2026 External references are resolved using other object files while local
|
|
|
2027 references are resolved using the local symbol table(s) from this file. This
|
|
|
2028 allows local symbols that are not exported to have the same names as
|
|
|
2029 exported symbols or external references.
|
|
|
2030 </para>
|
|
|
2031
|
|
|
2032 <table frame="all"><title>Object File Operator Numbers</title>
|
|
|
2033 <tgroup cols="2">
|
|
|
2034 <thead>
|
|
|
2035 <row>
|
|
|
2036 <entry>Number</entry>
|
|
|
2037 <entry>Operator</entry>
|
|
|
2038 </row>
|
|
|
2039 </thead>
|
|
|
2040 <tbody>
|
|
|
2041 <row>
|
|
|
2042 <entry>01</entry>
|
|
|
2043 <entry>addition (+)</entry>
|
|
|
2044 </row>
|
|
|
2045 <row>
|
|
|
2046 <entry>02</entry>
|
|
|
2047 <entry>subtraction (-)</entry>
|
|
|
2048 </row>
|
|
|
2049 <row>
|
|
|
2050 <entry>03</entry>
|
|
|
2051 <entry>multiplication (*)</entry>
|
|
|
2052 </row>
|
|
|
2053 <row>
|
|
|
2054 <entry>04</entry>
|
|
|
2055 <entry>division (/)</entry>
|
|
|
2056 </row>
|
|
|
2057 <row>
|
|
|
2058 <entry>05</entry>
|
|
|
2059 <entry>modulus (%)</entry>
|
|
|
2060 </row>
|
|
|
2061 <row>
|
|
|
2062 <entry>06</entry>
|
|
|
2063 <entry>integer division (\) (same as division)</entry>
|
|
|
2064 </row>
|
|
|
2065
|
|
|
2066 <row>
|
|
|
2067 <entry>07</entry>
|
|
|
2068 <entry>bitwise and</entry>
|
|
|
2069 </row>
|
|
|
2070
|
|
|
2071 <row>
|
|
|
2072 <entry>08</entry>
|
|
|
2073 <entry>bitwise or</entry>
|
|
|
2074 </row>
|
|
|
2075
|
|
|
2076 <row>
|
|
|
2077 <entry>09</entry>
|
|
|
2078 <entry>bitwise xor</entry>
|
|
|
2079 </row>
|
|
|
2080
|
|
|
2081 <row>
|
|
|
2082 <entry>0A</entry>
|
|
|
2083 <entry>boolean and</entry>
|
|
|
2084 </row>
|
|
|
2085
|
|
|
2086 <row>
|
|
|
2087 <entry>0B</entry>
|
|
|
2088 <entry>boolean or</entry>
|
|
|
2089 </row>
|
|
|
2090
|
|
|
2091 <row>
|
|
|
2092 <entry>0C</entry>
|
|
|
2093 <entry>unary negation, 2's complement (-)</entry>
|
|
|
2094 </row>
|
|
|
2095
|
|
|
2096 <row>
|
|
|
2097 <entry>0D</entry>
|
|
|
2098 <entry>unary 1's complement (^)</entry>
|
|
|
2099 </row>
|
|
|
2100 </tbody>
|
|
|
2101 </tgroup>
|
|
|
2102 </table>
|
|
|
2103
|
|
|
2104 <para>
|
|
|
2105 An expression is represented in a postfix manner with both operands for
|
|
|
2106 binary operators preceding the operator and the single operand for unary
|
|
|
2107 operators preceding the operator.
|
|
|
2108 </para>
|
|
|
2109
|
|
|
2110 </chapter>
|
|
|
2111 </book>
|
|
|
2112
|
