Mercurial > hg > index.cgi

comparison docs/manual/manual.html @ 324:b30091890d62

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation of the new hex output formats. Thanks to text contributed by Tom LeMense, the manual now includes documentation of the hex formats he contributed. This also includes some updated text on the ORG directive. Only minor editorial changes vary the text from Tom's original.
author William Astle <lost@l-w.ca>
date Tue, 04 Mar 2014 23:10:13 -0700
parents c4853a54b4a1
children 507f442dc71e
comparison
equal deleted inserted replaced
323:ba9a0434b115 324:b30091890d62
30 CLASS="AUTHOR" 30 CLASS="AUTHOR"
31 ><A 31 ><A
32 NAME="AEN4" 32 NAME="AEN4"
33 ></A 33 ></A
34 >William Astle</H3 34 >William Astle</H3
35 ><H3
36 CLASS="AUTHOR"
37 ><A
38 NAME="AEN7"
39 ></A
40 >LWTools Contributors </H3
35 ><P 41 ><P
36 CLASS="COPYRIGHT" 42 CLASS="COPYRIGHT"
37 >Copyright &copy; 2009-2013 William Astle</P 43 >Copyright &copy; 2009-2014 William Astle and LWTools contributors</P
38 ><HR></DIV 44 ><HR></DIV
39 ><DIV 45 ><DIV
40 CLASS="TOC" 46 CLASS="TOC"
41 ><DL 47 ><DL
42 ><DT 48 ><DT
43 ><B 49 ><B
44 >Table of Contents</B 50 >Table of Contents</B
45 ></DT 51 ></DT
46 ><DT 52 ><DT
47 >1. <A 53 >1. <A
48 HREF="#AEN10" 54 HREF="#AEN13"
49 >Introduction</A 55 >Introduction</A
50 ></DT 56 ></DT
51 ><DD 57 ><DD
52 ><DL 58 ><DL
53 ><DT 59 ><DT
54 >1.1. <A 60 >1.1. <A
55 HREF="#AEN13" 61 HREF="#AEN16"
56 >History</A 62 >History</A
57 ></DT 63 ></DT
58 ></DL 64 ></DL
59 ></DD 65 ></DD
60 ><DT 66 ><DT
61 >2. <A 67 >2. <A
62 HREF="#AEN18" 68 HREF="#AEN21"
63 >Output Formats</A 69 >Output Formats</A
64 ></DT 70 ></DT
65 ><DD 71 ><DD
66 ><DL 72 ><DL
67 ><DT 73 ><DT
68 >2.1. <A 74 >2.1. <A
69 HREF="#AEN21" 75 HREF="#AEN24"
70 >Raw Binaries</A 76 >Raw Binaries</A
71 ></DT 77 ></DT
72 ><DT 78 ><DT
73 >2.2. <A 79 >2.2. <A
74 HREF="#AEN24" 80 HREF="#AEN27"
75 >DECB Binaries</A 81 >DECB Binaries</A
76 ></DT 82 ></DT
77 ><DT 83 ><DT
78 >2.3. <A 84 >2.3. <A
79 HREF="#AEN29" 85 HREF="#AEN32"
86 >ASCII Hexadecimal</A
87 ></DT
88 ><DT
89 >2.4. <A
90 HREF="#AEN36"
91 >Motorola S-Record</A
92 ></DT
93 ><DT
94 >2.5. <A
95 HREF="#AEN41"
96 >Intel Hex</A
97 ></DT
98 ><DT
99 >2.6. <A
100 HREF="#AEN46"
80 >OS9 Modules</A 101 >OS9 Modules</A
81 ></DT 102 ></DT
82 ><DT 103 ><DT
83 >2.4. <A 104 >2.7. <A
84 HREF="#AEN37" 105 HREF="#AEN54"
85 >Object Files</A 106 >Object Files</A
86 ></DT 107 ></DT
87 ></DL 108 ></DL
88 ></DD 109 ></DD
89 ><DT 110 ><DT
90 >3. <A 111 >3. <A
91 HREF="#AEN45" 112 HREF="#AEN62"
92 >LWASM</A 113 >LWASM</A
93 ></DT 114 ></DT
94 ><DD 115 ><DD
95 ><DL 116 ><DL
96 ><DT 117 ><DT
97 >3.1. <A 118 >3.1. <A
98 HREF="#AEN48" 119 HREF="#AEN65"
99 >Command Line Options</A 120 >Command Line Options</A
100 ></DT 121 ></DT
101 ><DT 122 ><DT
102 >3.2. <A 123 >3.2. <A
103 HREF="#AEN170" 124 HREF="#AEN190"
104 >Dialects</A 125 >Dialects</A
105 ></DT 126 ></DT
106 ><DT 127 ><DT
107 >3.3. <A 128 >3.3. <A
108 HREF="#AEN177" 129 HREF="#AEN197"
109 >Source Format</A 130 >Source Format</A
110 ></DT 131 ></DT
111 ><DT 132 ><DT
112 >3.4. <A 133 >3.4. <A
113 HREF="#AEN187" 134 HREF="#AEN207"
114 >Symbols</A 135 >Symbols</A
115 ></DT 136 ></DT
116 ><DT 137 ><DT
117 >3.5. <A 138 >3.5. <A
118 HREF="#AEN192" 139 HREF="#AEN212"
119 >Numbers and Expressions</A 140 >Numbers and Expressions</A
120 ></DT 141 ></DT
121 ><DT 142 ><DT
122 >3.6. <A 143 >3.6. <A
123 HREF="#AEN200" 144 HREF="#AEN220"
124 >Assembler Directives</A 145 >Assembler Directives</A
125 ></DT 146 ></DT
126 ><DD 147 ><DD
127 ><DL 148 ><DL
128 ><DT 149 ><DT
129 >3.6.1. <A 150 >3.6.1. <A
130 HREF="#AEN203" 151 HREF="#AEN223"
131 >Data Directives</A 152 >Data Directives</A
132 ></DT 153 ></DT
133 ><DT 154 ><DT
134 >3.6.2. <A 155 >3.6.2. <A
135 HREF="#AEN314" 156 HREF="#AEN334"
136 >Address Definition</A 157 >Address Definition</A
137 ></DT 158 ></DT
138 ><DT 159 ><DT
139 >3.6.3. <A 160 >3.6.3. <A
140 HREF="#AEN361" 161 HREF="#AEN381"
141 >Conditional Assembly</A 162 >Conditional Assembly</A
142 ></DT 163 ></DT
143 ><DT 164 ><DT
144 >3.6.4. <A 165 >3.6.4. <A
145 HREF="#AEN426" 166 HREF="#AEN446"
146 >OS9 Target Directives</A 167 >OS9 Target Directives</A
147 ></DT 168 ></DT
148 ><DT 169 ><DT
149 >3.6.5. <A 170 >3.6.5. <A
150 HREF="#AEN451" 171 HREF="#AEN471"
151 >Miscelaneous Directives</A 172 >Miscelaneous Directives</A
152 ></DT 173 ></DT
153 ></DL 174 ></DL
154 ></DD 175 ></DD
155 ><DT 176 ><DT
156 >3.7. <A 177 >3.7. <A
157 HREF="#AEN491" 178 HREF="#AEN511"
158 >Macros</A 179 >Macros</A
159 ></DT 180 ></DT
160 ><DT 181 ><DT
161 >3.8. <A 182 >3.8. <A
162 HREF="#AEN514" 183 HREF="#AEN534"
163 >Structures</A 184 >Structures</A
164 ></DT 185 ></DT
165 ><DT 186 ><DT
166 >3.9. <A 187 >3.9. <A
167 HREF="#AEN535" 188 HREF="#AEN555"
168 >Object Files and Sections</A 189 >Object Files and Sections</A
169 ></DT 190 ></DT
170 ><DT 191 ><DT
171 >3.10. <A 192 >3.10. <A
172 HREF="#AEN599" 193 HREF="#AEN619"
173 >Assembler Modes and Pragmas</A 194 >Assembler Modes and Pragmas</A
174 ></DT 195 ></DT
175 ></DL 196 ></DL
176 ></DD 197 ></DD
177 ><DT 198 ><DT
178 >4. <A 199 >4. <A
179 HREF="#AEN693" 200 HREF="#AEN713"
180 >LWLINK</A 201 >LWLINK</A
181 ></DT 202 ></DT
182 ><DD 203 ><DD
183 ><DL 204 ><DL
184 ><DT 205 ><DT
185 >4.1. <A 206 >4.1. <A
186 HREF="#AEN696" 207 HREF="#AEN716"
187 >Command Line Options</A 208 >Command Line Options</A
188 ></DT 209 ></DT
189 ><DT 210 ><DT
190 >4.2. <A 211 >4.2. <A
191 HREF="#AEN793" 212 HREF="#AEN813"
192 >Linker Operation</A 213 >Linker Operation</A
193 ></DT 214 ></DT
194 ><DT 215 ><DT
195 >4.3. <A 216 >4.3. <A
196 HREF="#AEN807" 217 HREF="#AEN827"
197 >Linking Scripts</A 218 >Linking Scripts</A
198 ></DT 219 ></DT
199 ><DT 220 ><DT
200 >4.4. <A 221 >4.4. <A
201 HREF="#AEN873" 222 HREF="#AEN893"
202 >Format Specific Linking Notes</A 223 >Format Specific Linking Notes</A
203 ></DT 224 ></DT
204 ><DD 225 ><DD
205 ><DL 226 ><DL
206 ><DT 227 ><DT
207 >4.4.1. <A 228 >4.4.1. <A
208 HREF="#AEN876" 229 HREF="#AEN896"
209 >OS9 Modules</A 230 >OS9 Modules</A
210 ></DT 231 ></DT
211 ></DL 232 ></DL
212 ></DD 233 ></DD
213 ></DL 234 ></DL
214 ></DD 235 ></DD
215 ><DT 236 ><DT
216 >5. <A 237 >5. <A
217 HREF="#AEN888" 238 HREF="#AEN908"
218 >Libraries and LWAR</A 239 >Libraries and LWAR</A
219 ></DT 240 ></DT
220 ><DD 241 ><DD
221 ><DL 242 ><DL
222 ><DT 243 ><DT
223 >5.1. <A 244 >5.1. <A
224 HREF="#AEN892" 245 HREF="#AEN912"
225 >Command Line Options</A 246 >Command Line Options</A
226 ></DT 247 ></DT
227 ></DL 248 ></DL
228 ></DD 249 ></DD
229 ><DT 250 ><DT
241 ><B 262 ><B
242 >List of Tables</B 263 >List of Tables</B
243 ></DT 264 ></DT
244 ><DT 265 ><DT
245 >6-1. <A 266 >6-1. <A
246 HREF="#AEN975" 267 HREF="#AEN995"
247 >Object File Term Types</A 268 >Object File Term Types</A
248 ></DT 269 ></DT
249 ><DT 270 ><DT
250 >6-2. <A 271 >6-2. <A
251 HREF="#AEN1005" 272 HREF="#AEN1025"
252 >Object File Operator Numbers</A 273 >Object File Operator Numbers</A
253 ></DT 274 ></DT
254 ></DL 275 ></DL
255 ></DIV 276 ></DIV
256 ><DIV 277 ><DIV
257 CLASS="CHAPTER" 278 CLASS="CHAPTER"
258 ><HR><H1 279 ><HR><H1
259 ><A 280 ><A
260 NAME="AEN10" 281 NAME="AEN13"
261 ></A 282 ></A
262 >Chapter 1. Introduction</H1 283 >Chapter 1. Introduction</H1
263 ><P 284 ><P
264 >The LW tool chain provides utilities for building binaries for MC6809 and 285 >The LW tool chain provides utilities for building binaries for MC6809 and
265 HD6309 CPUs. The tool chain includes a cross-assembler and a cross-linker 286 HD6309 CPUs. The tool chain includes a cross-assembler and a cross-linker
267 ><DIV 288 ><DIV
268 CLASS="SECTION" 289 CLASS="SECTION"
269 ><HR><H2 290 ><HR><H2
270 CLASS="SECTION" 291 CLASS="SECTION"
271 ><A 292 ><A
272 NAME="AEN13" 293 NAME="AEN16"
273 >1.1. History</A 294 >1.1. History</A
274 ></H2 295 ></H2
275 ><P 296 ><P
276 >For a long time, I have had an interest in creating an operating system for 297 >For a long time, I have had an interest in creating an operating system for
277 the Coco3. I finally started working on that project around the beginning of 298 the Coco3. I finally started working on that project around the beginning of
298 ></DIV 319 ></DIV
299 ><DIV 320 ><DIV
300 CLASS="CHAPTER" 321 CLASS="CHAPTER"
301 ><HR><H1 322 ><HR><H1
302 ><A 323 ><A
303 NAME="AEN18" 324 NAME="AEN21"
304 ></A 325 ></A
305 >Chapter 2. Output Formats</H1 326 >Chapter 2. Output Formats</H1
306 ><P 327 ><P
307 >The LW tool chain supports multiple output formats. Each format has its 328 >The LW tool chain supports multiple output formats. Each format has its
308 advantages and disadvantages. Each format is described below.</P 329 advantages and disadvantages. Each format is described below.</P
309 ><DIV 330 ><DIV
310 CLASS="SECTION" 331 CLASS="SECTION"
311 ><HR><H2 332 ><HR><H2
312 CLASS="SECTION" 333 CLASS="SECTION"
313 ><A 334 ><A
314 NAME="AEN21" 335 NAME="AEN24"
315 >2.1. Raw Binaries</A 336 >2.1. Raw Binaries</A
316 ></H2 337 ></H2
317 ><P 338 ><P
318 >A raw binary is simply a string of bytes. There are no headers or other 339 >A raw binary is simply a string of bytes. There are no headers or other
319 niceties. Both LWLINK and LWASM support generating raw binaries. ORG directives 340 niceties. Both LWLINK and LWASM support generating raw binaries. ORG directives
323 ><DIV 344 ><DIV
324 CLASS="SECTION" 345 CLASS="SECTION"
325 ><HR><H2 346 ><HR><H2
326 CLASS="SECTION" 347 CLASS="SECTION"
327 ><A 348 ><A
328 NAME="AEN24" 349 NAME="AEN27"
329 >2.2. DECB Binaries</A 350 >2.2. DECB Binaries</A
330 ></H2 351 ></H2
331 ><P 352 ><P
332 >A DECB binary is compatible with the LOADM command in Disk Extended 353 >A DECB binary is compatible with the LOADM command in Disk Extended
333 Color Basic on the CoCo. They are also compatible with CLOADM from Extended 354 Color Basic on the CoCo. They are also compatible with CLOADM from Extended
348 ><DIV 369 ><DIV
349 CLASS="SECTION" 370 CLASS="SECTION"
350 ><HR><H2 371 ><HR><H2
351 CLASS="SECTION" 372 CLASS="SECTION"
352 ><A 373 ><A
353 NAME="AEN29" 374 NAME="AEN32"
354 >2.3. OS9 Modules</A 375 >2.3. ASCII Hexadecimal</A
376 ></H2
377 ><P
378 >This human-readable ASCII hexadecimal format consists of CR+LF terminated
379 lines of ASCII text. Each line has the following structure: a zero-padded
380 four-digit ASCII hex address, a colon separator, and one or more zero-padded
381 two-digit hex values separated by commas. ASCII Hexadecimal format favors
382 paragraph-aligned addresses (i.e. a least significant address nybble value
383 of zero). During output, the number of hex values on each line are adjusted
384 to align the address of the next line on a paragraph boundary. The sequence
385 of addresses in the ASCII Hexadecimal file directly follows that of the source
386 file; multiple ORG directives in the source code may result in out-of-sequence
387 addresses in the ASCII Hexadecimal output.</P
388 ><P
389 >LWASM can output this format since version 4.10.</P
390 ></DIV
391 ><DIV
392 CLASS="SECTION"
393 ><HR><H2
394 CLASS="SECTION"
395 ><A
396 NAME="AEN36"
397 >2.4. Motorola S-Record</A
398 ></H2
399 ><P
400 >This ASCII format consists of a series of CR+LF terminated "records" of ASCII
401 text. Each record has the following structure: a start-of-record character
402 "S", an ASCII record type digit (0-9), a two-digit ASCII hex byte count, a
403 four-digit ASCII hex address, an optional sequence of two-digit ASCII hex data
404 values, and a two-digit ASCII hex checksum. The LW tool chain issues only S0,
405 S1, S5 and S9 record types. S1 records are limited to maximum of 16 data bytes
406 in length, and paragraph alignment of addresses is favored. The address
407 sequence of the S-Records directly follows that of the source file; multiple
408 ORG directives in the source code may result in out-of-sequence addresses in
409 the S-Record output. </P
410 ><P
411 >Motorola S-Record format is a standard ASCII format accepted by most memory
412 device programming equipment. It is particularly useful when the assembled
413 code output is destined to reside within an EPROM or Flash memory device,
414 for example.</P
415 ><P
416 >LWASM can output this format since version 4.10.</P
417 ></DIV
418 ><DIV
419 CLASS="SECTION"
420 ><HR><H2
421 CLASS="SECTION"
422 ><A
423 NAME="AEN41"
424 >2.5. Intel Hex</A
425 ></H2
426 ><P
427 >This ASCII format consists of a series of CR+LF terminated "records" of ASCII
428 text. Each record has the following structure: a start-of-record character
429 ":", a two-digit ASCII hex byte count, a four-digit ASCII hex address, a two-
430 digit ASCII hex record type, an optional sequence of two-digit ASCII hex data
431 values, and a two-digit ASCII hex checksum. The LW tool chain issues only 00,
432 and 01 Intel Hex record types. Data records are limited to maximum of 16
433 data bytes in length, and paragraph alignment of addresses is favored. The
434 address sequence of the Intel hex records directly follows that of the source
435 file; multiple ORG directives in the source code may result in out-of-sequence
436 addresses in the Intel Hex output. </P
437 ><P
438 >Intel Hex format is the other standard ASCII format accepted by most memory
439 device programming equipment, it and the Motorola S-Record format are used for
440 similar purposes.</P
441 ><P
442 >LWASM can output this format since version 4.10.</P
443 ></DIV
444 ><DIV
445 CLASS="SECTION"
446 ><HR><H2
447 CLASS="SECTION"
448 ><A
449 NAME="AEN46"
450 >2.6. OS9 Modules</A
355 ></H2 451 ></H2
356 ><P 452 ><P
357 >&#13;Since version 2.5, LWASM is able to generate OS9 modules. The syntax is 453 >&#13;Since version 2.5, LWASM is able to generate OS9 modules. The syntax is
358 basically the same as for other assemblers. A module starts with the MOD 454 basically the same as for other assemblers. A module starts with the MOD
359 directive and ends with the EMOD directive. The OS9 directive is provided 455 directive and ends with the EMOD directive. The OS9 directive is provided
384 ><DIV 480 ><DIV
385 CLASS="SECTION" 481 CLASS="SECTION"
386 ><HR><H2 482 ><HR><H2
387 CLASS="SECTION" 483 CLASS="SECTION"
388 ><A 484 ><A
389 NAME="AEN37" 485 NAME="AEN54"
390 >2.4. Object Files</A 486 >2.7. Object Files</A
391 ></H2 487 ></H2
392 ><P 488 ><P
393 >LWASM supports generating a proprietary object file format which is 489 >LWASM supports generating a proprietary object file format which is
394 described in <A 490 described in <A
395 HREF="#OBJCHAP" 491 HREF="#OBJCHAP"
421 ></DIV 517 ></DIV
422 ><DIV 518 ><DIV
423 CLASS="CHAPTER" 519 CLASS="CHAPTER"
424 ><HR><H1 520 ><HR><H1
425 ><A 521 ><A
426 NAME="AEN45" 522 NAME="AEN62"
427 ></A 523 ></A
428 >Chapter 3. LWASM</H1 524 >Chapter 3. LWASM</H1
429 ><P 525 ><P
430 >The LWTOOLS assembler is called LWASM. This chapter documents the various 526 >The LWTOOLS assembler is called LWASM. This chapter documents the various
431 features of the assembler. It is not, however, a tutorial on 6x09 assembly 527 features of the assembler. It is not, however, a tutorial on 6x09 assembly
433 ><DIV 529 ><DIV
434 CLASS="SECTION" 530 CLASS="SECTION"
435 ><HR><H2 531 ><HR><H2
436 CLASS="SECTION" 532 CLASS="SECTION"
437 ><A 533 ><A
438 NAME="AEN48" 534 NAME="AEN65"
439 >3.1. Command Line Options</A 535 >3.1. Command Line Options</A
440 ></H2 536 ></H2
441 ><P 537 ><P
442 >The binary for LWASM is called "lwasm". Note that the binary is in lower 538 >The binary for LWASM is called "lwasm". Note that the binary is in lower
443 case. lwasm takes the following command line arguments.</P 539 case. lwasm takes the following command line arguments.</P
512 >decb</CODE 608 >decb</CODE
513 > for the DECB LOADM format, 609 > for the DECB LOADM format,
514 <CODE 610 <CODE
515 CLASS="OPTION" 611 CLASS="OPTION"
516 >os9</CODE 612 >os9</CODE
517 > for creating OS9 modules, and <CODE 613 > for creating OS9 modules, <CODE
518 CLASS="OPTION" 614 CLASS="OPTION"
519 >raw</CODE 615 >raw</CODE
520 > for 616 > for
521 a raw binary.</P 617 a raw binary, <CODE
618 CLASS="OPTION"
619 >hex</CODE
620 > for ASCII hexadecminal format,
621 <CODE
622 CLASS="OPTION"
623 >srec</CODE
624 > for Motorola S-Record format, and <CODE
625 CLASS="OPTION"
626 >ihex</CODE
627 >
628 for Intel Hex format.</P
522 ></DD 629 ></DD
523 ><DT 630 ><DT
524 ><CODE 631 ><CODE
525 CLASS="OPTION" 632 CLASS="OPTION"
526 >--list[=file]</CODE 633 >--list[=file]</CODE
688 ><DIV 795 ><DIV
689 CLASS="SECTION" 796 CLASS="SECTION"
690 ><HR><H2 797 ><HR><H2
691 CLASS="SECTION" 798 CLASS="SECTION"
692 ><A 799 ><A
693 NAME="AEN170" 800 NAME="AEN190"
694 >3.2. Dialects</A 801 >3.2. Dialects</A
695 ></H2 802 ></H2
696 ><P 803 ><P
697 >LWASM supports all documented MC6809 instructions as defined by Motorola. 804 >LWASM supports all documented MC6809 instructions as defined by Motorola.
698 It also supports all known HD6309 instructions. While there is general 805 It also supports all known HD6309 instructions. While there is general
722 ><DIV 829 ><DIV
723 CLASS="SECTION" 830 CLASS="SECTION"
724 ><HR><H2 831 ><HR><H2
725 CLASS="SECTION" 832 CLASS="SECTION"
726 ><A 833 ><A
727 NAME="AEN177" 834 NAME="AEN197"
728 >3.3. Source Format</A 835 >3.3. Source Format</A
729 ></H2 836 ></H2
730 ><P 837 ><P
731 >LWASM accepts plain text files in a relatively free form. It can handle 838 >LWASM accepts plain text files in a relatively free form. It can handle
732 lines terminated with CR, LF, CRLF, or LFCR which means it should be able 839 lines terminated with CR, LF, CRLF, or LFCR which means it should be able
768 ><DIV 875 ><DIV
769 CLASS="SECTION" 876 CLASS="SECTION"
770 ><HR><H2 877 ><HR><H2
771 CLASS="SECTION" 878 CLASS="SECTION"
772 ><A 879 ><A
773 NAME="AEN187" 880 NAME="AEN207"
774 >3.4. Symbols</A 881 >3.4. Symbols</A
775 ></H2 882 ></H2
776 ><P 883 ><P
777 >Symbols have no length restriction. They may contain letters, numbers, dots, 884 >Symbols have no length restriction. They may contain letters, numbers, dots,
778 dollar signs, and underscores. They must start with a letter, dot, or 885 dollar signs, and underscores. They must start with a letter, dot, or
796 ><DIV 903 ><DIV
797 CLASS="SECTION" 904 CLASS="SECTION"
798 ><HR><H2 905 ><HR><H2
799 CLASS="SECTION" 906 CLASS="SECTION"
800 ><A 907 ><A
801 NAME="AEN192" 908 NAME="AEN212"
802 >3.5. Numbers and Expressions</A 909 >3.5. Numbers and Expressions</A
803 ></H2 910 ></H2
804 ><P 911 ><P
805 >&#13;Numbers can be expressed in binary, octal, decimal, or hexadecimal. Binary 912 >&#13;Numbers can be expressed in binary, octal, decimal, or hexadecimal. Binary
806 numbers may be prefixed with a "%" symbol or suffixed with a "b" or "B". 913 numbers may be prefixed with a "%" symbol or suffixed with a "b" or "B".
841 ><DIV 948 ><DIV
842 CLASS="SECTION" 949 CLASS="SECTION"
843 ><HR><H2 950 ><HR><H2
844 CLASS="SECTION" 951 CLASS="SECTION"
845 ><A 952 ><A
846 NAME="AEN200" 953 NAME="AEN220"
847 >3.6. Assembler Directives</A 954 >3.6. Assembler Directives</A
848 ></H2 955 ></H2
849 ><P 956 ><P
850 >Various directives can be used to control the behaviour of the 957 >Various directives can be used to control the behaviour of the
851 assembler or to include non-code/data in the resulting output. Those directives 958 assembler or to include non-code/data in the resulting output. Those directives
854 ><DIV 961 ><DIV
855 CLASS="SECTION" 962 CLASS="SECTION"
856 ><HR><H3 963 ><HR><H3
857 CLASS="SECTION" 964 CLASS="SECTION"
858 ><A 965 ><A
859 NAME="AEN203" 966 NAME="AEN223"
860 >3.6.1. Data Directives</A 967 >3.6.1. Data Directives</A
861 ></H3 968 ></H3
862 ><P 969 ><P
863 ></P 970 ></P
864 ><DIV 971 ><DIV
1088 ><DIV 1195 ><DIV
1089 CLASS="SECTION" 1196 CLASS="SECTION"
1090 ><HR><H3 1197 ><HR><H3
1091 CLASS="SECTION" 1198 CLASS="SECTION"
1092 ><A 1199 ><A
1093 NAME="AEN314" 1200 NAME="AEN334"
1094 >3.6.2. Address Definition</A 1201 >3.6.2. Address Definition</A
1095 ></H3 1202 ></H3
1096 ><P 1203 ><P
1097 >The directives in this section all control the addresses of symbols 1204 >The directives in this section all control the addresses of symbols
1098 or the assembly process itself.</P 1205 or the assembly process itself.</P
1108 ></DT 1215 ></DT
1109 ><DD 1216 ><DD
1110 ><P 1217 ><P
1111 >Set the assembly address. The address must be fully resolvable on the 1218 >Set the assembly address. The address must be fully resolvable on the
1112 first pass so no external or forward references are permitted. ORG is not 1219 first pass so no external or forward references are permitted. ORG is not
1113 permitted within sections when outputting to object files. For the DECB 1220 permitted within sections when outputting to object files. For target formats
1114 target, each ORG directive after which output is generated will cause 1221 that include address information (decb, hex, srec, and ihex), an ORG
1115 a new preamble to be output. ORG is only used to determine the addresses 1222 directive will re-start the address sequence within the output. When using
1116 of symbols when the raw target is used.</P 1223 the raw target format, ORG is used only to determine the addresses of symbols.</P
1117 ></DD 1224 ></DD
1118 ><DT 1225 ><DT
1119 ><CODE 1226 ><CODE
1120 CLASS="PARAMETER" 1227 CLASS="PARAMETER"
1121 >sym</CODE 1228 >sym</CODE
1224 ><DIV 1331 ><DIV
1225 CLASS="SECTION" 1332 CLASS="SECTION"
1226 ><HR><H3 1333 ><HR><H3
1227 CLASS="SECTION" 1334 CLASS="SECTION"
1228 ><A 1335 ><A
1229 NAME="AEN361" 1336 NAME="AEN381"
1230 >3.6.3. Conditional Assembly</A 1337 >3.6.3. Conditional Assembly</A
1231 ></H3 1338 ></H3
1232 ><P 1339 ><P
1233 >Portions of the source code can be excluded or included based on conditions 1340 >Portions of the source code can be excluded or included based on conditions
1234 known at assembly time. Conditionals can be nested arbitrarily deeply. The 1341 known at assembly time. Conditionals can be nested arbitrarily deeply. The
1387 ><DIV 1494 ><DIV
1388 CLASS="SECTION" 1495 CLASS="SECTION"
1389 ><HR><H3 1496 ><HR><H3
1390 CLASS="SECTION" 1497 CLASS="SECTION"
1391 ><A 1498 ><A
1392 NAME="AEN426" 1499 NAME="AEN446"
1393 >3.6.4. OS9 Target Directives</A 1500 >3.6.4. OS9 Target Directives</A
1394 ></H3 1501 ></H3
1395 ><P 1502 ><P
1396 >This section includes directives that apply solely to the OS9 1503 >This section includes directives that apply solely to the OS9
1397 target.</P 1504 target.</P
1454 ><DIV 1561 ><DIV
1455 CLASS="SECTION" 1562 CLASS="SECTION"
1456 ><HR><H3 1563 ><HR><H3
1457 CLASS="SECTION" 1564 CLASS="SECTION"
1458 ><A 1565 ><A
1459 NAME="AEN451" 1566 NAME="AEN471"
1460 >3.6.5. Miscelaneous Directives</A 1567 >3.6.5. Miscelaneous Directives</A
1461 ></H3 1568 ></H3
1462 ><P 1569 ><P
1463 >This section includes directives that do not fit into the other 1570 >This section includes directives that do not fit into the other
1464 categories.</P 1571 categories.</P
1568 ><DIV 1675 ><DIV
1569 CLASS="SECTION" 1676 CLASS="SECTION"
1570 ><HR><H2 1677 ><HR><H2
1571 CLASS="SECTION" 1678 CLASS="SECTION"
1572 ><A 1679 ><A
1573 NAME="AEN491" 1680 NAME="AEN511"
1574 >3.7. Macros</A 1681 >3.7. Macros</A
1575 ></H2 1682 ></H2
1576 ><P 1683 ><P
1577 >LWASM is a macro assembler. A macro is simply a name that stands in for a 1684 >LWASM is a macro assembler. A macro is simply a name that stands in for a
1578 series of instructions. Once a macro is defined, it is used like any other 1685 series of instructions. Once a macro is defined, it is used like any other
1667 ><DIV 1774 ><DIV
1668 CLASS="SECTION" 1775 CLASS="SECTION"
1669 ><HR><H2 1776 ><HR><H2
1670 CLASS="SECTION" 1777 CLASS="SECTION"
1671 ><A 1778 ><A
1672 NAME="AEN514" 1779 NAME="AEN534"
1673 >3.8. Structures</A 1780 >3.8. Structures</A
1674 ></H2 1781 ></H2
1675 ><P 1782 ><P
1676 >&#13;Structures are used to group related data in a fixed structure. A structure 1783 >&#13;Structures are used to group related data in a fixed structure. A structure
1677 consists a number of fields, defined in sequential order and which take up 1784 consists a number of fields, defined in sequential order and which take up
1760 ><DIV 1867 ><DIV
1761 CLASS="SECTION" 1868 CLASS="SECTION"
1762 ><HR><H2 1869 ><HR><H2
1763 CLASS="SECTION" 1870 CLASS="SECTION"
1764 ><A 1871 ><A
1765 NAME="AEN535" 1872 NAME="AEN555"
1766 >3.9. Object Files and Sections</A 1873 >3.9. Object Files and Sections</A
1767 ></H2 1874 ></H2
1768 ><P 1875 ><P
1769 >The object file target is very useful for large project because it allows 1876 >The object file target is very useful for large project because it allows
1770 multiple files to be assembled independently and then linked into the final 1877 multiple files to be assembled independently and then linked into the final
1977 ><DIV 2084 ><DIV
1978 CLASS="SECTION" 2085 CLASS="SECTION"
1979 ><HR><H2 2086 ><HR><H2
1980 CLASS="SECTION" 2087 CLASS="SECTION"
1981 ><A 2088 ><A
1982 NAME="AEN599" 2089 NAME="AEN619"
1983 >3.10. Assembler Modes and Pragmas</A 2090 >3.10. Assembler Modes and Pragmas</A
1984 ></H2 2091 ></H2
1985 ><P 2092 ><P
1986 >There are a number of options that affect the way assembly is performed. 2093 >There are a number of options that affect the way assembly is performed.
1987 Some of these options can only be specified on the command line because 2094 Some of these options can only be specified on the command line because
2252 ></DIV 2359 ></DIV
2253 ><DIV 2360 ><DIV
2254 CLASS="CHAPTER" 2361 CLASS="CHAPTER"
2255 ><HR><H1 2362 ><HR><H1
2256 ><A 2363 ><A
2257 NAME="AEN693" 2364 NAME="AEN713"
2258 ></A 2365 ></A
2259 >Chapter 4. LWLINK</H1 2366 >Chapter 4. LWLINK</H1
2260 ><P 2367 ><P
2261 >The LWTOOLS linker is called LWLINK. This chapter documents the various features 2368 >The LWTOOLS linker is called LWLINK. This chapter documents the various features
2262 of the linker.</P 2369 of the linker.</P
2263 ><DIV 2370 ><DIV
2264 CLASS="SECTION" 2371 CLASS="SECTION"
2265 ><HR><H2 2372 ><HR><H2
2266 CLASS="SECTION" 2373 CLASS="SECTION"
2267 ><A 2374 ><A
2268 NAME="AEN696" 2375 NAME="AEN716"
2269 >4.1. Command Line Options</A 2376 >4.1. Command Line Options</A
2270 ></H2 2377 ></H2
2271 ><P 2378 ><P
2272 >The binary for LWLINK is called "lwlink". Note that the binary is in lower 2379 >The binary for LWLINK is called "lwlink". Note that the binary is in lower
2273 case. lwlink takes the following command line arguments.</P 2380 case. lwlink takes the following command line arguments.</P
2460 ><DIV 2567 ><DIV
2461 CLASS="SECTION" 2568 CLASS="SECTION"
2462 ><HR><H2 2569 ><HR><H2
2463 CLASS="SECTION" 2570 CLASS="SECTION"
2464 ><A 2571 ><A
2465 NAME="AEN793" 2572 NAME="AEN813"
2466 >4.2. Linker Operation</A 2573 >4.2. Linker Operation</A
2467 ></H2 2574 ></H2
2468 ><P 2575 ><P
2469 >&#13;LWLINK takes one or more files in supported input formats and links them 2576 >&#13;LWLINK takes one or more files in supported input formats and links them
2470 into a single binary. Currently supported formats are the LWTOOLS object 2577 into a single binary. Currently supported formats are the LWTOOLS object
2516 ><DIV 2623 ><DIV
2517 CLASS="SECTION" 2624 CLASS="SECTION"
2518 ><HR><H2 2625 ><HR><H2
2519 CLASS="SECTION" 2626 CLASS="SECTION"
2520 ><A 2627 ><A
2521 NAME="AEN807" 2628 NAME="AEN827"
2522 >4.3. Linking Scripts</A 2629 >4.3. Linking Scripts</A
2523 ></H2 2630 ></H2
2524 ><P 2631 ><P
2525 >A linker script is used to instruct the linker about how to assemble the 2632 >A linker script is used to instruct the linker about how to assemble the
2526 various sections into a completed binary. It consists of a series of 2633 various sections into a completed binary. It consists of a series of
2720 ><DIV 2827 ><DIV
2721 CLASS="SECTION" 2828 CLASS="SECTION"
2722 ><HR><H2 2829 ><HR><H2
2723 CLASS="SECTION" 2830 CLASS="SECTION"
2724 ><A 2831 ><A
2725 NAME="AEN873" 2832 NAME="AEN893"
2726 >4.4. Format Specific Linking Notes</A 2833 >4.4. Format Specific Linking Notes</A
2727 ></H2 2834 ></H2
2728 ><P 2835 ><P
2729 >Some formats require special information to be able to generate actual 2836 >Some formats require special information to be able to generate actual
2730 binaries. If the specific format you are interested in is not listed in 2837 binaries. If the specific format you are interested in is not listed in
2733 ><DIV 2840 ><DIV
2734 CLASS="SECTION" 2841 CLASS="SECTION"
2735 ><HR><H3 2842 ><HR><H3
2736 CLASS="SECTION" 2843 CLASS="SECTION"
2737 ><A 2844 ><A
2738 NAME="AEN876" 2845 NAME="AEN896"
2739 >4.4.1. OS9 Modules</A 2846 >4.4.1. OS9 Modules</A
2740 ></H3 2847 ></H3
2741 ><P 2848 ><P
2742 >OS9 modules need to embed several items into the module header. These 2849 >OS9 modules need to embed several items into the module header. These
2743 items are the type of module, the langauge of the module, the module 2850 items are the type of module, the langauge of the module, the module
2809 ></DIV 2916 ></DIV
2810 ><DIV 2917 ><DIV
2811 CLASS="CHAPTER" 2918 CLASS="CHAPTER"
2812 ><HR><H1 2919 ><HR><H1
2813 ><A 2920 ><A
2814 NAME="AEN888" 2921 NAME="AEN908"
2815 ></A 2922 ></A
2816 >Chapter 5. Libraries and LWAR</H1 2923 >Chapter 5. Libraries and LWAR</H1
2817 ><P 2924 ><P
2818 >LWTOOLS also includes a tool for managing libraries. These are analogous to 2925 >LWTOOLS also includes a tool for managing libraries. These are analogous to
2819 the static libraries created with the "ar" tool on POSIX systems. Each library 2926 the static libraries created with the "ar" tool on POSIX systems. Each library
2828 ><DIV 2935 ><DIV
2829 CLASS="SECTION" 2936 CLASS="SECTION"
2830 ><HR><H2 2937 ><HR><H2
2831 CLASS="SECTION" 2938 CLASS="SECTION"
2832 ><A 2939 ><A
2833 NAME="AEN892" 2940 NAME="AEN912"
2834 >5.1. Command Line Options</A 2941 >5.1. Command Line Options</A
2835 ></H2 2942 ></H2
2836 ><P 2943 ><P
2837 >The binary for LWAR is called "lwar". Note that the binary is in lower 2944 >The binary for LWAR is called "lwar". Note that the binary is in lower
2838 case. The options lwar understands are listed below. For archive manipulation 2945 case. The options lwar understands are listed below. For archive manipulation
3029 followed by any data required by the term. Then end of the list is flagged 3136 followed by any data required by the term. Then end of the list is flagged
3030 by a NULL expression (only an end of expression term).</P 3137 by a NULL expression (only an end of expression term).</P
3031 ><DIV 3138 ><DIV
3032 CLASS="TABLE" 3139 CLASS="TABLE"
3033 ><A 3140 ><A
3034 NAME="AEN975" 3141 NAME="AEN995"
3035 ></A 3142 ></A
3036 ><P 3143 ><P
3037 ><B 3144 ><B
3038 >Table 6-1. Object File Term Types</B 3145 >Table 6-1. Object File Term Types</B
3039 ></P 3146 ></P
3101 allows local symbols that are not exported to have the same names as 3208 allows local symbols that are not exported to have the same names as
3102 exported symbols or external references.</P 3209 exported symbols or external references.</P
3103 ><DIV 3210 ><DIV
3104 CLASS="TABLE" 3211 CLASS="TABLE"
3105 ><A 3212 ><A
3106 NAME="AEN1005" 3213 NAME="AEN1025"
3107 ></A 3214 ></A
3108 ><P 3215 ><P
3109 ><B 3216 ><B
3110 >Table 6-2. Object File Operator Numbers</B 3217 >Table 6-2. Object File Operator Numbers</B
3111 ></P 3218 ></P