Mercurial > hg-old > index.cgi
comparison doc/manual.docbook.sgml @ 145:afe30454382f
Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
| author | lost |
|---|---|
| date | Thu, 29 Jan 2009 06:13:00 +0000 |
| parents | f21a5593a661 |
| children | 6c0a30278982 |
comparison
equal
deleted
inserted
replaced
| 144:006d737756fd | 145:afe30454382f |
|---|---|
| 112 | 112 |
| 113 </section> | 113 </section> |
| 114 | 114 |
| 115 </chapter> | 115 </chapter> |
| 116 | 116 |
| 117 <chapter> | |
| 118 <title>LWASM</title> | |
| 119 <para> | |
| 120 The LWTOOLS assembler is called LWASM. This chapter documents the various | |
| 121 features of the assembler. It is not, however, a tutorial on 6x09 assembly | |
| 122 language programming. | |
| 123 </para> | |
| 124 | |
| 125 <section> | |
| 126 <title>Command Line Options</title> | |
| 127 <para> | |
| 128 The binary for LWASM is called "lwasm". Note that the binary is in lower | |
| 129 case. lwasm takes the following command line arguments. | |
| 130 </para> | |
| 131 | |
| 132 <variablelist> | |
| 133 <varlistentry> | |
| 134 <term><option>--decb</option></term> | |
| 135 <term><option>-b</option></term> | |
| 136 <listitem> | |
| 137 <para> | |
| 138 Select the DECB output format target. Equivalent to <option>--format=decb</option>. | |
| 139 </para> | |
| 140 </listitem> | |
| 141 </varlistentry> | |
| 142 | |
| 143 <varlistentry> | |
| 144 <term><option>--debug</option></term> | |
| 145 <term><option>-d</option></term> | |
| 146 <listitem> | |
| 147 <para> | |
| 148 Increase the debugging level. Only really useful to people hacking on the | |
| 149 LWASM source code itself. | |
| 150 </para> | |
| 151 </listitem> | |
| 152 </varlistentry> | |
| 153 | |
| 154 <varlistentry> | |
| 155 <term><option>--format=type</option></term> | |
| 156 <term><option>-f type</option></term> | |
| 157 <listitem> | |
| 158 <para> | |
| 159 Select the output format. Valid values are <option>obj</option> for the object | |
| 160 file target, <option>decb</option> for the DECB LOADM format, and <option>raw</option> | |
| 161 for a raw binary. | |
| 162 </para> | |
| 163 </listitem> | |
| 164 </varlistentry> | |
| 165 | |
| 166 | |
| 167 <varlistentry> | |
| 168 <term><option>--list[=file]</option></term> | |
| 169 <term><option>-l[file]</option></term> | |
| 170 <listitem> | |
| 171 <para> | |
| 172 Cause LWASM to generate a listing. If <option>file</option> is specified, | |
| 173 the listing will go to that file. Otherwise it will go to the standard output | |
| 174 stream. By default, no listing is generated. | |
| 175 </para> | |
| 176 </listitem> | |
| 177 </varlistentry> | |
| 178 | |
| 179 <varlistentry> | |
| 180 <term><option>--obj</option></term> | |
| 181 <listitem> | |
| 182 <para> | |
| 183 Select the proprietary object file format as the output target. | |
| 184 </para> | |
| 185 </listitem> | |
| 186 </varlistentry> | |
| 187 | |
| 188 <varlistentry> | |
| 189 <term><option>--pragma=pragma</option></term> | |
| 190 <term><option>-p pragma</option></term> | |
| 191 <listitem> | |
| 192 <para> | |
| 193 Specify assembler pragmas. Multiple pragmas are separated by commas. The | |
| 194 pragmas accepted are the same as for the PRAGMA assembler directive described | |
| 195 below. | |
| 196 </para> | |
| 197 </listitem> | |
| 198 </varlistentry> | |
| 199 | |
| 200 <varlistentry> | |
| 201 <term><option>--raw</option></term> | |
| 202 <term><option>-r</option></term> | |
| 203 <listitem> | |
| 204 <para> | |
| 205 Select raw binary as the output target. | |
| 206 </para> | |
| 207 </listitem> | |
| 208 </varlistentry> | |
| 209 | |
| 210 <varlistentry> | |
| 211 <term><option>--help</option></term> | |
| 212 <term><option>-?</option></term> | |
| 213 <listitem> | |
| 214 <para> | |
| 215 Present a help screen describing the command line options. | |
| 216 </para> | |
| 217 </listitem> | |
| 218 </varlistentry> | |
| 219 | |
| 220 <varlistentry> | |
| 221 <term><option>--usage</option></term> | |
| 222 <listitem> | |
| 223 <para> | |
| 224 Provide a summary of the command line options. | |
| 225 </para> | |
| 226 </listitem> | |
| 227 </varlistentry> | |
| 228 | |
| 229 <varlistentry> | |
| 230 <term><option>--version</option></term> | |
| 231 <term><option>-V</option></term> | |
| 232 <listitem> | |
| 233 <para> | |
| 234 Display the software version. | |
| 235 </para> | |
| 236 </listitem> | |
| 237 </varlistentry> | |
| 238 | |
| 239 </variablelist> | |
| 240 | |
| 241 </section> | |
| 242 | |
| 243 <section> | |
| 244 <title>Dialects</title> | |
| 245 <para> | |
| 246 LWASM supports all documented MC6809 instructions as defined by Motorola. | |
| 247 It also supports all known HD6309 instructions. There is some variation, | |
| 248 however, in the pneumonics used for the block transfer instructions. LWASM | |
| 249 uses TFM for all four of them as do several other assemblers. Others, such | |
| 250 as CCASM, use four separate opcodes for it (compare: copy+, copy-, implode, | |
| 251 and explode). There are advantages to both methods. However, it seems like | |
| 252 TFM has the most traction and thus, this is what LWASM supports. Support | |
| 253 for such variations may be added in the future. | |
| 254 </para> | |
| 255 | |
| 256 <para> | |
| 257 The standard addressing mode specifiers are supported. These are the | |
| 258 hash sign ("#") for immediate mode, the less than sign ("<") for forced | |
| 259 eight bit modes, and the greater than sign (">") for forced sixteen bit modes. | |
| 260 </para> | |
| 261 | |
| 262 </section> | |
| 263 | |
| 264 <section> | |
| 265 <title>Source Format</title> | |
| 266 | |
| 267 <para> | |
| 268 LWASM accepts plain text files in a relatively free form. It can handle | |
| 269 lines terminated with CR, LF, CRLF, or LFCR which means it should be able | |
| 270 to assemble files on any platform on which it compiles. | |
| 271 </para> | |
| 272 <para> | |
| 273 Each line may start with a symbol. If a symbol is present, there must not | |
| 274 be any whitespace preceding it. It is legal for a line to contain nothing | |
| 275 but a symbol.</para> | |
| 276 <para> | |
| 277 The op code is separated from the symbol by whitespace. If there is | |
| 278 no symbol, there must be at least one white space character preceding it. | |
| 279 If applicable, the operand follows separated by whitespace. Following the | |
| 280 opcode and operand is an optional comment. | |
| 281 </para> | |
| 282 <para> | |
| 283 A comment can also be introduced with a * or a ;. The comment character is | |
| 284 optional for end of statement comments. However, if a symbol is the only | |
| 285 thing present on the line other than the comment, the comment character is | |
| 286 mandatory to prevent the assembler from interpreting the comment as an opcode. | |
| 287 </para> | |
| 288 | |
| 289 <para> | |
| 290 The opcode is not treated case sensitively. Neither are register names in | |
| 291 the operand fields. Symbols, however, are case sensitive. | |
| 292 </para> | |
| 293 | |
| 294 <para> | |
| 295 LWASM does not support line numbers in the file. | |
| 296 </para> | |
| 297 | |
| 298 </section> | |
| 299 | |
| 300 <section> | |
| 301 <title>Symbols</title> | |
| 302 | |
| 303 <para> | |
| 304 Symbols have no length restriction. They may contain letters, numbers, dots, | |
| 305 dollar signs, and underscores. They must start with a letter, dot, or | |
| 306 underscore. | |
| 307 </para> | |
| 308 | |
| 309 <para> | |
| 310 LWASM also supports the concept of a local symbol. A local symbol is one | |
| 311 which contains either a "?" or a "@", which can appear anywhere in the symbol. | |
| 312 The scope of a local symbol is determined by a number of factors. First, | |
| 313 each included file gets its own local symbol scope. A blank line will also | |
| 314 be considered a local scope barrier. Macros each have their own local symbol | |
| 315 scope as well (which has a side effect that you cannot use a local symbol | |
| 316 as an argument to a macro). There are other factors as well. In general, | |
| 317 a local symbol is restricted to the block of code it is defined within. | |
| 318 </para> | |
| 319 | |
| 320 </section> | |
| 321 | |
| 322 <section> | |
| 323 <title>Numbers and Expressions</title> | |
| 324 <para> | |
| 325 Numbers can be expressed in binary, octal, decimal, or hexadecimal. | |
| 326 Binary numbers may be prefixed with a "%" symbol or suffixed with a | |
| 327 "b" or "B". Octal numbers may be prefixed with "@" or suffixed with | |
| 328 "Q", "q", "O", or "o". Hexadecimal numbers may be prefixed with "$" or | |
| 329 suffixed with "H". No prefix or suffix is required for decimal numbers but | |
| 330 they can be prefixed with "&" if desired. Any constant which begins with | |
| 331 a letter must be expressed with the correct prefix base identifier or be | |
| 332 prefixed with a 0. Thus hexadecimal FF would have to be written either 0FFH | |
| 333 or $FF. Numbers are not case sensitive. | |
| 334 </para> | |
| 335 | |
| 336 <para> A symbol may appear at any point where a number is acceptable. The | |
| 337 special symbol "*" can be used to represent the starting address of the | |
| 338 current source line within expressions. </para> | |
| 339 | |
| 340 <para>The ASCII value of a character can be included by prefixing it with a | |
| 341 single quote ('). The ASCII values of two characters can be included by | |
| 342 prefixing the characters with a quote (").</para> | |
| 343 | |
| 344 <para> | |
| 345 LWASM supports the following basic binary operators: +, -, *, /, and %. | |
| 346 These represent addition, subtraction, multiplication, division, and modulus. | |
| 347 It also supports unary negation and unary 1's complement (- and ^ respectively). | |
| 348 For completeness, a unary positive (+) is supported though it is a no-op. | |
| 349 </para> | |
| 350 | |
| 351 <para>Operator precedence follows the usual rules. multiplication, division, | |
| 352 and modulus take precedence over addition and subtraction. Unary operators | |
| 353 take precedence over binary operators. To force a specific order of evaluation, | |
| 354 parentheses can be used in the usual manner. | |
| 355 </para> | |
| 356 </section> | |
| 357 | |
| 358 <section> | |
| 359 <title>Assembler Directives</title> | |
| 360 <para> | |
| 361 Various directives can be used to control the behaviour of the | |
| 362 assembler or to include non-code/data in the resulting output. Those directives | |
| 363 that are not described in detail in other sections of this document are | |
| 364 described below. | |
| 365 </para> | |
| 366 | |
| 367 <section> | |
| 368 <title>Data Directives</title> | |
| 369 <variablelist> | |
| 370 <varlistentry><term>FCB <parameter>expr[,...]</parameter></term> | |
| 371 <listitem> | |
| 372 <para>Include one or more constant bytes (separated by commas) in the output.</para> | |
| 373 </listitem> | |
| 374 </varlistentry> | |
| 375 | |
| 376 <varlistentry><term>FDB <parameter>expr[,...]</parameter></term> | |
| 377 <listitem> | |
| 378 <para>Include one or more words (separated by commas) in the output.</para> | |
| 379 </listitem> | |
| 380 </varlistentry> | |
| 381 | |
| 382 <varlistentry><term>FQB <parameter>expr[,...]</parameter></term> | |
| 383 <listitem> | |
| 384 <para>Include one or more double words (separated by commas) in the output.</para> | |
| 385 </listitem> | |
| 386 </varlistentry> | |
| 387 | |
| 388 <varlistentry><term>FCC <parameter>string</parameter></term> | |
| 389 <listitem> | |
| 390 <para> | |
| 391 Include a string of text in the output. The first character of the operand | |
| 392 is the delimiter which must appear as the last character and cannot appear | |
| 393 within the string. The string is included with no modifications> | |
| 394 </para> | |
| 395 </listitem> | |
| 396 </varlistentry> | |
| 397 | |
| 398 <varlistentry><term>FCN <parameter>string</parameter></term> | |
| 399 <listitem> | |
| 400 <para> | |
| 401 Include a NUL terminated string of text in the output. The first character of | |
| 402 the operand is the delimiter which must appear as the last character and | |
| 403 cannot appear within the string. A NUL byte is automatically appended to | |
| 404 the string. | |
| 405 </para> | |
| 406 </listitem> | |
| 407 </varlistentry> | |
| 408 | |
| 409 <varlistentry><term>FCS <parameter>string</parameter></term> | |
| 410 <listitem> | |
| 411 <para> | |
| 412 Include a string of text in the output with bit 7 of the final byte set. The | |
| 413 first character of the operand is the delimiter which must appear as the last | |
| 414 character and cannot appear within the string. | |
| 415 </para> | |
| 416 </listitem> | |
| 417 </varlistentry> | |
| 418 | |
| 419 <varlistentry><term>ZMB <parameter>expr</parameter></term> | |
| 420 <listitem> | |
| 421 <para> | |
| 422 Include a number of NUL bytes in the output. The number must be fully resolvable | |
| 423 during pass 1 of assembly so no forward or external references are permitted. | |
| 424 </para> | |
| 425 </listitem> | |
| 426 </varlistentry> | |
| 427 | |
| 428 <varlistentry><term>ZMD <parameter>expr</parameter></term> | |
| 429 <listitem> | |
| 430 <para> | |
| 431 Include a number of zero words in the output. The number must be fully | |
| 432 resolvable during pass 1 of assembly so no forward or external references are | |
| 433 permitted. | |
| 434 </para> | |
| 435 </listitem> | |
| 436 </varlistentry> | |
| 437 | |
| 438 <varlistentry><term>ZMQ <parameter>expr<parameter></term> | |
| 439 <listitem> | |
| 440 <para> | |
| 441 Include a number of zero double-words in the output. The number must be fully | |
| 442 resolvable during pass 1 of assembly so no forward or external references are | |
| 443 permitted. | |
| 444 </para> | |
| 445 </listitem> | |
| 446 </varlistentry> | |
| 447 | |
| 448 <varlistentry><term>RMB <parameter>expr</parameter></term> | |
| 449 <listitem> | |
| 450 <para> | |
| 451 Reserve a number of bytes in the output. The number must be fully resolvable | |
| 452 during pass 1 of assembly so no forward or external references are permitted. | |
| 453 The value of the bytes is undefined. | |
| 454 </para> | |
| 455 </listitem> | |
| 456 </varlistentry> | |
| 457 | |
| 458 <varlistentry><term>RMD <parameter>expr</parameter></term> | |
| 459 <listitem> | |
| 460 <para> | |
| 461 Reserve a number of words in the output. The number must be fully | |
| 462 resolvable during pass 1 of assembly so no forward or external references are | |
| 463 permitted. The value of the words is undefined. | |
| 464 </para> | |
| 465 </listitem> | |
| 466 </varlistentry> | |
| 467 | |
| 468 <varlistentry><term>RMQ <parameter>expr</parameter></term> | |
| 469 <listitem> | |
| 470 <para> | |
| 471 Reserve a number of double-words in the output. The number must be fully | |
| 472 resolvable during pass 1 of assembly so no forward or external references are | |
| 473 permitted. The value of the double-words is undefined. | |
| 474 </para> | |
| 475 </listitem> | |
| 476 </varlistentry> | |
| 477 </variablelist> | |
| 478 | |
| 479 </section> | |
| 480 | |
| 481 <section> | |
| 482 <title>Address Definition</title> | |
| 483 <para>The directives in this section all control the addresses of symbols | |
| 484 or the assembly process itself.</para> | |
| 485 | |
| 486 <variablelist> | |
| 487 <varlistentry><term>ORG <parameter>expr</parameter></term> | |
| 488 <listitem> | |
| 489 <para>Set the assembly address. The address must be fully resolvable on the | |
| 490 first pass so no external or forward references are permitted. ORG is not | |
| 491 permitted within sections when outputting to object files. For the DECB | |
| 492 target, each ORG directive after which output is generated will cause | |
| 493 a new preamble to be output. ORG is only used to determine the addresses | |
| 494 of symbols when the raw target is used. | |
| 495 </para> | |
| 496 </listitem> | |
| 497 </varlistentry> | |
| 498 | |
| 499 <varlistentry> | |
| 500 <term><parameter>sym</parameter> EQU <parameter>expr</parameter></term> | |
| 501 <term><parameter>sym</parameter> = <parameter>expr</parameter></term> | |
| 502 <listitem> | |
| 503 <para>Define the value of <parameter>sym</parameter> to be <parameter>expr</parameter>. | |
| 504 </listitem> | |
| 505 </varlistentry> | |
| 506 | |
| 507 <varlistentry> | |
| 508 <term><parameter>sym</parameter> SET <parameter>expr</parameter></term> | |
| 509 <listitem> | |
| 510 <para>Define the value of <parameter>sym</parameter> to be <parameter>expr</parameter>. | |
| 511 Unlike EQU, SET permits symbols to be defined multiple times as long as SET | |
| 512 is used for all instances. Use of the symbol before the first SET statement | |
| 513 that sets its value is undefined.</para> | |
| 514 </listitem> | |
| 515 </varlistentry> | |
| 516 | |
| 517 <varlistentry> | |
| 518 <term>SETDP <parameter>expr</parameter></term> | |
| 519 <listitem> | |
| 520 <para>Inform the assembler that it can assume the DP register contains | |
| 521 <parameter>expr</parameter>. This directive is only advice to the assembler | |
| 522 to determine whether an address is in the direct page and has no effect | |
| 523 on the contents of the DP register. The value must be fully resolved during | |
| 524 the first assembly pass because it affects the sizes of subsequent instructions. | |
| 525 </para> | |
| 526 <para>This directive has no effect in the object file target. | |
| 527 </para> | |
| 528 </listitem> | |
| 529 </varlistentry> | |
| 530 | |
| 531 <varlistentry> | |
| 532 <term>ALIGN <parameter>expr</parameter></term> | |
| 533 <listitem> | |
| 534 <para>Force the current assembly address to be a multiple of <parameter>expr</parameter>. | |
| 535 A series of NUL bytes is output to force the alignment, if required. The | |
| 536 alignment value must be fully resolved on the first pass because it affects | |
| 537 the addresses of subsquent instructions.</para> | |
| 538 <para>This directive is not suitable for inclusion in the middle of actual | |
| 539 code. It is intended to appear where the bytes output will not be executed. | |
| 540 </para> | |
| 541 </listitem> | |
| 542 </varlistentry> | |
| 543 | |
| 544 </variablelist> | |
| 545 | |
| 546 </section> | |
| 547 | |
| 548 <section> | |
| 549 <title>Conditional Assembly</title> | |
| 550 <para> | |
| 551 Portions of the source code can be excluded or included based on conditions | |
| 552 known at assembly time. Conditionals can be nested arbitrarily deeply. The | |
| 553 directives associated with conditional assembly are described in this section. | |
| 554 </para> | |
| 555 <para>All conditionals must be fully bracketed. That is, every conditional | |
| 556 statement must eventually be followed by an ENDC at the same level of nesting. | |
| 557 </para> | |
| 558 <para>Conditional expressions are only evaluated on the first assembly pass. | |
| 559 It is not possible to game the assembly process by having a conditional | |
| 560 change its value between assembly passes. Thus there is not and never will | |
| 561 be any equivalent of IFP1 or IFP2 as provided by other assemblers.</para> | |
| 562 | |
| 563 <variablelist> | |
| 564 <varlistentry> | |
| 565 <term>IFEQ <parameter>expr</parameter></term> | |
| 566 <listitem> | |
| 567 <para>If <parameter>expr</parameter> evaluates to zero, the conditional | |
| 568 will be considered true. | |
| 569 </para> | |
| 570 </listitem> | |
| 571 </varlistentry> | |
| 572 | |
| 573 <varlistentry> | |
| 574 <term>IFNE <parameter>expr</parameter></term> | |
| 575 <term>IF <parameter>expr</parameter></term> | |
| 576 <listitem> | |
| 577 <para>If <parameter>expr</parameter> evaluates to a non-zero value, the conditional | |
| 578 will be considered true. | |
| 579 </para> | |
| 580 </listitem> | |
| 581 </varlistentry> | |
| 582 | |
| 583 <varlistentry> | |
| 584 <term>IFGT <parameter>expr</parameter></term> | |
| 585 <listitem> | |
| 586 <para>If <parameter>expr</parameter> evaluates to a value greater than zero, the conditional | |
| 587 will be considered true. | |
| 588 </para> | |
| 589 </listitem> | |
| 590 </varlistentry> | |
| 591 | |
| 592 <varlistentry> | |
| 593 <term>IFGE <parameter>expr</parameter></term> | |
| 594 <listitem> | |
| 595 <para>If <parameter>expr</parameter> evaluates to a value greater than or equal to zero, the conditional | |
| 596 will be considered true. | |
| 597 </para> | |
| 598 </listitem> | |
| 599 </varlistentry> | |
| 600 | |
| 601 <varlistentry> | |
| 602 <term>IFLT <parameter>expr</parameter></term> | |
| 603 <listitem> | |
| 604 <para>If <parameter>expr</parameter> evaluates to a value less than zero, the conditional | |
| 605 will be considered true. | |
| 606 </para> | |
| 607 </listitem> | |
| 608 </varlistentry> | |
| 609 | |
| 610 <varlistentry> | |
| 611 <term>IFLE <parameter>expr</parameter></term> | |
| 612 <listitem> | |
| 613 <para>If <parameter>expr</parameter> evaluates to a value less than or equal to zero , the conditional | |
| 614 will be considered true. | |
| 615 </para> | |
| 616 </listitem> | |
| 617 </varlistentry> | |
| 618 | |
| 619 <varlistentry> | |
| 620 <term>IFDEF <parameter>sym</parameter></term> | |
| 621 <listitem> | |
| 622 <para>If <parameter>sym</parameter> is defined at this point in the assembly | |
| 623 process, the conditional | |
| 624 will be considered true. | |
| 625 </para> | |
| 626 </listitem> | |
| 627 </varlistentry> | |
| 628 | |
| 629 <varlistentry> | |
| 630 <term>IFNDEF <parameter>sym</parameter></term> | |
| 631 <listitem> | |
| 632 <para>If <parameter>sym</parameter> is not defined at this point in the assembly | |
| 633 process, the conditional | |
| 634 will be considered true. | |
| 635 </para> | |
| 636 </listitem> | |
| 637 </varlistentry> | |
| 638 | |
| 639 <varlistentry> | |
| 640 <term>ELSE</term> | |
| 641 <listitem> | |
| 642 <para> | |
| 643 If the preceding conditional at the same level of nesting was false, the | |
| 644 statements following will be assembled. If the preceding conditional at | |
| 645 the same level was true, the statements following will not be assembled. | |
| 646 Note that the preceding conditional might have been another ELSE statement | |
| 647 although this behaviour is not guaranteed to be supported in future versions | |
| 648 of LWASM. | |
| 649 </para> | |
| 650 </listitem> | |
| 651 | |
| 652 <varlistentry> | |
| 653 <term>ENDC</term> | |
| 654 <listitem> | |
| 655 <para> | |
| 656 This directive marks the end of a conditional construct. Every conditional | |
| 657 construct must end with an ENDC directive. | |
| 658 </para> | |
| 659 </listitem> | |
| 660 </varlistentry> | |
| 661 | |
| 662 </variablelist> | |
| 663 </section> | |
| 664 | |
| 665 <section> | |
| 666 <title>Miscelaneous Directives</title> | |
| 667 | |
| 668 <para>This section includes directives that do not fit into the other | |
| 669 categories.</para> | |
| 670 | |
| 671 <variablelist> | |
| 672 | |
| 673 <varlistentry> | |
| 674 <term>INCLUDE <parameter>filename</parameter></term> | |
| 675 <listitem> | |
| 676 <para> | |
| 677 Include the contents of <parameter>filename</parameter> at this point in | |
| 678 the assembly as though it were a part of the file currently being processed. | |
| 679 Note that whitespace cannot appear in the name of the file. | |
| 680 </para> | |
| 681 </listitem> | |
| 682 </varlistentry> | |
| 683 | |
| 684 <varlistentry> | |
| 685 <term>END <parameter>[expr]</parameter></term> | |
| 686 <listitem> | |
| 687 <para> | |
| 688 This directive causes the assembler to stop assembling immediately as though | |
| 689 it ran out of input. For the DECB target only, <parameter>expr</parameter> | |
| 690 can be used to set the execution address of the resulting binary. For all | |
| 691 other targets, specifying <parameter>expr</parameter> will cause an error. | |
| 692 </para> | |
| 693 </listitem> | |
| 694 </varlistentry> | |
| 695 | |
| 696 <varlistentry> | |
| 697 <term>ERROR <parameter>string</parameter></term> | |
| 698 <listitem> | |
| 699 <para> | |
| 700 Causes a custom error message to be printed at this line. This will cause | |
| 701 assembly to fail. This directive is most useful inside conditional constructs | |
| 702 to cause assembly to fail if some condition that is known bad happens. | |
| 703 </para> | |
| 704 </listitem> | |
| 705 </varlistentry> | |
| 706 | |
| 707 </variablelist> | |
| 708 </section> | |
| 709 | |
| 710 </section> | |
| 711 | |
| 712 <section> | |
| 713 <title>Macros</title> | |
| 714 <para> | |
| 715 LWASM is a macro assembler. A macro is simply a name that stands in for a | |
| 716 series of instructions. Once a macro is defined, it is used like any other | |
| 717 assembler directive. Defining a macro can be considered equivalent to adding | |
| 718 additional assembler directives. | |
| 719 </para> | |
| 720 <para>Macros my accept parameters. These parameters are referenced within | |
| 721 a macro by the a backslash ("\") followed by a digit 1 through 9 for the first | |
| 722 through ninth parameters. They may also be referenced by enclosing the | |
| 723 decimal parameter number in braces ("{num}"). These parameter references | |
| 724 are replaced with the verbatim text of the parameter passed to the macro. A | |
| 725 reference to a non-existent parameter will be replaced by an empty string. | |
| 726 Macro parameters are expanded everywhere on each source line. That means | |
| 727 the parameter to a macro could be used as a symbol or it could even appear | |
| 728 in a comment or could cause an entire source line to be commented out | |
| 729 when the macro is expanded. | |
| 730 </para> | |
| 731 <para> | |
| 732 Parameters passed to a macro are separated by commas and the parameter list | |
| 733 is terminated by any whitespace. This means that neither a comma nor whitespace | |
| 734 may be included in a macro parameter. | |
| 735 </para> | |
| 736 <para> | |
| 737 Macro expansion is done recursively. That is, within a macro, macros are | |
| 738 expanded. This can lead to infinite loops in macro expansion. If the assembler | |
| 739 hangs for a long time while assembling a file that uses macros, this may be | |
| 740 the reason.</para> | |
| 741 | |
| 742 <para>Each macro expansion receives its own local symbol context which is not | |
| 743 inherited by any macros called by it nor is it inherited from the context | |
| 744 the macro was instantiated in. That means it is possible to use local symbols | |
| 745 within macros without having them collide with symbols in other macros or | |
| 746 outside the macro itself. However, this also means that using a local symbol | |
| 747 as a parameter to a macro, while legal, will not do what it would seem to do | |
| 748 as it will result in looking up the local symbol in the macro's symbol context | |
| 749 rather than the enclosing context where it came from, likely yielding either | |
| 750 an undefined symbol error or bizarre assembly results. | |
| 751 </para> | |
| 752 <para> | |
| 753 Note that there is no way to define a macro as local to a symbol context. All | |
| 754 macros are part of the global macro namespace. However, macros have a separate | |
| 755 namespace from symbols so it is possible to have a symbol with the same name | |
| 756 as a macro. | |
| 757 </para> | |
| 758 | |
| 759 <para> | |
| 760 Macros are defined only during the first pass. Macro expansion also | |
| 761 only occurs during the first pass. On the second pass, the macro | |
| 762 definition is simply ignored. Macros must be defined before they are used. | |
| 763 </para> | |
| 764 | |
| 765 <para>The following directives are used when defining macros.</para> | |
| 766 | |
| 767 <variablelist> | |
| 768 <varlistentry> | |
| 769 <term><parameter>macroname</parameter> MACRO</term> | |
| 770 <listitem> | |
| 771 <para>This directive is used to being the definition of a macro called | |
| 772 <parameter>macroname</parameter>. If <parameter>macroname</parameter> already | |
| 773 exists, it is considered an error. Attempting to define a macro within a | |
| 774 macro is undefined. It may work and it may not so the behaviour should not | |
| 775 be relied upon. | |
| 776 </para> | |
| 777 </listitem> | |
| 778 </varlistentry> | |
| 779 | |
| 780 <varlistentry> | |
| 781 <term>ENDM</term> | |
| 782 <listitem> | |
| 783 <para> | |
| 784 This directive indicates the end of the macro currently being defined. It | |
| 785 causes the assembler to resume interpreting source lines as normal. | |
| 786 </para> | |
| 787 </listitem> | |
| 788 </variablelist> | |
| 789 | |
| 790 </section> | |
| 791 | |
| 792 <section> | |
| 793 <title>Object Files and Sections</title> | |
| 794 <para> | |
| 795 The object file target is very useful for large project because it allows | |
| 796 multiple files to be assembled independently and then linked into the final | |
| 797 binary at a later time. It allows only the small portion of the project | |
| 798 that was modified to be re-assembled rather than requiring the entire set | |
| 799 of source code to be available to the assembler in a single assembly process. | |
| 800 This can be particularly important if there are a large number of macros, | |
| 801 symbol definitions, or other metadata that uses resources at assembly time. | |
| 802 By far the largest benefit, however, is keeping the source files small enough | |
| 803 for a mere mortal to find things in them. | |
| 804 </para> | |
| 805 | |
| 806 <para> | |
| 807 With multi-file projects, there needs to be a means of resolving references to | |
| 808 symbols in other source files. These are known as external references. The | |
| 809 addresses of these symbols cannot be known until the linker joins all the | |
| 810 object files into a single binary. This means that the assembler must be | |
| 811 able to output the object code without knowing the value of the symbol. This | |
| 812 places some restrictions on the code generated by the assembler. For | |
| 813 example, the assembler cannot generate direct page addressing for instructions | |
| 814 that reference external symbols because the address of the symbol may not | |
| 815 be in the direct page. Similarly, relative branches and PC relative addressing | |
| 816 cannot be used in their eight bit forms. Everything that must be resolved | |
| 817 by the linker must be assembled to use the largest address size possible to | |
| 818 allow the linker to fill in the correct value at link time. Note that the | |
| 819 same problem applies to absolute address references as well, even those in | |
| 820 the same source file, because the address is not known until link time. | |
| 821 </para> | |
| 822 | |
| 823 <para> | |
| 824 It is often desired in multi-file projects to have code of various types grouped | |
| 825 together in the final binary generated by the linker as well. The same applies | |
| 826 to data. In order for the linker to do that, the bits that are to be grouped | |
| 827 must be tagged in some manner. This is where the concept of sections comes in. | |
| 828 Each chunk of code or data is part of a section in the object file. Then, | |
| 829 when the linker reads all the object files, it coalesces all sections of the | |
| 830 same name into a single section and then considers it as a unit. | |
| 831 </para> | |
| 832 | |
| 833 <para> | |
| 834 The existence of sections, however, raises a problem for symbols even | |
| 835 within the same source file. Thus, the assembler must treat symbols from | |
| 836 different sections within the same source file in the same manner as external | |
| 837 symbols. That is, it must leave them for the linker to resolve at link time, | |
| 838 with all the limitations that entails. | |
| 839 </para> | |
| 840 | |
| 841 <para> | |
| 842 In the object file target mode, LWASM requires all source lines that | |
| 843 cause bytes to be output to be inside a section. Any directives that do | |
| 844 not cause any bytes to be output can appear outside of a section. This includes | |
| 845 such things as EQU or RMB. Even ORG can appear outside a section. ORG, however, | |
| 846 makes no sense within a section because it is the linker that determines | |
| 847 the starting address of the section's code, not the assembler. | |
| 848 </para> | |
| 849 | |
| 850 <para> | |
| 851 All symbols defined globally in the assembly process are local to the | |
| 852 source file and cannot be exported. All symbols defined within a section are | |
| 853 considered local to the source file unless otherwise explicitly exported. | |
| 854 Symbols referenced from external source files must be declared external, | |
| 855 either explicitly or by asking the assembler to assume that all undefined | |
| 856 symbols are external. | |
| 857 </para> | |
| 858 | |
| 859 <para> | |
| 860 It is often handy to define a number of memory addresses that will be | |
| 861 used for data at run-time but which need not be included in the binary file. | |
| 862 These memory addresses are not initialized until run-time, either by the | |
| 863 program itself or by the program loader, depending on the operating environment. | |
| 864 Such sections are often known as BSS sections. LWASM supports generating | |
| 865 sections with a BSS attribute set which causes the section definition including | |
| 866 symbols exported from that section and those symbols required to resolve | |
| 867 references from the local file, but with no actual code in the object file. | |
| 868 It is illegal for any source lines within a BSS flagged section to cause any | |
| 869 bytes to be output. | |
| 870 </para> | |
| 871 | |
| 872 <para>The following directives apply to section handling.</para> | |
| 873 | |
| 874 <variablelist> | |
| 875 <varlistentry> | |
| 876 <term>SECTION <parameter>name[,flags]</parameter></term> | |
| 877 <term>SECT <parameter>name[,flags]</parameter></term> | |
| 878 <listitem> | |
| 879 <para> | |
| 880 Instructs the assembler that the code following this directive is to be | |
| 881 considered part of the section <parameter>name</parameter>. A section name | |
| 882 may appear multiple times in which case it is as though all the code from | |
| 883 all the instances of that section appeared adjacent within the source file. | |
| 884 However, <parameter>flags</parameter> may only be specified on the first | |
| 885 instance of the section. | |
| 886 </para> | |
| 887 <para>There is a single flag supported in <parameter>flags</parameter>. The | |
| 888 flag <parameter>bss</parameter> will cause the section to be treated as a BSS | |
| 889 section and, thus, no code will be included in the object file nor will any | |
| 890 bytes be permitted to be output.</para> | |
| 891 <para> | |
| 892 If assembly is already happening within a section, the section is implicitly | |
| 893 ended and the new section started. This is not considered an error although | |
| 894 it is recommended that all sections be explicitly closed. | |
| 895 </para> | |
| 896 </listitem> | |
| 897 </varlistentry> | |
| 898 | |
| 899 <varlistentry> | |
| 900 <term>ENDSECTION</term> | |
| 901 <term>ENDSECT</term> | |
| 902 <term>ENDS</term> | |
| 903 <listitem> | |
| 904 <para> | |
| 905 This directive ends the current section. This puts assembly outside of any | |
| 906 sections until the next SECTION directive. | |
| 907 </listitem> | |
| 908 </varlistentry> | |
| 909 | |
| 910 <varlistentry> | |
| 911 <term><parameter>sym</parameter> EXTERN</term> | |
| 912 <term><parameter>sym</parameter> EXTERNAL</term> | |
| 913 <term><parameter>sym</parameter> IMPORT</term> | |
| 914 <listitem> | |
| 915 <para> | |
| 916 This directive defines <parameter>sym</parameter> as an external symbol. | |
| 917 This directive may occur at any point in the source code. EXTERN definitions | |
| 918 are resolved on the first pass so an EXTERN definition anywhere in the | |
| 919 source file is valid for the entire file. The use of this directive is | |
| 920 optional when the assembler is instructed to assume that all undefined | |
| 921 symbols are external. In fact, in that mode, if the symbol is referenced | |
| 922 before the EXTERN directive, an error will occur. | |
| 923 </para> | |
| 924 </listitem> | |
| 925 </varlistentry> | |
| 926 | |
| 927 <varlistentry> | |
| 928 <term><parameter>sym</parameter> EXPORT</term> | |
| 929 <listitem> | |
| 930 <para> | |
| 931 This directive defines <parameter>sym</parameter> as an exported symbol. | |
| 932 This directive may occur at any point in the source code, even before the | |
| 933 definition of the exported symbol. | |
| 934 </para> | |
| 935 </listitem> | |
| 936 </varlistentry> | |
| 937 | |
| 938 </variablelist> | |
| 939 | |
| 940 </section> | |
| 941 | |
| 942 <section> | |
| 943 <title>Assembler Modes and Pragmas</title> | |
| 944 <para> | |
| 945 There are a number of options that affect the way assembly is performed. | |
| 946 Some of these options can only be specified on the command line because | |
| 947 they determine something absolute about the assembly process. These include | |
| 948 such things as the output target. Other things may be switchable during | |
| 949 the assembly process. These are known as pragmas and are, by definition, | |
| 950 not portable between assemblers. | |
| 951 </para> | |
| 952 | |
| 953 <para>LWASM supports a number of pragmas that affect code generation or | |
| 954 otherwise affect the behaviour of the assembler. These may be specified by | |
| 955 way of a command line option or by assembler directives. The directives | |
| 956 are as follows. | |
| 957 </para> | |
| 958 | |
| 959 <variablelist> | |
| 960 <varlistentry> | |
| 961 <term>PRAGMA <parameter>pragma[,...]</parameter></term> | |
| 962 <listitem> | |
| 963 <para> | |
| 964 Specifies that the assembler should bring into force all <parameter>pragma</parameter>s | |
| 965 specified. Any unrecognized pragma will cause an assembly error. The new | |
| 966 pragmas will take effect immediately. This directive should be used when | |
| 967 the program will assemble incorrectly if the pragma is ignored or not supported. | |
| 968 </para> | |
| 969 </listitem> | |
| 970 </varlistentry> | |
| 971 | |
| 972 <varlistentry> | |
| 973 <term>*PRAGMA <parameter>pragma[,...]</parameter></term> | |
| 974 <listitem> | |
| 975 <para> | |
| 976 This is identical to the PRAGMA directive except no error will occur with | |
| 977 unrecognized or unsupported pragmas. This directive, by virtue of starting | |
| 978 with a comment character, will also be ignored by assemblers that do not | |
| 979 support this directive. Use this variation if the pragma is not required | |
| 980 for correct functioning of the code. | |
| 981 </para> | |
| 982 </listitem> | |
| 983 </varlistentry> | |
| 984 </variablelist> | |
| 985 | |
| 986 <para>Each pragma supported has a positive version and a negative version. | |
| 987 The positive version enables the pragma while the negative version disables | |
| 988 it. The negatitve version is simply the positive version with "no" prefixed | |
| 989 to it. For instance, "pragma" vs. "nopragma". Only the positive version is | |
| 990 listed below.</para> | |
| 991 | |
| 992 <para>Pragmas are not case sensitive.</para> | |
| 993 | |
| 994 <variablelist> | |
| 995 <varlistentry> | |
| 996 <term>index0tonone</term> | |
| 997 <listitem> | |
| 998 <para> | |
| 999 When in force, this pragma enables an optimization affecting indexed addressing | |
| 1000 modes. When the offset expression in an indexed mode evaluates to zero but is | |
| 1001 not explicity written as 0, this will replace the operand with the equivalent | |
| 1002 no offset mode, thus creating slightly faster code. Because of the advantages | |
| 1003 of this optimization, it is enabled by default. | |
| 1004 </para> | |
| 1005 </listitem> | |
| 1006 </varlistentry> | |
| 1007 | |
| 1008 <varlistentry> | |
| 1009 <term>undefextern</term> | |
| 1010 <listitem> | |
| 1011 <para> | |
| 1012 This pragma is only valid for targets that support external references. When in | |
| 1013 force, if the assembler sees an undefined symbol on the second pass, it will | |
| 1014 automatically define it as an external symbol. This automatic definition will | |
| 1015 apply for the remainder of the assembly process, even if the pragma is | |
| 1016 subsequently turned off. Because this behaviour would be potentially surprising, | |
| 1017 this pragma defaults to off. | |
| 1018 </para> | |
| 1019 <para> | |
| 1020 The primary use for this pragma is for projects that share a large number of | |
| 1021 symbols between source files. In such cases, it is impractical to enumerate | |
| 1022 all the external references in every source file. This allows the assembler | |
| 1023 and linker to do the heavy lifting while not preventing a particular source | |
| 1024 module from defining a local symbol of the same name as an external symbol | |
| 1025 if it does not need the external symbol. (This pragma will not cause an | |
| 1026 automatic external definition if there is already a locally defined symbol.) | |
| 1027 </para> | |
| 1028 <para> | |
| 1029 This pragma will often be specified on the command line for large projects. | |
| 1030 However, depending on the specific dynamics of the project, it may be sufficient | |
| 1031 for one or two files to use this pragma internally. | |
| 1032 </para> | |
| 1033 </listitem> | |
| 1034 </varlistentry> | |
| 1035 </variablelist> | |
| 1036 | |
| 1037 </section> | |
| 1038 | |
| 1039 </chapter> | |
| 1040 | |
| 1041 <chapter> | |
| 1042 <title>LWLINK</title> | |
| 1043 <para> | |
| 1044 </para> | |
| 1045 </chapter> | |
| 1046 | |
| 117 <chapter id="objchap"> | 1047 <chapter id="objchap"> |
| 118 <title>Object Files</title> | 1048 <title>Object Files</title> |
| 119 <para></para> | 1049 <para> |
| 1050 LWTOOLS uses a proprietary object file format. It is proprietary in the sense | |
| 1051 that it is specific to LWTOOLS, not that it is a hidden format. It would be | |
| 1052 hard to keep it hidden in an open source tool chain anyway. This chapter | |
| 1053 documents the object file format. | |
| 1054 </para> | |
| 120 </chapter> | 1055 </chapter> |
| 121 </book> | 1056 </book> |
| 122 | 1057 |