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