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