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