|
455
|
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
|
|
|
2 <HTML
|
|
|
3 ><HEAD
|
|
|
4 ><TITLE
|
|
|
5 >LW Tool Chain</TITLE
|
|
|
6 ><META
|
|
|
7 NAME="GENERATOR"
|
|
|
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"></HEAD
|
|
|
9 ><BODY
|
|
|
10 CLASS="BOOK"
|
|
|
11 BGCOLOR="#FFFFFF"
|
|
|
12 TEXT="#000000"
|
|
|
13 LINK="#0000FF"
|
|
|
14 VLINK="#840084"
|
|
|
15 ALINK="#0000FF"
|
|
|
16 ><DIV
|
|
|
17 CLASS="BOOK"
|
|
|
18 ><A
|
|
|
19 NAME="AEN1"
|
|
|
20 ></A
|
|
|
21 ><DIV
|
|
|
22 CLASS="TITLEPAGE"
|
|
|
23 ><H1
|
|
|
24 CLASS="TITLE"
|
|
|
25 ><A
|
|
|
26 NAME="AEN2"
|
|
|
27 >LW Tool Chain</A
|
|
|
28 ></H1
|
|
|
29 ><H3
|
|
|
30 CLASS="AUTHOR"
|
|
|
31 ><A
|
|
|
32 NAME="AEN4"
|
|
|
33 ></A
|
|
|
34 >William Astle</H3
|
|
|
35 ><H3
|
|
|
36 CLASS="AUTHOR"
|
|
|
37 ><A
|
|
|
38 NAME="AEN7"
|
|
|
39 ></A
|
|
|
40 >LWTools Contributors </H3
|
|
|
41 ><P
|
|
|
42 CLASS="COPYRIGHT"
|
|
|
43 >Copyright © 2009-2015 William Astle and LWTools contributors</P
|
|
|
44 ><HR></DIV
|
|
|
45 ><DIV
|
|
|
46 CLASS="TOC"
|
|
|
47 ><DL
|
|
|
48 ><DT
|
|
|
49 ><B
|
|
|
50 >Table of Contents</B
|
|
|
51 ></DT
|
|
|
52 ><DT
|
|
|
53 >1. <A
|
|
|
54 HREF="#AEN13"
|
|
|
55 >Introduction</A
|
|
|
56 ></DT
|
|
|
57 ><DD
|
|
|
58 ><DL
|
|
|
59 ><DT
|
|
|
60 >1.1. <A
|
|
|
61 HREF="#AEN16"
|
|
|
62 >History</A
|
|
|
63 ></DT
|
|
|
64 ></DL
|
|
|
65 ></DD
|
|
|
66 ><DT
|
|
|
67 >2. <A
|
|
|
68 HREF="#AEN21"
|
|
|
69 >Output Formats</A
|
|
|
70 ></DT
|
|
|
71 ><DD
|
|
|
72 ><DL
|
|
|
73 ><DT
|
|
|
74 >2.1. <A
|
|
|
75 HREF="#AEN24"
|
|
|
76 >Raw Binaries</A
|
|
|
77 ></DT
|
|
|
78 ><DT
|
|
|
79 >2.2. <A
|
|
|
80 HREF="#AEN27"
|
|
|
81 >DECB Binaries</A
|
|
|
82 ></DT
|
|
|
83 ><DT
|
|
|
84 >2.3. <A
|
|
|
85 HREF="#AEN32"
|
|
|
86 >ASCII Hexadecimal</A
|
|
|
87 ></DT
|
|
|
88 ><DT
|
|
|
89 >2.4. <A
|
|
|
90 HREF="#AEN36"
|
|
|
91 >Motorola S-Record</A
|
|
|
92 ></DT
|
|
|
93 ><DT
|
|
|
94 >2.5. <A
|
|
|
95 HREF="#AEN41"
|
|
|
96 >Intel Hex</A
|
|
|
97 ></DT
|
|
|
98 ><DT
|
|
|
99 >2.6. <A
|
|
|
100 HREF="#AEN46"
|
|
|
101 >OS9 Modules</A
|
|
|
102 ></DT
|
|
|
103 ><DT
|
|
|
104 >2.7. <A
|
|
|
105 HREF="#AEN54"
|
|
|
106 >Object Files</A
|
|
|
107 ></DT
|
|
|
108 ></DL
|
|
|
109 ></DD
|
|
|
110 ><DT
|
|
|
111 >3. <A
|
|
|
112 HREF="#AEN62"
|
|
|
113 >LWASM</A
|
|
|
114 ></DT
|
|
|
115 ><DD
|
|
|
116 ><DL
|
|
|
117 ><DT
|
|
|
118 >3.1. <A
|
|
|
119 HREF="#AEN65"
|
|
|
120 >Command Line Options</A
|
|
|
121 ></DT
|
|
|
122 ><DT
|
|
|
123 >3.2. <A
|
|
|
124 HREF="#AEN218"
|
|
|
125 >Dialects</A
|
|
|
126 ></DT
|
|
|
127 ><DT
|
|
|
128 >3.3. <A
|
|
|
129 HREF="#AEN227"
|
|
|
130 >Source Format</A
|
|
|
131 ></DT
|
|
|
132 ><DT
|
|
|
133 >3.4. <A
|
|
|
134 HREF="#AEN237"
|
|
|
135 >Symbols</A
|
|
|
136 ></DT
|
|
|
137 ><DT
|
|
|
138 >3.5. <A
|
|
|
139 HREF="#AEN242"
|
|
|
140 >Numbers and Expressions</A
|
|
|
141 ></DT
|
|
|
142 ><DT
|
|
|
143 >3.6. <A
|
|
|
144 HREF="#AEN250"
|
|
|
145 >Assembler Directives</A
|
|
|
146 ></DT
|
|
|
147 ><DD
|
|
|
148 ><DL
|
|
|
149 ><DT
|
|
|
150 >3.6.1. <A
|
|
|
151 HREF="#AEN253"
|
|
|
152 >Data Directives</A
|
|
|
153 ></DT
|
|
|
154 ><DT
|
|
|
155 >3.6.2. <A
|
|
|
156 HREF="#AEN364"
|
|
|
157 >Address Definition</A
|
|
|
158 ></DT
|
|
|
159 ><DT
|
|
|
160 >3.6.3. <A
|
|
|
161 HREF="#AEN415"
|
|
|
162 >Conditional Assembly</A
|
|
|
163 ></DT
|
|
|
164 ><DT
|
|
|
165 >3.6.4. <A
|
|
|
166 HREF="#AEN486"
|
|
|
167 >OS9 Target Directives</A
|
|
|
168 ></DT
|
|
|
169 ><DT
|
|
|
170 >3.6.5. <A
|
|
|
171 HREF="#AEN511"
|
|
|
172 >Miscelaneous Directives</A
|
|
|
173 ></DT
|
|
|
174 ></DL
|
|
|
175 ></DD
|
|
|
176 ><DT
|
|
|
177 >3.7. <A
|
|
|
178 HREF="#AEN551"
|
|
|
179 >Macros</A
|
|
|
180 ></DT
|
|
|
181 ><DT
|
|
|
182 >3.8. <A
|
|
|
183 HREF="#AEN574"
|
|
|
184 >Structures</A
|
|
|
185 ></DT
|
|
|
186 ><DT
|
|
|
187 >3.9. <A
|
|
|
188 HREF="#AEN595"
|
|
|
189 >Object Files and Sections</A
|
|
|
190 ></DT
|
|
|
191 ><DT
|
|
|
192 >3.10. <A
|
|
|
193 HREF="#AEN659"
|
|
|
194 >Assembler Modes and Pragmas</A
|
|
|
195 ></DT
|
|
|
196 ><DT
|
|
|
197 >3.11. <A
|
|
|
198 HREF="#CONVINST"
|
|
|
199 >Convenience Instructions</A
|
|
|
200 ></DT
|
|
|
201 ><DT
|
|
|
202 >3.12. <A
|
|
|
203 HREF="#AEN805"
|
|
|
204 >Cycle Counts</A
|
|
|
205 ></DT
|
|
|
206 ></DL
|
|
|
207 ></DD
|
|
|
208 ><DT
|
|
|
209 >4. <A
|
|
|
210 HREF="#AEN811"
|
|
|
211 >LWLINK</A
|
|
|
212 ></DT
|
|
|
213 ><DD
|
|
|
214 ><DL
|
|
|
215 ><DT
|
|
|
216 >4.1. <A
|
|
|
217 HREF="#AEN814"
|
|
|
218 >Command Line Options</A
|
|
|
219 ></DT
|
|
|
220 ><DT
|
|
|
221 >4.2. <A
|
|
|
222 HREF="#AEN911"
|
|
|
223 >Linker Operation</A
|
|
|
224 ></DT
|
|
|
225 ><DT
|
|
|
226 >4.3. <A
|
|
|
227 HREF="#AEN925"
|
|
|
228 >Linking Scripts</A
|
|
|
229 ></DT
|
|
|
230 ><DT
|
|
|
231 >4.4. <A
|
|
|
232 HREF="#AEN991"
|
|
|
233 >Format Specific Linking Notes</A
|
|
|
234 ></DT
|
|
|
235 ><DD
|
|
|
236 ><DL
|
|
|
237 ><DT
|
|
|
238 >4.4.1. <A
|
|
|
239 HREF="#AEN994"
|
|
|
240 >OS9 Modules</A
|
|
|
241 ></DT
|
|
|
242 ></DL
|
|
|
243 ></DD
|
|
|
244 ></DL
|
|
|
245 ></DD
|
|
|
246 ><DT
|
|
|
247 >5. <A
|
|
|
248 HREF="#AEN1006"
|
|
|
249 >Libraries and LWAR</A
|
|
|
250 ></DT
|
|
|
251 ><DD
|
|
|
252 ><DL
|
|
|
253 ><DT
|
|
|
254 >5.1. <A
|
|
|
255 HREF="#AEN1010"
|
|
|
256 >Command Line Options</A
|
|
|
257 ></DT
|
|
|
258 ></DL
|
|
|
259 ></DD
|
|
|
260 ><DT
|
|
|
261 >6. <A
|
|
|
262 HREF="#OBJCHAP"
|
|
|
263 >Object Files</A
|
|
|
264 ></DT
|
|
|
265 ></DL
|
|
|
266 ></DIV
|
|
|
267 ><DIV
|
|
|
268 CLASS="LOT"
|
|
|
269 ><DL
|
|
|
270 CLASS="LOT"
|
|
|
271 ><DT
|
|
|
272 ><B
|
|
|
273 >List of Tables</B
|
|
|
274 ></DT
|
|
|
275 ><DT
|
|
|
276 >6-1. <A
|
|
|
277 HREF="#AEN1093"
|
|
|
278 >Object File Term Types</A
|
|
|
279 ></DT
|
|
|
280 ><DT
|
|
|
281 >6-2. <A
|
|
|
282 HREF="#AEN1123"
|
|
|
283 >Object File Operator Numbers</A
|
|
|
284 ></DT
|
|
|
285 ></DL
|
|
|
286 ></DIV
|
|
|
287 ><DIV
|
|
|
288 CLASS="CHAPTER"
|
|
|
289 ><HR><H1
|
|
|
290 ><A
|
|
|
291 NAME="AEN13"
|
|
|
292 ></A
|
|
|
293 >Chapter 1. Introduction</H1
|
|
|
294 ><P
|
|
|
295 >The LW tool chain provides utilities for building binaries for MC6809 and
|
|
|
296 HD6309 CPUs. The tool chain includes a cross-assembler and a cross-linker
|
|
|
297 which support several styles of output.</P
|
|
|
298 ><DIV
|
|
|
299 CLASS="SECTION"
|
|
|
300 ><HR><H2
|
|
|
301 CLASS="SECTION"
|
|
|
302 ><A
|
|
|
303 NAME="AEN16"
|
|
|
304 >1.1. History</A
|
|
|
305 ></H2
|
|
|
306 ><P
|
|
|
307 >For a long time, I have had an interest in creating an operating system for
|
|
|
308 the Coco3. I finally started working on that project around the beginning of
|
|
|
309 2006. I had a number of assemblers I could choose from. Eventually, I settled
|
|
|
310 on one and started tinkering. After a while, I realized that assembler was not
|
|
|
311 going to be sufficient due to lack of macros and issues with forward references.
|
|
|
312 Then I tried another which handled forward references correctly but still did
|
|
|
313 not support macros. I looked around at other assemblers and they all lacked
|
|
|
314 one feature or another that I really wanted for creating my operating system.</P
|
|
|
315 ><P
|
|
|
316 >The solution seemed clear at that point. I am a fair programmer so I figured
|
|
|
317 I could write an assembler that would do everything I wanted an assembler to
|
|
|
318 do. Thus the LWASM probject was born. After more than two years of on and off
|
|
|
319 work, version 1.0 of LWASM was released in October of 2008.</P
|
|
|
320 ><P
|
|
|
321 >As the aforementioned operating system project progressed further, it became
|
|
|
322 clear that while assembling the whole project through a single file was doable,
|
|
|
323 it was not practical. When I found myself playing some fancy games with macros
|
|
|
324 in a bid to simulate sections, I realized I needed a means of assembling
|
|
|
325 source files separately and linking them later. This spawned a major development
|
|
|
326 effort to add an object file support to LWASM. It also spawned the LWLINK
|
|
|
327 project to provide a means to actually link the files.</P
|
|
|
328 ></DIV
|
|
|
329 ></DIV
|
|
|
330 ><DIV
|
|
|
331 CLASS="CHAPTER"
|
|
|
332 ><HR><H1
|
|
|
333 ><A
|
|
|
334 NAME="AEN21"
|
|
|
335 ></A
|
|
|
336 >Chapter 2. Output Formats</H1
|
|
|
337 ><P
|
|
|
338 >The LW tool chain supports multiple output formats. Each format has its
|
|
|
339 advantages and disadvantages. Each format is described below.</P
|
|
|
340 ><DIV
|
|
|
341 CLASS="SECTION"
|
|
|
342 ><HR><H2
|
|
|
343 CLASS="SECTION"
|
|
|
344 ><A
|
|
|
345 NAME="AEN24"
|
|
|
346 >2.1. Raw Binaries</A
|
|
|
347 ></H2
|
|
|
348 ><P
|
|
|
349 >A raw binary is simply a string of bytes. There are no headers or other
|
|
|
350 niceties. Both LWLINK and LWASM support generating raw binaries. ORG directives
|
|
|
351 in the source code only serve to set the addresses that will be used for
|
|
|
352 symbols but otherwise have no direct impact on the resulting binary.</P
|
|
|
353 ></DIV
|
|
|
354 ><DIV
|
|
|
355 CLASS="SECTION"
|
|
|
356 ><HR><H2
|
|
|
357 CLASS="SECTION"
|
|
|
358 ><A
|
|
|
359 NAME="AEN27"
|
|
|
360 >2.2. DECB Binaries</A
|
|
|
361 ></H2
|
|
|
362 ><P
|
|
|
363 >A DECB binary is compatible with the LOADM command in Disk Extended
|
|
|
364 Color Basic on the CoCo. They are also compatible with CLOADM from Extended
|
|
|
365 Color Basic. These binaries include the load address of the binary as well
|
|
|
366 as encoding an execution address. These binaries may contain multiple loadable
|
|
|
367 sections, each of which has its own load address.</P
|
|
|
368 ><P
|
|
|
369 >Each binary starts with a preamble. Each preamble is five bytes long. The
|
|
|
370 first byte is zero. The next two bytes specify the number of bytes to load
|
|
|
371 and the last two bytes specify the address to load the bytes at. Then, a
|
|
|
372 string of bytes follows. After this string of bytes, there may be another
|
|
|
373 preamble or a postamble. A postamble is also five bytes in length. The first
|
|
|
374 byte of the postamble is $FF, the next two are zero, and the last two are
|
|
|
375 the execution address for the binary.</P
|
|
|
376 ><P
|
|
|
377 >Both LWASM and LWLINK can output this format.</P
|
|
|
378 ></DIV
|
|
|
379 ><DIV
|
|
|
380 CLASS="SECTION"
|
|
|
381 ><HR><H2
|
|
|
382 CLASS="SECTION"
|
|
|
383 ><A
|
|
|
384 NAME="AEN32"
|
|
|
385 >2.3. ASCII Hexadecimal</A
|
|
|
386 ></H2
|
|
|
387 ><P
|
|
|
388 >This human-readable ASCII hexadecimal format consists of CR+LF terminated
|
|
|
389 lines of ASCII text. Each line has the following structure: a zero-padded
|
|
|
390 four-digit ASCII hex address, a colon separator, and one or more zero-padded
|
|
|
391 two-digit hex values separated by commas. ASCII Hexadecimal format favors
|
|
|
392 paragraph-aligned addresses (i.e. a least significant address nybble value
|
|
|
393 of zero). During output, the number of hex values on each line are adjusted
|
|
|
394 to align the address of the next line on a paragraph boundary. The sequence
|
|
|
395 of addresses in the ASCII Hexadecimal file directly follows that of the source
|
|
|
396 file; multiple ORG directives in the source code may result in out-of-sequence
|
|
|
397 addresses in the ASCII Hexadecimal output.</P
|
|
|
398 ><P
|
|
|
399 >LWASM can output this format since version 4.10.</P
|
|
|
400 ></DIV
|
|
|
401 ><DIV
|
|
|
402 CLASS="SECTION"
|
|
|
403 ><HR><H2
|
|
|
404 CLASS="SECTION"
|
|
|
405 ><A
|
|
|
406 NAME="AEN36"
|
|
|
407 >2.4. Motorola S-Record</A
|
|
|
408 ></H2
|
|
|
409 ><P
|
|
|
410 >This ASCII format consists of a series of CR+LF terminated "records" of ASCII
|
|
|
411 text. Each record has the following structure: a start-of-record character
|
|
|
412 "S", an ASCII record type digit (0-9), a two-digit ASCII hex byte count, a
|
|
|
413 four-digit ASCII hex address, an optional sequence of two-digit ASCII hex data
|
|
|
414 values, and a two-digit ASCII hex checksum. The LW tool chain issues only S0,
|
|
|
415 S1, S5 and S9 record types. S1 records are limited to maximum of 16 data bytes
|
|
|
416 in length, and paragraph alignment of addresses is favored. The address
|
|
|
417 sequence of the S-Records directly follows that of the source file; multiple
|
|
|
418 ORG directives in the source code may result in out-of-sequence addresses in
|
|
|
419 the S-Record output. </P
|
|
|
420 ><P
|
|
|
421 >Motorola S-Record format is a standard ASCII format accepted by most memory
|
|
|
422 device programming equipment. It is particularly useful when the assembled
|
|
|
423 code output is destined to reside within an EPROM or Flash memory device,
|
|
|
424 for example.</P
|
|
|
425 ><P
|
|
|
426 >LWASM can output this format since version 4.10. LWLINK can output this format
|
|
|
427 since version 4.11.</P
|
|
|
428 ></DIV
|
|
|
429 ><DIV
|
|
|
430 CLASS="SECTION"
|
|
|
431 ><HR><H2
|
|
|
432 CLASS="SECTION"
|
|
|
433 ><A
|
|
|
434 NAME="AEN41"
|
|
|
435 >2.5. Intel Hex</A
|
|
|
436 ></H2
|
|
|
437 ><P
|
|
|
438 >This ASCII format consists of a series of CR+LF terminated "records" of ASCII
|
|
|
439 text. Each record has the following structure: a start-of-record character
|
|
|
440 ":", a two-digit ASCII hex byte count, a four-digit ASCII hex address, a two-
|
|
|
441 digit ASCII hex record type, an optional sequence of two-digit ASCII hex data
|
|
|
442 values, and a two-digit ASCII hex checksum. The LW tool chain issues only 00,
|
|
|
443 and 01 Intel Hex record types. Data records are limited to maximum of 16
|
|
|
444 data bytes in length, and paragraph alignment of addresses is favored. The
|
|
|
445 address sequence of the Intel hex records directly follows that of the source
|
|
|
446 file; multiple ORG directives in the source code may result in out-of-sequence
|
|
|
447 addresses in the Intel Hex output. </P
|
|
|
448 ><P
|
|
|
449 >Intel Hex format is the other standard ASCII format accepted by most memory
|
|
|
450 device programming equipment, it and the Motorola S-Record format are used for
|
|
|
451 similar purposes.</P
|
|
|
452 ><P
|
|
|
453 >LWASM can output this format since version 4.10.</P
|
|
|
454 ></DIV
|
|
|
455 ><DIV
|
|
|
456 CLASS="SECTION"
|
|
|
457 ><HR><H2
|
|
|
458 CLASS="SECTION"
|
|
|
459 ><A
|
|
|
460 NAME="AEN46"
|
|
|
461 >2.6. OS9 Modules</A
|
|
|
462 ></H2
|
|
|
463 ><P
|
|
|
464 > Since version 2.5, LWASM is able to generate OS9 modules. The syntax is
|
|
|
465 basically the same as for other assemblers. A module starts with the MOD
|
|
|
466 directive and ends with the EMOD directive. The OS9 directive is provided
|
|
|
467 as a shortcut for writing system calls. </P
|
|
|
468 ><P
|
|
|
469 > LWASM does NOT provide an OS9Defs file. You must provide your own. Also note
|
|
|
470 that the common practice of using "ifp1" around the inclusion of the OS9Defs
|
|
|
471 file is discouraged as it is pointless and can lead to unintentional
|
|
|
472 problems and phasing errors. Because LWASM reads each file exactly once,
|
|
|
473 there is no benefit to restricting the inclusion to the first assembly pass. </P
|
|
|
474 ><P
|
|
|
475 > As of version 4.5, LWASM also implements the standard data/code address
|
|
|
476 streams for OS9 modules. That means that between MOD and EMOD, any RMB,
|
|
|
477 RMD, RMQ, or equivalent directives will move the data address ahead and
|
|
|
478 leave the code address unmodified. Outside of an actual module, both the
|
|
|
479 code and data addresses are moved ahead equally. That last bit is critical
|
|
|
480 to understand because it means any directives that follow an EMOD directive
|
|
|
481 may have different results than other assemblers. </P
|
|
|
482 ><P
|
|
|
483 > Additionally, within a module body, the ORG directive sets only the data
|
|
|
484 address, not the code address. However, outside a module body, ORG sets both
|
|
|
485 addresses. </P
|
|
|
486 ><P
|
|
|
487 >Both code and data addresses are reset to 0 by the MOD directive.</P
|
|
|
488 ><P
|
|
|
489 > As of version 4.5, LWLINK also supports creation of OS9 modules. </P
|
|
|
490 ></DIV
|
|
|
491 ><DIV
|
|
|
492 CLASS="SECTION"
|
|
|
493 ><HR><H2
|
|
|
494 CLASS="SECTION"
|
|
|
495 ><A
|
|
|
496 NAME="AEN54"
|
|
|
497 >2.7. Object Files</A
|
|
|
498 ></H2
|
|
|
499 ><P
|
|
|
500 >LWASM supports generating a proprietary object file format which is
|
|
|
501 described in <A
|
|
|
502 HREF="#OBJCHAP"
|
|
|
503 >Chapter 6</A
|
|
|
504 >. LWLINK is then used to link these
|
|
|
505 object files into a final binary in any of LWLINK's supported binary
|
|
|
506 formats.</P
|
|
|
507 ><P
|
|
|
508 >Object files also support the concept of sections which are not valid
|
|
|
509 for other output types. This allows related code from each object file
|
|
|
510 linked to be collapsed together in the final binary.</P
|
|
|
511 ><P
|
|
|
512 >Object files are very flexible in that they allow references that are not
|
|
|
513 known at assembly time to be resolved at link time. However, because the
|
|
|
514 addresses of such references are not known at assembly time, there is no way
|
|
|
515 for the assembler to deduce that an eight bit addressing mode is possible.
|
|
|
516 That means the assember will default to using sixteen bit addressing
|
|
|
517 whenever an external or cross-section reference is used.</P
|
|
|
518 ><P
|
|
|
519 >As of LWASM 2.4, it is possible to force direct page addressing for an
|
|
|
520 external reference. Care must be taken to ensure the resulting addresses
|
|
|
521 are really in the direct page since the linker does not know what the direct
|
|
|
522 page is supposed to be and does not emit errors for byte overflows.</P
|
|
|
523 ><P
|
|
|
524 >It is also possible to use external references in an eight bit immediate
|
|
|
525 mode instruction. In this case, only the low order eight bits will be used.
|
|
|
526 Again, no byte overflows will be flagged.</P
|
|
|
527 ></DIV
|
|
|
528 ></DIV
|
|
|
529 ><DIV
|
|
|
530 CLASS="CHAPTER"
|
|
|
531 ><HR><H1
|
|
|
532 ><A
|
|
|
533 NAME="AEN62"
|
|
|
534 ></A
|
|
|
535 >Chapter 3. LWASM</H1
|
|
|
536 ><P
|
|
|
537 >The LWTOOLS assembler is called LWASM. This chapter documents the various
|
|
|
538 features of the assembler. It is not, however, a tutorial on 6x09 assembly
|
|
|
539 language programming.</P
|
|
|
540 ><DIV
|
|
|
541 CLASS="SECTION"
|
|
|
542 ><HR><H2
|
|
|
543 CLASS="SECTION"
|
|
|
544 ><A
|
|
|
545 NAME="AEN65"
|
|
|
546 >3.1. Command Line Options</A
|
|
|
547 ></H2
|
|
|
548 ><P
|
|
|
549 >The binary for LWASM is called "lwasm". Note that the binary is in lower
|
|
|
550 case. lwasm takes the following command line arguments.</P
|
|
|
551 ><P
|
|
|
552 ></P
|
|
|
553 ><DIV
|
|
|
554 CLASS="VARIABLELIST"
|
|
|
555 ><DL
|
|
|
556 ><DT
|
|
|
557 ><CODE
|
|
|
558 CLASS="OPTION"
|
|
|
559 >--6309</CODE
|
|
|
560 >, <CODE
|
|
|
561 CLASS="OPTION"
|
|
|
562 >-3</CODE
|
|
|
563 ></DT
|
|
|
564 ><DD
|
|
|
565 ><P
|
|
|
566 >This will cause the assembler to accept the additional instructions available
|
|
|
567 on the 6309 processor. This is the default mode; this option is provided for
|
|
|
568 completeness and to override preset command arguments.</P
|
|
|
569 ><P
|
|
|
570 >This option is the same as if the first line of the source code is "PRAGMA 6309".</P
|
|
|
571 ></DD
|
|
|
572 ><DT
|
|
|
573 ><CODE
|
|
|
574 CLASS="OPTION"
|
|
|
575 >--6800compat</CODE
|
|
|
576 ></DT
|
|
|
577 ><DD
|
|
|
578 ><P
|
|
|
579 >This is equivalent to <CODE
|
|
|
580 CLASS="OPTION"
|
|
|
581 >--pragma=6800compat</CODE
|
|
|
582 >.</P
|
|
|
583 ><P
|
|
|
584 >This will enable recognition of 6800 compatibility instructions.</P
|
|
|
585 ></DD
|
|
|
586 ><DT
|
|
|
587 ><CODE
|
|
|
588 CLASS="OPTION"
|
|
|
589 >--6809</CODE
|
|
|
590 >, <CODE
|
|
|
591 CLASS="OPTION"
|
|
|
592 >-9</CODE
|
|
|
593 ></DT
|
|
|
594 ><DD
|
|
|
595 ><P
|
|
|
596 >This will cause the assembler to reject instructions that are only available
|
|
|
597 on the 6309 processor. This actually has the effect of starting the assembler
|
|
|
598 as though the first line of the source is "PRAGMA 6809".</P
|
|
|
599 ></DD
|
|
|
600 ><DT
|
|
|
601 ><CODE
|
|
|
602 CLASS="OPTION"
|
|
|
603 >--decb</CODE
|
|
|
604 >, <CODE
|
|
|
605 CLASS="OPTION"
|
|
|
606 >-b</CODE
|
|
|
607 ></DT
|
|
|
608 ><DD
|
|
|
609 ><P
|
|
|
610 >Select the DECB output format target. Equivalent to <CODE
|
|
|
611 CLASS="OPTION"
|
|
|
612 >--format=decb</CODE
|
|
|
613 >.</P
|
|
|
614 ><P
|
|
|
615 >While this is the default output format currently, it is not safe to rely
|
|
|
616 on that fact. Future versions may have different defaults. It is also trivial
|
|
|
617 to modify the source code to change the default. Thus, it is recommended to specify
|
|
|
618 this option if you need DECB output.</P
|
|
|
619 ></DD
|
|
|
620 ><DT
|
|
|
621 ><CODE
|
|
|
622 CLASS="OPTION"
|
|
|
623 >--format=type</CODE
|
|
|
624 >, <CODE
|
|
|
625 CLASS="OPTION"
|
|
|
626 >-f type</CODE
|
|
|
627 ></DT
|
|
|
628 ><DD
|
|
|
629 ><P
|
|
|
630 >Select the output format. Valid values are <CODE
|
|
|
631 CLASS="OPTION"
|
|
|
632 >obj</CODE
|
|
|
633 > for the
|
|
|
634 object file target, <CODE
|
|
|
635 CLASS="OPTION"
|
|
|
636 >decb</CODE
|
|
|
637 > for the DECB LOADM format,
|
|
|
638 <CODE
|
|
|
639 CLASS="OPTION"
|
|
|
640 >os9</CODE
|
|
|
641 > for creating OS9 modules, <CODE
|
|
|
642 CLASS="OPTION"
|
|
|
643 >raw</CODE
|
|
|
644 > for
|
|
|
645 a raw binary, <CODE
|
|
|
646 CLASS="OPTION"
|
|
|
647 >hex</CODE
|
|
|
648 > for ASCII hexadecminal format,
|
|
|
649 <CODE
|
|
|
650 CLASS="OPTION"
|
|
|
651 >srec</CODE
|
|
|
652 > for Motorola S-Record format, and <CODE
|
|
|
653 CLASS="OPTION"
|
|
|
654 >ihex</CODE
|
|
|
655 >
|
|
|
656 for Intel Hex format.</P
|
|
|
657 ></DD
|
|
|
658 ><DT
|
|
|
659 ><CODE
|
|
|
660 CLASS="OPTION"
|
|
|
661 >--list[=file]</CODE
|
|
|
662 >, <CODE
|
|
|
663 CLASS="OPTION"
|
|
|
664 >-l[file]</CODE
|
|
|
665 ></DT
|
|
|
666 ><DD
|
|
|
667 ><P
|
|
|
668 >Cause LWASM to generate a listing. If <CODE
|
|
|
669 CLASS="OPTION"
|
|
|
670 >file</CODE
|
|
|
671 > is specified,
|
|
|
672 the listing will go to that file. Otherwise it will go to the standard output
|
|
|
673 stream. By default, no listing is generated. Unless <CODE
|
|
|
674 CLASS="OPTION"
|
|
|
675 >--symbols</CODE
|
|
|
676 >
|
|
|
677 is specified, the list will not include the symbol table.</P
|
|
|
678 ></DD
|
|
|
679 ><DT
|
|
|
680 ><CODE
|
|
|
681 CLASS="OPTION"
|
|
|
682 >--symbols</CODE
|
|
|
683 >, <CODE
|
|
|
684 CLASS="OPTION"
|
|
|
685 >-s</CODE
|
|
|
686 ></DT
|
|
|
687 ><DD
|
|
|
688 ><P
|
|
|
689 >Causes LWASM to generate a list of symbols when generating a listing.
|
|
|
690 It has no effect unless a listing is being generated.</P
|
|
|
691 ></DD
|
|
|
692 ><DT
|
|
|
693 ><CODE
|
|
|
694 CLASS="OPTION"
|
|
|
695 >--symbols-nolocals</CODE
|
|
|
696 ></DT
|
|
|
697 ><DD
|
|
|
698 ><P
|
|
|
699 >Behaves just like <CODE
|
|
|
700 CLASS="OPTION"
|
|
|
701 >--symbols</CODE
|
|
|
702 > but with local labels omitted.</P
|
|
|
703 ></DD
|
|
|
704 ><DT
|
|
|
705 ><CODE
|
|
|
706 CLASS="OPTION"
|
|
|
707 >--map=FILE</CODE
|
|
|
708 ></DT
|
|
|
709 ><DD
|
|
|
710 ><P
|
|
|
711 > This option generates a map file which can be used by debuggers and monitors to provide symbol information. A map file may be created independent of a listing file. (Patches are pending for MAME and exec09.) </P
|
|
|
712 ></DD
|
|
|
713 ><DT
|
|
|
714 ><CODE
|
|
|
715 CLASS="OPTION"
|
|
|
716 >--obj</CODE
|
|
|
717 ></DT
|
|
|
718 ><DD
|
|
|
719 ><P
|
|
|
720 >Select the proprietary object file format as the output target.</P
|
|
|
721 ></DD
|
|
|
722 ><DT
|
|
|
723 ><CODE
|
|
|
724 CLASS="OPTION"
|
|
|
725 >--output=FILE</CODE
|
|
|
726 >, <CODE
|
|
|
727 CLASS="OPTION"
|
|
|
728 >-o FILE</CODE
|
|
|
729 ></DT
|
|
|
730 ><DD
|
|
|
731 ><P
|
|
|
732 >This option specifies the name of the output file. If not specified, the
|
|
|
733 default is <CODE
|
|
|
734 CLASS="OPTION"
|
|
|
735 >a.out</CODE
|
|
|
736 >.</P
|
|
|
737 ></DD
|
|
|
738 ><DT
|
|
|
739 ><CODE
|
|
|
740 CLASS="OPTION"
|
|
|
741 >--pragma=pragma</CODE
|
|
|
742 >, <CODE
|
|
|
743 CLASS="OPTION"
|
|
|
744 >-p pragma</CODE
|
|
|
745 ></DT
|
|
|
746 ><DD
|
|
|
747 ><P
|
|
|
748 >Specify assembler pragmas. Multiple pragmas are separated by commas. The
|
|
|
749 pragmas accepted are the same as for the PRAGMA assembler directive described
|
|
|
750 below.</P
|
|
|
751 ></DD
|
|
|
752 ><DT
|
|
|
753 ><CODE
|
|
|
754 CLASS="OPTION"
|
|
|
755 >--raw</CODE
|
|
|
756 >, <CODE
|
|
|
757 CLASS="OPTION"
|
|
|
758 >-r</CODE
|
|
|
759 ></DT
|
|
|
760 ><DD
|
|
|
761 ><P
|
|
|
762 >Select raw binary as the output target.</P
|
|
|
763 ></DD
|
|
|
764 ><DT
|
|
|
765 ><CODE
|
|
|
766 CLASS="OPTION"
|
|
|
767 >--includedir=path</CODE
|
|
|
768 >, <CODE
|
|
|
769 CLASS="OPTION"
|
|
|
770 >-I path</CODE
|
|
|
771 ></DT
|
|
|
772 ><DD
|
|
|
773 ><P
|
|
|
774 >Add <CODE
|
|
|
775 CLASS="OPTION"
|
|
|
776 >path</CODE
|
|
|
777 > to the end of the include path.</P
|
|
|
778 ></DD
|
|
|
779 ><DT
|
|
|
780 ><CODE
|
|
|
781 CLASS="OPTION"
|
|
|
782 >--define=SYM[=VAL]</CODE
|
|
|
783 >, <CODE
|
|
|
784 CLASS="OPTION"
|
|
|
785 >-D SYM[=VAL]</CODE
|
|
|
786 ></DT
|
|
|
787 ><DD
|
|
|
788 ><P
|
|
|
789 >Pre-defines the symbol SYM as either the specified VAL. If VAL is omitted,
|
|
|
790 the symbol is defined as 1. The symbol will be defined as though it were
|
|
|
791 defined using the SET directive in the assembly source. That means it can
|
|
|
792 be overridden by a SET directive within the source code. Attempting to
|
|
|
793 redefine SYM using EQU will result in a multiply defined symbol error.</P
|
|
|
794 ></DD
|
|
|
795 ><DT
|
|
|
796 ><CODE
|
|
|
797 CLASS="OPTION"
|
|
|
798 >-t WIDTH</CODE
|
|
|
799 >, <CODE
|
|
|
800 CLASS="OPTION"
|
|
|
801 >--tabs=WIDTH</CODE
|
|
|
802 ></DT
|
|
|
803 ><DD
|
|
|
804 ><P
|
|
|
805 >Specifies the handling of tabs in listing files. <CODE
|
|
|
806 CLASS="OPTION"
|
|
|
807 >--tabs=0</CODE
|
|
|
808 >
|
|
|
809 disables tab expansion. <CODE
|
|
|
810 CLASS="OPTION"
|
|
|
811 >--tabs=8</CODE
|
|
|
812 > is the default setting.</P
|
|
|
813 ></DD
|
|
|
814 ><DT
|
|
|
815 ><CODE
|
|
|
816 CLASS="OPTION"
|
|
|
817 >--help</CODE
|
|
|
818 >, <CODE
|
|
|
819 CLASS="OPTION"
|
|
|
820 >-?</CODE
|
|
|
821 ></DT
|
|
|
822 ><DD
|
|
|
823 ><P
|
|
|
824 >Present a help screen describing the command line options.</P
|
|
|
825 ></DD
|
|
|
826 ><DT
|
|
|
827 ><CODE
|
|
|
828 CLASS="OPTION"
|
|
|
829 >--usage</CODE
|
|
|
830 ></DT
|
|
|
831 ><DD
|
|
|
832 ><P
|
|
|
833 >Provide a summary of the command line options.</P
|
|
|
834 ></DD
|
|
|
835 ><DT
|
|
|
836 ><CODE
|
|
|
837 CLASS="OPTION"
|
|
|
838 >--version</CODE
|
|
|
839 >, <CODE
|
|
|
840 CLASS="OPTION"
|
|
|
841 >-V</CODE
|
|
|
842 ></DT
|
|
|
843 ><DD
|
|
|
844 ><P
|
|
|
845 >Display the software version.</P
|
|
|
846 ></DD
|
|
|
847 ><DT
|
|
|
848 ><CODE
|
|
|
849 CLASS="OPTION"
|
|
|
850 >--debug</CODE
|
|
|
851 >, <CODE
|
|
|
852 CLASS="OPTION"
|
|
|
853 >-d</CODE
|
|
|
854 ></DT
|
|
|
855 ><DD
|
|
|
856 ><P
|
|
|
857 >Increase the debugging level. Only really useful to people hacking on the
|
|
|
858 LWASM source code itself.</P
|
|
|
859 ></DD
|
|
|
860 ></DL
|
|
|
861 ></DIV
|
|
|
862 ></DIV
|
|
|
863 ><DIV
|
|
|
864 CLASS="SECTION"
|
|
|
865 ><HR><H2
|
|
|
866 CLASS="SECTION"
|
|
|
867 ><A
|
|
|
868 NAME="AEN218"
|
|
|
869 >3.2. Dialects</A
|
|
|
870 ></H2
|
|
|
871 ><P
|
|
|
872 > LWASM supports all documented MC6809 instructions as defined by
|
|
|
873 Motorola. By default, this does not include any MC6800 compatibility
|
|
|
874 instructions. As of LWASM 4.11, those compatibility instructions can be
|
|
|
875 enabled using the <CODE
|
|
|
876 CLASS="PARAMETER"
|
|
|
877 >--6800compat</CODE
|
|
|
878 > option or the
|
|
|
879 <CODE
|
|
|
880 CLASS="PARAMETER"
|
|
|
881 >6800compat</CODE
|
|
|
882 > pragma. It also supports all known HD6309
|
|
|
883 instructions. While there is general agreement on the pneumonics for most
|
|
|
884 of the 6309 instructions, there is some variance with the block transfer
|
|
|
885 instructions. TFM for all four variations seems to have gained the most
|
|
|
886 traction and, thus, this is the form that is recommended for LWASM.
|
|
|
887 However, it also supports COPY, COPY-, IMP, EXP, TFRP, TFRM, TFRS, and TFRR.
|
|
|
888 It further adds COPY+ as a synomym for COPY, IMPLODE for IMP, and EXPAND for
|
|
|
889 EXP. </P
|
|
|
890 ><P
|
|
|
891 >By default, LWASM accepts 6309 instructions. However, using the
|
|
|
892 <CODE
|
|
|
893 CLASS="PARAMETER"
|
|
|
894 >--6809</CODE
|
|
|
895 > parameter, you can cause it to throw errors on
|
|
|
896 6309 instructions instead.</P
|
|
|
897 ><P
|
|
|
898 >The standard addressing mode specifiers are supported. These are the
|
|
|
899 hash sign ("#") for immediate mode, the less than sign ("<") for forced
|
|
|
900 eight bit modes, and the greater than sign (">") for forced sixteen bit modes.</P
|
|
|
901 ><P
|
|
|
902 >Additionally, LWASM supports using the asterisk ("*") to indicate
|
|
|
903 base page addressing. This should not be used in hand-written source code,
|
|
|
904 however, because it is non-standard and may or may not be present in future
|
|
|
905 versions of LWASM.</P
|
|
|
906 ></DIV
|
|
|
907 ><DIV
|
|
|
908 CLASS="SECTION"
|
|
|
909 ><HR><H2
|
|
|
910 CLASS="SECTION"
|
|
|
911 ><A
|
|
|
912 NAME="AEN227"
|
|
|
913 >3.3. Source Format</A
|
|
|
914 ></H2
|
|
|
915 ><P
|
|
|
916 >LWASM accepts plain text files in a relatively free form. It can handle
|
|
|
917 lines terminated with CR, LF, CRLF, or LFCR which means it should be able
|
|
|
918 to assemble files on any platform on which it compiles.</P
|
|
|
919 ><P
|
|
|
920 >Each line may start with a symbol. If a symbol is present, there must not
|
|
|
921 be any whitespace preceding it. It is legal for a line to contain nothing
|
|
|
922 but a symbol.</P
|
|
|
923 ><P
|
|
|
924 >The op code is separated from the symbol by whitespace. If there is
|
|
|
925 no symbol, there must be at least one white space character preceding it.
|
|
|
926 If applicable, the operand follows separated by whitespace. Following the
|
|
|
927 opcode and operand is an optional comment.</P
|
|
|
928 ><P
|
|
|
929 > It is important to note that operands cannot contain any whitespace
|
|
|
930 except in the case of delimited strings. This is because the first
|
|
|
931 whitespace character will be interpreted as the separator between the
|
|
|
932 operand column and the comment. This behaviour is required for approximate
|
|
|
933 source compatibility with other 6x09 assemblers. </P
|
|
|
934 ><P
|
|
|
935 >A comment can also be introduced with a * or a ;. The comment character is
|
|
|
936 optional for end of statement comments. However, if a symbol is the only
|
|
|
937 thing present on the line other than the comment, the comment character is
|
|
|
938 mandatory to prevent the assembler from interpreting the comment as an opcode.</P
|
|
|
939 ><P
|
|
|
940 >For compatibility with the output generated by some C preprocessors, LWASM
|
|
|
941 will also ignore lines that begin with a #. This should not be used as a general
|
|
|
942 comment character, however.</P
|
|
|
943 ><P
|
|
|
944 >The opcode is not treated case sensitively. Neither are register names in
|
|
|
945 the operand fields. Symbols, however, are case sensitive.</P
|
|
|
946 ><P
|
|
|
947 > As of version 2.6, LWASM supports files with line numbers. If line
|
|
|
948 numbers are present, the line must start with a digit. The line number
|
|
|
949 itself must consist only of digits. The line number must then be followed
|
|
|
950 by either the end of the line or exactly one white space character. After
|
|
|
951 that white space character, the lines are interpreted exactly as above. </P
|
|
|
952 ></DIV
|
|
|
953 ><DIV
|
|
|
954 CLASS="SECTION"
|
|
|
955 ><HR><H2
|
|
|
956 CLASS="SECTION"
|
|
|
957 ><A
|
|
|
958 NAME="AEN237"
|
|
|
959 >3.4. Symbols</A
|
|
|
960 ></H2
|
|
|
961 ><P
|
|
|
962 >Symbols have no length restriction. They may contain letters, numbers, dots,
|
|
|
963 dollar signs, and underscores. They must start with a letter, dot, or
|
|
|
964 underscore.</P
|
|
|
965 ><P
|
|
|
966 >LWASM also supports the concept of a local symbol. A local symbol is one
|
|
|
967 which contains either a "?" or a "@", which can appear anywhere in the symbol.
|
|
|
968 The scope of a local symbol is determined by a number of factors. First,
|
|
|
969 each included file gets its own local symbol scope. A blank line will also
|
|
|
970 be considered a local scope barrier. Macros each have their own local symbol
|
|
|
971 scope as well (which has a side effect that you cannot use a local symbol
|
|
|
972 as an argument to a macro). There are other factors as well. In general,
|
|
|
973 a local symbol is restricted to the block of code it is defined within.</P
|
|
|
974 ><P
|
|
|
975 >By default, unless assembling to the os9 target, a "$" in the symbol will
|
|
|
976 also make it local. This can be controlled by the "dollarlocal" and
|
|
|
977 "nodollarlocal" pragmas. In the absence of a pragma to the contrary, for
|
|
|
978 the os9 target, a "$" in the symbol will not make it considered local while
|
|
|
979 for all other targets it will.</P
|
|
|
980 ></DIV
|
|
|
981 ><DIV
|
|
|
982 CLASS="SECTION"
|
|
|
983 ><HR><H2
|
|
|
984 CLASS="SECTION"
|
|
|
985 ><A
|
|
|
986 NAME="AEN242"
|
|
|
987 >3.5. Numbers and Expressions</A
|
|
|
988 ></H2
|
|
|
989 ><P
|
|
|
990 > Numbers can be expressed in binary, octal, decimal, or hexadecimal. Binary
|
|
|
991 numbers may be prefixed with a "%" symbol or suffixed with a "b" or "B".
|
|
|
992 Octal numbers may be prefixed with "@" or suffixed with "Q", "q", "O", or
|
|
|
993 "o". Hexadecimal numbers may be prefixed with "$", "0x" or "0X", or suffixed
|
|
|
994 with "H". No prefix or suffix is required for decimal numbers but they can
|
|
|
995 be prefixed with "&" if desired. Any constant which begins with a letter
|
|
|
996 must be expressed with the correct prefix base identifier or be prefixed
|
|
|
997 with a 0. Thus hexadecimal FF would have to be written either 0FFH or $FF.
|
|
|
998 Numbers are not case sensitive. </P
|
|
|
999 ><P
|
|
|
1000 > A symbol may appear at any point where a number is acceptable. The
|
|
|
1001 special symbol "*" can be used to represent the starting address of the
|
|
|
1002 current source line within expressions. </P
|
|
|
1003 ><P
|
|
|
1004 >The ASCII value of a character can be included by prefixing it with a
|
|
|
1005 single quote ('). The ASCII values of two characters can be included by
|
|
|
1006 prefixing the characters with a quote (").</P
|
|
|
1007 ><P
|
|
|
1008 > LWASM supports the following basic binary operators: +, -, *, /, and %.
|
|
|
1009 These represent addition, subtraction, multiplication, division, and
|
|
|
1010 modulus. It also supports unary negation and unary 1's complement (- and ^
|
|
|
1011 respectively). It is also possible to use ~ for the unary 1's complement
|
|
|
1012 operator. For completeness, a unary positive (+) is supported though it is
|
|
|
1013 a no-op. LWASM also supports using |, &, and ^ for bitwise or, bitwise and,
|
|
|
1014 and bitwise exclusive or respectively. </P
|
|
|
1015 ><P
|
|
|
1016 > Operator precedence follows the usual rules. Multiplication, division, and
|
|
|
1017 modulus take precedence over addition and subtraction. Unary operators take
|
|
|
1018 precedence over binary operators. Bitwise operators are lower precdence
|
|
|
1019 than addition and subtraction. To force a specific order of evaluation,
|
|
|
1020 parentheses can be used in the usual manner. </P
|
|
|
1021 ><P
|
|
|
1022 > As of LWASM 2.5, the operators && and || are recognized for boolean and and
|
|
|
1023 boolean or respectively. They will return either 0 or 1 (false or true).
|
|
|
1024 They have the lowest precedence of all the binary operators. </P
|
|
|
1025 ></DIV
|
|
|
1026 ><DIV
|
|
|
1027 CLASS="SECTION"
|
|
|
1028 ><HR><H2
|
|
|
1029 CLASS="SECTION"
|
|
|
1030 ><A
|
|
|
1031 NAME="AEN250"
|
|
|
1032 >3.6. Assembler Directives</A
|
|
|
1033 ></H2
|
|
|
1034 ><P
|
|
|
1035 >Various directives can be used to control the behaviour of the
|
|
|
1036 assembler or to include non-code/data in the resulting output. Those directives
|
|
|
1037 that are not described in detail in other sections of this document are
|
|
|
1038 described below.</P
|
|
|
1039 ><DIV
|
|
|
1040 CLASS="SECTION"
|
|
|
1041 ><HR><H3
|
|
|
1042 CLASS="SECTION"
|
|
|
1043 ><A
|
|
|
1044 NAME="AEN253"
|
|
|
1045 >3.6.1. Data Directives</A
|
|
|
1046 ></H3
|
|
|
1047 ><P
|
|
|
1048 ></P
|
|
|
1049 ><DIV
|
|
|
1050 CLASS="VARIABLELIST"
|
|
|
1051 ><DL
|
|
|
1052 ><DT
|
|
|
1053 >FCB <CODE
|
|
|
1054 CLASS="PARAMETER"
|
|
|
1055 >expr[,...]</CODE
|
|
|
1056 >, .DB <CODE
|
|
|
1057 CLASS="PARAMETER"
|
|
|
1058 >expr[,...]</CODE
|
|
|
1059 >, .BYTE <CODE
|
|
|
1060 CLASS="PARAMETER"
|
|
|
1061 >expr[,...]</CODE
|
|
|
1062 ></DT
|
|
|
1063 ><DD
|
|
|
1064 ><P
|
|
|
1065 >Include one or more constant bytes (separated by commas) in the output.</P
|
|
|
1066 ></DD
|
|
|
1067 ><DT
|
|
|
1068 >FDB <CODE
|
|
|
1069 CLASS="PARAMETER"
|
|
|
1070 >expr[,...]</CODE
|
|
|
1071 >, .DW <CODE
|
|
|
1072 CLASS="PARAMETER"
|
|
|
1073 >expr[,...]</CODE
|
|
|
1074 >, .WORD <CODE
|
|
|
1075 CLASS="PARAMETER"
|
|
|
1076 >expr[,...]</CODE
|
|
|
1077 ></DT
|
|
|
1078 ><DD
|
|
|
1079 ><P
|
|
|
1080 >Include one or more words (separated by commas) in the output.</P
|
|
|
1081 ></DD
|
|
|
1082 ><DT
|
|
|
1083 >FQB <CODE
|
|
|
1084 CLASS="PARAMETER"
|
|
|
1085 >expr[,...]</CODE
|
|
|
1086 >, .QUAD <CODE
|
|
|
1087 CLASS="PARAMETER"
|
|
|
1088 >expr[,...]</CODE
|
|
|
1089 >, .4BYTE <CODE
|
|
|
1090 CLASS="PARAMETER"
|
|
|
1091 >expr[,...]</CODE
|
|
|
1092 ></DT
|
|
|
1093 ><DD
|
|
|
1094 ><P
|
|
|
1095 >Include one or more double words (separated by commas) in the output.</P
|
|
|
1096 ></DD
|
|
|
1097 ><DT
|
|
|
1098 >FCC <CODE
|
|
|
1099 CLASS="PARAMETER"
|
|
|
1100 >string</CODE
|
|
|
1101 >, .ASCII <CODE
|
|
|
1102 CLASS="PARAMETER"
|
|
|
1103 >string</CODE
|
|
|
1104 >, .STR <CODE
|
|
|
1105 CLASS="PARAMETER"
|
|
|
1106 >string</CODE
|
|
|
1107 ></DT
|
|
|
1108 ><DD
|
|
|
1109 ><P
|
|
|
1110 >Include a string of text in the output. The first character of the operand
|
|
|
1111 is the delimiter which must appear as the last character and cannot appear
|
|
|
1112 within the string. The string is included with no modifications></P
|
|
|
1113 ></DD
|
|
|
1114 ><DT
|
|
|
1115 >FCN <CODE
|
|
|
1116 CLASS="PARAMETER"
|
|
|
1117 >string</CODE
|
|
|
1118 >, .ASCIZ <CODE
|
|
|
1119 CLASS="PARAMETER"
|
|
|
1120 >string</CODE
|
|
|
1121 >, .STRZ <CODE
|
|
|
1122 CLASS="PARAMETER"
|
|
|
1123 >string</CODE
|
|
|
1124 ></DT
|
|
|
1125 ><DD
|
|
|
1126 ><P
|
|
|
1127 >Include a NUL terminated string of text in the output. The first character of
|
|
|
1128 the operand is the delimiter which must appear as the last character and
|
|
|
1129 cannot appear within the string. A NUL byte is automatically appended to
|
|
|
1130 the string.</P
|
|
|
1131 ></DD
|
|
|
1132 ><DT
|
|
|
1133 >FCS <CODE
|
|
|
1134 CLASS="PARAMETER"
|
|
|
1135 >string</CODE
|
|
|
1136 >, .ASCIS <CODE
|
|
|
1137 CLASS="PARAMETER"
|
|
|
1138 >string</CODE
|
|
|
1139 >, .STRS <CODE
|
|
|
1140 CLASS="PARAMETER"
|
|
|
1141 >string</CODE
|
|
|
1142 ></DT
|
|
|
1143 ><DD
|
|
|
1144 ><P
|
|
|
1145 >Include a string of text in the output with bit 7 of the final byte set. The
|
|
|
1146 first character of the operand is the delimiter which must appear as the last
|
|
|
1147 character and cannot appear within the string.</P
|
|
|
1148 ></DD
|
|
|
1149 ><DT
|
|
|
1150 >ZMB <CODE
|
|
|
1151 CLASS="PARAMETER"
|
|
|
1152 >expr</CODE
|
|
|
1153 ></DT
|
|
|
1154 ><DD
|
|
|
1155 ><P
|
|
|
1156 >Include a number of NUL bytes in the output. The number must be fully resolvable
|
|
|
1157 during pass 1 of assembly so no forward or external references are permitted.</P
|
|
|
1158 ></DD
|
|
|
1159 ><DT
|
|
|
1160 >ZMD <CODE
|
|
|
1161 CLASS="PARAMETER"
|
|
|
1162 >expr</CODE
|
|
|
1163 ></DT
|
|
|
1164 ><DD
|
|
|
1165 ><P
|
|
|
1166 >Include a number of zero words in the output. The number must be fully
|
|
|
1167 resolvable during pass 1 of assembly so no forward or external references are
|
|
|
1168 permitted.</P
|
|
|
1169 ></DD
|
|
|
1170 ><DT
|
|
|
1171 >ZMQ <CODE
|
|
|
1172 CLASS="PARAMETER"
|
|
|
1173 >expr<CODE
|
|
|
1174 CLASS="PARAMETER"
|
|
|
1175 ></CODE
|
|
|
1176 ></CODE
|
|
|
1177 ></DT
|
|
|
1178 ><DD
|
|
|
1179 ><P
|
|
|
1180 >Include a number of zero double-words in the output. The number must be fully
|
|
|
1181 resolvable during pass 1 of assembly so no forward or external references are
|
|
|
1182 permitted.</P
|
|
|
1183 ></DD
|
|
|
1184 ><DT
|
|
|
1185 >RMB <CODE
|
|
|
1186 CLASS="PARAMETER"
|
|
|
1187 >expr</CODE
|
|
|
1188 >, .BLKB <CODE
|
|
|
1189 CLASS="PARAMETER"
|
|
|
1190 >expr</CODE
|
|
|
1191 >, .DS <CODE
|
|
|
1192 CLASS="PARAMETER"
|
|
|
1193 >expr</CODE
|
|
|
1194 >, .RS <CODE
|
|
|
1195 CLASS="PARAMETER"
|
|
|
1196 >expr</CODE
|
|
|
1197 ></DT
|
|
|
1198 ><DD
|
|
|
1199 ><P
|
|
|
1200 >Reserve a number of bytes in the output. The number must be fully resolvable
|
|
|
1201 during pass 1 of assembly so no forward or external references are permitted.
|
|
|
1202 The value of the bytes is undefined.</P
|
|
|
1203 ></DD
|
|
|
1204 ><DT
|
|
|
1205 >RMD <CODE
|
|
|
1206 CLASS="PARAMETER"
|
|
|
1207 >expr</CODE
|
|
|
1208 ></DT
|
|
|
1209 ><DD
|
|
|
1210 ><P
|
|
|
1211 >Reserve a number of words in the output. The number must be fully
|
|
|
1212 resolvable during pass 1 of assembly so no forward or external references are
|
|
|
1213 permitted. The value of the words is undefined.</P
|
|
|
1214 ></DD
|
|
|
1215 ><DT
|
|
|
1216 >RMQ <CODE
|
|
|
1217 CLASS="PARAMETER"
|
|
|
1218 >expr</CODE
|
|
|
1219 ></DT
|
|
|
1220 ><DD
|
|
|
1221 ><P
|
|
|
1222 >Reserve a number of double-words in the output. The number must be fully
|
|
|
1223 resolvable during pass 1 of assembly so no forward or external references are
|
|
|
1224 permitted. The value of the double-words is undefined.</P
|
|
|
1225 ></DD
|
|
|
1226 ><DT
|
|
|
1227 >INCLUDEBIN <CODE
|
|
|
1228 CLASS="PARAMETER"
|
|
|
1229 >filename</CODE
|
|
|
1230 ></DT
|
|
|
1231 ><DD
|
|
|
1232 ><P
|
|
|
1233 >Treat the contents of <CODE
|
|
|
1234 CLASS="PARAMETER"
|
|
|
1235 >filename</CODE
|
|
|
1236 > as a string of bytes to
|
|
|
1237 be included literally at the current assembly point. This has the same effect
|
|
|
1238 as converting the file contents to a series of FCB statements and including
|
|
|
1239 those at the current assembly point.</P
|
|
|
1240 ><P
|
|
|
1241 > If <CODE
|
|
|
1242 CLASS="PARAMETER"
|
|
|
1243 >filename</CODE
|
|
|
1244 > beings with a /, the file name
|
|
|
1245 will be taken as absolute. Otherwise, the current directory will be
|
|
|
1246 searched followed by the search path in the order specified.</P
|
|
|
1247 ><P
|
|
|
1248 > Please note that absolute path detection including drive letters will
|
|
|
1249 not function correctly on Windows platforms. Non-absolute inclusion will
|
|
|
1250 work, however.</P
|
|
|
1251 ></DD
|
|
|
1252 ><DT
|
|
|
1253 >FILL <CODE
|
|
|
1254 CLASS="PARAMETER"
|
|
|
1255 >byte</CODE
|
|
|
1256 >,<CODE
|
|
|
1257 CLASS="PARAMETER"
|
|
|
1258 >size</CODE
|
|
|
1259 ></DT
|
|
|
1260 ><DD
|
|
|
1261 ><P
|
|
|
1262 >Insert <CODE
|
|
|
1263 CLASS="PARAMETER"
|
|
|
1264 >size</CODE
|
|
|
1265 > bytes of <CODE
|
|
|
1266 CLASS="PARAMETER"
|
|
|
1267 >byte</CODE
|
|
|
1268 >.</P
|
|
|
1269 ></DD
|
|
|
1270 ></DL
|
|
|
1271 ></DIV
|
|
|
1272 ></DIV
|
|
|
1273 ><DIV
|
|
|
1274 CLASS="SECTION"
|
|
|
1275 ><HR><H3
|
|
|
1276 CLASS="SECTION"
|
|
|
1277 ><A
|
|
|
1278 NAME="AEN364"
|
|
|
1279 >3.6.2. Address Definition</A
|
|
|
1280 ></H3
|
|
|
1281 ><P
|
|
|
1282 >The directives in this section all control the addresses of symbols
|
|
|
1283 or the assembly process itself.</P
|
|
|
1284 ><P
|
|
|
1285 ></P
|
|
|
1286 ><DIV
|
|
|
1287 CLASS="VARIABLELIST"
|
|
|
1288 ><DL
|
|
|
1289 ><DT
|
|
|
1290 >ORG <CODE
|
|
|
1291 CLASS="PARAMETER"
|
|
|
1292 >expr</CODE
|
|
|
1293 ></DT
|
|
|
1294 ><DD
|
|
|
1295 ><P
|
|
|
1296 >Set the assembly address. The address must be fully resolvable on the
|
|
|
1297 first pass so no external or forward references are permitted. ORG is not
|
|
|
1298 permitted within sections when outputting to object files. For target formats
|
|
|
1299 that include address information (decb, hex, srec, and ihex), an ORG
|
|
|
1300 directive will re-start the address sequence within the output. When using
|
|
|
1301 the raw target format, ORG is used only to determine the addresses of symbols.</P
|
|
|
1302 ></DD
|
|
|
1303 ><DT
|
|
|
1304 >REORG</DT
|
|
|
1305 ><DD
|
|
|
1306 ><P
|
|
|
1307 >Sets the assembly address to the value it had immediately prior to the
|
|
|
1308 previous ORG statement. It is used to continue assembly after some
|
|
|
1309 specification that required an additional ORG. This directive is primarily
|
|
|
1310 intended for MACRO-80c compatibility. Consider using alternatives in
|
|
|
1311 modern code.</P
|
|
|
1312 ></DD
|
|
|
1313 ><DT
|
|
|
1314 ><CODE
|
|
|
1315 CLASS="PARAMETER"
|
|
|
1316 >sym</CODE
|
|
|
1317 > EQU <CODE
|
|
|
1318 CLASS="PARAMETER"
|
|
|
1319 >expr</CODE
|
|
|
1320 >, <CODE
|
|
|
1321 CLASS="PARAMETER"
|
|
|
1322 >sym</CODE
|
|
|
1323 > = <CODE
|
|
|
1324 CLASS="PARAMETER"
|
|
|
1325 >expr</CODE
|
|
|
1326 ></DT
|
|
|
1327 ><DD
|
|
|
1328 ><P
|
|
|
1329 >Define the value of <CODE
|
|
|
1330 CLASS="PARAMETER"
|
|
|
1331 >sym</CODE
|
|
|
1332 > to be <CODE
|
|
|
1333 CLASS="PARAMETER"
|
|
|
1334 >expr</CODE
|
|
|
1335 >.</P
|
|
|
1336 ></DD
|
|
|
1337 ><DT
|
|
|
1338 ><CODE
|
|
|
1339 CLASS="PARAMETER"
|
|
|
1340 >sym</CODE
|
|
|
1341 > SET <CODE
|
|
|
1342 CLASS="PARAMETER"
|
|
|
1343 >expr</CODE
|
|
|
1344 ></DT
|
|
|
1345 ><DD
|
|
|
1346 ><P
|
|
|
1347 >Define the value of <CODE
|
|
|
1348 CLASS="PARAMETER"
|
|
|
1349 >sym</CODE
|
|
|
1350 > to be <CODE
|
|
|
1351 CLASS="PARAMETER"
|
|
|
1352 >expr</CODE
|
|
|
1353 >.
|
|
|
1354 Unlike EQU, SET permits symbols to be defined multiple times as long as SET
|
|
|
1355 is used for all instances. Use of the symbol before the first SET statement
|
|
|
1356 that sets its value is undefined.</P
|
|
|
1357 ></DD
|
|
|
1358 ><DT
|
|
|
1359 >SETDP <CODE
|
|
|
1360 CLASS="PARAMETER"
|
|
|
1361 >expr</CODE
|
|
|
1362 ></DT
|
|
|
1363 ><DD
|
|
|
1364 ><P
|
|
|
1365 >Inform the assembler that it can assume the DP register contains
|
|
|
1366 <CODE
|
|
|
1367 CLASS="PARAMETER"
|
|
|
1368 >expr</CODE
|
|
|
1369 >. This directive is only advice to the assembler
|
|
|
1370 to determine whether an address is in the direct page and has no effect
|
|
|
1371 on the contents of the DP register. The value must be fully resolved during
|
|
|
1372 the first assembly pass because it affects the sizes of subsequent instructions.</P
|
|
|
1373 ><P
|
|
|
1374 >This directive has no effect in the object file target.</P
|
|
|
1375 ></DD
|
|
|
1376 ><DT
|
|
|
1377 >ALIGN <CODE
|
|
|
1378 CLASS="PARAMETER"
|
|
|
1379 >expr</CODE
|
|
|
1380 >[,<CODE
|
|
|
1381 CLASS="PARAMETER"
|
|
|
1382 >value</CODE
|
|
|
1383 >]</DT
|
|
|
1384 ><DD
|
|
|
1385 ><P
|
|
|
1386 >Force the current assembly address to be a multiple of
|
|
|
1387 <CODE
|
|
|
1388 CLASS="PARAMETER"
|
|
|
1389 >expr</CODE
|
|
|
1390 >. If <CODE
|
|
|
1391 CLASS="PARAMETER"
|
|
|
1392 >value</CODE
|
|
|
1393 > is not
|
|
|
1394 specified, a series of NUL bytes is output to force the alignment, if
|
|
|
1395 required. Otherwise, the low order 8 bits of <CODE
|
|
|
1396 CLASS="PARAMETER"
|
|
|
1397 >value</CODE
|
|
|
1398 >
|
|
|
1399 will be used as the fill. The alignment value must be fully resolved on the
|
|
|
1400 first pass because it affects the addresses of subsquent instructions.
|
|
|
1401 However, <CODE
|
|
|
1402 CLASS="PARAMETER"
|
|
|
1403 >value</CODE
|
|
|
1404 > may include forward references; as
|
|
|
1405 long as it resolves to a constant for the second pass, the value will be
|
|
|
1406 accepted.</P
|
|
|
1407 ><P
|
|
|
1408 >Unless <CODE
|
|
|
1409 CLASS="PARAMETER"
|
|
|
1410 >value</CODE
|
|
|
1411 > is specified as something like $12,
|
|
|
1412 this directive is not suitable for inclusion in the middle of actual code.
|
|
|
1413 The default padding value is $00 which is intended to be used within data
|
|
|
1414 blocks. </P
|
|
|
1415 ></DD
|
|
|
1416 ></DL
|
|
|
1417 ></DIV
|
|
|
1418 ></DIV
|
|
|
1419 ><DIV
|
|
|
1420 CLASS="SECTION"
|
|
|
1421 ><HR><H3
|
|
|
1422 CLASS="SECTION"
|
|
|
1423 ><A
|
|
|
1424 NAME="AEN415"
|
|
|
1425 >3.6.3. Conditional Assembly</A
|
|
|
1426 ></H3
|
|
|
1427 ><P
|
|
|
1428 >Portions of the source code can be excluded or included based on conditions
|
|
|
1429 known at assembly time. Conditionals can be nested arbitrarily deeply. The
|
|
|
1430 directives associated with conditional assembly are described in this section.</P
|
|
|
1431 ><P
|
|
|
1432 >All conditionals must be fully bracketed. That is, every conditional
|
|
|
1433 statement must eventually be followed by an ENDC at the same level of nesting.</P
|
|
|
1434 ><P
|
|
|
1435 >Conditional expressions are only evaluated on the first assembly pass.
|
|
|
1436 It is not possible to game the assembly process by having a conditional
|
|
|
1437 change its value between assembly passes. Due to the underlying architecture
|
|
|
1438 of LWASM, there is no possible utility to IFP1 and IFP2, nor can they, as of LWASM 3.0, actually
|
|
|
1439 be implemented meaningfully. Thus there is not and never will
|
|
|
1440 be any equivalent of IFP1 or IFP2 as provided by other assemblers. Use of those opcodes
|
|
|
1441 will throw a warning and be ignored.</P
|
|
|
1442 ><P
|
|
|
1443 >It is important to note that if a conditional does not resolve to a constant
|
|
|
1444 during the first parsing pass, an error will be thrown. This is unavoidable because the assembler
|
|
|
1445 must make a decision about which source to include and which source to exclude at this stage.
|
|
|
1446 Thus, expressions that work normally elsewhere will not work for conditions.</P
|
|
|
1447 ><P
|
|
|
1448 ></P
|
|
|
1449 ><DIV
|
|
|
1450 CLASS="VARIABLELIST"
|
|
|
1451 ><DL
|
|
|
1452 ><DT
|
|
|
1453 >IFEQ <CODE
|
|
|
1454 CLASS="PARAMETER"
|
|
|
1455 >expr</CODE
|
|
|
1456 ></DT
|
|
|
1457 ><DD
|
|
|
1458 ><P
|
|
|
1459 >If <CODE
|
|
|
1460 CLASS="PARAMETER"
|
|
|
1461 >expr</CODE
|
|
|
1462 > evaluates to zero, the conditional
|
|
|
1463 will be considered true.</P
|
|
|
1464 ></DD
|
|
|
1465 ><DT
|
|
|
1466 >IFNE <CODE
|
|
|
1467 CLASS="PARAMETER"
|
|
|
1468 >expr</CODE
|
|
|
1469 >, IF <CODE
|
|
|
1470 CLASS="PARAMETER"
|
|
|
1471 >expr</CODE
|
|
|
1472 ></DT
|
|
|
1473 ><DD
|
|
|
1474 ><P
|
|
|
1475 >If <CODE
|
|
|
1476 CLASS="PARAMETER"
|
|
|
1477 >expr</CODE
|
|
|
1478 > evaluates to a non-zero value, the conditional
|
|
|
1479 will be considered true.</P
|
|
|
1480 ></DD
|
|
|
1481 ><DT
|
|
|
1482 >IFGT <CODE
|
|
|
1483 CLASS="PARAMETER"
|
|
|
1484 >expr</CODE
|
|
|
1485 ></DT
|
|
|
1486 ><DD
|
|
|
1487 ><P
|
|
|
1488 >If <CODE
|
|
|
1489 CLASS="PARAMETER"
|
|
|
1490 >expr</CODE
|
|
|
1491 > evaluates to a value greater than zero, the conditional
|
|
|
1492 will be considered true.</P
|
|
|
1493 ></DD
|
|
|
1494 ><DT
|
|
|
1495 >IFGE <CODE
|
|
|
1496 CLASS="PARAMETER"
|
|
|
1497 >expr</CODE
|
|
|
1498 ></DT
|
|
|
1499 ><DD
|
|
|
1500 ><P
|
|
|
1501 >If <CODE
|
|
|
1502 CLASS="PARAMETER"
|
|
|
1503 >expr</CODE
|
|
|
1504 > evaluates to a value greater than or equal to zero, the conditional
|
|
|
1505 will be considered true.</P
|
|
|
1506 ></DD
|
|
|
1507 ><DT
|
|
|
1508 >IFLT <CODE
|
|
|
1509 CLASS="PARAMETER"
|
|
|
1510 >expr</CODE
|
|
|
1511 ></DT
|
|
|
1512 ><DD
|
|
|
1513 ><P
|
|
|
1514 >If <CODE
|
|
|
1515 CLASS="PARAMETER"
|
|
|
1516 >expr</CODE
|
|
|
1517 > evaluates to a value less than zero, the conditional
|
|
|
1518 will be considered true.</P
|
|
|
1519 ></DD
|
|
|
1520 ><DT
|
|
|
1521 >IFLE <CODE
|
|
|
1522 CLASS="PARAMETER"
|
|
|
1523 >expr</CODE
|
|
|
1524 ></DT
|
|
|
1525 ><DD
|
|
|
1526 ><P
|
|
|
1527 >If <CODE
|
|
|
1528 CLASS="PARAMETER"
|
|
|
1529 >expr</CODE
|
|
|
1530 > evaluates to a value less than or equal to zero , the conditional
|
|
|
1531 will be considered true.</P
|
|
|
1532 ></DD
|
|
|
1533 ><DT
|
|
|
1534 >IFDEF <CODE
|
|
|
1535 CLASS="PARAMETER"
|
|
|
1536 >sym</CODE
|
|
|
1537 ></DT
|
|
|
1538 ><DD
|
|
|
1539 ><P
|
|
|
1540 >If <CODE
|
|
|
1541 CLASS="PARAMETER"
|
|
|
1542 >sym</CODE
|
|
|
1543 > is defined at this point in the assembly
|
|
|
1544 process, the conditional
|
|
|
1545 will be considered true.</P
|
|
|
1546 ></DD
|
|
|
1547 ><DT
|
|
|
1548 >IFPRAGMA <CODE
|
|
|
1549 CLASS="PARAMETER"
|
|
|
1550 >pragma</CODE
|
|
|
1551 ></DT
|
|
|
1552 ><DD
|
|
|
1553 ><P
|
|
|
1554 >If <CODE
|
|
|
1555 CLASS="PARAMETER"
|
|
|
1556 >pragma</CODE
|
|
|
1557 > is in effect, the condition will be considered true.</P
|
|
|
1558 ></DD
|
|
|
1559 ><DT
|
|
|
1560 >IFNDEF <CODE
|
|
|
1561 CLASS="PARAMETER"
|
|
|
1562 >sym</CODE
|
|
|
1563 ></DT
|
|
|
1564 ><DD
|
|
|
1565 ><P
|
|
|
1566 >If <CODE
|
|
|
1567 CLASS="PARAMETER"
|
|
|
1568 >sym</CODE
|
|
|
1569 > is not defined at this point in the assembly
|
|
|
1570 process, the conditional
|
|
|
1571 will be considered true.</P
|
|
|
1572 ></DD
|
|
|
1573 ><DT
|
|
|
1574 >ELSE</DT
|
|
|
1575 ><DD
|
|
|
1576 ><P
|
|
|
1577 >If the preceding conditional at the same level of nesting was false, the
|
|
|
1578 statements following will be assembled. If the preceding conditional at
|
|
|
1579 the same level was true, the statements following will not be assembled.
|
|
|
1580 Note that the preceding conditional might have been another ELSE statement
|
|
|
1581 although this behaviour is not guaranteed to be supported in future versions
|
|
|
1582 of LWASM.</P
|
|
|
1583 ></DD
|
|
|
1584 ><DT
|
|
|
1585 >ENDC</DT
|
|
|
1586 ><DD
|
|
|
1587 ><P
|
|
|
1588 >This directive marks the end of a conditional construct. Every conditional
|
|
|
1589 construct must end with an ENDC directive.</P
|
|
|
1590 ></DD
|
|
|
1591 ></DL
|
|
|
1592 ></DIV
|
|
|
1593 ></DIV
|
|
|
1594 ><DIV
|
|
|
1595 CLASS="SECTION"
|
|
|
1596 ><HR><H3
|
|
|
1597 CLASS="SECTION"
|
|
|
1598 ><A
|
|
|
1599 NAME="AEN486"
|
|
|
1600 >3.6.4. OS9 Target Directives</A
|
|
|
1601 ></H3
|
|
|
1602 ><P
|
|
|
1603 >This section includes directives that apply solely to the OS9
|
|
|
1604 target.</P
|
|
|
1605 ><P
|
|
|
1606 ></P
|
|
|
1607 ><DIV
|
|
|
1608 CLASS="VARIABLELIST"
|
|
|
1609 ><DL
|
|
|
1610 ><DT
|
|
|
1611 >OS9 <CODE
|
|
|
1612 CLASS="PARAMETER"
|
|
|
1613 >syscall</CODE
|
|
|
1614 ></DT
|
|
|
1615 ><DD
|
|
|
1616 ><P
|
|
|
1617 > This directive generates a call to the specified system call. <CODE
|
|
|
1618 CLASS="PARAMETER"
|
|
|
1619 >syscall</CODE
|
|
|
1620 > may be an arbitrary expression. </P
|
|
|
1621 ></DD
|
|
|
1622 ><DT
|
|
|
1623 >MOD <CODE
|
|
|
1624 CLASS="PARAMETER"
|
|
|
1625 >size</CODE
|
|
|
1626 >,<CODE
|
|
|
1627 CLASS="PARAMETER"
|
|
|
1628 >name</CODE
|
|
|
1629 >,<CODE
|
|
|
1630 CLASS="PARAMETER"
|
|
|
1631 >type</CODE
|
|
|
1632 >,<CODE
|
|
|
1633 CLASS="PARAMETER"
|
|
|
1634 >flags</CODE
|
|
|
1635 >,<CODE
|
|
|
1636 CLASS="PARAMETER"
|
|
|
1637 >execoff</CODE
|
|
|
1638 >,<CODE
|
|
|
1639 CLASS="PARAMETER"
|
|
|
1640 >datasize</CODE
|
|
|
1641 ></DT
|
|
|
1642 ><DD
|
|
|
1643 ><P
|
|
|
1644 > This tells LWASM that the beginning of the actual module is here. It will
|
|
|
1645 generate a module header based on the parameters specified. It will also
|
|
|
1646 begin calcuating the module CRC. </P
|
|
|
1647 ><P
|
|
|
1648 > The precise meaning of the various parameters is beyond the scope of this
|
|
|
1649 document since it is not a tutorial on OS9 module programming. </P
|
|
|
1650 ></DD
|
|
|
1651 ><DT
|
|
|
1652 >EMOD</DT
|
|
|
1653 ><DD
|
|
|
1654 ><P
|
|
|
1655 > This marks the end of a module and causes LWASM to emit the calculated CRC
|
|
|
1656 for the module. </P
|
|
|
1657 ></DD
|
|
|
1658 ></DL
|
|
|
1659 ></DIV
|
|
|
1660 ></DIV
|
|
|
1661 ><DIV
|
|
|
1662 CLASS="SECTION"
|
|
|
1663 ><HR><H3
|
|
|
1664 CLASS="SECTION"
|
|
|
1665 ><A
|
|
|
1666 NAME="AEN511"
|
|
|
1667 >3.6.5. Miscelaneous Directives</A
|
|
|
1668 ></H3
|
|
|
1669 ><P
|
|
|
1670 >This section includes directives that do not fit into the other
|
|
|
1671 categories.</P
|
|
|
1672 ><P
|
|
|
1673 ></P
|
|
|
1674 ><DIV
|
|
|
1675 CLASS="VARIABLELIST"
|
|
|
1676 ><DL
|
|
|
1677 ><DT
|
|
|
1678 >INCLUDE <CODE
|
|
|
1679 CLASS="PARAMETER"
|
|
|
1680 >filename</CODE
|
|
|
1681 >, USE <CODE
|
|
|
1682 CLASS="PARAMETER"
|
|
|
1683 >filename</CODE
|
|
|
1684 ></DT
|
|
|
1685 ><DD
|
|
|
1686 ><P
|
|
|
1687 > Include the contents of <CODE
|
|
|
1688 CLASS="PARAMETER"
|
|
|
1689 >filename</CODE
|
|
|
1690 > at
|
|
|
1691 this point in the assembly as though it were a part of the file currently
|
|
|
1692 being processed. Note that if whitespace appears in the name of the file,
|
|
|
1693 you must enclose <CODE
|
|
|
1694 CLASS="PARAMETER"
|
|
|
1695 >filename</CODE
|
|
|
1696 > in quotes.</P
|
|
|
1697 ><P
|
|
|
1698 >Note that the USE variation is provided only for compatibility with other
|
|
|
1699 assemblers. It is recommended to use the INCLUDE variation.</P
|
|
|
1700 ><P
|
|
|
1701 >If <CODE
|
|
|
1702 CLASS="PARAMETER"
|
|
|
1703 >filename</CODE
|
|
|
1704 > begins with a "/", it is
|
|
|
1705 interpreted as an absolute path. If it does not, the search path will be used
|
|
|
1706 to find the file. First, the directory containing the file that contains this
|
|
|
1707 directive. (Includes within an included file are relative to the included file,
|
|
|
1708 not the file that included it.) If the file is not found there, the include path
|
|
|
1709 is searched. If it is still not found, an error will be thrown. Note that the
|
|
|
1710 current directory as understood by your shell or operating system is not searched.</P
|
|
|
1711 ></DD
|
|
|
1712 ><DT
|
|
|
1713 >END <CODE
|
|
|
1714 CLASS="PARAMETER"
|
|
|
1715 >[expr]</CODE
|
|
|
1716 ></DT
|
|
|
1717 ><DD
|
|
|
1718 ><P
|
|
|
1719 >This directive causes the assembler to stop assembling immediately as though
|
|
|
1720 it ran out of input. For the DECB target only, <CODE
|
|
|
1721 CLASS="PARAMETER"
|
|
|
1722 >expr</CODE
|
|
|
1723 >
|
|
|
1724 can be used to set the execution address of the resulting binary. For all
|
|
|
1725 other targets, specifying <CODE
|
|
|
1726 CLASS="PARAMETER"
|
|
|
1727 >expr</CODE
|
|
|
1728 > will cause an error.</P
|
|
|
1729 ></DD
|
|
|
1730 ><DT
|
|
|
1731 >ERROR <CODE
|
|
|
1732 CLASS="PARAMETER"
|
|
|
1733 >string</CODE
|
|
|
1734 ></DT
|
|
|
1735 ><DD
|
|
|
1736 ><P
|
|
|
1737 >Causes a custom error message to be printed at this line. This will cause
|
|
|
1738 assembly to fail. This directive is most useful inside conditional constructs
|
|
|
1739 to cause assembly to fail if some condition that is known bad happens. Everything
|
|
|
1740 from the directive to the end of the line is considered the error message.</P
|
|
|
1741 ></DD
|
|
|
1742 ><DT
|
|
|
1743 >WARNING <CODE
|
|
|
1744 CLASS="PARAMETER"
|
|
|
1745 >string</CODE
|
|
|
1746 ></DT
|
|
|
1747 ><DD
|
|
|
1748 ><P
|
|
|
1749 >Causes a custom warning message to be printed at this line. This will not cause
|
|
|
1750 assembly to fail. This directive is most useful inside conditional constructs
|
|
|
1751 or include files to alert the programmer to a deprecated feature being used
|
|
|
1752 or some other condition that may cause trouble later, but which may, in fact,
|
|
|
1753 not cause any trouble.</P
|
|
|
1754 ></DD
|
|
|
1755 ><DT
|
|
|
1756 >.MODULE <CODE
|
|
|
1757 CLASS="PARAMETER"
|
|
|
1758 >string</CODE
|
|
|
1759 ></DT
|
|
|
1760 ><DD
|
|
|
1761 ><P
|
|
|
1762 >This directive is ignored for most output targets. If the output target
|
|
|
1763 supports encoding a module name into it, <CODE
|
|
|
1764 CLASS="PARAMETER"
|
|
|
1765 >string</CODE
|
|
|
1766 >
|
|
|
1767 will be used as the module name.</P
|
|
|
1768 ><P
|
|
|
1769 >As of version 3.0, no supported output targets support this directive.</P
|
|
|
1770 ></DD
|
|
|
1771 ></DL
|
|
|
1772 ></DIV
|
|
|
1773 ></DIV
|
|
|
1774 ></DIV
|
|
|
1775 ><DIV
|
|
|
1776 CLASS="SECTION"
|
|
|
1777 ><HR><H2
|
|
|
1778 CLASS="SECTION"
|
|
|
1779 ><A
|
|
|
1780 NAME="AEN551"
|
|
|
1781 >3.7. Macros</A
|
|
|
1782 ></H2
|
|
|
1783 ><P
|
|
|
1784 >LWASM is a macro assembler. A macro is simply a name that stands in for a
|
|
|
1785 series of instructions. Once a macro is defined, it is used like any other
|
|
|
1786 assembler directive. Defining a macro can be considered equivalent to adding
|
|
|
1787 additional assembler directives.</P
|
|
|
1788 ><P
|
|
|
1789 >Macros may accept parameters. These parameters are referenced within a
|
|
|
1790 macro by the a backslash ("\") followed by a digit 1 through 9 for the first
|
|
|
1791 through ninth parameters. They may also be referenced by enclosing the
|
|
|
1792 decimal parameter number in braces ("{num}"). The special expansion "\*"
|
|
|
1793 translates to the exact parameter string, including all parameters, passed
|
|
|
1794 to the macro. These parameter references are replaced with the verbatim text
|
|
|
1795 of the parameter passed to the macro. A reference to a non-existent
|
|
|
1796 parameter will be replaced by an empty string. Macro parameters are expanded
|
|
|
1797 everywhere on each source line. That means the parameter to a macro could be
|
|
|
1798 used as a symbol or it could even appear in a comment or could cause an
|
|
|
1799 entire source line to be commented out when the macro is expanded. </P
|
|
|
1800 ><P
|
|
|
1801 >Parameters passed to a macro are separated by commas and the parameter list
|
|
|
1802 is terminated by any whitespace. This means that neither a comma nor whitespace
|
|
|
1803 may be included in a macro parameter.</P
|
|
|
1804 ><P
|
|
|
1805 >Macro expansion is done recursively. That is, within a macro, macros are
|
|
|
1806 expanded. This can lead to infinite loops in macro expansion. If the assembler
|
|
|
1807 hangs for a long time while assembling a file that uses macros, this may be
|
|
|
1808 the reason.</P
|
|
|
1809 ><P
|
|
|
1810 >Each macro expansion receives its own local symbol context which is not
|
|
|
1811 inherited by any macros called by it nor is it inherited from the context
|
|
|
1812 the macro was instantiated in. That means it is possible to use local symbols
|
|
|
1813 within macros without having them collide with symbols in other macros or
|
|
|
1814 outside the macro itself. However, this also means that using a local symbol
|
|
|
1815 as a parameter to a macro, while legal, will not do what it would seem to do
|
|
|
1816 as it will result in looking up the local symbol in the macro's symbol context
|
|
|
1817 rather than the enclosing context where it came from, likely yielding either
|
|
|
1818 an undefined symbol error or bizarre assembly results.</P
|
|
|
1819 ><P
|
|
|
1820 >Note that there is no way to define a macro as local to a symbol context. All
|
|
|
1821 macros are part of the global macro namespace. However, macros have a separate
|
|
|
1822 namespace from symbols so it is possible to have a symbol with the same name
|
|
|
1823 as a macro.</P
|
|
|
1824 ><P
|
|
|
1825 >Macros are defined only during the first pass. Macro expansion also
|
|
|
1826 only occurs during the first pass. On the second pass, the macro
|
|
|
1827 definition is simply ignored. Macros must be defined before they are used.</P
|
|
|
1828 ><P
|
|
|
1829 >The following directives are used when defining macros.</P
|
|
|
1830 ><P
|
|
|
1831 ></P
|
|
|
1832 ><DIV
|
|
|
1833 CLASS="VARIABLELIST"
|
|
|
1834 ><DL
|
|
|
1835 ><DT
|
|
|
1836 ><CODE
|
|
|
1837 CLASS="PARAMETER"
|
|
|
1838 >macroname</CODE
|
|
|
1839 > MACRO [NOEXPAND]</DT
|
|
|
1840 ><DD
|
|
|
1841 ><P
|
|
|
1842 >This directive is used to being the definition of a macro called
|
|
|
1843 <CODE
|
|
|
1844 CLASS="PARAMETER"
|
|
|
1845 >macroname</CODE
|
|
|
1846 >. If <CODE
|
|
|
1847 CLASS="PARAMETER"
|
|
|
1848 >macroname</CODE
|
|
|
1849 > already
|
|
|
1850 exists, it is considered an error. Attempting to define a macro within a
|
|
|
1851 macro is undefined. It may work and it may not so the behaviour should not
|
|
|
1852 be relied upon.</P
|
|
|
1853 ><P
|
|
|
1854 >If NOEXPAND is specified, the macro will not be expanded in a program
|
|
|
1855 listing. Instead, all bytes emitted by all instructions within the macro
|
|
|
1856 will appear to be emitted on the line where the macro is invoked, starting
|
|
|
1857 at the address of the line of the invokation. If the macro uses ORG or other
|
|
|
1858 directives that define symbols or change the assembly address, these things
|
|
|
1859 will also be hidden (except in the symbol table) and the output bytes will
|
|
|
1860 appear with incorrect address attribution. Thus, NOEXPAND should only be
|
|
|
1861 used for macros that do not mess with the assembly address or otherwise
|
|
|
1862 define symbols that should be visible.</P
|
|
|
1863 ></DD
|
|
|
1864 ><DT
|
|
|
1865 >ENDM</DT
|
|
|
1866 ><DD
|
|
|
1867 ><P
|
|
|
1868 >This directive indicates the end of the macro currently being defined. It
|
|
|
1869 causes the assembler to resume interpreting source lines as normal.</P
|
|
|
1870 ></DD
|
|
|
1871 ></DL
|
|
|
1872 ></DIV
|
|
|
1873 ></DIV
|
|
|
1874 ><DIV
|
|
|
1875 CLASS="SECTION"
|
|
|
1876 ><HR><H2
|
|
|
1877 CLASS="SECTION"
|
|
|
1878 ><A
|
|
|
1879 NAME="AEN574"
|
|
|
1880 >3.8. Structures</A
|
|
|
1881 ></H2
|
|
|
1882 ><P
|
|
|
1883 > Structures are used to group related data in a fixed structure. A structure
|
|
|
1884 consists a number of fields, defined in sequential order and which take up
|
|
|
1885 specified size. The assembler does not enforce any means of access within a
|
|
|
1886 structure; it assumes that whatever you are doing, you intended to do.
|
|
|
1887 There are two pseudo ops that are used for defining structures. </P
|
|
|
1888 ><P
|
|
|
1889 ></P
|
|
|
1890 ><DIV
|
|
|
1891 CLASS="VARIABLELIST"
|
|
|
1892 ><DL
|
|
|
1893 ><DT
|
|
|
1894 ><CODE
|
|
|
1895 CLASS="PARAMETER"
|
|
|
1896 >structname</CODE
|
|
|
1897 > STRUCT</DT
|
|
|
1898 ><DD
|
|
|
1899 ><P
|
|
|
1900 > This directive is used to begin the definition of a structure with name
|
|
|
1901 <CODE
|
|
|
1902 CLASS="PARAMETER"
|
|
|
1903 >structname</CODE
|
|
|
1904 >. Subsequent statements all form part of
|
|
|
1905 the structure definition until the end of the structure is declared. </P
|
|
|
1906 ></DD
|
|
|
1907 ><DT
|
|
|
1908 >ENDSTRUCT, ENDS</DT
|
|
|
1909 ><DD
|
|
|
1910 ><P
|
|
|
1911 >This directive ends the definition of the structure. ENDSTRUCT is the
|
|
|
1912 preferred form. Prior to version 3.0 of LWASM, ENDS was used to end a
|
|
|
1913 section instead of a structure.</P
|
|
|
1914 ></DD
|
|
|
1915 ></DL
|
|
|
1916 ></DIV
|
|
|
1917 ><P
|
|
|
1918 > Within a structure definition, only reservation pseudo ops are permitted.
|
|
|
1919 Anything else will cause an assembly error.</P
|
|
|
1920 ><P
|
|
|
1921 > Once a structure is defined, you can reserve an area of memory in the
|
|
|
1922 same structure by using the structure name as the opcode. Structures can
|
|
|
1923 also contain fields that are themselves structures. See the example
|
|
|
1924 below.</P
|
|
|
1925 ><PRE
|
|
|
1926 CLASS="PROGRAMLISTING"
|
|
|
1927 >tstruct2 STRUCT
|
|
|
1928 f1 rmb 1
|
|
|
1929 f2 rmb 1
|
|
|
1930 ENDSTRUCT
|
|
|
1931
|
|
|
1932 tstruct STRUCT
|
|
|
1933 field1 rmb 2
|
|
|
1934 field2 rmb 3
|
|
|
1935 field3 tstruct2
|
|
|
1936 ENDSTRUCT
|
|
|
1937
|
|
|
1938 ORG $2000
|
|
|
1939 var1 tstruct
|
|
|
1940 var2 tstruct2</PRE
|
|
|
1941 ><P
|
|
|
1942 >Fields are referenced using a dot (.) as a separator. To refer to the
|
|
|
1943 generic offset within a structure, use the structure name to the left of the
|
|
|
1944 dot. If referring to a field within an actual variable, use the variable's
|
|
|
1945 symbol name to the left of the dot.</P
|
|
|
1946 ><P
|
|
|
1947 >You can also refer to the actual size of a structure (or a variable
|
|
|
1948 declared as a structure) using the special symbol sizeof{structname} where
|
|
|
1949 structname will be the name of the structure or the name of the
|
|
|
1950 variable.</P
|
|
|
1951 ><P
|
|
|
1952 >Essentially, structures are a shortcut for defining a vast number of
|
|
|
1953 symbols. When a structure is defined, the assembler creates symbols for the
|
|
|
1954 various fields in the form structname.fieldname as well as the appropriate
|
|
|
1955 sizeof{structname} symbol. When a variable is declared as a structure, the
|
|
|
1956 assembler does the same thing using the name of the variable. You will see
|
|
|
1957 these symbols in the symbol table when the assembler is instructed to
|
|
|
1958 provide a listing. For instance, the above listing will create the
|
|
|
1959 following symbols (symbol values in parentheses): tstruct2.f1 (0),
|
|
|
1960 tstruct2.f2 (1), sizeof{tstruct2} (2), tstruct.field1 (0), tstruct.field2
|
|
|
1961 (2), tstruct.field3 (5), tstruct.field3.f1 (5), tstruct.field3.f2 (6),
|
|
|
1962 sizeof{tstruct.field3} (2), sizeof{tstruct} (7), var1 {$2000}, var1.field1
|
|
|
1963 {$2000}, var1.field2 {$2002}, var1.field3 {$2005}, var1.field3.f1 {$2005},
|
|
|
1964 var1.field3.f2 {$2006}, sizeof(var1.field3} (2), sizeof{var1} (7), var2
|
|
|
1965 ($2007), var2.f1 ($2007), var2.f2 ($2008), sizeof{var2} (2). </P
|
|
|
1966 ></DIV
|
|
|
1967 ><DIV
|
|
|
1968 CLASS="SECTION"
|
|
|
1969 ><HR><H2
|
|
|
1970 CLASS="SECTION"
|
|
|
1971 ><A
|
|
|
1972 NAME="AEN595"
|
|
|
1973 >3.9. Object Files and Sections</A
|
|
|
1974 ></H2
|
|
|
1975 ><P
|
|
|
1976 >The object file target is very useful for large project because it allows
|
|
|
1977 multiple files to be assembled independently and then linked into the final
|
|
|
1978 binary at a later time. It allows only the small portion of the project
|
|
|
1979 that was modified to be re-assembled rather than requiring the entire set
|
|
|
1980 of source code to be available to the assembler in a single assembly process.
|
|
|
1981 This can be particularly important if there are a large number of macros,
|
|
|
1982 symbol definitions, or other metadata that uses resources at assembly time.
|
|
|
1983 By far the largest benefit, however, is keeping the source files small enough
|
|
|
1984 for a mere mortal to find things in them.</P
|
|
|
1985 ><P
|
|
|
1986 >With multi-file projects, there needs to be a means of resolving references to
|
|
|
1987 symbols in other source files. These are known as external references. The
|
|
|
1988 addresses of these symbols cannot be known until the linker joins all the
|
|
|
1989 object files into a single binary. This means that the assembler must be
|
|
|
1990 able to output the object code without knowing the value of the symbol. This
|
|
|
1991 places some restrictions on the code generated by the assembler. For
|
|
|
1992 example, the assembler cannot generate direct page addressing for instructions
|
|
|
1993 that reference external symbols because the address of the symbol may not
|
|
|
1994 be in the direct page. Similarly, relative branches and PC relative addressing
|
|
|
1995 cannot be used in their eight bit forms. Everything that must be resolved
|
|
|
1996 by the linker must be assembled to use the largest address size possible to
|
|
|
1997 allow the linker to fill in the correct value at link time. Note that the
|
|
|
1998 same problem applies to absolute address references as well, even those in
|
|
|
1999 the same source file, because the address is not known until link time.</P
|
|
|
2000 ><P
|
|
|
2001 >It is often desired in multi-file projects to have code of various types grouped
|
|
|
2002 together in the final binary generated by the linker as well. The same applies
|
|
|
2003 to data. In order for the linker to do that, the bits that are to be grouped
|
|
|
2004 must be tagged in some manner. This is where the concept of sections comes in.
|
|
|
2005 Each chunk of code or data is part of a section in the object file. Then,
|
|
|
2006 when the linker reads all the object files, it coalesces all sections of the
|
|
|
2007 same name into a single section and then considers it as a unit.</P
|
|
|
2008 ><P
|
|
|
2009 >The existence of sections, however, raises a problem for symbols even
|
|
|
2010 within the same source file. Thus, the assembler must treat symbols from
|
|
|
2011 different sections within the same source file in the same manner as external
|
|
|
2012 symbols. That is, it must leave them for the linker to resolve at link time,
|
|
|
2013 with all the limitations that entails.</P
|
|
|
2014 ><P
|
|
|
2015 >In the object file target mode, LWASM requires all source lines that
|
|
|
2016 cause bytes to be output to be inside a section. Any directives that do
|
|
|
2017 not cause any bytes to be output can appear outside of a section. This includes
|
|
|
2018 such things as EQU or RMB. Even ORG can appear outside a section. ORG, however,
|
|
|
2019 makes no sense within a section because it is the linker that determines
|
|
|
2020 the starting address of the section's code, not the assembler.</P
|
|
|
2021 ><P
|
|
|
2022 >All symbols defined globally in the assembly process are local to the
|
|
|
2023 source file and cannot be exported. All symbols defined within a section are
|
|
|
2024 considered local to the source file unless otherwise explicitly exported.
|
|
|
2025 Symbols referenced from external source files must be declared external,
|
|
|
2026 either explicitly or by asking the assembler to assume that all undefined
|
|
|
2027 symbols are external.</P
|
|
|
2028 ><P
|
|
|
2029 >It is often handy to define a number of memory addresses that will be
|
|
|
2030 used for data at run-time but which need not be included in the binary file.
|
|
|
2031 These memory addresses are not initialized until run-time, either by the
|
|
|
2032 program itself or by the program loader, depending on the operating environment.
|
|
|
2033 Such sections are often known as BSS sections. LWASM supports generating
|
|
|
2034 sections with a BSS attribute set which causes the section definition including
|
|
|
2035 symbols exported from that section and those symbols required to resolve
|
|
|
2036 references from the local file, but with no actual code in the object file.
|
|
|
2037 It is illegal for any source lines within a BSS flagged section to cause any
|
|
|
2038 bytes to be output.</P
|
|
|
2039 ><P
|
|
|
2040 >The following directives apply to section handling.</P
|
|
|
2041 ><P
|
|
|
2042 ></P
|
|
|
2043 ><DIV
|
|
|
2044 CLASS="VARIABLELIST"
|
|
|
2045 ><DL
|
|
|
2046 ><DT
|
|
|
2047 >SECTION <CODE
|
|
|
2048 CLASS="PARAMETER"
|
|
|
2049 >name[,flags]</CODE
|
|
|
2050 >, SECT <CODE
|
|
|
2051 CLASS="PARAMETER"
|
|
|
2052 >name[,flags]</CODE
|
|
|
2053 >, .AREA <CODE
|
|
|
2054 CLASS="PARAMETER"
|
|
|
2055 >name[,flags]</CODE
|
|
|
2056 ></DT
|
|
|
2057 ><DD
|
|
|
2058 ><P
|
|
|
2059 >Instructs the assembler that the code following this directive is to be
|
|
|
2060 considered part of the section <CODE
|
|
|
2061 CLASS="PARAMETER"
|
|
|
2062 >name</CODE
|
|
|
2063 >. A section name
|
|
|
2064 may appear multiple times in which case it is as though all the code from
|
|
|
2065 all the instances of that section appeared adjacent within the source file.
|
|
|
2066 However, <CODE
|
|
|
2067 CLASS="PARAMETER"
|
|
|
2068 >flags</CODE
|
|
|
2069 > may only be specified on the first
|
|
|
2070 instance of the section.</P
|
|
|
2071 ><P
|
|
|
2072 ><CODE
|
|
|
2073 CLASS="PARAMETER"
|
|
|
2074 >flags</CODE
|
|
|
2075 > is a comma separated list of flags. If a
|
|
|
2076 flag is "bss", the section will be treated as a BSS section and no
|
|
|
2077 statements that generate output are permitted.</P
|
|
|
2078 ><P
|
|
|
2079 >If the flag is "constant",
|
|
|
2080 the same restrictions apply as for BSS sections. Additionally, all symbols
|
|
|
2081 defined in a constant section define absolute values and will not be
|
|
|
2082 adjusted by the linker at link time. Constant sections cannot define
|
|
|
2083 complex expressions for symbols; the value must be fully defined at assembly
|
|
|
2084 time. Additionally, multiple instances of a constant section do not
|
|
|
2085 coalesce into a single addressing unit; each instance starts again at offset
|
|
|
2086 0.</P
|
|
|
2087 ><P
|
|
|
2088 >If the section name is "bss" or ".bss" in any combination of upper and
|
|
|
2089 lower case, the section is assumed to be a BSS section. In that case,
|
|
|
2090 the flag <CODE
|
|
|
2091 CLASS="PARAMETER"
|
|
|
2092 >!bss</CODE
|
|
|
2093 > can be used to override this assumption.</P
|
|
|
2094 ><P
|
|
|
2095 > If the section name is "_constants" or "_constant", in any
|
|
|
2096 combination of upper and lower case, the section is assumed to be a constant
|
|
|
2097 section. This assumption can be overridden with the "!constant"
|
|
|
2098 flag.</P
|
|
|
2099 ><P
|
|
|
2100 >If assembly is already happening within a section, the section is implicitly
|
|
|
2101 ended and the new section started. This is not considered an error although
|
|
|
2102 it is recommended that all sections be explicitly closed.</P
|
|
|
2103 ></DD
|
|
|
2104 ><DT
|
|
|
2105 >ENDSECTION, ENDSECT</DT
|
|
|
2106 ><DD
|
|
|
2107 ><P
|
|
|
2108 >This directive ends the current section. This puts assembly outside of any
|
|
|
2109 sections until the next SECTION directive. ENDSECTION is the preferred form.
|
|
|
2110 Prior to version 3.0 of LWASM, ENDS could also be used to end a section but
|
|
|
2111 as of version 3.0, it is now an alias for ENDSTRUCT instead.</P
|
|
|
2112 ></DD
|
|
|
2113 ><DT
|
|
|
2114 ><CODE
|
|
|
2115 CLASS="PARAMETER"
|
|
|
2116 >sym</CODE
|
|
|
2117 > EXTERN, <CODE
|
|
|
2118 CLASS="PARAMETER"
|
|
|
2119 >sym</CODE
|
|
|
2120 > EXTERNAL, <CODE
|
|
|
2121 CLASS="PARAMETER"
|
|
|
2122 >sym</CODE
|
|
|
2123 > IMPORT</DT
|
|
|
2124 ><DD
|
|
|
2125 ><P
|
|
|
2126 >This directive defines <CODE
|
|
|
2127 CLASS="PARAMETER"
|
|
|
2128 >sym</CODE
|
|
|
2129 > as an external symbol.
|
|
|
2130 This directive may occur at any point in the source code. EXTERN definitions
|
|
|
2131 are resolved on the first pass so an EXTERN definition anywhere in the
|
|
|
2132 source file is valid for the entire file. The use of this directive is
|
|
|
2133 optional when the assembler is instructed to assume that all undefined
|
|
|
2134 symbols are external. In fact, in that mode, if the symbol is referenced
|
|
|
2135 before the EXTERN directive, an error will occur.</P
|
|
|
2136 ></DD
|
|
|
2137 ><DT
|
|
|
2138 ><CODE
|
|
|
2139 CLASS="PARAMETER"
|
|
|
2140 >sym</CODE
|
|
|
2141 > EXPORT, <CODE
|
|
|
2142 CLASS="PARAMETER"
|
|
|
2143 >sym</CODE
|
|
|
2144 > .GLOBL, EXPORT <CODE
|
|
|
2145 CLASS="PARAMETER"
|
|
|
2146 >sym</CODE
|
|
|
2147 >, .GLOBL <CODE
|
|
|
2148 CLASS="PARAMETER"
|
|
|
2149 >sym</CODE
|
|
|
2150 ></DT
|
|
|
2151 ><DD
|
|
|
2152 ><P
|
|
|
2153 >This directive defines <CODE
|
|
|
2154 CLASS="PARAMETER"
|
|
|
2155 >sym</CODE
|
|
|
2156 > as an exported symbol.
|
|
|
2157 This directive may occur at any point in the source code, even before the
|
|
|
2158 definition of the exported symbol.</P
|
|
|
2159 ><P
|
|
|
2160 >Note that <CODE
|
|
|
2161 CLASS="PARAMETER"
|
|
|
2162 >sym</CODE
|
|
|
2163 > may appear as the operand or as the
|
|
|
2164 statement's symbol. If there is a symbol on the statement, that will
|
|
|
2165 take precedence over any operand that is present.</P
|
|
|
2166 ></DD
|
|
|
2167 ><DT
|
|
|
2168 ><CODE
|
|
|
2169 CLASS="PARAMETER"
|
|
|
2170 >sym</CODE
|
|
|
2171 > EXTDEP</DT
|
|
|
2172 ><DD
|
|
|
2173 ><P
|
|
|
2174 >This directive forces an external dependency on
|
|
|
2175 <CODE
|
|
|
2176 CLASS="PARAMETER"
|
|
|
2177 >sym</CODE
|
|
|
2178 >, even if it is never referenced anywhere else in
|
|
|
2179 this file.</P
|
|
|
2180 ></DD
|
|
|
2181 ></DL
|
|
|
2182 ></DIV
|
|
|
2183 ></DIV
|
|
|
2184 ><DIV
|
|
|
2185 CLASS="SECTION"
|
|
|
2186 ><HR><H2
|
|
|
2187 CLASS="SECTION"
|
|
|
2188 ><A
|
|
|
2189 NAME="AEN659"
|
|
|
2190 >3.10. Assembler Modes and Pragmas</A
|
|
|
2191 ></H2
|
|
|
2192 ><P
|
|
|
2193 >There are a number of options that affect the way assembly is performed.
|
|
|
2194 Some of these options can only be specified on the command line because
|
|
|
2195 they determine something absolute about the assembly process. These include
|
|
|
2196 such things as the output target. Other things may be switchable during
|
|
|
2197 the assembly process. These are known as pragmas and are, by definition,
|
|
|
2198 not portable between assemblers.</P
|
|
|
2199 ><P
|
|
|
2200 >LWASM supports a number of pragmas that affect code generation or
|
|
|
2201 otherwise affect the behaviour of the assembler. These may be specified by
|
|
|
2202 way of a command line option or by assembler directives. The directives
|
|
|
2203 are as follows.</P
|
|
|
2204 ><P
|
|
|
2205 ></P
|
|
|
2206 ><DIV
|
|
|
2207 CLASS="VARIABLELIST"
|
|
|
2208 ><DL
|
|
|
2209 ><DT
|
|
|
2210 >PRAGMA <CODE
|
|
|
2211 CLASS="PARAMETER"
|
|
|
2212 >pragma[,...]</CODE
|
|
|
2213 ></DT
|
|
|
2214 ><DD
|
|
|
2215 ><P
|
|
|
2216 >Specifies that the assembler should bring into force all <CODE
|
|
|
2217 CLASS="PARAMETER"
|
|
|
2218 >pragma</CODE
|
|
|
2219 >s
|
|
|
2220 specified. Any unrecognized pragma will cause an assembly error. The new
|
|
|
2221 pragmas will take effect immediately. This directive should be used when
|
|
|
2222 the program will assemble incorrectly if the pragma is ignored or not supported.</P
|
|
|
2223 ></DD
|
|
|
2224 ><DT
|
|
|
2225 >*PRAGMA <CODE
|
|
|
2226 CLASS="PARAMETER"
|
|
|
2227 >pragma[,...]</CODE
|
|
|
2228 ></DT
|
|
|
2229 ><DD
|
|
|
2230 ><P
|
|
|
2231 >This is identical to the PRAGMA directive except no error will occur with
|
|
|
2232 unrecognized or unsupported pragmas. This directive, by virtue of starting
|
|
|
2233 with a comment character, will also be ignored by assemblers that do not
|
|
|
2234 support this directive. Use this variation if the pragma is not required
|
|
|
2235 for correct functioning of the code.</P
|
|
|
2236 ></DD
|
|
|
2237 ><DT
|
|
|
2238 >*PRAGMAPUSH <CODE
|
|
|
2239 CLASS="PARAMETER"
|
|
|
2240 >pragma[,...]</CODE
|
|
|
2241 ></DT
|
|
|
2242 ><DD
|
|
|
2243 ><P
|
|
|
2244 >This directive saves the current state of the specified pragma(s) for later retrieval. See discussion below for more information.</P
|
|
|
2245 ><P
|
|
|
2246 >This directive will not throw any errors for any reason.</P
|
|
|
2247 ></DD
|
|
|
2248 ><DT
|
|
|
2249 >*PRAGMAPOP <CODE
|
|
|
2250 CLASS="PARAMETER"
|
|
|
2251 >pragma[,...]</CODE
|
|
|
2252 ></DT
|
|
|
2253 ><DD
|
|
|
2254 ><P
|
|
|
2255 >This directive restores the previously saved state of the specified pragma(s). See discussion below for more information.</P
|
|
|
2256 ><P
|
|
|
2257 >This directive will not throw any errors for any reason.</P
|
|
|
2258 ></DD
|
|
|
2259 ></DL
|
|
|
2260 ></DIV
|
|
|
2261 ><P
|
|
|
2262 >Each pragma supported has a positive version and a negative version.
|
|
|
2263 The positive version enables the pragma while the negative version disables
|
|
|
2264 it. The negatitve version is simply the positive version with "no" prefixed
|
|
|
2265 to it. For instance, "pragma" vs. "nopragma". When only one version is
|
|
|
2266 listed below, its opposite can be obtained by prepending "no" if it is not
|
|
|
2267 present or removing "no" from the beginning if it is present.</P
|
|
|
2268 ><P
|
|
|
2269 >Pragmas are not case sensitive.</P
|
|
|
2270 ><P
|
|
|
2271 ></P
|
|
|
2272 ><DIV
|
|
|
2273 CLASS="VARIABLELIST"
|
|
|
2274 ><DL
|
|
|
2275 ><DT
|
|
|
2276 >6800compat</DT
|
|
|
2277 ><DD
|
|
|
2278 ><P
|
|
|
2279 >When in force, this pragma enables recognition of various
|
|
|
2280 compatibility instructions useful when assembling 6800 code. These
|
|
|
2281 compatibility instructions are assembled into equivalent 6809 instructions.
|
|
|
2282 This mode also includes several analogous instructions which are not
|
|
|
2283 strictly 6800 instructions but allow the similar style to be applied to 6809
|
|
|
2284 specific features.</P
|
|
|
2285 ><P
|
|
|
2286 >Technically, a compliant 6809 assembler must recognize these
|
|
|
2287 instructions by default since Motorola advertised the 6809 as being source
|
|
|
2288 compatible with the 6800. However, most source code does not require this
|
|
|
2289 compatibility and LWASM itself did not support these instructions prior to
|
|
|
2290 version 4.11 so this mode is disabled by default.</P
|
|
|
2291 ></DD
|
|
|
2292 ><DT
|
|
|
2293 >6809</DT
|
|
|
2294 ><DD
|
|
|
2295 ><P
|
|
|
2296 >This pragma allows you to mark a section of code as 6809-only. In ths mode,
|
|
|
2297 the assembler will throw an error if any 6309 instructions are used.</P
|
|
|
2298 ></DD
|
|
|
2299 ><DT
|
|
|
2300 >6309</DT
|
|
|
2301 ><DD
|
|
|
2302 ><P
|
|
|
2303 >This pragma enables the use of 6309 instructions and disables any 6809 specific
|
|
|
2304 instructions. It also changes the cycle count listing output (if selected)
|
|
|
2305 to display 6309 timings.</P
|
|
|
2306 ></DD
|
|
|
2307 ><DT
|
|
|
2308 >6809conv, 6309conv</DT
|
|
|
2309 ><DD
|
|
|
2310 ><P
|
|
|
2311 >These pragmas enable convenience instructions extending the 6809 and 6309
|
|
|
2312 instruction sets respectively. For more information, see
|
|
|
2313 <A
|
|
|
2314 HREF="#CONVINST"
|
|
|
2315 >Section 3.11</A
|
|
|
2316 >.</P
|
|
|
2317 ></DD
|
|
|
2318 ><DT
|
|
|
2319 >index0tonone</DT
|
|
|
2320 ><DD
|
|
|
2321 ><P
|
|
|
2322 >When in force, this pragma enables an optimization affecting indexed addressing
|
|
|
2323 modes. When the offset expression in an indexed mode evaluates to zero but is
|
|
|
2324 not explicity written as 0, this will replace the operand with the equivalent
|
|
|
2325 no offset mode, thus creating slightly faster code. Because of the advantages
|
|
|
2326 of this optimization, it is enabled by default.</P
|
|
|
2327 ></DD
|
|
|
2328 ><DT
|
|
|
2329 >cescapes</DT
|
|
|
2330 ><DD
|
|
|
2331 ><P
|
|
|
2332 >This pragma will cause strings in the FCC, FCS, and FCN pseudo operations to
|
|
|
2333 have C-style escape sequences interpreted. The one departure from the official
|
|
|
2334 spec is that unrecognized escape sequences will return either the character
|
|
|
2335 immediately following the backslash or some undefined value. Do not rely
|
|
|
2336 on the behaviour of undefined escape sequences.</P
|
|
|
2337 ></DD
|
|
|
2338 ><DT
|
|
|
2339 >importundefexport</DT
|
|
|
2340 ><DD
|
|
|
2341 ><P
|
|
|
2342 >This pragma is only valid for targets that support external references. When
|
|
|
2343 in force, it will cause the EXPORT directive to act as IMPORT if the symbol
|
|
|
2344 to be exported is not defined. This is provided for compatibility with the
|
|
|
2345 output of gcc6809 and should not be used in hand written code. Because of
|
|
|
2346 the confusion this pragma can cause, it is disabled by default.</P
|
|
|
2347 ></DD
|
|
|
2348 ><DT
|
|
|
2349 >undefextern</DT
|
|
|
2350 ><DD
|
|
|
2351 ><P
|
|
|
2352 >This pragma is only valid for targets that support external references. When in
|
|
|
2353 force, if the assembler sees an undefined symbol on the second pass, it will
|
|
|
2354 automatically define it as an external symbol. This automatic definition will
|
|
|
2355 apply for the remainder of the assembly process, even if the pragma is
|
|
|
2356 subsequently turned off. Because this behaviour would be potentially surprising,
|
|
|
2357 this pragma defaults to off.</P
|
|
|
2358 ><P
|
|
|
2359 >The primary use for this pragma is for projects that share a large number of
|
|
|
2360 symbols between source files. In such cases, it is impractical to enumerate
|
|
|
2361 all the external references in every source file. This allows the assembler
|
|
|
2362 and linker to do the heavy lifting while not preventing a particular source
|
|
|
2363 module from defining a local symbol of the same name as an external symbol
|
|
|
2364 if it does not need the external symbol. (This pragma will not cause an
|
|
|
2365 automatic external definition if there is already a locally defined symbol.)</P
|
|
|
2366 ><P
|
|
|
2367 >This pragma will often be specified on the command line for large projects.
|
|
|
2368 However, depending on the specific dynamics of the project, it may be sufficient
|
|
|
2369 for one or two files to use this pragma internally.</P
|
|
|
2370 ></DD
|
|
|
2371 ><DT
|
|
|
2372 >export</DT
|
|
|
2373 ><DD
|
|
|
2374 ><P
|
|
|
2375 >This pragma causes all symbols to be added to the export list
|
|
|
2376 automatically. This is useful when a large number of symbols need to be
|
|
|
2377 exported but you do not wish to include an EXPORT directive for all of them.
|
|
|
2378 This is often useful on the command line but might be useful even inline
|
|
|
2379 with the PRAGMA directive if a large number of symbols in a row are to be
|
|
|
2380 exported.</P
|
|
|
2381 ></DD
|
|
|
2382 ><DT
|
|
|
2383 >dollarlocal</DT
|
|
|
2384 ><DD
|
|
|
2385 ><P
|
|
|
2386 >When set, a "$" in a symbol makes it local. When not set, "$" does not
|
|
|
2387 cause a symbol to be local. It is set by default except when using the OS9
|
|
|
2388 target.</P
|
|
|
2389 ></DD
|
|
|
2390 ><DT
|
|
|
2391 >dollarnotlocal</DT
|
|
|
2392 ><DD
|
|
|
2393 ><P
|
|
|
2394 > This is the same as the "dollarlocal" pragma except its sense is
|
|
|
2395 reversed. That is, "dollarlocal" and "nodollarnotlocal" are equivalent and
|
|
|
2396 "nodollarlocal" and "dollarnotlocal" are equivalent. </P
|
|
|
2397 ></DD
|
|
|
2398 ><DT
|
|
|
2399 >pcaspcr</DT
|
|
|
2400 ><DD
|
|
|
2401 ><P
|
|
|
2402 > Normally, LWASM makes a distinction between PC and PCR in program
|
|
|
2403 counter relative addressing. In particular, the use of PC means an absolute
|
|
|
2404 offset from PC while PCR causes the assembler to calculate the offset to the
|
|
|
2405 specified operand and use that as the offset from PC. By setting this
|
|
|
2406 pragma, you can have PC treated the same as PCR. </P
|
|
|
2407 ></DD
|
|
|
2408 ><DT
|
|
|
2409 >shadow</DT
|
|
|
2410 ><DD
|
|
|
2411 ><P
|
|
|
2412 >When this pragma is in effect, it becomes possible to define a macro
|
|
|
2413 that matches an internal operation code. Thus, it makes it possible to
|
|
|
2414 redefine either CPU instructions or pseudo operations. Because this feature
|
|
|
2415 is of dubious utility, it is disabled by default.</P
|
|
|
2416 ></DD
|
|
|
2417 ><DT
|
|
|
2418 >nolist</DT
|
|
|
2419 ><DD
|
|
|
2420 ><P
|
|
|
2421 >Lines where this pragma is in effect will not appear in the assembly
|
|
|
2422 listing. Also, any symbols defined under this pragma will not show up in
|
|
|
2423 the symbol list. This is most useful in include files to avoid spamming the
|
|
|
2424 assembly listing with dozens, hundreds, or thousands of irrelevant
|
|
|
2425 symbols.</P
|
|
|
2426 ></DD
|
|
|
2427 ><DT
|
|
|
2428 >autobranchlength</DT
|
|
|
2429 ><DD
|
|
|
2430 ><P
|
|
|
2431 >One of the perennial annoyances for 6809 programmers is that the
|
|
|
2432 mneumonics for the short and long branch instructions are different (bxx vs.
|
|
|
2433 lbxx), which is at odds with the rest of the instruction set. This pragma
|
|
|
2434 is a solution to those annoying byte overflow errors that short branch
|
|
|
2435 instructions tend to aquire.</P
|
|
|
2436 ><P
|
|
|
2437 >When this pragma is in effect, which is not the default, whenever any
|
|
|
2438 relative branch instruction is used, its size will be automatically
|
|
|
2439 determined based on the actual distance to the destination. In other words,
|
|
|
2440 one can write code with long or short branches everywhere and the assembler
|
|
|
2441 will choose a size for the branch.</P
|
|
|
2442 ><P
|
|
|
2443 >Also, while this pragma is in effect, the > and < symbols can be used
|
|
|
2444 to force the branch size, analogous to their use for other instructions with
|
|
|
2445 < forcing 8 bit offsets and > forcing 16 bit offets.</P
|
|
|
2446 ><P
|
|
|
2447 >Because this pragma leads to source that is incompatible with other
|
|
|
2448 assemblers, it is strongly recommended that it be invoked using the PRAGMA
|
|
|
2449 directive within the source code rather than on the command line or via the
|
|
|
2450 *PRAGMA directive. This way, an error will be raised if someone tries to
|
|
|
2451 assemble the code under a different assembler.</P
|
|
|
2452 ></DD
|
|
|
2453 ><DT
|
|
|
2454 >nosymbolcase, symbolnocase</DT
|
|
|
2455 ><DD
|
|
|
2456 ><P
|
|
|
2457 >Any symbol defined while this pragma is in force will be treated as
|
|
|
2458 case insensitive, regardless whether the pragma is in force when the symbol
|
|
|
2459 is referenced.</P
|
|
|
2460 ><P
|
|
|
2461 >It is important to note that this pragma will not work as expected in
|
|
|
2462 all cases when using the object file assembly target. It is intended for
|
|
|
2463 use only when the assembler will be producing the final binary.</P
|
|
|
2464 ></DD
|
|
|
2465 ><DT
|
|
|
2466 >condundefzero</DT
|
|
|
2467 ><DD
|
|
|
2468 ><P
|
|
|
2469 >This pragma will cause the assembler to change the way it handles
|
|
|
2470 symbols in conditional expressions. Ordinarily, any symbol that is not
|
|
|
2471 defined prior to the conditional will throw an undefined symbol error. With
|
|
|
2472 this pragma in effect, symbols that are not yet defined at the point the
|
|
|
2473 conditional is encountered will be treated as zero.</P
|
|
|
2474 ><P
|
|
|
2475 >This is not the default because it encourages poor code design. One
|
|
|
2476 should use the "IFDEF" or "IFNDEF" conditionals to test for the presence of
|
|
|
2477 a symbol.</P
|
|
|
2478 ><P
|
|
|
2479 >It is important to note that if a symbol is defined but it does not
|
|
|
2480 yet evaluate to a constant value at the point where the conditional appears,
|
|
|
2481 the assembler will still complain about a non constant condition.</P
|
|
|
2482 ></DD
|
|
|
2483 ><DT
|
|
|
2484 >forwardrefmax</DT
|
|
|
2485 ><DD
|
|
|
2486 ><P
|
|
|
2487 >This pragma will disable forward reference optimization completely.
|
|
|
2488 Ordinarily, LWASM will attempt to select the shortest possible addressing
|
|
|
2489 mode for forward references. However, in many source files, especially
|
|
|
2490 those not using the PCR relative addressing modes, this optimization is
|
|
|
2491 pointless since the assembler will almost certainly settle on a 16 bit
|
|
|
2492 offset or address. If all variables in the direct page are defined before
|
|
|
2493 the main body of the code, the benefit of forward reference optimization
|
|
|
2494 almost certainly vanishes completely. However, the cost of doing that
|
|
|
2495 optimization remains and can result in a very long assembly time.</P
|
|
|
2496 ><P
|
|
|
2497 >Enabling this pragma will cause all forward references to use the
|
|
|
2498 maximum offset or address size, much the same has EDTASM and other pure
|
|
|
2499 two pass assemblers do. The side effect is that all line lengths and
|
|
|
2500 symbol values are fully resolved after the initial parsing pass and the
|
|
|
2501 amount of work to resolve everything becomes almost nil.</P
|
|
|
2502 ><P
|
|
|
2503 >While this pragma can be applied selectively to sections of source
|
|
|
2504 code (use *PRAGMA if doing so and compatibility with other assemblers
|
|
|
2505 is desired), it is likely more useful when provided as a command line
|
|
|
2506 pragma.</P
|
|
|
2507 ><P
|
|
|
2508 >It should be noted that the presence or absence of this pragma
|
|
|
2509 will not change the correctness of the generated code unless cycle counts
|
|
|
2510 or byte counts are critical (which they usually are not). It also will
|
|
|
2511 not override the operand size override prefixes (< and >). It only
|
|
|
2512 applies when the assembler is left to guess what the operand size is.</P
|
|
|
2513 ></DD
|
|
|
2514 ><DT
|
|
|
2515 >operandsizewarning</DT
|
|
|
2516 ><DD
|
|
|
2517 ><P
|
|
|
2518 >Enabling this pragma will cause LWASM to show a warning when it
|
|
|
2519 detects that a smaller addressing mode could be used for an instruction.
|
|
|
2520 This is particularly useful for finding places where long branches are used
|
|
|
2521 where short branches could be used instead. It will also show the warnings
|
|
|
2522 for indexing offsets (regardless of whether the operand size is
|
|
|
2523 forced).</P
|
|
|
2524 ><P
|
|
|
2525 >As of LWASM 4.16, no other checks are performed.</P
|
|
|
2526 ></DD
|
|
|
2527 ><DT
|
|
|
2528 >qrts</DT
|
|
|
2529 ><DD
|
|
|
2530 ><P
|
|
|
2531 > Enables the use of the ?RTS branch target. ?RTS is implemented to maintain
|
|
|
2532 compatibility with the MACRO-80c assembler. It works by searching backward
|
|
|
2533 in the code for an RTS instruction. If none is found, it inverts the branch
|
|
|
2534 logic and inserts an RTS following the branch instruction. Below you can
|
|
|
2535 see how a BMI (2B xx) has been assembled as a BPL *+1 (2A 01) to skip over an
|
|
|
2536 inserted RTS (39).</P
|
|
|
2537 ><PRE
|
|
|
2538 CLASS="PROGRAMLISTING"
|
|
|
2539 >1D1E 7D1D1D TST WHICH1
|
|
|
2540 1D21 2A0139 BMI ?RTS
|
|
|
2541 1D24 BD1D65 JSR INV</PRE
|
|
|
2542 ></DD
|
|
|
2543 ><DT
|
|
|
2544 >m80ext</DT
|
|
|
2545 ><DD
|
|
|
2546 ><P
|
|
|
2547 > This pragma (along with pragma qrts) enables some uncommon behaviors to
|
|
|
2548 accomodate The Micro Works MACRO-80c assembler from 1982. This assembler
|
|
|
2549 was used by a number of notable TRS-80 Color Computer applications and the
|
|
|
2550 goal of this pragma is to allow them to build identical binaries from
|
|
|
2551 unmodified, vintage source code.</P
|
|
|
2552 ><P
|
|
|
2553 > In m80ext mode, the handling of the "END" pseudo-op changes when used inside
|
|
|
2554 an include file. Instead of terminating all assembly, it merely stops
|
|
|
2555 processing of the current include file (this behavior matches the original
|
|
|
2556 Motorola 6809 assembler). In addition, loading an ASCII value with a single
|
|
|
2557 quote (e.g., LDA #'N) is extended to 16-bit registers (e.g., LDD #'NO).
|
|
|
2558 LWASM normally supports this via double quote and that is the proper use in
|
|
|
2559 modern code. Finally, the FCC pseudo-op is extended to handle FCB-like
|
|
|
2560 behavior after the closing delimiter:</P
|
|
|
2561 ><PRE
|
|
|
2562 CLASS="PROGRAMLISTING"
|
|
|
2563 > FCC "Greetings from 1982",13,0</PRE
|
|
|
2564 ></DD
|
|
|
2565 ><DT
|
|
|
2566 >testmode</DT
|
|
|
2567 ><DD
|
|
|
2568 ><P
|
|
|
2569 > This pragma is intended for internal testing purposes. In testmode, the
|
|
|
2570 assembler searches for a specially-formatted comment starting with a
|
|
|
2571 semicolon followed by a period. Immediately afterward are a list of hex
|
|
|
2572 bytes that the assembler is expected to generate. Likewise, if the
|
|
|
2573 assembler is expected to throw an error or warning on a given line, you can
|
|
|
2574 check by specifying "E:" followed by the error number. In this case the
|
|
|
2575 error is ignored and the assembler continues ignoring the line in question. </P
|
|
|
2576 ><PRE
|
|
|
2577 CLASS="PROGRAMLISTING"
|
|
|
2578 >1D1E 7D1D1D TST WHICH1 ;.7d1d1d
|
|
|
2579 1D21 2A0139 BMI ?RTS ;.2a0139
|
|
|
2580 1D24 1D24 FDB * ;.1d24
|
|
|
2581 1D26 xyz INV ;.E:32 (Error 32 is "Bad opcode")</PRE
|
|
|
2582 ></DD
|
|
|
2583 ></DL
|
|
|
2584 ></DIV
|
|
|
2585 ><P
|
|
|
2586 >As a convenience, each input file has a pragma state stack. This
|
|
|
2587 allows, through the use of *PRAGMAPUSH and *PRAGMAPOP, a file to change a
|
|
|
2588 pragma state and then restore it to the precise state it had previously.
|
|
|
2589 If, at the end of an input file, all pragma states have not been popped,
|
|
|
2590 they will be removed from the stack. Thus, it is critical to employ
|
|
|
2591 *PRAGMAPOP correctly. Because each input file has its own pragma stack,
|
|
|
2592 using *PRAGMAPUSH in one file and *PRAGMAPOP in another file will not
|
|
|
2593 work.</P
|
|
|
2594 ><P
|
|
|
2595 >Pragma stacks are more useful in include files, in particular in
|
|
|
2596 conjunction with the nolist pragma. One can push the state of the nolist
|
|
|
2597 pragma, engage the nolist pragma, and then pop the state of the nolist
|
|
|
2598 pragma at the end of the include file. This will cause the entire include
|
|
|
2599 file to operate under the nolist pragma. However, if the file is included
|
|
|
2600 while nolist is already engaged, it will not undo that state.</P
|
|
|
2601 ></DIV
|
|
|
2602 ><DIV
|
|
|
2603 CLASS="SECTION"
|
|
|
2604 ><HR><H2
|
|
|
2605 CLASS="SECTION"
|
|
|
2606 ><A
|
|
|
2607 NAME="CONVINST"
|
|
|
2608 >3.11. Convenience Instructions</A
|
|
|
2609 ></H2
|
|
|
2610 ><P
|
|
|
2611 > Similar to the 6800 compatibility instructions (pragma 6800compat) these
|
|
|
2612 pragma 6809conv and pragma 6309conv enable convenience extensions to the
|
|
|
2613 6809 and 6309 instruction set. Originally intended for compatibility with
|
|
|
2614 the MACRO-80c assembler, these have proven useful in large codebases that
|
|
|
2615 target both the 6809 and the 6309.</P
|
|
|
2616 ><P
|
|
|
2617 > The 6809 extensions are straightforward with the exception of "TSTD" which
|
|
|
2618 assembles as "STD -2,S". A benefit of using these is they will "just work"
|
|
|
2619 and take on their 6309 equivalent when you enable 6309 assembly mode.
|
|
|
2620 Supported instructions: ASRD, CLRD, COMD, LSLD, LSRD, NEGD, TSTD.</P
|
|
|
2621 ><P
|
|
|
2622 > 6309 extensions are based on common patterns described by Chris Burke and
|
|
|
2623 Darren Atkinson in their 6309 documentation and include the following
|
|
|
2624 instructions: ASRQ, CLRQ, COMQ, LSLE, LSLF, LSLQ, LSRQ, NEGE,
|
|
|
2625 NEGF, NEGW, NEGQ, TSTQ.</P
|
|
|
2626 ></DIV
|
|
|
2627 ><DIV
|
|
|
2628 CLASS="SECTION"
|
|
|
2629 ><HR><H2
|
|
|
2630 CLASS="SECTION"
|
|
|
2631 ><A
|
|
|
2632 NAME="AEN805"
|
|
|
2633 >3.12. Cycle Counts</A
|
|
|
2634 ></H2
|
|
|
2635 ><P
|
|
|
2636 > The following options for displaying cycle counts in listings are provided.
|
|
|
2637 These options are enabled from pragmas on the command line or in the
|
|
|
2638 assembly files themselves. For compatibility with other assemblers you can
|
|
|
2639 use the "OPT" keyword in addition to "PRAGMA."</P
|
|
|
2640 ><PRE
|
|
|
2641 CLASS="PROGRAMLISTING"
|
|
|
2642 >opt c - enable cycle counts: [8]
|
|
|
2643 opt cd - enable detailed cycle counts breaking down addressing modes: [5+3]
|
|
|
2644 opt ct - show a running subtotal of cycles
|
|
|
2645 opt cc - clear the running subtotal</PRE
|
|
|
2646 ><P
|
|
|
2647 > The assembler supports both 6809 as well as native-mode 6309 cycle counts.
|
|
|
2648 In 6309 mode the counts are displayed in parenthesis instead of brackets.
|
|
|
2649 In addition, some operations have a variable cycle count. In this case a
|
|
|
2650 "+?" is displayed to alert the reader. Sample output is shown below.</P
|
|
|
2651 ><PRE
|
|
|
2652 CLASS="PROGRAMLISTING"
|
|
|
2653 >266f 7d25e2 (window.asm):00313 [7] 7 move tst putflg
|
|
|
2654 2672 2602 (window.asm):00314 [5] 12 bne a@
|
|
|
2655 2674 1e13 (window.asm):00315 [8] 20 exg x,u
|
|
|
2656 2676 0dd6 (window.asm):00316 [6] 26 a@ tst is6309
|
|
|
2657 2678 2618 (window.asm):00317 [5] 31 bne exit@
|
|
|
2658 (window.asm):00318 opt 6309
|
|
|
2659 267a 10860085 (window.asm):00319 (4) 35 b@ ldw #133
|
|
|
2660 267e 113813 (window.asm):00320 (6+?) 41 tfm x+,u+
|
|
|
2661 2681 30881b (window.asm):00321 (4+1) 46 leax 27,x
|
|
|
2662 2684 33c81b (window.asm):00322 (4+1) 51 leau 27,u
|
|
|
2663 2687 4a (window.asm):00323 (1) 52 deca
|
|
|
2664 2688 26f0 (window.asm):00324 (5) 57 bne b@</PRE
|
|
|
2665 ></DIV
|
|
|
2666 ></DIV
|
|
|
2667 ><DIV
|
|
|
2668 CLASS="CHAPTER"
|
|
|
2669 ><HR><H1
|
|
|
2670 ><A
|
|
|
2671 NAME="AEN811"
|
|
|
2672 ></A
|
|
|
2673 >Chapter 4. LWLINK</H1
|
|
|
2674 ><P
|
|
|
2675 >The LWTOOLS linker is called LWLINK. This chapter documents the various features
|
|
|
2676 of the linker.</P
|
|
|
2677 ><DIV
|
|
|
2678 CLASS="SECTION"
|
|
|
2679 ><HR><H2
|
|
|
2680 CLASS="SECTION"
|
|
|
2681 ><A
|
|
|
2682 NAME="AEN814"
|
|
|
2683 >4.1. Command Line Options</A
|
|
|
2684 ></H2
|
|
|
2685 ><P
|
|
|
2686 >The binary for LWLINK is called "lwlink". Note that the binary is in lower
|
|
|
2687 case. lwlink takes the following command line arguments.</P
|
|
|
2688 ><P
|
|
|
2689 ></P
|
|
|
2690 ><DIV
|
|
|
2691 CLASS="VARIABLELIST"
|
|
|
2692 ><DL
|
|
|
2693 ><DT
|
|
|
2694 ><CODE
|
|
|
2695 CLASS="OPTION"
|
|
|
2696 >--decb</CODE
|
|
|
2697 >, <CODE
|
|
|
2698 CLASS="OPTION"
|
|
|
2699 >-b</CODE
|
|
|
2700 ></DT
|
|
|
2701 ><DD
|
|
|
2702 ><P
|
|
|
2703 >Selects the DECB output format target. This is equivalent to <CODE
|
|
|
2704 CLASS="OPTION"
|
|
|
2705 >--format=decb</CODE
|
|
|
2706 ></P
|
|
|
2707 ></DD
|
|
|
2708 ><DT
|
|
|
2709 ><CODE
|
|
|
2710 CLASS="OPTION"
|
|
|
2711 >--output=FILE</CODE
|
|
|
2712 >, <CODE
|
|
|
2713 CLASS="OPTION"
|
|
|
2714 >-o FILE</CODE
|
|
|
2715 ></DT
|
|
|
2716 ><DD
|
|
|
2717 ><P
|
|
|
2718 >This option specifies the name of the output file. If not specified, the
|
|
|
2719 default is <CODE
|
|
|
2720 CLASS="OPTION"
|
|
|
2721 >a.out</CODE
|
|
|
2722 >.</P
|
|
|
2723 ></DD
|
|
|
2724 ><DT
|
|
|
2725 ><CODE
|
|
|
2726 CLASS="OPTION"
|
|
|
2727 >--format=TYPE</CODE
|
|
|
2728 >, <CODE
|
|
|
2729 CLASS="OPTION"
|
|
|
2730 >-f TYPE</CODE
|
|
|
2731 ></DT
|
|
|
2732 ><DD
|
|
|
2733 ><P
|
|
|
2734 >This option specifies the output format. Valid values are <CODE
|
|
|
2735 CLASS="OPTION"
|
|
|
2736 >decb</CODE
|
|
|
2737 >
|
|
|
2738 and <CODE
|
|
|
2739 CLASS="OPTION"
|
|
|
2740 >raw</CODE
|
|
|
2741 ></P
|
|
|
2742 ></DD
|
|
|
2743 ><DT
|
|
|
2744 ><CODE
|
|
|
2745 CLASS="OPTION"
|
|
|
2746 >--raw</CODE
|
|
|
2747 >, <CODE
|
|
|
2748 CLASS="OPTION"
|
|
|
2749 >-r</CODE
|
|
|
2750 ></DT
|
|
|
2751 ><DD
|
|
|
2752 ><P
|
|
|
2753 >This option specifies the raw output format.
|
|
|
2754 It is equivalent to <CODE
|
|
|
2755 CLASS="OPTION"
|
|
|
2756 >--format=raw</CODE
|
|
|
2757 >
|
|
|
2758 and <CODE
|
|
|
2759 CLASS="OPTION"
|
|
|
2760 >-f raw</CODE
|
|
|
2761 ></P
|
|
|
2762 ></DD
|
|
|
2763 ><DT
|
|
|
2764 ><CODE
|
|
|
2765 CLASS="OPTION"
|
|
|
2766 >--script=FILE</CODE
|
|
|
2767 >, <CODE
|
|
|
2768 CLASS="OPTION"
|
|
|
2769 >-s</CODE
|
|
|
2770 ></DT
|
|
|
2771 ><DD
|
|
|
2772 ><P
|
|
|
2773 >This option allows specifying a linking script to override the linker's
|
|
|
2774 built in defaults.</P
|
|
|
2775 ></DD
|
|
|
2776 ><DT
|
|
|
2777 ><CODE
|
|
|
2778 CLASS="OPTION"
|
|
|
2779 >--section-base=SECT=BASE</CODE
|
|
|
2780 ></DT
|
|
|
2781 ><DD
|
|
|
2782 ><P
|
|
|
2783 >Cause section SECT to load at base address BASE. This will be prepended
|
|
|
2784 to the built-in link script. It is ignored if a link script is provided.</P
|
|
|
2785 ></DD
|
|
|
2786 ><DT
|
|
|
2787 ><CODE
|
|
|
2788 CLASS="OPTION"
|
|
|
2789 >--map=FILE</CODE
|
|
|
2790 >, <CODE
|
|
|
2791 CLASS="OPTION"
|
|
|
2792 >-m FILE</CODE
|
|
|
2793 ></DT
|
|
|
2794 ><DD
|
|
|
2795 ><P
|
|
|
2796 >This will output a description of the link result to FILE.</P
|
|
|
2797 ></DD
|
|
|
2798 ><DT
|
|
|
2799 ><CODE
|
|
|
2800 CLASS="OPTION"
|
|
|
2801 >--library=LIBSPEC</CODE
|
|
|
2802 >, <CODE
|
|
|
2803 CLASS="OPTION"
|
|
|
2804 >-l LIBSPEC</CODE
|
|
|
2805 ></DT
|
|
|
2806 ><DD
|
|
|
2807 ><P
|
|
|
2808 >Load a library using the library search path. If LIBSPEC is prefixed with a
|
|
|
2809 colon (":"), then LIBSPEC is the precise filename to be searched for in the
|
|
|
2810 library path. Otherwise, LIBSPEC will have "lib" prepended and ".a" appended.</P
|
|
|
2811 ></DD
|
|
|
2812 ><DT
|
|
|
2813 ><CODE
|
|
|
2814 CLASS="OPTION"
|
|
|
2815 >--library-path=DIR</CODE
|
|
|
2816 >, <CODE
|
|
|
2817 CLASS="OPTION"
|
|
|
2818 >-L DIR</CODE
|
|
|
2819 ></DT
|
|
|
2820 ><DD
|
|
|
2821 ><P
|
|
|
2822 >Add DIR to the library search path.</P
|
|
|
2823 ></DD
|
|
|
2824 ><DT
|
|
|
2825 ><CODE
|
|
|
2826 CLASS="OPTION"
|
|
|
2827 >--debug</CODE
|
|
|
2828 >, <CODE
|
|
|
2829 CLASS="OPTION"
|
|
|
2830 >-d</CODE
|
|
|
2831 ></DT
|
|
|
2832 ><DD
|
|
|
2833 ><P
|
|
|
2834 >This option increases the debugging level. It is only useful for LWTOOLS
|
|
|
2835 developers.</P
|
|
|
2836 ></DD
|
|
|
2837 ><DT
|
|
|
2838 ><CODE
|
|
|
2839 CLASS="OPTION"
|
|
|
2840 >--help</CODE
|
|
|
2841 >, <CODE
|
|
|
2842 CLASS="OPTION"
|
|
|
2843 >-?</CODE
|
|
|
2844 ></DT
|
|
|
2845 ><DD
|
|
|
2846 ><P
|
|
|
2847 >This provides a listing of command line options and a brief description
|
|
|
2848 of each.</P
|
|
|
2849 ></DD
|
|
|
2850 ><DT
|
|
|
2851 ><CODE
|
|
|
2852 CLASS="OPTION"
|
|
|
2853 >--usage</CODE
|
|
|
2854 ></DT
|
|
|
2855 ><DD
|
|
|
2856 ><P
|
|
|
2857 >This will display a usage summary
|
|
|
2858 of each command line option.</P
|
|
|
2859 ></DD
|
|
|
2860 ><DT
|
|
|
2861 ><CODE
|
|
|
2862 CLASS="OPTION"
|
|
|
2863 >--version</CODE
|
|
|
2864 >, <CODE
|
|
|
2865 CLASS="OPTION"
|
|
|
2866 >-V</CODE
|
|
|
2867 ></DT
|
|
|
2868 ><DD
|
|
|
2869 ><P
|
|
|
2870 >This will display the version of LWLINK.</P
|
|
|
2871 ></DD
|
|
|
2872 ></DL
|
|
|
2873 ></DIV
|
|
|
2874 ></DIV
|
|
|
2875 ><DIV
|
|
|
2876 CLASS="SECTION"
|
|
|
2877 ><HR><H2
|
|
|
2878 CLASS="SECTION"
|
|
|
2879 ><A
|
|
|
2880 NAME="AEN911"
|
|
|
2881 >4.2. Linker Operation</A
|
|
|
2882 ></H2
|
|
|
2883 ><P
|
|
|
2884 > LWLINK takes one or more files in supported input formats and links them
|
|
|
2885 into a single binary. Currently supported formats are the LWTOOLS object
|
|
|
2886 file format and the archive format used by LWAR. While the precise method is
|
|
|
2887 slightly different, linking can be conceptualized as the following steps. </P
|
|
|
2888 ><P
|
|
|
2889 ></P
|
|
|
2890 ><OL
|
|
|
2891 TYPE="1"
|
|
|
2892 ><LI
|
|
|
2893 ><P
|
|
|
2894 >First, the linker loads a linking script. If no script is specified, it
|
|
|
2895 loads a built-in default script based on the output format selected. This
|
|
|
2896 script tells the linker how to lay out the various sections in the final
|
|
|
2897 binary.</P
|
|
|
2898 ></LI
|
|
|
2899 ><LI
|
|
|
2900 ><P
|
|
|
2901 >Next, the linker reads all the input files into memory. At this time, it
|
|
|
2902 flags any format errors in those files. It constructs a table of symbols
|
|
|
2903 for each object at this time.</P
|
|
|
2904 ></LI
|
|
|
2905 ><LI
|
|
|
2906 ><P
|
|
|
2907 >The linker then proceeds with organizing the sections loaded from each file
|
|
|
2908 according to the linking script. As it does so, it is able to assign addresses
|
|
|
2909 to each symbol defined in each object file. At this time, the linker may
|
|
|
2910 also collapse different instances of the same section name into a single
|
|
|
2911 section by appending the data from each subsequent instance of the section
|
|
|
2912 to the first instance of the section.</P
|
|
|
2913 ></LI
|
|
|
2914 ><LI
|
|
|
2915 ><P
|
|
|
2916 >Next, the linker looks through every object file for every incomplete reference.
|
|
|
2917 It then attempts to fully resolve that reference. If it cannot do so, it
|
|
|
2918 throws an error. Once a reference is resolved, the value is placed into
|
|
|
2919 the binary code at the specified section. It should be noted that an
|
|
|
2920 incomplete reference can reference either a symbol internal to the object
|
|
|
2921 file or an external symbol which is in the export list of another object
|
|
|
2922 file.</P
|
|
|
2923 ></LI
|
|
|
2924 ><LI
|
|
|
2925 ><P
|
|
|
2926 >If all of the above steps are successful, the linker opens the output file
|
|
|
2927 and actually constructs the binary.</P
|
|
|
2928 ></LI
|
|
|
2929 ></OL
|
|
|
2930 ></DIV
|
|
|
2931 ><DIV
|
|
|
2932 CLASS="SECTION"
|
|
|
2933 ><HR><H2
|
|
|
2934 CLASS="SECTION"
|
|
|
2935 ><A
|
|
|
2936 NAME="AEN925"
|
|
|
2937 >4.3. Linking Scripts</A
|
|
|
2938 ></H2
|
|
|
2939 ><P
|
|
|
2940 >A linker script is used to instruct the linker about how to assemble the
|
|
|
2941 various sections into a completed binary. It consists of a series of
|
|
|
2942 directives which are considered in the order they are encountered.</P
|
|
|
2943 ><P
|
|
|
2944 >The sections will appear in the resulting binary in the order they are
|
|
|
2945 specified in the script file. If a referenced section is not found, the linker will behave as though the
|
|
|
2946 section did exist but had a zero size, no relocations, and no exports.
|
|
|
2947 A section should only be referenced once. Any subsequent references will have
|
|
|
2948 an undefined effect.</P
|
|
|
2949 ><P
|
|
|
2950 >All numbers are in linking scripts are specified in hexadecimal. All directives
|
|
|
2951 are case sensitive although the hexadecimal numbers are not.</P
|
|
|
2952 ><P
|
|
|
2953 >A section name can be specified as a "*", then any section not
|
|
|
2954 already matched by the script will be matched. The "*" can be followed
|
|
|
2955 by a comma and a flag to narrow the section down slightly, also.
|
|
|
2956 If the flag is "!bss", then any section that is not flagged as a bss section
|
|
|
2957 will be matched. If the flag is "bss", then any section that is flagged as
|
|
|
2958 bss will be matched.</P
|
|
|
2959 ><P
|
|
|
2960 >The following directives are understood in a linker script.</P
|
|
|
2961 ><P
|
|
|
2962 ></P
|
|
|
2963 ><DIV
|
|
|
2964 CLASS="VARIABLELIST"
|
|
|
2965 ><DL
|
|
|
2966 ><DT
|
|
|
2967 >sectopt <CODE
|
|
|
2968 CLASS="PARAMETER"
|
|
|
2969 >section</CODE
|
|
|
2970 > padafter <CODE
|
|
|
2971 CLASS="PARAMETER"
|
|
|
2972 >byte,...</CODE
|
|
|
2973 ></DT
|
|
|
2974 ><DD
|
|
|
2975 ><P
|
|
|
2976 > This will cause the linker to append the specified list of byte values
|
|
|
2977 (specified in hexadecimal separated by commas) to the end of the named
|
|
|
2978 section. This is done once all instances of the specified section are
|
|
|
2979 collected together. This has no effect if the specified section does not
|
|
|
2980 appear anywhere in any of the objects specified for linking. </P
|
|
|
2981 ><P
|
|
|
2982 > If code depends on the presence of this padding somewhere, it is sufficient
|
|
|
2983 to include an empty section of the specified name in the object that depends
|
|
|
2984 on it. </P
|
|
|
2985 ></DD
|
|
|
2986 ><DT
|
|
|
2987 >define basesympat <CODE
|
|
|
2988 CLASS="PARAMETER"
|
|
|
2989 >string</CODE
|
|
|
2990 ></DT
|
|
|
2991 ><DD
|
|
|
2992 ><P
|
|
|
2993 > This causes the linker to define a symbol for the ultimate base address of
|
|
|
2994 each section using the pattern specified by <CODE
|
|
|
2995 CLASS="PARAMETER"
|
|
|
2996 >string</CODE
|
|
|
2997 >.
|
|
|
2998 In the string, %s can appear exactly once and will be replaced with the
|
|
|
2999 section name. The base address is calculated after all instances of each
|
|
|
3000 section have been collapsed together. </P
|
|
|
3001 ><P
|
|
|
3002 > It should be noted that if none of the objects to be linked contains a
|
|
|
3003 particular section name, there will be no base symbol defined for it, even
|
|
|
3004 if it is listed explicitly in the link script. If code depends on the
|
|
|
3005 presence of these symbols, it is sufficient to include an empty section of
|
|
|
3006 the specified name in the object that depends on it. </P
|
|
|
3007 ><P
|
|
|
3008 > If the pattern resolves to the same string for multiple
|
|
|
3009 sections, the results are undefined. </P
|
|
|
3010 ></DD
|
|
|
3011 ><DT
|
|
|
3012 >define lensympat <CODE
|
|
|
3013 CLASS="PARAMETER"
|
|
|
3014 >string</CODE
|
|
|
3015 ></DT
|
|
|
3016 ><DD
|
|
|
3017 ><P
|
|
|
3018 > This causes the linker to define a symbol for the ultimate length of each
|
|
|
3019 section using the pattern specified by <CODE
|
|
|
3020 CLASS="PARAMETER"
|
|
|
3021 >string</CODE
|
|
|
3022 >. In
|
|
|
3023 the string, %s can appear exactly once and will be replaced with the section
|
|
|
3024 name. The length is calculated after all instances of a section have been
|
|
|
3025 collapsed together. </P
|
|
|
3026 ><P
|
|
|
3027 > It should be noted that if none of the objects to be linked contains a
|
|
|
3028 particular section name, there will be no length symbol defined for it, even
|
|
|
3029 if it is listed explicitly in the link script. If code depends on the
|
|
|
3030 presence of these symbols, it is sufficient to include an empty section of
|
|
|
3031 the specified name in the object that depends on it. </P
|
|
|
3032 ><P
|
|
|
3033 >If the pattern resolves to the same string for multiple
|
|
|
3034 sections, the results are undefined. </P
|
|
|
3035 ></DD
|
|
|
3036 ><DT
|
|
|
3037 >section <CODE
|
|
|
3038 CLASS="PARAMETER"
|
|
|
3039 >name</CODE
|
|
|
3040 > load <CODE
|
|
|
3041 CLASS="PARAMETER"
|
|
|
3042 >addr</CODE
|
|
|
3043 ></DT
|
|
|
3044 ><DD
|
|
|
3045 ><P
|
|
|
3046 > This causes the section <CODE
|
|
|
3047 CLASS="PARAMETER"
|
|
|
3048 >name</CODE
|
|
|
3049 > to load at
|
|
|
3050 <CODE
|
|
|
3051 CLASS="PARAMETER"
|
|
|
3052 >addr</CODE
|
|
|
3053 >. For the raw target, only one "load at" entry is
|
|
|
3054 allowed for non-bss sections and it must be the first one. For raw targets,
|
|
|
3055 it affects the addresses the linker assigns to symbols but has no other
|
|
|
3056 affect on the output. bss sections may all have separate load addresses but
|
|
|
3057 since they will not appear in the binary anyway, this is okay.</P
|
|
|
3058 ><P
|
|
|
3059 >For the decb target, each "load" entry will cause a new "block" to be
|
|
|
3060 output to the binary which will contain the load address. It is legal for
|
|
|
3061 sections to overlap in this manner - the linker assumes the loader will sort
|
|
|
3062 everything out.</P
|
|
|
3063 ></DD
|
|
|
3064 ><DT
|
|
|
3065 >section <CODE
|
|
|
3066 CLASS="PARAMETER"
|
|
|
3067 >name</CODE
|
|
|
3068 > high <CODE
|
|
|
3069 CLASS="PARAMETER"
|
|
|
3070 >addr</CODE
|
|
|
3071 ></DT
|
|
|
3072 ><DD
|
|
|
3073 ><P
|
|
|
3074 > This causes the section <CODE
|
|
|
3075 CLASS="PARAMETER"
|
|
|
3076 >name</CODE
|
|
|
3077 > to load with its end
|
|
|
3078 address just below <CODE
|
|
|
3079 CLASS="PARAMETER"
|
|
|
3080 >addr</CODE
|
|
|
3081 >. Subsequent sections are
|
|
|
3082 loaded at progressively lower addresses. This may lead to inefficient file
|
|
|
3083 encoding for some targets. As of this writing, it will also almost
|
|
|
3084 certainly do the wrong thing for a raw target. </P
|
|
|
3085 ><P
|
|
|
3086 > This is useful for aligning a block of code with high memory. As an
|
|
|
3087 example, if the total size of a section is $100 bytes and a high address of
|
|
|
3088 $FE00 is specified, the section will actually load at $FD00. </P
|
|
|
3089 ></DD
|
|
|
3090 ><DT
|
|
|
3091 >section <CODE
|
|
|
3092 CLASS="PARAMETER"
|
|
|
3093 >name</CODE
|
|
|
3094 ></DT
|
|
|
3095 ><DD
|
|
|
3096 ><P
|
|
|
3097 > This will cause the section <CODE
|
|
|
3098 CLASS="PARAMETER"
|
|
|
3099 >name</CODE
|
|
|
3100 > to load after the previously listed
|
|
|
3101 section.</P
|
|
|
3102 ></DD
|
|
|
3103 ><DT
|
|
|
3104 >entry <CODE
|
|
|
3105 CLASS="PARAMETER"
|
|
|
3106 >addr or sym</CODE
|
|
|
3107 ></DT
|
|
|
3108 ><DD
|
|
|
3109 ><P
|
|
|
3110 >This will cause the execution address (entry point) to be the address
|
|
|
3111 specified (in hex) or the specified symbol name. The symbol name must
|
|
|
3112 match a symbol that is exported by one of the object files being linked.
|
|
|
3113 This has no effect for targets that do not encode the entry point into the
|
|
|
3114 resulting file. If not specified, the entry point is assumed to be address 0
|
|
|
3115 which is probably not what you want. The default link scripts for targets
|
|
|
3116 that support this directive automatically starts at the beginning of the
|
|
|
3117 first section (usually "init" or "code") that is emitted in the binary.</P
|
|
|
3118 ></DD
|
|
|
3119 ><DT
|
|
|
3120 >pad <CODE
|
|
|
3121 CLASS="PARAMETER"
|
|
|
3122 >size</CODE
|
|
|
3123 ></DT
|
|
|
3124 ><DD
|
|
|
3125 ><P
|
|
|
3126 >This will cause the output file to be padded with NUL bytes to be exactly
|
|
|
3127 <CODE
|
|
|
3128 CLASS="PARAMETER"
|
|
|
3129 >size</CODE
|
|
|
3130 > bytes in length. This only makes sense for a raw target.</P
|
|
|
3131 ></DD
|
|
|
3132 ></DL
|
|
|
3133 ></DIV
|
|
|
3134 ></DIV
|
|
|
3135 ><DIV
|
|
|
3136 CLASS="SECTION"
|
|
|
3137 ><HR><H2
|
|
|
3138 CLASS="SECTION"
|
|
|
3139 ><A
|
|
|
3140 NAME="AEN991"
|
|
|
3141 >4.4. Format Specific Linking Notes</A
|
|
|
3142 ></H2
|
|
|
3143 ><P
|
|
|
3144 >Some formats require special information to be able to generate actual
|
|
|
3145 binaries. If the specific format you are interested in is not listed in
|
|
|
3146 this section, then there is nothing special you need to know about to create
|
|
|
3147 a final binary.</P
|
|
|
3148 ><DIV
|
|
|
3149 CLASS="SECTION"
|
|
|
3150 ><HR><H3
|
|
|
3151 CLASS="SECTION"
|
|
|
3152 ><A
|
|
|
3153 NAME="AEN994"
|
|
|
3154 >4.4.1. OS9 Modules</A
|
|
|
3155 ></H3
|
|
|
3156 ><P
|
|
|
3157 >OS9 modules need to embed several items into the module header. These
|
|
|
3158 items are the type of module, the langauge of the module, the module
|
|
|
3159 attributes, the module revision number, the data size (bss), and the
|
|
|
3160 execution offset. These are all either calculated or default to reasonable
|
|
|
3161 values.</P
|
|
|
3162 ><P
|
|
|
3163 >The data size is calcuated as the sum of all sections named "bss" or
|
|
|
3164 ".bss" in all object files that are linked together.</P
|
|
|
3165 ><P
|
|
|
3166 >The execution offset is calculated from the address of the special
|
|
|
3167 symbol "__start" which must be an exported (external) symbol in one of the
|
|
|
3168 objects to be linked.</P
|
|
|
3169 ><P
|
|
|
3170 >The type defaults to "Prgrm" or "Program module". The language
|
|
|
3171 defaults to "Objct" or "6809 object code". Attributes default to enabling
|
|
|
3172 the re-entrant flag. And finally, the revision defaults to zero.</P
|
|
|
3173 ><P
|
|
|
3174 >The embedded module name is the output filename. If the output
|
|
|
3175 filename includes more than just the filename, this will probably not be
|
|
|
3176 what you want.</P
|
|
|
3177 ><P
|
|
|
3178 >The type, language, attributes, revision, and module name can all be
|
|
|
3179 overridden by providing a special section in exactly one of the object files
|
|
|
3180 to be linked. This section is called "__os9" (note the two underscores).
|
|
|
3181 To override the type, language, attributes, or revision values, define a
|
|
|
3182 non-exported symbol in this section called "type", "lang", "attr", or "rev"
|
|
|
3183 respectively. Any other symbols defined are ignored. To override the
|
|
|
3184 module name, include as the only actual code in the section a NUL terminated
|
|
|
3185 string (the FCN directive is useful for this). If there is no code in the
|
|
|
3186 section or it beings with a NUL, the default name will be used. Any of the
|
|
|
3187 preceeding that are not defined in the special section will retain their
|
|
|
3188 default values.</P
|
|
|
3189 ><P
|
|
|
3190 >The built-in link script for OS9 modules will place the following
|
|
|
3191 sections, in order, in the module: "code", ".text", "data", ".data". It
|
|
|
3192 will merge all sections with the name "bss" or ".bss" into the "data"
|
|
|
3193 section. All other section names are ignored. What this means is that you
|
|
|
3194 must define your data variables in the a section called "bss" or ".bss" even
|
|
|
3195 though you will be refencing them all as offsets from U. This does have the
|
|
|
3196 unpleasant side effect that all BSS references will end up being 16 bit
|
|
|
3197 offsets because the assembler cannot know what the offset will be once the
|
|
|
3198 linker is finished its work. Thus, if the tightest possible code is
|
|
|
3199 required, having LWASM directly output the module is a better choice.</P
|
|
|
3200 ><P
|
|
|
3201 >While the built-in link script is probably sufficient for most
|
|
|
3202 purposes, you can provide your own script. If you provide a custom link
|
|
|
3203 script, you must start your code and data sections at location 000D to
|
|
|
3204 accommodate the module header. Otherwise, you will have an incorrect
|
|
|
3205 location for the execution offset. You must use the ENTRY directive in the
|
|
|
3206 script to define the entry point for the module.</P
|
|
|
3207 ><P
|
|
|
3208 >It should also be obvious from the above that you cannot mix the bss
|
|
|
3209 (rmb) definitions with the module code when linking separately. Those
|
|
|
3210 familiar with typical module creation will probably find this an unpleasant
|
|
|
3211 difference but it is unavoidable.</P
|
|
|
3212 ><P
|
|
|
3213 >It should also be noted that direct page references should also be
|
|
|
3214 avoided because you cannot know ahead of time whether the linker is going to
|
|
|
3215 end up putting a particular variable in the first 256 bytes of the module's
|
|
|
3216 data space. If, however, you know for certain you will have less than 256
|
|
|
3217 bytes of defined data space across all of the object files that will be
|
|
|
3218 linked, you can instead use forced DP addressing for your data addresses
|
|
|
3219 instead of the ,u notation. When linking with 3rd party libraries, this
|
|
|
3220 practice should be avoided. Also, when creating libraries, always use the
|
|
|
3221 offset from U technique.</P
|
|
|
3222 ></DIV
|
|
|
3223 ></DIV
|
|
|
3224 ></DIV
|
|
|
3225 ><DIV
|
|
|
3226 CLASS="CHAPTER"
|
|
|
3227 ><HR><H1
|
|
|
3228 ><A
|
|
|
3229 NAME="AEN1006"
|
|
|
3230 ></A
|
|
|
3231 >Chapter 5. Libraries and LWAR</H1
|
|
|
3232 ><P
|
|
|
3233 >LWTOOLS also includes a tool for managing libraries. These are analogous to
|
|
|
3234 the static libraries created with the "ar" tool on POSIX systems. Each library
|
|
|
3235 file contains one or more object files. The linker will treat the object
|
|
|
3236 files within a library as though they had been specified individually on
|
|
|
3237 the command line except when resolving external references. External references
|
|
|
3238 are looked up first within the object files within the library and then, if
|
|
|
3239 not found, the usual lookup based on the order the files are specified on
|
|
|
3240 the command line occurs.</P
|
|
|
3241 ><P
|
|
|
3242 >The tool for creating these libary files is called LWAR.</P
|
|
|
3243 ><DIV
|
|
|
3244 CLASS="SECTION"
|
|
|
3245 ><HR><H2
|
|
|
3246 CLASS="SECTION"
|
|
|
3247 ><A
|
|
|
3248 NAME="AEN1010"
|
|
|
3249 >5.1. Command Line Options</A
|
|
|
3250 ></H2
|
|
|
3251 ><P
|
|
|
3252 >The binary for LWAR is called "lwar". Note that the binary is in lower
|
|
|
3253 case. The options lwar understands are listed below. For archive manipulation
|
|
|
3254 options, the first non-option argument is the name of the archive. All other
|
|
|
3255 non-option arguments are the names of files to operate on.</P
|
|
|
3256 ><P
|
|
|
3257 ></P
|
|
|
3258 ><DIV
|
|
|
3259 CLASS="VARIABLELIST"
|
|
|
3260 ><DL
|
|
|
3261 ><DT
|
|
|
3262 ><CODE
|
|
|
3263 CLASS="OPTION"
|
|
|
3264 >--add</CODE
|
|
|
3265 >, <CODE
|
|
|
3266 CLASS="OPTION"
|
|
|
3267 >-a</CODE
|
|
|
3268 ></DT
|
|
|
3269 ><DD
|
|
|
3270 ><P
|
|
|
3271 >This option specifies that an archive is going to have files added to it.
|
|
|
3272 If the archive does not already exist, it is created. New files are added
|
|
|
3273 to the end of the archive.</P
|
|
|
3274 ></DD
|
|
|
3275 ><DT
|
|
|
3276 ><CODE
|
|
|
3277 CLASS="OPTION"
|
|
|
3278 >--create</CODE
|
|
|
3279 >, <CODE
|
|
|
3280 CLASS="OPTION"
|
|
|
3281 >-c</CODE
|
|
|
3282 ></DT
|
|
|
3283 ><DD
|
|
|
3284 ><P
|
|
|
3285 >This option specifies that an archive is going to be created and have files
|
|
|
3286 added to it. If the archive already exists, it is truncated.</P
|
|
|
3287 ></DD
|
|
|
3288 ><DT
|
|
|
3289 ><CODE
|
|
|
3290 CLASS="OPTION"
|
|
|
3291 >--merge</CODE
|
|
|
3292 >, <CODE
|
|
|
3293 CLASS="OPTION"
|
|
|
3294 >-m</CODE
|
|
|
3295 ></DT
|
|
|
3296 ><DD
|
|
|
3297 ><P
|
|
|
3298 >If specified, any files specified to be added to an archive will be checked
|
|
|
3299 to see if they are archives themselves. If so, their constituent members are
|
|
|
3300 added to the archive. This is useful for avoiding archives containing archives.</P
|
|
|
3301 ></DD
|
|
|
3302 ><DT
|
|
|
3303 ><CODE
|
|
|
3304 CLASS="OPTION"
|
|
|
3305 >--list</CODE
|
|
|
3306 >, <CODE
|
|
|
3307 CLASS="OPTION"
|
|
|
3308 >-l</CODE
|
|
|
3309 ></DT
|
|
|
3310 ><DD
|
|
|
3311 ><P
|
|
|
3312 >This will display a list of the files contained in the archive.</P
|
|
|
3313 ></DD
|
|
|
3314 ><DT
|
|
|
3315 ><CODE
|
|
|
3316 CLASS="OPTION"
|
|
|
3317 >--debug</CODE
|
|
|
3318 >, <CODE
|
|
|
3319 CLASS="OPTION"
|
|
|
3320 >-d</CODE
|
|
|
3321 ></DT
|
|
|
3322 ><DD
|
|
|
3323 ><P
|
|
|
3324 >This option increases the debugging level. It is only useful for LWTOOLS
|
|
|
3325 developers.</P
|
|
|
3326 ></DD
|
|
|
3327 ><DT
|
|
|
3328 ><CODE
|
|
|
3329 CLASS="OPTION"
|
|
|
3330 >--help</CODE
|
|
|
3331 >, <CODE
|
|
|
3332 CLASS="OPTION"
|
|
|
3333 >-?</CODE
|
|
|
3334 ></DT
|
|
|
3335 ><DD
|
|
|
3336 ><P
|
|
|
3337 >This provides a listing of command line options and a brief description
|
|
|
3338 of each.</P
|
|
|
3339 ></DD
|
|
|
3340 ><DT
|
|
|
3341 ><CODE
|
|
|
3342 CLASS="OPTION"
|
|
|
3343 >--usage</CODE
|
|
|
3344 ></DT
|
|
|
3345 ><DD
|
|
|
3346 ><P
|
|
|
3347 >This will display a usage summary
|
|
|
3348 of each command line option.</P
|
|
|
3349 ></DD
|
|
|
3350 ><DT
|
|
|
3351 ><CODE
|
|
|
3352 CLASS="OPTION"
|
|
|
3353 >--version</CODE
|
|
|
3354 >, <CODE
|
|
|
3355 CLASS="OPTION"
|
|
|
3356 >-V</CODE
|
|
|
3357 ></DT
|
|
|
3358 ><DD
|
|
|
3359 ><P
|
|
|
3360 >This will display the version of LWLINK.
|
|
|
3361 of each.</P
|
|
|
3362 ></DD
|
|
|
3363 ></DL
|
|
|
3364 ></DIV
|
|
|
3365 ></DIV
|
|
|
3366 ></DIV
|
|
|
3367 ><DIV
|
|
|
3368 CLASS="CHAPTER"
|
|
|
3369 ><HR><H1
|
|
|
3370 ><A
|
|
|
3371 NAME="OBJCHAP"
|
|
|
3372 ></A
|
|
|
3373 >Chapter 6. Object Files</H1
|
|
|
3374 ><P
|
|
|
3375 >LWTOOLS uses a proprietary object file format. It is proprietary in the sense
|
|
|
3376 that it is specific to LWTOOLS, not that it is a hidden format. It would be
|
|
|
3377 hard to keep it hidden in an open source tool chain anyway. This chapter
|
|
|
3378 documents the object file format.</P
|
|
|
3379 ><P
|
|
|
3380 >An object file consists of a series of sections each of which contains a
|
|
|
3381 list of exported symbols, a list of incomplete references, and a list of
|
|
|
3382 "local" symbols which may be used in calculating incomplete references. Each
|
|
|
3383 section will obviously also contain the object code.</P
|
|
|
3384 ><P
|
|
|
3385 >Exported symbols must be completely resolved to an address within the
|
|
|
3386 section it is exported from. That is, an exported symbol must be a constant
|
|
|
3387 rather than defined in terms of other symbols.</P
|
|
|
3388 ><P
|
|
|
3389 >Each object file starts with a magic number and version number. The magic
|
|
|
3390 number is the string "LWOBJ16" for this 16 bit object file format. The only
|
|
|
3391 defined version number is currently 0. Thus, the first 8 bytes of the object
|
|
|
3392 file are <FONT
|
|
|
3393 COLOR="RED"
|
|
|
3394 >4C574F424A313600</FONT
|
|
|
3395 ></P
|
|
|
3396 ><P
|
|
|
3397 >Each section has the following items in order:</P
|
|
|
3398 ><P
|
|
|
3399 ></P
|
|
|
3400 ><UL
|
|
|
3401 ><LI
|
|
|
3402 ><P
|
|
|
3403 >section name</P
|
|
|
3404 ></LI
|
|
|
3405 ><LI
|
|
|
3406 ><P
|
|
|
3407 >flags</P
|
|
|
3408 ></LI
|
|
|
3409 ><LI
|
|
|
3410 ><P
|
|
|
3411 >list of local symbols (and addresses within the section)</P
|
|
|
3412 ></LI
|
|
|
3413 ><LI
|
|
|
3414 ><P
|
|
|
3415 >list of exported symbols (and addresses within the section)</P
|
|
|
3416 ></LI
|
|
|
3417 ><LI
|
|
|
3418 ><P
|
|
|
3419 >list of incomplete references along with the expressions to calculate them</P
|
|
|
3420 ></LI
|
|
|
3421 ><LI
|
|
|
3422 ><P
|
|
|
3423 >the actual object code (for non-BSS sections)</P
|
|
|
3424 ></LI
|
|
|
3425 ></UL
|
|
|
3426 ><P
|
|
|
3427 >The section starts with the name of the section with a NUL termination
|
|
|
3428 followed by a series of flag bytes terminated by NUL. There are only two
|
|
|
3429 flag bytes defined. A NUL (0) indicates no more flags and a value of 1
|
|
|
3430 indicates the section is a BSS section. For a BSS section, no actual
|
|
|
3431 code is included in the object file.</P
|
|
|
3432 ><P
|
|
|
3433 >Either a NULL section name or end of file indicate the presence of no more
|
|
|
3434 sections.</P
|
|
|
3435 ><P
|
|
|
3436 >Each entry in the exported and local symbols table consists of the symbol
|
|
|
3437 (NUL terminated) followed by two bytes which contain the value in big endian
|
|
|
3438 order. The end of a symbol table is indicated by a NULL symbol name.</P
|
|
|
3439 ><P
|
|
|
3440 >Each entry in the incomplete references table consists of an expression
|
|
|
3441 followed by a 16 bit offset where the reference goes. Expressions are
|
|
|
3442 defined as a series of terms up to an "end of expression" term. Each term
|
|
|
3443 consists of a single byte which identifies the type of term (see below)
|
|
|
3444 followed by any data required by the term. Then end of the list is flagged
|
|
|
3445 by a NULL expression (only an end of expression term).</P
|
|
|
3446 ><DIV
|
|
|
3447 CLASS="TABLE"
|
|
|
3448 ><A
|
|
|
3449 NAME="AEN1093"
|
|
|
3450 ></A
|
|
|
3451 ><P
|
|
|
3452 ><B
|
|
|
3453 >Table 6-1. Object File Term Types</B
|
|
|
3454 ></P
|
|
|
3455 ><TABLE
|
|
|
3456 BORDER="1"
|
|
|
3457 FRAME="border"
|
|
|
3458 CLASS="CALSTABLE"
|
|
|
3459 ><COL><COL><THEAD
|
|
|
3460 ><TR
|
|
|
3461 ><TH
|
|
|
3462 >TERMTYPE</TH
|
|
|
3463 ><TH
|
|
|
3464 >Meaning</TH
|
|
|
3465 ></TR
|
|
|
3466 ></THEAD
|
|
|
3467 ><TBODY
|
|
|
3468 ><TR
|
|
|
3469 ><TD
|
|
|
3470 >00</TD
|
|
|
3471 ><TD
|
|
|
3472 >end of expression</TD
|
|
|
3473 ></TR
|
|
|
3474 ><TR
|
|
|
3475 ><TD
|
|
|
3476 >01</TD
|
|
|
3477 ><TD
|
|
|
3478 >integer (16 bit in big endian order follows)</TD
|
|
|
3479 ></TR
|
|
|
3480 ><TR
|
|
|
3481 ><TD
|
|
|
3482 >02</TD
|
|
|
3483 ><TD
|
|
|
3484 > external symbol reference (NUL terminated symbol name follows)</TD
|
|
|
3485 ></TR
|
|
|
3486 ><TR
|
|
|
3487 ><TD
|
|
|
3488 >03</TD
|
|
|
3489 ><TD
|
|
|
3490 >local symbol reference (NUL terminated symbol name follows)</TD
|
|
|
3491 ></TR
|
|
|
3492 ><TR
|
|
|
3493 ><TD
|
|
|
3494 >04</TD
|
|
|
3495 ><TD
|
|
|
3496 >operator (1 byte operator number)</TD
|
|
|
3497 ></TR
|
|
|
3498 ><TR
|
|
|
3499 ><TD
|
|
|
3500 >05</TD
|
|
|
3501 ><TD
|
|
|
3502 >section base address reference</TD
|
|
|
3503 ></TR
|
|
|
3504 ><TR
|
|
|
3505 ><TD
|
|
|
3506 >FF</TD
|
|
|
3507 ><TD
|
|
|
3508 >This term will set flags for the expression. Each one of these terms will set a single flag. All of them should be specified first in an expression. If they are not, the behaviour is undefined. The byte following is the flag. Flag 01 indicates an 8 bit relocation. Flag 02 indicates a zero-width relocation (see the EXTDEP pseudo op in LWASM).</TD
|
|
|
3509 ></TR
|
|
|
3510 ></TBODY
|
|
|
3511 ></TABLE
|
|
|
3512 ></DIV
|
|
|
3513 ><P
|
|
|
3514 >External references are resolved using other object files while local
|
|
|
3515 references are resolved using the local symbol table(s) from this file. This
|
|
|
3516 allows local symbols that are not exported to have the same names as
|
|
|
3517 exported symbols or external references.</P
|
|
|
3518 ><DIV
|
|
|
3519 CLASS="TABLE"
|
|
|
3520 ><A
|
|
|
3521 NAME="AEN1123"
|
|
|
3522 ></A
|
|
|
3523 ><P
|
|
|
3524 ><B
|
|
|
3525 >Table 6-2. Object File Operator Numbers</B
|
|
|
3526 ></P
|
|
|
3527 ><TABLE
|
|
|
3528 BORDER="1"
|
|
|
3529 FRAME="border"
|
|
|
3530 CLASS="CALSTABLE"
|
|
|
3531 ><COL><COL><THEAD
|
|
|
3532 ><TR
|
|
|
3533 ><TH
|
|
|
3534 >Number</TH
|
|
|
3535 ><TH
|
|
|
3536 >Operator</TH
|
|
|
3537 ></TR
|
|
|
3538 ></THEAD
|
|
|
3539 ><TBODY
|
|
|
3540 ><TR
|
|
|
3541 ><TD
|
|
|
3542 >01</TD
|
|
|
3543 ><TD
|
|
|
3544 >addition (+)</TD
|
|
|
3545 ></TR
|
|
|
3546 ><TR
|
|
|
3547 ><TD
|
|
|
3548 >02</TD
|
|
|
3549 ><TD
|
|
|
3550 >subtraction (-)</TD
|
|
|
3551 ></TR
|
|
|
3552 ><TR
|
|
|
3553 ><TD
|
|
|
3554 >03</TD
|
|
|
3555 ><TD
|
|
|
3556 >multiplication (*)</TD
|
|
|
3557 ></TR
|
|
|
3558 ><TR
|
|
|
3559 ><TD
|
|
|
3560 >04</TD
|
|
|
3561 ><TD
|
|
|
3562 >division (/)</TD
|
|
|
3563 ></TR
|
|
|
3564 ><TR
|
|
|
3565 ><TD
|
|
|
3566 >05</TD
|
|
|
3567 ><TD
|
|
|
3568 >modulus (%)</TD
|
|
|
3569 ></TR
|
|
|
3570 ><TR
|
|
|
3571 ><TD
|
|
|
3572 >06</TD
|
|
|
3573 ><TD
|
|
|
3574 >integer division (\) (same as division)</TD
|
|
|
3575 ></TR
|
|
|
3576 ><TR
|
|
|
3577 ><TD
|
|
|
3578 >07</TD
|
|
|
3579 ><TD
|
|
|
3580 >bitwise and</TD
|
|
|
3581 ></TR
|
|
|
3582 ><TR
|
|
|
3583 ><TD
|
|
|
3584 >08</TD
|
|
|
3585 ><TD
|
|
|
3586 >bitwise or</TD
|
|
|
3587 ></TR
|
|
|
3588 ><TR
|
|
|
3589 ><TD
|
|
|
3590 >09</TD
|
|
|
3591 ><TD
|
|
|
3592 >bitwise xor</TD
|
|
|
3593 ></TR
|
|
|
3594 ><TR
|
|
|
3595 ><TD
|
|
|
3596 >0A</TD
|
|
|
3597 ><TD
|
|
|
3598 >boolean and</TD
|
|
|
3599 ></TR
|
|
|
3600 ><TR
|
|
|
3601 ><TD
|
|
|
3602 >0B</TD
|
|
|
3603 ><TD
|
|
|
3604 >boolean or</TD
|
|
|
3605 ></TR
|
|
|
3606 ><TR
|
|
|
3607 ><TD
|
|
|
3608 >0C</TD
|
|
|
3609 ><TD
|
|
|
3610 >unary negation, 2's complement (-)</TD
|
|
|
3611 ></TR
|
|
|
3612 ><TR
|
|
|
3613 ><TD
|
|
|
3614 >0D</TD
|
|
|
3615 ><TD
|
|
|
3616 >unary 1's complement (^)</TD
|
|
|
3617 ></TR
|
|
|
3618 ></TBODY
|
|
|
3619 ></TABLE
|
|
|
3620 ></DIV
|
|
|
3621 ><P
|
|
|
3622 >An expression is represented in a postfix manner with both operands for
|
|
|
3623 binary operators preceding the operator and the single operand for unary
|
|
|
3624 operators preceding the operator.</P
|
|
|
3625 ></DIV
|
|
|
3626 ></DIV
|
|
|
3627 ></BODY
|
|
|
3628 ></HTML
|
|
|
3629 > |
