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