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