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