1<!doctype linuxdoc system> 2 3<article> 4<title>ca65 Users Guide 5<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline> 6<url url="mailto:greg.king5@verizon.net" name="Greg King"> 7 8<abstract> 9ca65 is a powerful macro assembler for the 6502, 65C02, and 65816 CPUs. It is 10used as a companion assembler for the cc65 crosscompiler, but it may also be 11used as a standalone product. 12</abstract> 13 14<!-- Table of contents --> 15<toc> 16 17<!-- Begin the document --> 18 19<sect>Overview<p> 20 21ca65 is a replacement for the ra65 assembler that was part of the cc65 C 22compiler, originally developed by John R. Dunning. I had some problems with 23ra65 and the copyright does not permit some things which I wanted to be 24possible, so I decided to write a completely new assembler/linker/archiver 25suite for the cc65 compiler. ca65 is part of this suite. 26 27Some parts of the assembler (code generation and some routines for symbol 28table handling) are taken from an older crossassembler named a816 written 29by me a long time ago. 30 31 32<sect1>Design criteria<p> 33 34Here's a list of the design criteria, that I considered important for the 35development: 36 37<itemize> 38 39<item> The assembler must support macros. Macros are not essential, but they 40 make some things easier, especially when you use the assembler in the 41 backend of a compiler. 42<item> The assembler must support the newer 65C02 and 65816 CPUs. I have been 43 thinking about a 65816 backend for the C compiler, and even my old 44 a816 assembler had support for these CPUs, so this wasn't really a 45 problem. 46<item> The assembler must produce relocatable code. This is necessary for the 47 compiler support, and it is more convenient. 48<item> Conditional assembly must be supported. This is a must for bigger 49 projects written in assembler (like Elite128). 50<item> The assembler must support segments, and it must support more than 51 three segments (this is the count, most other assemblers support). 52 Having more than one code segments helps developing code for systems 53 with a divided ROM area (like the C64). 54<item> The linker must be able to resolve arbitrary expressions. It should 55 be able to get things like 56<tscreen><verb> 57 .import S1, S2 58 .export Special 59 Special = 2*S1 + S2/7 60</verb></tscreen> 61 right. 62<item> True lexical nesting for symbols. This is very convenient for larger 63 assembly projects. 64<item> "Cheap" local symbols without lexical nesting for those quick, late 65 night hacks. 66<item> I liked the idea of "options" as Anre Fachats .o65 format has it, so I 67 introduced the concept into the object file format use by the new cc65 68 binutils. 69<item> The assembler will be a one pass assembler. There was no real need for 70 this decision, but I've written several multipass assemblers, and it 71 started to get boring. A one pass assembler needs much more elaborated 72 data structures, and because of that it's much more fun:-) 73<item> Non-GPLed code that may be used in any project without restrictions or 74 fear of "GPL infecting" other code. 75</itemize> 76<p> 77 78 79<sect>Usage<p> 80 81 82<sect1>Command line option overview<p> 83 84The assembler accepts the following options: 85 86<tscreen><verb> 87--------------------------------------------------------------------------- 88Usage: ca65 [options] file 89Short options: 90 -D name[=value] Define a symbol 91 -I dir Set an include directory search path 92 -U Mark unresolved symbols as import 93 -V Print the assembler version 94 -W n Set warning level n 95 -d Debug mode 96 -g Add debug info to object file 97 -h Help (this text) 98 -i Ignore case of symbols 99 -l name Create a listing file if assembly was ok 100 -mm model Set the memory model 101 -o name Name the output file 102 -s Enable smart mode 103 -t sys Set the target system 104 -v Increase verbosity 105 106Long options: 107 --auto-import Mark unresolved symbols as import 108 --bin-include-dir dir Set a search path for binary includes 109 --cpu type Set cpu type 110 --create-dep name Create a make dependency file 111 --create-full-dep name Create a full make dependency file 112 --debug Debug mode 113 --debug-info Add debug info to object file 114 --feature name Set an emulation feature 115 --help Help (this text) 116 --ignore-case Ignore case of symbols 117 --include-dir dir Set an include directory search path 118 --large-alignment Don't warn about large alignments 119 --listing name Create a listing file if assembly was ok 120 --list-bytes n Maximum number of bytes per listing line 121 --memory-model model Set the memory model 122 --pagelength n Set the page length for the listing 123 --relax-checks Relax some checks (see docs) 124 --smart Enable smart mode 125 --target sys Set the target system 126 --verbose Increase verbosity 127 --version Print the assembler version 128--------------------------------------------------------------------------- 129</verb></tscreen> 130 131 132<sect1>Command line options in detail<p> 133 134Here is a description of all the command line options: 135 136<descrip> 137 138 <label id="option--bin-include-dir"> 139 <tag><tt>--bin-include-dir dir</tt></tag> 140 141 Name a directory which is searched for binary include files. The option 142 may be used more than once to specify more than one directory to search. The 143 current directory is always searched first before considering any 144 additional directories. See also the section about <ref id="search-paths" 145 name="search paths">. 146 147 148 <label id="option--cpu"> 149 <tag><tt>--cpu type</tt></tag> 150 151 Set the default for the CPU type. The option takes a parameter, which 152 may be one of 153 154 6502, 6502X, 65SC02, 65C02, 65816, sweet16, HuC6280, 4510 155 156 157 <label id="option-create-dep"> 158 <tag><tt>--create-dep name</tt></tag> 159 160 Tells the assembler to generate a file containing the dependency list for 161 the assembled module in makefile syntax. The output is written to a file 162 with the given name. The output does not include files passed via debug 163 information to the assembler. 164 165 166 <label id="option-create-full-dep"> 167 <tag><tt>--create-full-dep name</tt></tag> 168 169 Tells the assembler to generate a file containing the dependency list for 170 the assembled module in makefile syntax. The output is written to a file 171 with the given name. The output does include files passed via debug 172 information to the assembler. 173 174 175 <tag><tt>-d, --debug</tt></tag> 176 177 Enables debug mode, something that should not be needed for mere 178 mortals:-) 179 180 181 <label id="option--feature"> 182 <tag><tt>--feature name</tt></tag> 183 184 Enable an emulation feature. This is identical as using <tt/.FEATURE/ 185 in the source with two exceptions: Feature names must be lower case, and 186 each feature must be specified by using an extra <tt/--feature/ option, 187 comma separated lists are not allowed. 188 189 See the discussion of the <tt><ref id=".FEATURE" name=".FEATURE"></tt> 190 command for a list of emulation features. 191 192 193 <label id="option-g"> 194 <tag><tt>-g, --debug-info</tt></tag> 195 196 When this option (or the equivalent control command <tt/.DEBUGINFO/) is 197 used, the assembler will add a section to the object file that contains 198 all symbols (including local ones) together with the symbol values and 199 source file positions. The linker will put these additional symbols into 200 the VICE label file, so even local symbols can be seen in the VICE 201 monitor. 202 203 204 <label id="option-h"> 205 <tag><tt>-h, --help</tt></tag> 206 207 Print the short option summary shown above. 208 209 210 <label id="option-i"> 211 <tag><tt>-i, --ignore-case</tt></tag> 212 213 This option makes the assembler case insensitive on identifiers and labels. 214 This option will override the default, but may itself be overridden by the 215 <tt><ref id=".CASE" name=".CASE"></tt> control command. 216 217 218 <label id="option-l"> 219 <tag><tt>-l name, --listing name</tt></tag> 220 221 Generate an assembler listing with the given name. A listing file will 222 never be generated in case of assembly errors. 223 224 225 <label id="option--large-alignment"> 226 <tag><tt>--large-alignment</tt></tag> 227 228 Disable warnings about a large combined alignment. See the discussion of the 229 <tt><ref id=".ALIGN" name=".ALIGN"></tt> directive for further information. 230 231 232 <label id="option--list-bytes"> 233 <tag><tt>--list-bytes n</tt></tag> 234 235 Set the maximum number of bytes printed in the listing for one line of 236 input. See the <tt><ref id=".LISTBYTES" name=".LISTBYTES"></tt> directive 237 for more information. The value zero can be used to encode an unlimited 238 number of printed bytes. 239 240 241 <label id="option-mm"> 242 <tag><tt>-mm model, --memory-model model</tt></tag> 243 244 Define the default memory model. Possible model specifiers are near, far and 245 huge. 246 247 248 <label id="option-o"> 249 <tag><tt>-o name</tt></tag> 250 251 The default output name is the name of the input file with the extension 252 replaced by ".o". If you don't like that, you may give another name with 253 the -o option. The output file will be placed in the same directory as 254 the source file, or, if -o is given, the full path in this name is used. 255 256 257 <label id="option--pagelength"> 258 <tag><tt>--pagelength n</tt></tag> 259 260 sets the length of a listing page in lines. See the <tt><ref 261 id=".PAGELENGTH" name=".PAGELENGTH"></tt> directive for more information. 262 263 264 <label id="option--relax-checks"> 265 <tag><tt>--relax-checks</tt></tag> 266 267 Relax some checks done by the assembler. This will allow code that is an 268 error in most cases and flagged as such by the assembler, but can be valid 269 in special situations. 270 271 Examples are: 272<itemize> 273<item>Short branches between two different segments. 274<item>Byte sized address loads where the address is not a zeropage address. 275</itemize> 276 277 278 <label id="option-s"> 279 <tag><tt>-s, --smart-mode</tt></tag> 280 281 In smart mode (enabled by -s or the <tt><ref id=".SMART" name=".SMART"></tt> 282 pseudo instruction) the assembler will track usage of the <tt/REP/ and 283 <tt/SEP/ instructions in 65816 mode and update the operand sizes 284 accordingly. If the operand of such an instruction cannot be evaluated by 285 the assembler (for example, because the operand is an imported symbol), a 286 warning is issued. 287 288 Beware: Since the assembler cannot trace the execution flow this may 289 lead to false results in some cases. If in doubt, use the .ixx and .axx 290 instructions to tell the assembler about the current settings. Smart 291 mode is off by default. 292 293 294 <label id="option-t"> 295 <tag><tt>-t sys, --target sys</tt></tag> 296 297 Set the target system. This will enable translation of character strings and 298 character constants into the character set of the target platform. The 299 default for the target system is "none", which means that no translation 300 will take place. The assembler supports the same target systems as the 301 compiler, see there for a list. 302 303 Depending on the target, the default CPU type is also set. This can be 304 overriden by using the <tt/<ref id="option--cpu" name="--cpu">/ option. 305 306 307 <label id="option-v"> 308 <tag><tt>-v, --verbose</tt></tag> 309 310 Increase the assembler verbosity. Usually only needed for debugging 311 purposes. You may use this option more than one time for even more 312 verbose output. 313 314 315 <label id="option-D"> 316 <tag><tt>-D</tt></tag> 317 318 This option allows you to define symbols on the command line. Without a 319 value, the symbol is defined with the value zero. When giving a value, 320 you may use the '$' prefix for hexadecimal symbols. Please note 321 that for some operating systems, '$' has a special meaning, so 322 you may have to quote the expression. 323 324 325 <label id="option-I"> 326 <tag><tt>-I dir, --include-dir dir</tt></tag> 327 328 Name a directory which is searched for include files. The option may be 329 used more than once to specify more than one directory to search. The 330 current directory is always searched first before considering any 331 additional directories. See also the section about <ref id="search-paths" 332 name="search paths">. 333 334 335 <label id="option-U"> 336 <tag><tt>-U, --auto-import</tt></tag> 337 338 Mark symbols that are not defined in the sources as imported symbols. This 339 should be used with care since it delays error messages about typos and such 340 until the linker is run. The compiler uses the equivalent of this switch 341 (<tt><ref id=".AUTOIMPORT" name=".AUTOIMPORT"></tt>) to enable auto imported 342 symbols for the runtime library. However, the compiler is supposed to 343 generate code that runs through the assembler without problems, something 344 which is not always true for assembler programmers. 345 346 347 <label id="option-V"> 348 <tag><tt>-V, --version</tt></tag> 349 350 Print the version number of the assembler. If you send any suggestions 351 or bugfixes, please include the version number. 352 353 354 <label id="option-W"> 355 <tag><tt>-Wn</tt></tag> 356 357 Set the warning level for the assembler. Using -W2 the assembler will 358 even warn about such things like unused imported symbols. The default 359 warning level is 1, and it would probably be silly to set it to 360 something lower. 361 362</descrip> 363<p> 364 365 366 367<sect>Search paths<label id="search-paths"><p> 368 369Normal include files are searched in the following places: 370 371<enum> 372<item>The current file's directory. 373<item>Any directory added with the <tt/<ref id="option-I" name="-I">/ option 374on the command line. 375<item>The value of the environment variable <tt/CA65_INC/ if it is defined. 376<item>A subdirectory named <tt/asminc/ of the directory defined in the 377 environment variable <tt/CC65_HOME/, if it is defined. 378<item>An optionally compiled-in directory. 379</enum> 380 381Binary include files are searched in the following places: 382 383<enum> 384<item>The current file's directory. 385<item>Any directory added with the <tt/<ref id="option--bin-include-dir" 386name="--bin-include-dir">/ option on the command line. 387</enum> 388 389 390 391<sect>Input format<p> 392 393<sect1>Assembler syntax<p> 394 395The assembler accepts the standard 6502/65816 assembler syntax. One line may 396contain a label (which is identified by a colon), and, in addition to the 397label, an assembler mnemonic, a macro, or a control command (see section <ref 398id="control-commands" name="Control Commands"> for supported control 399commands). Alternatively, the line may contain a symbol definition using 400the '=' token. Everything after a semicolon is handled as a comment (that is, 401it is ignored). 402 403Here are some examples for valid input lines: 404 405<tscreen><verb> 406 Label: ; A label and a comment 407 lda #$20 ; A 6502 instruction plus comment 408 L1: ldx #$20 ; Same with label 409 L2: .byte "Hello world" ; Label plus control command 410 mymac $20 ; Macro expansion 411 MySym = 3*L1 ; Symbol definition 412 MaSym = Label ; Another symbol 413</verb></tscreen> 414 415The assembler accepts 416 417<itemize> 418<item>all valid 6502 mnemonics when in 6502 mode (the default or after the 419 <tt><ref id=".P02" name=".P02"></tt> command was given). 420<item>all valid 6502 mnemonics plus a set of illegal instructions when in 421 <ref id="6502X-mode" name="6502X mode">. 422<item>all valid 65SC02 mnemonics when in 65SC02 mode (after the 423 <tt><ref id=".PSC02" name=".PSC02"></tt> command was given). 424<item>all valid 65C02 mnemonics when in 65C02 mode (after the 425 <tt><ref id=".PC02" name=".PC02"></tt> command was given). 426<item>all valid 65816 mnemonics when in 65816 mode (after the 427 <tt><ref id=".P816" name=".P816"></tt> command was given). 428<item>all valid 4510 mnemonics when in 4510 mode (after the 429 <tt><ref id=".P4510" name=".P4510"></tt> command was given). 430</itemize> 431 432 433<sect1>65816 mode<p> 434 435In 65816 mode, several aliases are accepted, in addition to the official 436mnemonics: 437 438<itemize> 439<item><tt>CPA</tt> is an alias for <tt>CMP</tt> 440<item><tt>DEA</tt> is an alias for <tt>DEC A</tt> 441<item><tt>INA</tt> is an alias for <tt>INC A</tt> 442<item><tt>SWA</tt> is an alias for <tt>XBA</tt> 443<item><tt>TAD</tt> is an alias for <tt>TCD</tt> 444<item><tt>TAS</tt> is an alias for <tt>TCS</tt> 445<item><tt>TDA</tt> is an alias for <tt>TDC</tt> 446<item><tt>TSA</tt> is an alias for <tt>TSC</tt> 447</itemize> 448 449 450<sect1>6502X mode<label id="6502X-mode"><p> 451 4526502X mode is an extension to the normal 6502 mode. In this mode, several 453mnemonics for illegal instructions of the NMOS 6502 CPUs are accepted. Since 454these instructions are illegal, there are no official mnemonics for them. The 455unofficial ones are taken from <url 456url="http://www.oxyron.de/html/opcodes02.html">. Please note that only the 457ones marked as "stable" are supported. The following table uses information 458from the mentioned web page, for more information, see there. 459 460<itemize> 461<item><tt>ALR: A:=(A and #{imm})/2;</tt> 462<item><tt>ANC: A:=A and #{imm};</tt> Generates opcode $0B. 463<item><tt>ARR: A:=(A and #{imm})/2;</tt> 464<item><tt>AXS: X:=A and X-#{imm};</tt> 465<item><tt>DCP: {adr}:={adr}-1; A-{adr};</tt> 466<item><tt>ISC: {adr}:={adr}+1; A:=A-{adr};</tt> 467<item><tt>LAS: A,X,S:={adr} and S;</tt> 468<item><tt>LAX: A,X:={adr};</tt> 469<item><tt>RLA: {adr}:={adr}rol; A:=A and {adr};</tt> 470<item><tt>RRA: {adr}:={adr}ror; A:=A adc {adr};</tt> 471<item><tt>SAX: {adr}:=A and X;</tt> 472<item><tt>SLO: {adr}:={adr}*2; A:=A or {adr};</tt> 473<item><tt>SRE: {adr}:={adr}/2; A:=A xor {adr};</tt> 474</itemize> 475 476 477<sect1>4510 mode<p> 478 479The 4510 is a microcontroller that is the core of the Commodore C65 aka C64DX. 480It contains among other functions a slightly modified 65CE02/4502 CPU, to allow 481address mapping for 20 bits of address space (1 megabyte addressable area). 482As compared to the description of the CPU in the 483<url url="http://www.zimmers.net/anonftp/pub/cbm/c65/c65manualupdated.txt.gz" 484name="C65 System Specification"> 485<url url="https://raw.githubusercontent.com/MEGA65/c65-specifications/master/c65manualupdated.txt" 486name="(updated version)"> uses these changes: 487<itemize> 488<item><tt>LDA (d,SP),Y</tt> may also be written as <tt>LDA (d,S),Y</tt> 489(matching the 65816 notataion). 490<item>All branch instruction allow now 16 bit offsets. To use a 16 bit 491branch you have to prefix these with an "L" (e.g. "<tt>LBNE</tt>" instead of 492"<tt>BNE</tt>"). This might change at a later implementation of the assembler. 493</itemize> 494For more information about the Commodore C65/C64DX and the 4510 CPU, see 495<url url="http://www.zimmers.net/anonftp/pub/cbm/c65/"> and 496<url url="https://en.wikipedia.org/wiki/Commodore_65" name="Wikipedia">. 497 498 499<sect1>sweet16 mode<label id="sweet16-mode"><p> 500 501SWEET 16 is an interpreter for a pseudo 16 bit CPU written by Steve Wozniak 502for the Apple ][ machines. It is available in the Apple ][ ROM. ca65 can 503generate code for this pseudo CPU when switched into sweet16 mode. The 504following is special in sweet16 mode: 505 506<itemize> 507 508<item>The '@' character denotes indirect addressing and is no longer available 509for cheap local labels. If you need cheap local labels, you will have to 510switch to another lead character using the <tt/<ref id=".LOCALCHAR" 511name=".LOCALCHAR">/ command. 512 513<item>Registers are specified using <tt/R0/ .. <tt/R15/. In sweet16 mode, 514these identifiers are reserved words. 515 516</itemize> 517 518Please note that the assembler does neither supply the interpreter needed for 519SWEET 16 code, nor the zero page locations needed for the SWEET 16 registers, 520nor does it call the interpreter. All this must be done by your program. Apple 521][ programmers do probably know how to use sweet16 mode. 522 523For more information about SWEET 16, see 524<url url="http://www.6502.org/source/interpreters/sweet16.htm">. 525 526 527<sect1>Number format<p> 528 529For literal values, the assembler accepts the widely used number formats: A 530preceding '$' or a trailing 'h' denotes a hex value, a preceding '%' 531denotes a binary value, and a bare number is interpreted as a decimal. There 532are currently no octal values and no floats. 533 534 535<sect1>Conditional assembly<p> 536 537Please note that when using the conditional directives (<tt/.IF/ and friends), 538the input must consist of valid assembler tokens, even in <tt/.IF/ branches 539that are not assembled. The reason for this behaviour is that the assembler 540must still be able to detect the ending tokens (like <tt/.ENDIF/), so 541conversion of the input stream into tokens still takes place. As a consequence 542conditional assembly directives may <bf/not/ be used to prevent normal text 543(used as a comment or similar) from being assembled. <p> 544 545 546<sect>Expressions<p> 547 548 549<sect1>Expression evaluation<p> 550 551All expressions are evaluated with (at least) 32 bit precision. An 552expression may contain constant values and any combination of internal and 553external symbols. Expressions that cannot be evaluated at assembly time 554are stored inside the object file for evaluation by the linker. 555Expressions referencing imported symbols must always be evaluated by the 556linker. 557 558 559<sect1>Size of an expression result<p> 560 561Sometimes, the assembler must know about the size of the value that is the 562result of an expression. This is usually the case, if a decision has to be 563made, to generate a zero page or an absolute memory references. In this 564case, the assembler has to make some assumptions about the result of an 565expression: 566 567<itemize> 568<item> If the result of an expression is constant, the actual value is 569 checked to see if it's a byte sized expression or not. 570<item> If the expression is explicitly casted to a byte sized expression by 571 one of the '>', '<' or '^' operators, it is a byte expression. 572<item> If this is not the case, and the expression contains a symbol, 573 explicitly declared as zero page symbol (by one of the .importzp or 574 .exportzp instructions), then the whole expression is assumed to be 575 byte sized. 576<item> If the expression contains symbols that are not defined, and these 577 symbols are local symbols, the enclosing scopes are searched for a 578 symbol with the same name. If one exists and this symbol is defined, 579 its attributes are used to determine the result size. 580<item> In all other cases the expression is assumed to be word sized. 581</itemize> 582 583Note: If the assembler is not able to evaluate the expression at assembly 584time, the linker will evaluate it and check for range errors as soon as 585the result is known. 586 587 588<sect1>Boolean expressions<p> 589 590In the context of a boolean expression, any non zero value is evaluated as 591true, any other value to false. The result of a boolean expression is 1 if 592it's true, and zero if it's false. There are boolean operators with extreme 593low precedence with version 2.x (where x > 0). The <tt/.AND/ and <tt/.OR/ 594operators are shortcut operators. That is, if the result of the expression is 595already known, after evaluating the left hand side, the right hand side is 596not evaluated. 597 598 599<sect1>Constant expressions<p> 600 601Sometimes an expression must evaluate to a constant without looking at any 602further input. One such example is the <tt/<ref id=".IF" name=".IF">/ command 603that decides if parts of the code are assembled or not. An expression used in 604the <tt/.IF/ command cannot reference a symbol defined later, because the 605decision about the <tt/.IF/ must be made at the point when it is read. If the 606expression used in such a context contains only constant numerical values, 607there is no problem. When unresolvable symbols are involved it may get harder 608for the assembler to determine if the expression is actually constant, and it 609is even possible to create expressions that aren't recognized as constant. 610Simplifying the expressions will often help. 611 612In cases where the result of the expression is not needed immediately, the 613assembler will delay evaluation until all input is read, at which point all 614symbols are known. So using arbitrary complex constant expressions is no 615problem in most cases. 616 617 618 619<sect1>Available operators<label id="operators"><p> 620 621<table> 622<tabular ca="clc"> 623<bf/Operator/| <bf/Description/| <bf/Precedence/@<hline> 624 | Built-in string functions| 0@ 625 | |~@ 626 | Built-in pseudo-variables| 1@ 627 | Built-in pseudo-functions| 1@ 628+| Unary positive| 1@ 629-| Unary negative| 1@ 630˜<newline> 631.BITNOT| Unary bitwise not| 1@ 632<<newline> 633.LOBYTE| Unary low-byte operator| 1@ 634><newline> 635.HIBYTE| Unary high-byte operator| 1@ 636^<newline> 637.BANKBYTE| Unary bank-byte operator| 1@ 638 | |~@ 639*| Multiplication| 2@ 640/| Division| 2@ 641.MOD| Modulo operator| 2@ 642&<newline> 643.BITAND| Bitwise and| 2@ 644^<newline> 645.BITXOR| Binary bitwise xor| 2@ 646<<<newline> 647.SHL| Shift-left operator| 2@ 648>><newline> 649.SHR| Shift-right operator| 2@ 650 | |~@ 651+| Binary addition| 3@ 652-| Binary subtraction| 3@ 653|<newline> 654.BITOR| Bitwise or| 3@ 655 | |~@ 656= | Compare operator (equal)| 4@ 657<>| Compare operator (not equal)| 4@ 658<| Compare operator (less)| 4@ 659>| Compare operator (greater)| 4@ 660<=| Compare operator (less or equal)| 4@ 661>=| Compare operator (greater or equal)| 4@ 662 | |~@ 663&&<newline> 664.AND| Boolean and| 5@ 665.XOR| Boolean xor| 5@ 666 | |~@ 667||<newline> 668.OR| Boolean or| 6@ 669 | |~@ 670!<newline> 671.NOT| Boolean not| 7@<hline> 672</tabular> 673<caption>Available operators, sorted by precedence 674</table> 675 676To force a specific order of evaluation, parentheses may be used, as usual. 677 678 679 680<sect>Symbols and labels<p> 681 682A symbol or label is an identifier that starts with a letter and is followed 683by letters and digits. Depending on some features enabled (see 684<tt><ref id="at_in_identifiers" name="at_in_identifiers"></tt>, 685<tt><ref id="dollar_in_identifiers" name="dollar_in_identifiers"></tt> and 686<tt><ref id="leading_dot_in_identifiers" name="leading_dot_in_identifiers"></tt>) 687other characters may be present. Use of identifiers consisting of a single 688character will not work in all cases, because some of these identifiers are 689reserved keywords (for example "A" is not a valid identifier for a label, 690because it is the keyword for the accumulator). 691 692The assembler allows you to use symbols instead of naked values to make 693the source more readable. There are a lot of different ways to define and 694use symbols and labels, giving a lot of flexibility. 695 696<sect1>Numeric constants<p> 697 698Numeric constants are defined using the equal sign or the label assignment 699operator. After doing 700 701<tscreen><verb> 702 two = 2 703</verb></tscreen> 704 705may use the symbol "two" in every place where a number is expected, and it is 706evaluated to the value 2 in this context. The label assignment operator is 707almost identical, but causes the symbol to be marked as a label, so it may be 708handled differently in a debugger: 709 710<tscreen><verb> 711 io := $d000 712</verb></tscreen> 713 714The right side can of course be an expression: 715 716<tscreen><verb> 717 four = two * two 718</verb></tscreen> 719 720 721<label id="variables"> 722<sect1>Numeric variables<p> 723 724Within macros and other control structures (<tt><ref id=".REPEAT" 725name=".REPEAT"></tt>, ...) it is sometimes useful to have some sort of 726variable. This can be achieved by the <tt>.SET</tt> operator. It creates a 727symbol that may get assigned a different value later: 728 729<tscreen><verb> 730 four .set 4 731 lda #four ; Loads 4 into A 732 four .set 3 733 lda #four ; Loads 3 into A 734</verb></tscreen> 735 736Since the value of the symbol can change later, it must be possible to 737evaluate it when used (no delayed evaluation as with normal symbols). So the 738expression used as the value must be constant. 739 740Following is an example for a macro that generates a different label each time 741it is used. It uses the <tt><ref id=".SPRINTF" name=".SPRINTF"></tt> function 742and a numeric variable named <tt>lcount</tt>. 743 744<tscreen><verb> 745 .lcount .set 0 ; Initialize the counter 746 747 .macro genlab 748 .ident (.sprintf ("L%04X", lcount)): 749 lcount .set lcount + 1 750 .endmacro 751</verb></tscreen> 752 753 754<sect1>Standard labels<p> 755 756A label is defined by writing the name of the label at the start of the line 757(before any instruction mnemonic, macro or pseudo directive), followed by a 758colon. This will declare a symbol with the given name and the value of the 759current program counter. 760 761 762<sect1>Local labels and symbols<p> 763 764Using the <tt><ref id=".PROC" name=".PROC"></tt> directive, it is possible to 765create regions of code where the names of labels and symbols are local to this 766region. They are not known outside of this region and cannot be accessed from 767there. Such regions may be nested like PROCEDUREs in Pascal. 768 769See the description of the <tt><ref id=".PROC" name=".PROC"></tt> 770directive for more information. 771 772 773<sect1>Cheap local labels<p> 774 775Cheap local labels are defined like standard labels, but the name of the 776label must begin with a special symbol (usually '@', but this can be 777changed by the <tt><ref id=".LOCALCHAR" name=".LOCALCHAR"></tt> 778directive). 779 780Cheap local labels are visible only between two non cheap labels. As soon as a 781standard symbol is encountered (this may also be a local symbol if inside a 782region defined with the <tt><ref id=".PROC" name=".PROC"></tt> directive), the 783cheap local symbol goes out of scope. 784 785You may use cheap local labels as an easy way to reuse common label 786names like "Loop". Here is an example: 787 788<tscreen><verb> 789 Clear: lda #$00 ; Global label 790 ldy #$20 791 @Loop: sta Mem,y ; Local label 792 dey 793 bne @Loop ; Ok 794 rts 795 Sub: ... ; New global label 796 bne @Loop ; ERROR: Unknown identifier! 797</verb></tscreen> 798 799<sect1>Unnamed labels<p> 800 801If you really want to write messy code, there are also unnamed labels. These 802labels do not have a name (you guessed that already, didn't you?). A colon is 803used to mark the absence of the name. 804 805Unnamed labels may be accessed by using the colon plus several minus or plus 806characters as a label designator. Using the '-' characters will create a back 807reference (use the n'th label backwards), using '+' will create a forward 808reference (use the n'th label in forward direction). An example will help to 809understand this: 810 811<tscreen><verb> 812 : lda (ptr1),y ; #1 813 cmp (ptr2),y 814 bne :+ ; -> #2 815 tax 816 beq :+++ ; -> #4 817 iny 818 bne :- ; -> #1 819 inc ptr1+1 820 inc ptr2+1 821 bne :- ; -> #1 822 823 : bcs :+ ; #2 -> #3 824 ldx #$FF 825 rts 826 827 : ldx #$01 ; #3 828 : rts ; #4 829</verb></tscreen> 830 831As you can see from the example, unnamed labels will make even short 832sections of code hard to understand, because you have to count labels 833to find branch targets (this is the reason why I for my part do 834prefer the "cheap" local labels). Nevertheless, unnamed labels are 835convenient in some situations, so it's your decision. 836 837<em/Note:/ <ref id="scopes" name="Scopes"> organize named symbols, not 838unnamed ones, so scopes don't have an effect on unnamed labels. 839 840 841 842<sect1>Using macros to define labels and constants<p> 843 844While there are drawbacks with this approach, it may be handy in a few rare 845situations. Using <tt><ref id=".DEFINE" name=".DEFINE"></tt>, it is possible 846to define symbols or constants that may be used elsewhere. One of the 847advantages is that you can use it to define string constants (this is not 848possible with the other symbol types). 849 850Please note: <tt/.DEFINE/ style macros do token replacements on a low level, 851so the names do not adhere to scoping, diagnostics may be misleading, there 852are no symbols to look up in the map file, and there is no debug info. 853Especially the first problem in the list can lead to very nasty programming 854errors. Because of these problems, the general advice is, <bf/NOT/ do use 855<tt/.DEFINE/ if you don't have to. 856 857Example: 858 859<tscreen><verb> 860 .DEFINE two 2 861 .DEFINE version "SOS V2.3" 862 863 four = two * two ; Ok 864 .byte version ; Ok 865 866 .PROC ; Start local scope 867 two = 3 ; Will give "2 = 3" - invalid! 868 .ENDPROC 869</verb></tscreen> 870 871 872<sect1>Symbols and <tt>.DEBUGINFO</tt><p> 873 874If <tt><ref id=".DEBUGINFO" name=".DEBUGINFO"></tt> is enabled (or <ref 875id="option-g" name="-g"> is given on the command line), global, local and 876cheap local labels are written to the object file and will be available in the 877symbol file via the linker. Unnamed labels are not written to the object file, 878because they don't have a name which would allow to access them. 879 880 881 882<sect>Scopes<label id="scopes"><p> 883 884ca65 implements several sorts of scopes for symbols. 885 886<sect1>Global scope<p> 887 888All (non cheap local) symbols that are declared outside of any nested scopes 889are in global scope. 890 891 892<sect1>Cheap locals<p> 893 894A special scope is the scope for cheap local symbols. It lasts from one non 895local symbol to the next one, without any provisions made by the programmer. 896All other scopes differ in usage but use the same concept internally. 897 898 899<sect1>Generic nested scopes<p> 900 901A nested scoped for generic use is started with <tt/<ref id=".SCOPE" 902name=".SCOPE">/ and closed with <tt/<ref id=".ENDSCOPE" name=".ENDSCOPE">/. 903The scope can have a name, in which case it is accessible from the outside by 904using <ref id="scopesyntax" name="explicit scopes">. If the scope does not 905have a name, all symbols created within the scope are local to the scope, and 906aren't accessible from the outside. 907 908A nested scope can access symbols from the local or from enclosing scopes by 909name without using explicit scope names. In some cases there may be 910ambiguities, for example if there is a reference to a local symbol that is not 911yet defined, but a symbol with the same name exists in outer scopes: 912 913<tscreen><verb> 914 .scope outer 915 foo = 2 916 .scope inner 917 lda #foo 918 foo = 3 919 .endscope 920 .endscope 921</verb></tscreen> 922 923In the example above, the <tt/lda/ instruction will load the value 3 into the 924accumulator, because <tt/foo/ is redefined in the scope. However: 925 926<tscreen><verb> 927 .scope outer 928 foo = $1234 929 .scope inner 930 lda foo,x 931 foo = $12 932 .endscope 933 .endscope 934</verb></tscreen> 935 936Here, <tt/lda/ will still load from <tt/$12,x/, but since it is unknown to the 937assembler that <tt/foo/ is a zeropage symbol when translating the instruction, 938absolute mode is used instead. In fact, the assembler will not use absolute 939mode by default, but it will search through the enclosing scopes for a symbol 940with the given name. If one is found, the address size of this symbol is used. 941This may lead to errors: 942 943<tscreen><verb> 944 .scope outer 945 foo = $12 946 .scope inner 947 lda foo,x 948 foo = $1234 949 .endscope 950 .endscope 951</verb></tscreen> 952 953In this case, when the assembler sees the symbol <tt/foo/ in the <tt/lda/ 954instruction, it will search for an already defined symbol <tt/foo/. It will 955find <tt/foo/ in scope <tt/outer/, and a close look reveals that it is a 956zeropage symbol. So the assembler will use zeropage addressing mode. If 957<tt/foo/ is redefined later in scope <tt/inner/, the assembler tries to change 958the address in the <tt/lda/ instruction already translated, but since the new 959value needs absolute addressing mode, this fails, and an error message "Range 960error" is output. 961 962Of course the most simple solution for the problem is to move the definition 963of <tt/foo/ in scope <tt/inner/ upwards, so it precedes its use. There may be 964rare cases when this cannot be done. In these cases, you can use one of the 965address size override operators: 966 967<tscreen><verb> 968 .scope outer 969 foo = $12 970 .scope inner 971 lda a:foo,x 972 foo = $1234 973 .endscope 974 .endscope 975</verb></tscreen> 976 977This will cause the <tt/lda/ instruction to be translated using absolute 978addressing mode, which means changing the symbol reference later does not 979cause any errors. 980 981 982<sect1>Nested procedures<p> 983 984A nested procedure is created by use of <tt/<ref id=".PROC" name=".PROC">/. It 985differs from a <tt/<ref id=".SCOPE" name=".SCOPE">/ in that it must have a 986name, and a it will introduce a symbol with this name in the enclosing scope. 987So 988 989<tscreen><verb> 990 .proc foo 991 ... 992 .endproc 993</verb></tscreen> 994 995is actually the same as 996 997<tscreen><verb> 998 foo: 999 .scope foo 1000 ... 1001 .endscope 1002</verb></tscreen> 1003 1004This is the reason why a procedure must have a name. If you want a scope 1005without a name, use <tt/<ref id=".SCOPE" name=".SCOPE">/. 1006 1007<em/Note:/ As you can see from the example above, scopes and symbols live in 1008different namespaces. There can be a symbol named <tt/foo/ and a scope named 1009<tt/foo/ without any conflicts (but see the section titled <ref 1010id="scopesearch" name=""Scope search order"">). 1011 1012 1013<sect1>Structs, unions and enums<p> 1014 1015Structs, unions and enums are explained in a <ref id="structs" name="separate 1016section">, I do only cover them here, because if they are declared with a 1017name, they open a nested scope, similar to <tt/<ref id=".SCOPE" 1018name=".SCOPE">/. However, when no name is specified, the behaviour is 1019different: In this case, no new scope will be opened, symbols declared within 1020a struct, union, or enum declaration will then be added to the enclosing scope 1021instead. 1022 1023 1024<sect1>Explicit scope specification<label id="scopesyntax"><p> 1025 1026Accessing symbols from other scopes is possible by using an explicit scope 1027specification, provided that the scope where the symbol lives in has a name. 1028The namespace token (<tt/::/) is used to access other scopes: 1029 1030<tscreen><verb> 1031 .scope foo 1032 bar: .word 0 1033 .endscope 1034 1035 ... 1036 lda foo::bar ; Access foo in scope bar 1037</verb></tscreen> 1038 1039The only way to deny access to a scope from the outside is to declare a scope 1040without a name (using the <tt/<ref id=".SCOPE" name=".SCOPE">/ command). 1041 1042A special syntax is used to specify the global scope: If a symbol or scope is 1043preceded by the namespace token, the global scope is searched: 1044 1045<tscreen><verb> 1046 bar = 3 1047 1048 .scope foo 1049 bar = 2 1050 lda #::bar ; Access the global bar (which is 3) 1051 .endscope 1052</verb></tscreen> 1053 1054 1055<sect1>Scope search order<label id="scopesearch"><p> 1056 1057The assembler searches for a scope in a similar way as for a symbol. First, it 1058looks in the current scope, and then it walks up the enclosing scopes until 1059the scope is found. 1060 1061However, one important thing to note when using explicit scope syntax is, that 1062a symbol may be accessed before it is defined, but a scope may <bf/not/ be 1063used without a preceding definition. This means that in the following 1064example: 1065 1066<tscreen><verb> 1067 .scope foo 1068 bar = 3 1069 .endscope 1070 1071 .scope outer 1072 lda #foo::bar ; Will load 3, not 2! 1073 .scope foo 1074 bar = 2 1075 .endscope 1076 .endscope 1077</verb></tscreen> 1078 1079the reference to the scope <tt/foo/ will use the global scope, and not the 1080local one, because the local one is not visible at the point where it is 1081referenced. 1082 1083Things get more complex if a complete chain of scopes is specified: 1084 1085<tscreen><verb> 1086 .scope foo 1087 .scope outer 1088 .scope inner 1089 bar = 1 1090 .endscope 1091 .endscope 1092 .scope another 1093 .scope nested 1094 lda #outer::inner::bar ; 1 1095 .endscope 1096 .endscope 1097 .endscope 1098 1099 .scope outer 1100 .scope inner 1101 bar = 2 1102 .endscope 1103 .endscope 1104</verb></tscreen> 1105 1106When <tt/outer::inner::bar/ is referenced in the <tt/lda/ instruction, the 1107assembler will first search in the local scope for a scope named <tt/outer/. 1108Since none is found, the enclosing scope (<tt/another/) is checked. There is 1109still no scope named <tt/outer/, so scope <tt/foo/ is checked, and finally 1110scope <tt/outer/ is found. Within this scope, <tt/inner/ is searched, and in 1111this scope, the assembler looks for a symbol named <tt/bar/. 1112 1113Please note that once the anchor scope is found, all following scopes 1114(<tt/inner/ in this case) are expected to be found exactly in this scope. The 1115assembler will search the scope tree only for the first scope (if it is not 1116anchored in the root scope). Starting from there on, there is no flexibility, 1117so if the scope named <tt/outer/ found by the assembler does not contain a 1118scope named <tt/inner/, this would be an error, even if such a pair does exist 1119(one level up in global scope). 1120 1121Ambiguities that may be introduced by this search algorithm may be removed by 1122anchoring the scope specification in the global scope. In the example above, 1123if you want to access the "other" symbol <tt/bar/, you would have to write: 1124 1125<tscreen><verb> 1126 .scope foo 1127 .scope outer 1128 .scope inner 1129 bar = 1 1130 .endscope 1131 .endscope 1132 .scope another 1133 .scope nested 1134 lda #::outer::inner::bar ; 2 1135 .endscope 1136 .endscope 1137 .endscope 1138 1139 .scope outer 1140 .scope inner 1141 bar = 2 1142 .endscope 1143 .endscope 1144</verb></tscreen> 1145 1146 1147<sect>Address sizes and memory models<label id="address-sizes"><p> 1148 1149<sect1>Address sizes<p> 1150 1151ca65 assigns each segment and each symbol an address size. This is true, even 1152if the symbol is not used as an address. You may also think of a value range 1153of the symbol instead of an address size. 1154 1155Possible address sizes are: 1156 1157<itemize> 1158<item>Zeropage or direct (8 bits) 1159<item>Absolute (16 bits) 1160<item>Far (24 bits) 1161<item>Long (32 bits) 1162</itemize> 1163 1164Since the assembler uses default address sizes for the segments and symbols, 1165it is usually not necessary to override the default behaviour. In cases, where 1166it is necessary, the following keywords may be used to specify address sizes: 1167 1168<itemize> 1169<item>DIRECT, ZEROPAGE or ZP for zeropage addressing (8 bits). 1170<item>ABSOLUTE, ABS or NEAR for absolute addressing (16 bits). 1171<item>FAR for far addressing (24 bits). 1172<item>LONG or DWORD for long addressing (32 bits). 1173</itemize> 1174 1175 1176<sect1>Address sizes of segments<p> 1177 1178The assembler assigns an address size to each segment. Since the 1179representation of a label within this segment is "segment start + offset", 1180labels will inherit the address size of the segment they are declared in. 1181 1182The address size of a segment may be changed, by using an optional address 1183size modifier. See the <tt/<ref id=".SEGMENT" name="segment directive">/ for 1184an explanation on how this is done. 1185 1186 1187<sect1>Address sizes of symbols<p> 1188 1189The address size of a symbol can be specified with a prefix: 1190 1191<itemize> 1192<item>z: zeropage addressing (8 bits). 1193<item>a: absolute addressing (16 bits). 1194<item>f: far addressing (24 bits). 1195</itemize> 1196 1197The zeropage addressing override can be used to ensure the use of optimal 1198zeropage instructions, or correct cases where the size isn't yet known 1199due to the single-pass assembly model. 1200 1201The larger addressing overrides can be used to promote a smaller address 1202to absolute or far addressing, instead of being automatically fit into 1203a smaller addressing type. 1204 1205 1206<sect1>Memory models<p> 1207 1208The default address size of a segment depends on the memory model used. Since 1209labels inherit the address size from the segment they are declared in, 1210changing the memory model is an easy way to change the address size of many 1211symbols at once. 1212 1213 1214 1215 1216<sect>Pseudo variables<label id="pseudo-variables"><p> 1217 1218Pseudo variables are readable in all cases, and in some special cases also 1219writable. 1220 1221<sect1><tt>*</tt><p> 1222 1223 Reading this pseudo variable will return the program counter at the start 1224 of the current input line. 1225 1226 Assignment to this variable is possible when <tt/<ref id=".FEATURE" 1227 name=".FEATURE pc_assignment">/ is used. Note: You should not use 1228 assignments to <tt/*/, use <tt/<ref id=".ORG" name=".ORG">/ instead. 1229 1230 1231<sect1><tt>.ASIZE</tt><label id=".ASIZE"><p> 1232 1233 Reading this pseudo variable will return the current size of the 1234 Accumulator in bits. 1235 1236 For the 65816 instruction set .ASIZE will return either 8 or 16, depending 1237 on the current size of the operand in immediate accu addressing mode. 1238 1239 For all other CPU instruction sets, .ASIZE will always return 8. 1240 1241 Example: 1242 1243 <tscreen><verb> 1244 ; Reverse Subtract with Accumulator 1245 ; A = memory - A 1246 .macro rsb param 1247 .if .asize = 8 1248 eor #$ff 1249 .else 1250 eor #$ffff 1251 .endif 1252 sec 1253 adc param 1254 .endmacro 1255 </verb></tscreen> 1256 1257 See also: <tt><ref id=".ISIZE" name=".ISIZE"></tt> 1258 1259 1260<sect1><tt>.CPU</tt><label id=".CPU"><p> 1261 1262 Reading this pseudo variable will give a constant integer value that 1263 tells which CPU is currently enabled. It can also tell which instruction 1264 set the CPU is able to translate. The value read from the pseudo variable 1265 should be further examined by using one of the constants defined by the 1266 "cpu" macro package (see <tt/<ref id=".MACPACK" name=".MACPACK">/). 1267 1268 It may be used to replace the .IFPxx pseudo instructions or to construct 1269 even more complex expressions. 1270 1271 Example: 1272 1273 <tscreen><verb> 1274 .macpack cpu 1275 .if (.cpu .bitand CPU_ISET_65816) 1276 phx 1277 phy 1278 .else 1279 txa 1280 pha 1281 tya 1282 pha 1283 .endif 1284 </verb></tscreen> 1285 1286 1287<sect1><tt>.ISIZE</tt><label id=".ISIZE"><p> 1288 1289 Reading this pseudo variable will return the current size of the Index 1290 register in bits. 1291 1292 For the 65816 instruction set .ISIZE will return either 8 or 16, depending 1293 on the current size of the operand in immediate index addressing mode. 1294 1295 For all other CPU instruction sets, .ISIZE will always return 8. 1296 1297 See also: <tt><ref id=".ASIZE" name=".ASIZE"></tt> 1298 1299 1300<sect1><tt>.PARAMCOUNT</tt><label id=".PARAMCOUNT"><p> 1301 1302 This builtin pseudo variable is only available in macros. It is replaced by 1303 the actual number of parameters that were given in the macro invocation. 1304 1305 Example: 1306 1307 <tscreen><verb> 1308 .macro foo arg1, arg2, arg3 1309 .if .paramcount <> 3 1310 .error "Too few parameters for macro foo" 1311 .endif 1312 ... 1313 .endmacro 1314 </verb></tscreen> 1315 1316 See section <ref id="macros" name="Macros">. 1317 1318 1319<sect1><tt>.TIME</tt><label id=".TIME"><p> 1320 1321 Reading this pseudo variable will give a constant integer value that 1322 represents the current time in POSIX standard (as seconds since the 1323 Epoch). 1324 1325 It may be used to encode the time of translation somewhere in the created 1326 code. 1327 1328 Example: 1329 1330 <tscreen><verb> 1331 .dword .time ; Place time here 1332 </verb></tscreen> 1333 1334 1335<sect1><tt>.VERSION</tt><label id=".VERSION"><p> 1336 1337 Reading this pseudo variable will give the assembler version according to 1338 the following formula: 1339 1340 VER_MAJOR*$100 + VER_MINOR*$10 1341 1342 It may be used to encode the assembler version or check the assembler for 1343 special features not available with older versions. 1344 1345 Example: 1346 1347 Version 2.14 of the assembler will return $2E0 as numerical constant when 1348 reading the pseudo variable <tt/.VERSION/. 1349 1350 1351 1352<sect>Pseudo functions<label id="pseudo-functions"><p> 1353 1354Pseudo functions expect their arguments in parenthesis, and they have a result, 1355either a string or an expression. 1356 1357 1358<sect1><tt>.ADDRSIZE</tt><label id=".ADDRSIZE"><p> 1359 1360 The <tt/.ADDRSIZE/ function is used to return the interal address size 1361 associated with a symbol. This can be helpful in macros when knowing the address 1362 size of symbol can help with custom instructions. 1363 1364 Example: 1365 1366 <tscreen><verb> 1367 .macro myLDA foo 1368 .if .ADDRSIZE(foo) = 1 1369 ;do custom command based on zeropage addressing: 1370 .byte 0A5h, foo 1371 .elseif .ADDRSIZE(foo) = 2 1372 ;do custom command based on absolute addressing: 1373 .byte 0ADh 1374 .word foo 1375 .elseif .ADDRSIZE(foo) = 0 1376 ; no address size defined for this symbol: 1377 .out .sprintf("Error, address size unknown for symbol %s", .string(foo)) 1378 .endif 1379 .endmacro 1380 </verb></tscreen> 1381 1382 This command is new and must be enabled with the <tt/.FEATURE addrsize/ command. 1383 1384 See: <tt><ref id=".FEATURE" name=".FEATURE"></tt> 1385 1386 1387<sect1><tt>.BANK</tt><label id=".BANK"><p> 1388 1389 The <tt/.BANK/ function is used to support systems with banked memory. The 1390 argument is an expression with exactly one segment reference - usually a 1391 label. The function result is the value of the <tt/bank/ attribute assigned 1392 to the run memory area of the segment. Please see the linker documentation 1393 for more information about memory areas and their attributes. 1394 1395 The value of <tt/.BANK/ can be used to switch memory so that a memory bank 1396 containing specific data is available. 1397 1398 The <tt/bank/ attribute is a 32 bit integer and so is the result of the 1399 <tt/.BANK/ function. You will have to use <tt><ref id=".LOBYTE" 1400 name=".LOBYTE"></tt> or similar functions to address just part of it. 1401 1402 Please note that <tt/.BANK/ will always get evaluated in the link stage, so 1403 an expression containing <tt/.BANK/ can never be used where a constant known 1404 result is expected (for example with <tt/.RES/). 1405 1406 Example: 1407 1408 <tscreen><verb> 1409 .segment "BANK1" 1410 .proc banked_func_1 1411 ... 1412 .endproc 1413 1414 .segment "BANK2" 1415 .proc banked_func_2 1416 ... 1417 .endproc 1418 1419 .proc bank_table 1420 .addr banked_func_1 1421 .byte <.BANK (banked_func_1) 1422 1423 .addr banked_func_2 1424 .byte <.BANK (banked_func_2) 1425 .endproc 1426 </verb></tscreen> 1427 1428 1429 1430<sect1><tt>.BANKBYTE</tt><label id=".BANKBYTE"><p> 1431 1432 The function returns the bank byte (that is, bits 16-23) of its argument. 1433 It works identical to the '^' operator. 1434 1435 See: <tt><ref id=".HIBYTE" name=".HIBYTE"></tt>, 1436 <tt><ref id=".LOBYTE" name=".LOBYTE"></tt> 1437 1438 1439<sect1><tt>.BLANK</tt><label id=".BLANK"><p> 1440 1441 Builtin function. The function evaluates its argument in braces and yields 1442 "false" if the argument is non blank (there is an argument), and "true" if 1443 there is no argument. The token list that makes up the function argument 1444 may optionally be enclosed in curly braces. This allows the inclusion of 1445 tokens that would otherwise terminate the list (the closing right 1446 parenthesis). The curly braces are not considered part of the list, a list 1447 just consisting of curly braces is considered to be empty. 1448 1449 As an example, the <tt/.IFBLANK/ statement may be replaced by 1450 1451 <tscreen><verb> 1452 .if .blank({arg}) 1453 </verb></tscreen> 1454 1455 1456 1457<sect1><tt>.CONCAT</tt><label id=".CONCAT"><p> 1458 1459 Builtin string function. The function allows to concatenate a list of string 1460 constants separated by commas. The result is a string constant that is the 1461 concatenation of all arguments. This function is most useful in macros and 1462 when used together with the <tt/.STRING/ builtin function. The function may 1463 be used in any case where a string constant is expected. 1464 1465 Example: 1466 1467 <tscreen><verb> 1468 .include .concat ("myheader", ".", "inc") 1469 </verb></tscreen> 1470 1471 This is the same as the command 1472 1473 <tscreen><verb> 1474 .include "myheader.inc" 1475 </verb></tscreen> 1476 1477 1478<sect1><tt>.CONST</tt><label id=".CONST"><p> 1479 1480 Builtin function. The function evaluates its argument in braces and 1481 yields "true" if the argument is a constant expression (that is, an 1482 expression that yields a constant value at assembly time) and "false" 1483 otherwise. As an example, the .IFCONST statement may be replaced by 1484 1485 <tscreen><verb> 1486 .if .const(a + 3) 1487 </verb></tscreen> 1488 1489 1490<sect1><tt>.HIBYTE</tt><label id=".HIBYTE"><p> 1491 1492 The function returns the high byte (that is, bits 8-15) of its argument. 1493 It works identical to the '>' operator. 1494 1495 See: <tt><ref id=".LOBYTE" name=".LOBYTE"></tt>, 1496 <tt><ref id=".BANKBYTE" name=".BANKBYTE"></tt> 1497 1498 1499<sect1><tt>.HIWORD</tt><label id=".HIWORD"><p> 1500 1501 The function returns the high word (that is, bits 16-31) of its argument. 1502 1503 See: <tt><ref id=".LOWORD" name=".LOWORD"></tt> 1504 1505 1506<sect1><tt>.IDENT</tt><label id=".IDENT"><p> 1507 1508 The function expects a string as its argument, and converts this argument 1509 into an identifier. If the string starts with the current <tt/<ref 1510 id=".LOCALCHAR" name=".LOCALCHAR">/, it will be converted into a cheap local 1511 identifier, otherwise it will be converted into a normal identifier. 1512 1513 Example: 1514 1515 <tscreen><verb> 1516 .macro makelabel arg1, arg2 1517 .ident (.concat (arg1, arg2)): 1518 .endmacro 1519 1520 makelabel "foo", "bar" 1521 1522 .word foobar ; Valid label 1523 </verb></tscreen> 1524 1525 1526<sect1><tt>.LEFT</tt><label id=".LEFT"><p> 1527 1528 Builtin function. Extracts the left part of a given token list. 1529 1530 Syntax: 1531 1532 <tscreen><verb> 1533 .LEFT (<int expr>, <token list>) 1534 </verb></tscreen> 1535 1536 The first integer expression gives the number of tokens to extract from 1537 the token list. The second argument is the token list itself. The token 1538 list may optionally be enclosed into curly braces. This allows the 1539 inclusion of tokens that would otherwise terminate the list (the closing 1540 right paren in the given case). 1541 1542 Example: 1543 1544 To check in a macro if the given argument has a '#' as first token 1545 (immediate addressing mode), use something like this: 1546 1547 <tscreen><verb> 1548 .macro ldax arg 1549 ... 1550 .if (.match (.left (1, {arg}), #)) 1551 1552 ; ldax called with immediate operand 1553 ... 1554 1555 .endif 1556 ... 1557 .endmacro 1558 </verb></tscreen> 1559 1560 See also the <tt><ref id=".MID" name=".MID"></tt> and <tt><ref id=".RIGHT" 1561 name=".RIGHT"></tt> builtin functions. 1562 1563 1564<sect1><tt>.LOBYTE</tt><label id=".LOBYTE"><p> 1565 1566 The function returns the low byte (that is, bits 0-7) of its argument. 1567 It works identical to the '<' operator. 1568 1569 See: <tt><ref id=".HIBYTE" name=".HIBYTE"></tt>, 1570 <tt><ref id=".BANKBYTE" name=".BANKBYTE"></tt> 1571 1572 1573<sect1><tt>.LOWORD</tt><label id=".LOWORD"><p> 1574 1575 The function returns the low word (that is, bits 0-15) of its argument. 1576 1577 See: <tt><ref id=".HIWORD" name=".HIWORD"></tt> 1578 1579 1580<sect1><tt>.MATCH</tt><label id=".MATCH"><p> 1581 1582 Builtin function. Matches two token lists against each other. This is 1583 most useful within macros, since macros are not stored as strings, but 1584 as lists of tokens. 1585 1586 The syntax is 1587 1588 <tscreen><verb> 1589 .MATCH(<token list #1>, <token list #2>) 1590 </verb></tscreen> 1591 1592 Both token list may contain arbitrary tokens with the exception of the 1593 terminator token (comma resp. right parenthesis) and 1594 1595 <itemize> 1596 <item>end-of-line 1597 <item>end-of-file 1598 </itemize> 1599 1600 The token lists may optionally be enclosed into curly braces. This allows 1601 the inclusion of tokens that would otherwise terminate the list (the closing 1602 right paren in the given case). Often a macro parameter is used for any of 1603 the token lists. 1604 1605 Please note that the function does only compare tokens, not token 1606 attributes. So any number is equal to any other number, regardless of the 1607 actual value. The same is true for strings. If you need to compare tokens 1608 <em/and/ token attributes, use the <tt><ref id=".XMATCH" 1609 name=".XMATCH"></tt> function. 1610 1611 Example: 1612 1613 Assume the macro <tt/ASR/, that will shift right the accumulator by one, 1614 while honoring the sign bit. The builtin processor instructions will allow 1615 an optional "A" for accu addressing for instructions like <tt/ROL/ and 1616 <tt/ROR/. We will use the <tt><ref id=".MATCH" name=".MATCH"></tt> function 1617 to check for this and print and error for invalid calls. 1618 1619 <tscreen><verb> 1620 .macro asr arg 1621 1622 .if (.not .blank(arg)) .and (.not .match ({arg}, a)) 1623 .error "Syntax error" 1624 .endif 1625 1626 cmp #$80 ; Bit 7 into carry 1627 lsr a ; Shift carry into bit 7 1628 1629 .endmacro 1630 </verb></tscreen> 1631 1632 The macro will only accept no arguments, or one argument that must be the 1633 reserved keyword "A". 1634 1635 See: <tt><ref id=".XMATCH" name=".XMATCH"></tt> 1636 1637 1638<sect1><tt>.MAX</tt><label id=".MAX"><p> 1639 1640 Builtin function. The result is the larger of two values. 1641 1642 The syntax is 1643 1644 <tscreen><verb> 1645 .MAX (<value #1>, <value #2>) 1646 </verb></tscreen> 1647 1648 Example: 1649 1650 <tscreen><verb> 1651 ; Reserve space for the larger of two data blocks 1652 savearea: .res .max (.sizeof (foo), .sizeof (bar)) 1653 </verb></tscreen> 1654 1655 See: <tt><ref id=".MIN" name=".MIN"></tt> 1656 1657 1658<sect1><tt>.MID</tt><label id=".MID"><p> 1659 1660 Builtin function. Takes a starting index, a count and a token list as 1661 arguments. Will return part of the token list. 1662 1663 Syntax: 1664 1665 <tscreen><verb> 1666 .MID (<int expr>, <int expr>, <token list>) 1667 </verb></tscreen> 1668 1669 The first integer expression gives the starting token in the list (the first 1670 token has index 0). The second integer expression gives the number of tokens 1671 to extract from the token list. The third argument is the token list itself. 1672 The token list may optionally be enclosed into curly braces. This allows the 1673 inclusion of tokens that would otherwise terminate the list (the closing 1674 right paren in the given case). 1675 1676 Example: 1677 1678 To check in a macro if the given argument has a '<tt/#/' as first token 1679 (immediate addressing mode), use something like this: 1680 1681 <tscreen><verb> 1682 .macro ldax arg 1683 ... 1684 .if (.match (.mid (0, 1, {arg}), #)) 1685 1686 ; ldax called with immediate operand 1687 ... 1688 1689 .endif 1690 ... 1691 .endmacro 1692 </verb></tscreen> 1693 1694 See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".RIGHT" 1695 name=".RIGHT"></tt> builtin functions. 1696 1697 1698<sect1><tt>.MIN</tt><label id=".MIN"><p> 1699 1700 Builtin function. The result is the smaller of two values. 1701 1702 The syntax is 1703 1704 <tscreen><verb> 1705 .MIN (<value #1>, <value #2>) 1706 </verb></tscreen> 1707 1708 Example: 1709 1710 <tscreen><verb> 1711 ; Reserve space for some data, but 256 bytes maximum 1712 savearea: .res .min (.sizeof (foo), 256) 1713 </verb></tscreen> 1714 1715 See: <tt><ref id=".MAX" name=".MAX"></tt> 1716 1717 1718<sect1><tt>.REF, .REFERENCED</tt><label id=".REFERENCED"><p> 1719 1720 Builtin function. The function expects an identifier as argument in braces. 1721 The argument is evaluated, and the function yields "true" if the identifier 1722 is a symbol that has already been referenced somewhere in the source file up 1723 to the current position. Otherwise the function yields false. As an example, 1724 the <tt><ref id=".IFREF" name=".IFREF"></tt> statement may be replaced by 1725 1726 <tscreen><verb> 1727 .if .referenced(a) 1728 </verb></tscreen> 1729 1730 See: <tt><ref id=".DEFINED" name=".DEFINED"></tt> 1731 1732 1733<sect1><tt>.RIGHT</tt><label id=".RIGHT"><p> 1734 1735 Builtin function. Extracts the right part of a given token list. 1736 1737 Syntax: 1738 1739 <tscreen><verb> 1740 .RIGHT (<int expr>, <token list>) 1741 </verb></tscreen> 1742 1743 The first integer expression gives the number of tokens to extract from the 1744 token list. The second argument is the token list itself. The token list 1745 may optionally be enclosed into curly braces. This allows the inclusion of 1746 tokens that would otherwise terminate the list (the closing right paren in 1747 the given case). 1748 1749 See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".MID" 1750 name=".MID"></tt> builtin functions. 1751 1752 1753<sect1><tt>.SIZEOF</tt><label id=".SIZEOF"><p> 1754 1755 <tt/.SIZEOF()/ is a pseudo function that returns the size of its argument. 1756 The argument can be a struct/union, a struct member, a scope/procedure, or a 1757 label. In the case of a procedure or label, its size is defined by the 1758 amount of data placed in the segment where the label is relative to. If a 1759 line of code switches segments (for example, in a macro), data placed in 1760 other segments does not count for the size. 1761 1762 Please note that a symbol or scope must exist before it can be used together 1763 with <tt/.SIZEOF()/ (that may get relaxed later, but always will be true for 1764 scopes). A scope has preference over a symbol with the same name; so, if the 1765 last part of a name represents both a scope and a symbol, then the scope is 1766 chosen over the symbol. 1767 1768 After the following code: 1769 1770 <tscreen><verb> 1771 .struct Point ; Struct size = 4 1772 xcoord .word 1773 ycoord .word 1774 .endstruct 1775 1776 P: .tag Point ; Declare a point 1777 @P: .tag Point ; Declare another point 1778 1779 .code 1780 .proc Code 1781 nop 1782 .proc Inner 1783 nop 1784 .endproc 1785 nop 1786 .endproc 1787 1788 .proc Data 1789 .data ; Segment switch!!! 1790 .res 4 1791 .endproc 1792 </verb></tscreen> 1793 1794 <descrip> 1795 <tag><tt/.sizeof(Point)/</tag> 1796 will have the value 4, because this is the size of struct <tt/Point/. 1797 1798 <tag><tt/.sizeof(Point::xcoord)/</tag> 1799 will have the value 2, because this is the size of the member <tt/xcoord/ 1800 in struct <tt/Point/. 1801 1802 <tag><tt/.sizeof(P)/</tag> 1803 will have the value 4, this is the size of the data declared on the same 1804 source line as the label <tt/P/, which is in the same segment that <tt/P/ 1805 is relative to. 1806 1807 <tag><tt/.sizeof(@P)/</tag> 1808 will have the value 4, see above. The example demonstrates that <tt/.SIZEOF/ 1809 does also work for cheap local symbols. 1810 1811 <tag><tt/.sizeof(Code)/</tag> 1812 will have the value 3, since this is amount of data emitted into the code 1813 segment, the segment that was active when <tt/Code/ was entered. Note that 1814 this value includes the amount of data emitted in child scopes (in this 1815 case <tt/Code::Inner/). 1816 1817 <tag><tt/.sizeof(Code::Inner)/</tag> 1818 will have the value 1 as expected. 1819 1820 <tag><tt/.sizeof(Data)/</tag> 1821 will have the value 0. Data is emitted within the scope <tt/Data/, but since 1822 the segment is switched after entry, this data is emitted into another 1823 segment. 1824 </descrip> 1825 1826 1827<sect1><tt>.STRAT</tt><label id=".STRAT"><p> 1828 1829 Builtin function. The function accepts a string and an index as 1830 arguments and returns the value of the character at the given position 1831 as an integer value. The index is zero based. 1832 1833 Example: 1834 1835 <tscreen><verb> 1836 .macro M Arg 1837 ; Check if the argument string starts with '#' 1838 .if (.strat (Arg, 0) = '#') 1839 ... 1840 .endif 1841 .endmacro 1842 </verb></tscreen> 1843 1844 1845<sect1><tt>.SPRINTF</tt><label id=".SPRINTF"><p> 1846 1847 Builtin function. It expects a format string as first argument. The number 1848 and type of the following arguments depend on the format string. The format 1849 string is similar to the one of the C <tt/printf/ function. Missing things 1850 are: Length modifiers, variable width. 1851 1852 The result of the function is a string. 1853 1854 Example: 1855 1856 <tscreen><verb> 1857 num = 3 1858 1859 ; Generate an identifier: 1860 .ident (.sprintf ("%s%03d", "label", num)): 1861 </verb></tscreen> 1862 1863 1864<sect1><tt>.STRING</tt><label id=".STRING"><p> 1865 1866 Builtin function. The function accepts an argument in braces and converts 1867 this argument into a string constant. The argument may be an identifier, or 1868 a constant numeric value. 1869 1870 Since you can use a string in the first place, the use of the function may 1871 not be obvious. However, it is useful in macros, or more complex setups. 1872 1873 Example: 1874 1875 <tscreen><verb> 1876 ; Emulate other assemblers: 1877 .macro section name 1878 .segment .string(name) 1879 .endmacro 1880 </verb></tscreen> 1881 1882 1883<sect1><tt>.STRLEN</tt><label id=".STRLEN"><p> 1884 1885 Builtin function. The function accepts a string argument in braces and 1886 evaluates to the length of the string. 1887 1888 Example: 1889 1890 The following macro encodes a string as a pascal style string with 1891 a leading length byte. 1892 1893 <tscreen><verb> 1894 .macro PString Arg 1895 .byte .strlen(Arg), Arg 1896 .endmacro 1897 </verb></tscreen> 1898 1899 1900<sect1><tt>.TCOUNT</tt><label id=".TCOUNT"><p> 1901 1902 Builtin function. The function accepts a token list in braces. The function 1903 result is the number of tokens given as argument. The token list may 1904 optionally be enclosed into curly braces which are not considered part of 1905 the list and not counted. Enclosement in curly braces allows the inclusion 1906 of tokens that would otherwise terminate the list (the closing right paren 1907 in the given case). 1908 1909 Example: 1910 1911 The <tt/ldax/ macro accepts the '#' token to denote immediate addressing (as 1912 with the normal 6502 instructions). To translate it into two separate 8 bit 1913 load instructions, the '#' token has to get stripped from the argument: 1914 1915 <tscreen><verb> 1916 .macro ldax arg 1917 .if (.match (.mid (0, 1, {arg}), #)) 1918 ; ldax called with immediate operand 1919 lda #<(.right (.tcount ({arg})-1, {arg})) 1920 ldx #>(.right (.tcount ({arg})-1, {arg})) 1921 .else 1922 ... 1923 .endif 1924 .endmacro 1925 </verb></tscreen> 1926 1927 1928<sect1><tt>.XMATCH</tt><label id=".XMATCH"><p> 1929 1930 Builtin function. Matches two token lists against each other. This is 1931 most useful within macros, since macros are not stored as strings, but 1932 as lists of tokens. 1933 1934 The syntax is 1935 1936 <tscreen><verb> 1937 .XMATCH(<token list #1>, <token list #2>) 1938 </verb></tscreen> 1939 1940 Both token list may contain arbitrary tokens with the exception of the 1941 terminator token (comma resp. right parenthesis) and 1942 1943 <itemize> 1944 <item>end-of-line 1945 <item>end-of-file 1946 </itemize> 1947 1948 The token lists may optionally be enclosed into curly braces. This allows 1949 the inclusion of tokens that would otherwise terminate the list (the closing 1950 right paren in the given case). Often a macro parameter is used for any of 1951 the token lists. 1952 1953 The function compares tokens <em/and/ token values. If you need a function 1954 that just compares the type of tokens, have a look at the <tt><ref 1955 id=".MATCH" name=".MATCH"></tt> function. 1956 1957 See: <tt><ref id=".MATCH" name=".MATCH"></tt> 1958 1959 1960 1961<sect>Control commands<label id="control-commands"><p> 1962 1963Here's a list of all control commands and a description, what they do: 1964 1965 1966<sect1><tt>.A16</tt><label id=".A16"><p> 1967 1968 Valid only in 65816 mode. Switch the accumulator to 16 bit. 1969 1970 Note: This command will not emit any code, it will tell the assembler to 1971 create 16 bit operands for immediate accumulator addressing mode. 1972 1973 See also: <tt><ref id=".SMART" name=".SMART"></tt> 1974 1975 1976<sect1><tt>.A8</tt><label id=".A8"><p> 1977 1978 Valid only in 65816 mode. Switch the accumulator to 8 bit. 1979 1980 Note: This command will not emit any code, it will tell the assembler to 1981 create 8 bit operands for immediate accu addressing mode. 1982 1983 See also: <tt><ref id=".SMART" name=".SMART"></tt> 1984 1985 1986<sect1><tt>.ADDR</tt><label id=".ADDR"><p> 1987 1988 Define word sized data. In 6502 mode, this is an alias for <tt/.WORD/ and 1989 may be used for better readability if the data words are address values. In 1990 65816 mode, the address is forced to be 16 bit wide to fit into the current 1991 segment. See also <tt><ref id=".FARADDR" name=".FARADDR"></tt>. The command 1992 must be followed by a sequence of (not necessarily constant) expressions. 1993 1994 Example: 1995 1996 <tscreen><verb> 1997 .addr $0D00, $AF13, _Clear 1998 </verb></tscreen> 1999 2000 See: <tt><ref id=".FARADDR" name=".FARADDR"></tt>, <tt><ref id=".WORD" 2001 name=".WORD"></tt> 2002 2003 2004<sect1><tt>.ALIGN</tt><label id=".ALIGN"><p> 2005 2006 Align data to a given boundary. The command expects a constant integer 2007 argument in the range 1 ... 65536, plus an optional second argument 2008 in byte range. If there is a second argument, it is used as fill value, 2009 otherwise the value defined in the linker configuration file is used 2010 (the default for this value is zero). 2011 2012 <tt/.ALIGN/ will insert fill bytes, and the number of fill bytes depend of 2013 the final address of the segment. <tt/.ALIGN/ cannot insert a variable 2014 number of bytes, since that would break address calculations within the 2015 module. So each <tt/.ALIGN/ expects the segment to be aligned to a multiple 2016 of the alignment, because that allows the number of fill bytes to be 2017 calculated in advance by the assembler. You are therefore required to 2018 specify a matching alignment for the segment in the linker config. The 2019 linker will output a warning if the alignment of the segment is less than 2020 what is necessary to have a correct alignment in the object file. 2021 2022 Example: 2023 2024 <tscreen><verb> 2025 .align 256 2026 </verb></tscreen> 2027 2028 Some unexpected behaviour might occur if there are multiple <tt/.ALIGN/ 2029 commands with different arguments. To allow the assembler to calculate the 2030 number of fill bytes in advance, the alignment of the segment must be a 2031 multiple of each of the alignment factors. This may result in unexpectedly 2032 large alignments for the segment within the module. 2033 2034 Example: 2035 2036 <tscreen><verb> 2037 .align 15 2038 .byte 15 2039 .align 18 2040 .byte 18 2041 </verb></tscreen> 2042 2043 For the assembler to be able to align correctly, the segment must be aligned 2044 to the least common multiple of 15 and 18 which is 90. The assembler will 2045 calculate this automatically and will mark the segment with this value. 2046 2047 Unfortunately, the combined alignment may get rather large without the user 2048 knowing about it, wasting space in the final executable. If we add another 2049 alignment to the example above 2050 2051 <tscreen><verb> 2052 .align 15 2053 .byte 15 2054 .align 18 2055 .byte 18 2056 .align 251 2057 .byte 0 2058 </verb></tscreen> 2059 2060 the assembler will force a segment alignment to the least common multiple of 2061 15, 18 and 251 - which is 22590. To protect the user against errors, the 2062 assembler will issue a warning when the combined alignment exceeds 256. The 2063 command line option <tt><ref id="option--large-alignment" 2064 name="--large-alignment"></tt> will disable this warning. 2065 2066 Please note that with alignments that are a power of two (which were the 2067 only alignments possible in older versions of the assembler), the problem is 2068 less severe, because the least common multiple of powers to the same base is 2069 always the larger one. 2070 2071 2072 2073<sect1><tt>.ASCIIZ</tt><label id=".ASCIIZ"><p> 2074 2075 Define a string with a trailing zero. 2076 2077 Example: 2078 2079 <tscreen><verb> 2080 Msg: .asciiz "Hello world" 2081 </verb></tscreen> 2082 2083 This will put the string "Hello world" followed by a binary zero into 2084 the current segment. There may be more strings separated by commas, but 2085 the binary zero is only appended once (after the last one). 2086 2087 2088<sect1><tt>.ASSERT</tt><label id=".ASSERT"><p> 2089 2090 Add an assertion. The command is followed by an expression, an action 2091 specifier, and an optional message that is output in case the assertion 2092 fails. If no message was given, the string "Assertion failed" is used. The 2093 action specifier may be one of <tt/warning/, <tt/error/, <tt/ldwarning/ or 2094 <tt/lderror/. In the former two cases, the assertion is evaluated by the 2095 assembler if possible, and in any case, it's also passed to the linker in 2096 the object file (if one is generated). The linker will then evaluate the 2097 expression when segment placement has been done. 2098 2099 Example: 2100 2101 <tscreen><verb> 2102 .assert * = $8000, error, "Code not at $8000" 2103 </verb></tscreen> 2104 2105 The example assertion will check that the current location is at $8000, 2106 when the output file is written, and abort with an error if this is not 2107 the case. More complex expressions are possible. The action specifier 2108 <tt/warning/ outputs a warning, while the <tt/error/ specifier outputs 2109 an error message. In the latter case, generation of the output file is 2110 suppressed in both the assembler and linker. 2111 2112 2113<sect1><tt>.AUTOIMPORT</tt><label id=".AUTOIMPORT"><p> 2114 2115 Is followed by a plus or a minus character. When switched on (using a 2116 +), undefined symbols are automatically marked as import instead of 2117 giving errors. When switched off (which is the default so this does not 2118 make much sense), this does not happen and an error message is 2119 displayed. The state of the autoimport flag is evaluated when the 2120 complete source was translated, before outputting actual code, so it is 2121 <em/not/ possible to switch this feature on or off for separate sections 2122 of code. The last setting is used for all symbols. 2123 2124 You should probably not use this switch because it delays error 2125 messages about undefined symbols until the link stage. The cc65 2126 compiler (which is supposed to produce correct assembler code in all 2127 circumstances, something which is not true for most assembler 2128 programmers) will insert this command to avoid importing each and every 2129 routine from the runtime library. 2130 2131 Example: 2132 2133 <tscreen><verb> 2134 .autoimport + ; Switch on auto import 2135 </verb></tscreen> 2136 2137<sect1><tt>.BANKBYTES</tt><label id=".BANKBYTES"><p> 2138 2139 Define byte sized data by extracting only the bank byte (that is, bits 16-23) from 2140 each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with 2141 the operator '^' prepended to each expression in its list. 2142 2143 Example: 2144 2145 <tscreen><verb> 2146 .define MyTable TableItem0, TableItem1, TableItem2, TableItem3 2147 2148 TableLookupLo: .lobytes MyTable 2149 TableLookupHi: .hibytes MyTable 2150 TableLookupBank: .bankbytes MyTable 2151 </verb></tscreen> 2152 2153 which is equivalent to 2154 2155 <tscreen><verb> 2156 TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3 2157 TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 2158 TableLookupBank: .byte ^TableItem0, ^TableItem1, ^TableItem2, ^TableItem3 2159 </verb></tscreen> 2160 2161 See also: <tt><ref id=".BYTE" name=".BYTE"></tt>, 2162 <tt><ref id=".HIBYTES" name=".HIBYTES"></tt>, 2163 <tt><ref id=".LOBYTES" name=".LOBYTES"></tt> 2164 2165 2166<sect1><tt>.BSS</tt><label id=".BSS"><p> 2167 2168 Switch to the BSS segment. The name of the BSS segment is always "BSS", 2169 so this is a shortcut for 2170 2171 <tscreen><verb> 2172 .segment "BSS" 2173 </verb></tscreen> 2174 2175 See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. 2176 2177 2178<sect1><tt>.BYT, .BYTE</tt><label id=".BYTE"><p> 2179 2180 Define byte sized data. Must be followed by a sequence of (byte ranged) 2181 expressions or strings. 2182 2183 Example: 2184 2185 <tscreen><verb> 2186 .byte "Hello " 2187 .byt "world", $0D, $00 2188 </verb></tscreen> 2189 2190 2191<sect1><tt>.CASE</tt><label id=".CASE"><p> 2192 2193 Switch on or off case sensitivity on identifiers. The default is off 2194 (that is, identifiers are case sensitive), but may be changed by the 2195 -i switch on the command line. 2196 The command must be followed by a '+' or '-' character to switch the 2197 option on or off respectively. 2198 2199 Example: 2200 2201 <tscreen><verb> 2202 .case - ; Identifiers are not case sensitive 2203 </verb></tscreen> 2204 2205 2206<sect1><tt>.CHARMAP</tt><label id=".CHARMAP"><p> 2207 2208 Apply a custom mapping for characters. The command is followed by two 2209 numbers. The first one is the index of the source character (range 0..255); 2210 the second one is the mapping (range 0..255). The mapping applies to all 2211 character and string constants <em/when/ they generate output; and, overrides 2212 a mapping table specified with the <tt><ref id="option-t" name="-t"></tt> 2213 command line switch. 2214 2215 Example: 2216 <tscreen><verb> 2217 .charmap $41, $61 ; Map 'A' to 'a' 2218 </verb></tscreen> 2219 2220 2221<sect1><tt>.CODE</tt><label id=".CODE"><p> 2222 2223 Switch to the CODE segment. The name of the CODE segment is always 2224 "CODE", so this is a shortcut for 2225 2226 <tscreen><verb> 2227 .segment "CODE" 2228 </verb></tscreen> 2229 2230 See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. 2231 2232 2233<sect1><tt>.CONDES</tt><label id=".CONDES"><p> 2234 2235 Export a symbol and mark it in a special way. The linker is able to build 2236 tables of all such symbols. This may be used to automatically create a list 2237 of functions needed to initialize linked library modules. 2238 2239 Note: The linker has a feature to build a table of marked routines, but it 2240 is your code that must call these routines, so just declaring a symbol with 2241 <tt/.CONDES/ does nothing by itself. 2242 2243 All symbols are exported as an absolute (16 bit) symbol. You don't need to 2244 use an additional <tt><ref id=".EXPORT" name=".EXPORT"></tt> statement, this 2245 is implied by <tt/.CONDES/. 2246 2247 <tt/.CONDES/ is followed by the type, which may be <tt/constructor/, 2248 <tt/destructor/ or a numeric value between 0 and 6 (where 0 is the same as 2249 specifying <tt/constructor/ and 1 is equal to specifying <tt/destructor/). 2250 The <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref 2251 id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR" 2252 name=".INTERRUPTOR"></tt> commands are actually shortcuts for <tt/.CONDES/ 2253 with a type of <tt/constructor/ resp. <tt/destructor/ or <tt/interruptor/. 2254 2255 After the type, an optional priority may be specified. Higher numeric values 2256 mean higher priority. If no priority is given, the default priority of 7 is 2257 used. Be careful when assigning priorities to your own module constructors 2258 so they won't interfere with the ones in the cc65 library. 2259 2260 Example: 2261 2262 <tscreen><verb> 2263 .condes ModuleInit, constructor 2264 .condes ModInit, 0, 16 2265 </verb></tscreen> 2266 2267 See the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref 2268 id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR" 2269 name=".INTERRUPTOR"></tt> commands and the separate section <ref id="condes" 2270 name="Module constructors/destructors"> explaining the feature in more 2271 detail. 2272 2273 2274<sect1><tt>.CONSTRUCTOR</tt><label id=".CONSTRUCTOR"><p> 2275 2276 Export a symbol and mark it as a module constructor. This may be used 2277 together with the linker to build a table of constructor subroutines that 2278 are called by the startup code. 2279 2280 Note: The linker has a feature to build a table of marked routines, but it 2281 is your code that must call these routines, so just declaring a symbol as 2282 constructor does nothing by itself. 2283 2284 A constructor is always exported as an absolute (16 bit) symbol. You don't 2285 need to use an additional <tt/.export/ statement, this is implied by 2286 <tt/.constructor/. It may have an optional priority that is separated by a 2287 comma. Higher numeric values mean a higher priority. If no priority is 2288 given, the default priority of 7 is used. Be careful when assigning 2289 priorities to your own module constructors so they won't interfere with the 2290 ones in the cc65 library. 2291 2292 Example: 2293 2294 <tscreen><verb> 2295 .constructor ModuleInit 2296 .constructor ModInit, 16 2297 </verb></tscreen> 2298 2299 See the <tt><ref id=".CONDES" name=".CONDES"></tt> and <tt><ref 2300 id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> commands and the separate section 2301 <ref id="condes" name="Module constructors/destructors"> explaining the 2302 feature in more detail. 2303 2304 2305<sect1><tt>.DATA</tt><label id=".DATA"><p> 2306 2307 Switch to the DATA segment. The name of the DATA segment is always 2308 "DATA", so this is a shortcut for 2309 2310 <tscreen><verb> 2311 .segment "DATA" 2312 </verb></tscreen> 2313 2314 See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. 2315 2316 2317<sect1><tt>.DBYT</tt><label id=".DBYT"><p> 2318 2319 Define word sized data with the hi and lo bytes swapped (use <tt/.WORD/ to 2320 create word sized data in native 65XX format). Must be followed by a 2321 sequence of (word ranged) expressions. 2322 2323 Example: 2324 2325 <tscreen><verb> 2326 .dbyt $1234, $4512 2327 </verb></tscreen> 2328 2329 This will emit the bytes 2330 2331 <tscreen><verb> 2332 $12 $34 $45 $12 2333 </verb></tscreen> 2334 2335 into the current segment in that order. 2336 2337 2338<sect1><tt>.DEBUGINFO</tt><label id=".DEBUGINFO"><p> 2339 2340 Switch on or off debug info generation. The default is off (that is, 2341 the object file will not contain debug infos), but may be changed by the 2342 -g switch on the command line. 2343 The command must be followed by a '+' or '-' character to switch the 2344 option on or off respectively. 2345 2346 Example: 2347 2348 <tscreen><verb> 2349 .debuginfo + ; Generate debug info 2350 </verb></tscreen> 2351 2352 2353<sect1><tt>.DEFINE</tt><label id=".DEFINE"><p> 2354 2355 Start a define style macro definition. The command is followed by an 2356 identifier (the macro name) and optionally by a list of formal arguments 2357 in braces. 2358 2359 Please note that <tt/.DEFINE/ shares most disadvantages with its C 2360 counterpart, so the general advice is, <bf/NOT/ do use <tt/.DEFINE/ if you 2361 don't have to. 2362 2363 See also the <tt><ref id=".UNDEFINE" name=".UNDEFINE"></tt> command and 2364 section <ref id="macros" name="Macros">. 2365 2366 2367<sect1><tt>.DELMAC, .DELMACRO</tt><label id=".DELMACRO"><p> 2368 2369 Delete a classic macro (defined with <tt><ref id=".MACRO" 2370 name=".MACRO"></tt>) . The command is followed by the name of an 2371 existing macro. Its definition will be deleted together with the name. 2372 If necessary, another macro with this name may be defined later. 2373 2374 See: <tt><ref id=".ENDMACRO" name=".ENDMACRO"></tt>, 2375 <tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt>, 2376 <tt><ref id=".MACRO" name=".MACRO"></tt> 2377 2378 See also section <ref id="macros" name="Macros">. 2379 2380 2381<sect1><tt>.DEF, .DEFINED</tt><label id=".DEFINED"><p> 2382 2383 Builtin function. The function expects an identifier as argument in braces. 2384 The argument is evaluated, and the function yields "true" if the identifier 2385 is a symbol that is already defined somewhere in the source file up to the 2386 current position. Otherwise the function yields false. As an example, the 2387 <tt><ref id=".IFDEF" name=".IFDEF"></tt> statement may be replaced by 2388 2389 <tscreen><verb> 2390 .if .defined(a) 2391 </verb></tscreen> 2392 2393 2394<sect1><tt>.DEFINEDMACRO</tt><label id=".DEFINEDMACRO"><p> 2395 2396 Builtin function. The function expects an identifier as argument in braces. 2397 The argument is evaluated, and the function yields "true" if the identifier 2398 has already been defined as the name of a macro. Otherwise the function yields 2399 false. Example: 2400 2401 <tscreen><verb> 2402 .macro add foo 2403 clc 2404 adc foo 2405 .endmacro 2406 2407 .if .definedmacro(add) 2408 add #$01 2409 .else 2410 clc 2411 adc #$01 2412 .endif 2413 </verb></tscreen> 2414 2415 2416<sect1><tt>.DESTRUCTOR</tt><label id=".DESTRUCTOR"><p> 2417 2418 Export a symbol and mark it as a module destructor. This may be used 2419 together with the linker to build a table of destructor subroutines that 2420 are called by the startup code. 2421 2422 Note: The linker has a feature to build a table of marked routines, but it 2423 is your code that must call these routines, so just declaring a symbol as 2424 constructor does nothing by itself. 2425 2426 A destructor is always exported as an absolute (16 bit) symbol. You don't 2427 need to use an additional <tt/.export/ statement, this is implied by 2428 <tt/.destructor/. It may have an optional priority that is separated by a 2429 comma. Higher numerical values mean a higher priority. If no priority is 2430 given, the default priority of 7 is used. Be careful when assigning 2431 priorities to your own module destructors so they won't interfere with the 2432 ones in the cc65 library. 2433 2434 Example: 2435 2436 <tscreen><verb> 2437 .destructor ModuleDone 2438 .destructor ModDone, 16 2439 </verb></tscreen> 2440 2441 See the <tt><ref id=".CONDES" name=".CONDES"></tt> and <tt><ref 2442 id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> commands and the separate 2443 section <ref id="condes" name="Module constructors/destructors"> explaining 2444 the feature in more detail. 2445 2446 2447<sect1><tt>.DWORD</tt><label id=".DWORD"><p> 2448 2449 Define dword sized data (4 bytes) Must be followed by a sequence of 2450 expressions. 2451 2452 Example: 2453 2454 <tscreen><verb> 2455 .dword $12344512, $12FA489 2456 </verb></tscreen> 2457 2458 2459<sect1><tt>.ELSE</tt><label id=".ELSE"><p> 2460 2461 Conditional assembly: Reverse the current condition. 2462 2463 2464<sect1><tt>.ELSEIF</tt><label id=".ELSEIF"><p> 2465 2466 Conditional assembly: Reverse current condition and test a new one. 2467 2468 2469<sect1><tt>.END</tt><label id=".END"><p> 2470 2471 Forced end of assembly. Assembly stops at this point, even if the command 2472 is read from an include file. 2473 2474 2475<sect1><tt>.ENDENUM</tt><label id=".ENDENUM"><p> 2476 2477 End a <tt><ref id=".ENUM" name=".ENUM"></tt> declaration. 2478 2479 2480<sect1><tt>.ENDIF</tt><label id=".ENDIF"><p> 2481 2482 Conditional assembly: Close a <tt><ref id=".IF" name=".IF..."></tt> or 2483 <tt><ref id=".ELSE" name=".ELSE"></tt> branch. 2484 2485 2486<sect1><tt>.ENDMAC, .ENDMACRO</tt><label id=".ENDMACRO"><p> 2487 2488 Marks the end of a macro definition. 2489 2490 See: <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, 2491 <tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt>, 2492 <tt><ref id=".MACRO" name=".MACRO"></tt> 2493 2494 See also section <ref id="macros" name="Macros">. 2495 2496 2497<sect1><tt>.ENDPROC</tt><label id=".ENDPROC"><p> 2498 2499 End of the local lexical level (see <tt><ref id=".PROC" name=".PROC"></tt>). 2500 2501 2502<sect1><tt>.ENDREP, .ENDREPEAT</tt><label id=".ENDREPEAT"><p> 2503 2504 End a <tt><ref id=".REPEAT" name=".REPEAT"></tt> block. 2505 2506 2507<sect1><tt>.ENDSCOPE</tt><label id=".ENDSCOPE"><p> 2508 2509 End of the local lexical level (see <tt/<ref id=".SCOPE" name=".SCOPE">/). 2510 2511 2512<sect1><tt>.ENDSTRUCT</tt><label id=".ENDSTRUCT"><p> 2513 2514 Ends a struct definition. See the <tt/<ref id=".STRUCT" name=".STRUCT">/ 2515 command and the separate section named <ref id="structs" name=""Structs 2516 and unions"">. 2517 2518 2519<sect1><tt>.ENDUNION</tt><label id=".ENDUNION"><p> 2520 2521 Ends a union definition. See the <tt/<ref id=".UNION" name=".UNION">/ 2522 command and the separate section named <ref id="structs" name=""Structs 2523 and unions"">. 2524 2525 2526<sect1><tt>.ENUM</tt><label id=".ENUM"><p> 2527 2528 Start an enumeration. This directive is very similar to the C <tt/enum/ 2529 keyword. If a name is given, a new scope is created for the enumeration, 2530 otherwise the enumeration members are placed in the enclosing scope. 2531 2532 In the enumeration body, symbols are declared. The first symbol has a value 2533 of zero, and each following symbol will get the value of the preceding, plus 2534 one. That behaviour may be overridden by an explicit assignment. Two symbols 2535 may have the same value. 2536 2537 Example: 2538 2539 <tscreen><verb> 2540 .enum errorcodes 2541 no_error 2542 file_error 2543 parse_error 2544 .endenum 2545 </verb></tscreen> 2546 2547 The above example will create a new scope named <tt/errorcodes/ with three 2548 symbols in it that get the values 0, 1, and 2 respectively. Another way 2549 to write that would have been: 2550 2551 <tscreen><verb> 2552 .scope errorcodes 2553 no_error = 0 2554 file_error = 1 2555 parse_error = 2 2556 .endscope 2557 </verb></tscreen> 2558 2559 Please note that explicit scoping must be used to access the identifiers: 2560 2561 <tscreen><verb> 2562 .word errorcodes::no_error 2563 </verb></tscreen> 2564 2565 A more complex example: 2566 2567 <tscreen><verb> 2568 .enum 2569 EUNKNOWN = -1 2570 EOK 2571 EFILE 2572 EBUSY 2573 EAGAIN 2574 EWOULDBLOCK = EAGAIN 2575 .endenum 2576 </verb></tscreen> 2577 2578 In that example, the enumeration does not have a name, which means that the 2579 members will be visible in the enclosing scope, and can be used in that scope 2580 without explicit scoping. The first member (<tt/EUNKNOWN/) has the value -1. 2581 The values for the following members are incremented by one; so, <tt/EOK/ 2582 would be zero, and so on. <tt/EWOULDBLOCK/ is an alias for <tt/EAGAIN/; so, 2583 it has an override for the value, using an already defined symbol. 2584 2585 2586<sect1><tt>.ERROR</tt><label id=".ERROR"><p> 2587 2588 Force an assembly error. The assembler will output an error message 2589 preceded by "User error". Assembly is continued but no object file will 2590 generated. 2591 2592 This command may be used to check for initial conditions that must be 2593 set before assembling a source file. 2594 2595 Example: 2596 2597 <tscreen><verb> 2598 .if foo = 1 2599 ... 2600 .elseif bar = 1 2601 ... 2602 .else 2603 .error "Must define foo or bar!" 2604 .endif 2605 </verb></tscreen> 2606 2607 See also: <tt><ref id=".FATAL" name=".FATAL"></tt>, 2608 <tt><ref id=".OUT" name=".OUT"></tt>, 2609 <tt><ref id=".WARNING" name=".WARNING"></tt> 2610 2611 2612<sect1><tt>.EXITMAC, .EXITMACRO</tt><label id=".EXITMACRO"><p> 2613 2614 Abort a macro expansion immediately. This command is often useful in 2615 recursive macros. 2616 2617 See: <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, 2618 <tt><ref id=".ENDMACRO" name=".ENDMACRO"></tt>, 2619 <tt><ref id=".MACRO" name=".MACRO"></tt> 2620 2621 See also section <ref id="macros" name="Macros">. 2622 2623 2624<sect1><tt>.EXPORT</tt><label id=".EXPORT"><p> 2625 2626 Make symbols accessible from other modules. Must be followed by a comma 2627 separated list of symbols to export, with each one optionally followed by an 2628 address specification and (also optional) an assignment. Using an additional 2629 assignment in the export statement allows to define and export a symbol in 2630 one statement. The default is to export the symbol with the address size it 2631 actually has. The assembler will issue a warning, if the symbol is exported 2632 with an address size smaller than the actual address size. 2633 2634 Examples: 2635 2636 <tscreen><verb> 2637 .export foo 2638 .export bar: far 2639 .export foobar: far = foo * bar 2640 .export baz := foobar, zap: far = baz - bar 2641 </verb></tscreen> 2642 2643 As with constant definitions, using <tt/:=/ instead of <tt/=/ marks the 2644 symbols as a label. 2645 2646 See: <tt><ref id=".EXPORTZP" name=".EXPORTZP"></tt> 2647 2648 2649<sect1><tt>.EXPORTZP</tt><label id=".EXPORTZP"><p> 2650 2651 Make symbols accessible from other modules. Must be followed by a comma 2652 separated list of symbols to export. The exported symbols are explicitly 2653 marked as zero page symbols. An assignment may be included in the 2654 <tt/.EXPORTZP/ statement. This allows to define and export a symbol in one 2655 statement. 2656 2657 Examples: 2658 2659 <tscreen><verb> 2660 .exportzp foo, bar 2661 .exportzp baz := $02 2662 </verb></tscreen> 2663 2664 See: <tt><ref id=".EXPORT" name=".EXPORT"></tt> 2665 2666 2667<sect1><tt>.FARADDR</tt><label id=".FARADDR"><p> 2668 2669 Define far (24 bit) address data. The command must be followed by a 2670 sequence of (not necessarily constant) expressions. 2671 2672 Example: 2673 2674 <tscreen><verb> 2675 .faraddr DrawCircle, DrawRectangle, DrawHexagon 2676 </verb></tscreen> 2677 2678 See: <tt><ref id=".ADDR" name=".ADDR"></tt> 2679 2680 2681<sect1><tt>.FATAL</tt><label id=".FATAL"><p> 2682 2683 Force an assembly error and terminate assembly. The assembler will output an 2684 error message preceded by "User error" and will terminate assembly 2685 immediately. 2686 2687 This command may be used to check for initial conditions that must be 2688 set before assembling a source file. 2689 2690 Example: 2691 2692 <tscreen><verb> 2693 .if foo = 1 2694 ... 2695 .elseif bar = 1 2696 ... 2697 .else 2698 .fatal "Must define foo or bar!" 2699 .endif 2700 </verb></tscreen> 2701 2702 See also: <tt><ref id=".ERROR" name=".ERROR"></tt>, 2703 <tt><ref id=".OUT" name=".OUT"></tt>, 2704 <tt><ref id=".WARNING" name=".WARNING"></tt> 2705 2706 2707<sect1><tt>.FEATURE</tt><label id=".FEATURE"><p> 2708 2709 This directive may be used to enable one or more compatibility features 2710 of the assembler. While the use of <tt/.FEATURE/ should be avoided when 2711 possible, it may be useful when porting sources written for other 2712 assemblers. There is no way to switch a feature off, once you have 2713 enabled it, so using 2714 2715 <tscreen><verb> 2716 .FEATURE xxx 2717 </verb></tscreen> 2718 2719 will enable the feature until end of assembly is reached. 2720 2721 The following features are available: 2722 2723 <descrip> 2724 2725 <tag><tt>addrsize</tt><label id="addrsize"></tag> 2726 2727 Enables the .ADDRSIZE pseudo function. This function is experimental and not enabled by default. 2728 2729 See also: <tt><ref id=".ADDRSIZE" name=".ADDRSIZE"></tt> 2730 2731 <tag><tt>at_in_identifiers</tt><label id="at_in_identifiers"></tag> 2732 2733 Accept the at character ('@') as a valid character in identifiers. The 2734 at character is not allowed to start an identifier, even with this 2735 feature enabled. 2736 2737 <tag><tt>bracket_as_indirect</tt><label id="bracket_as_indirect"></tag> 2738 2739 Use <tt>[]</tt> instead of <tt>()</tt> for the indirect addressing modes. 2740 Example: 2741 2742 <tscreen><verb> 2743 lda [$82] 2744 lda [$82,x] 2745 lda [$82],y 2746 jmp [$fffe] 2747 jmp [table,x] 2748 </verb></tscreen> 2749 <em/Note:/ This should not be used in 65186 mode because it conflicts with 2750 the 65816 instruction syntax for far addressing. See the section covering 2751 <tt/<ref id="address-sizes" name="address sizes">/ for more information. 2752 2753 <tag><tt>c_comments</tt><label id="c_comments"></tag> 2754 2755 Allow C like comments using <tt>/*</tt> and <tt>*/</tt> as left and right 2756 comment terminators. Note that C comments may not be nested. There's also a 2757 pitfall when using C like comments: All statements must be terminated by 2758 "end-of-line". Using C like comments, it is possible to hide the newline, 2759 which results in error messages. See the following non working example: 2760 2761 <tscreen><verb> 2762 lda #$00 /* This comment hides the newline 2763*/ sta $82 2764 </verb></tscreen> 2765 2766 <tag><tt>dollar_in_identifiers</tt><label id="dollar_in_identifiers"></tag> 2767 2768 Accept the dollar sign ('$') as a valid character in identifiers. The 2769 dollar character is not allowed to start an identifier, even with this 2770 feature enabled. 2771 2772 <tag><tt>dollar_is_pc</tt><label id="dollar_is_pc"></tag> 2773 2774 The dollar sign may be used as an alias for the star ('*'), which 2775 gives the value of the current PC in expressions. 2776 Note: Assignment to the pseudo variable is not allowed. 2777 2778 <tag><tt>force_range</tt><label id="force_range"></tag> 2779 2780 Force expressions into their valid range for immediate addressing and 2781 storage operators like <tt><ref id=".BYTE" name=".BYTE"></tt> and 2782 <tt><ref id=".WORD" name=".WORD"></tt>. Be very careful with this one, 2783 since it will completely disable error checks. 2784 2785 <tag><tt>labels_without_colons</tt><label id="labels_without_colons"></tag> 2786 2787 Allow labels without a trailing colon. These labels are only accepted, 2788 if they start at the beginning of a line (no leading white space). 2789 2790 <tag><tt>leading_dot_in_identifiers</tt><label id="leading_dot_in_identifiers"></tag> 2791 2792 Accept the dot ('.') as the first character of an identifier. This may be 2793 used for example to create macro names that start with a dot emulating 2794 control directives of other assemblers. Note however, that none of the 2795 reserved keywords built into the assembler, that starts with a dot, may be 2796 overridden. When using this feature, you may also get into trouble if 2797 later versions of the assembler define new keywords starting with a dot. 2798 2799 <tag><tt>loose_char_term</tt><label id="loose_char_term"></tag> 2800 2801 Accept single quotes as well as double quotes as terminators for char 2802 constants. 2803 2804 <tag><tt>loose_string_term</tt><label id="loose_string_term"></tag> 2805 2806 Accept single quotes as well as double quotes as terminators for string 2807 constants. 2808 2809 <tag><tt>missing_char_term</tt><label id="missing_char_term"></tag> 2810 2811 Accept single quoted character constants where the terminating quote is 2812 missing. 2813 <tscreen><verb> 2814 lda #'a 2815 </verb></tscreen> 2816 <em/Note:/ This does not work in conjunction with <tt/.FEATURE 2817 loose_string_term/, since in this case the input would be ambiguous. 2818 2819 <tag><tt>org_per_seg</tt><label id="org_per_seg"></tag> 2820 2821 This feature makes relocatable/absolute mode local to the current segment. 2822 Using <tt><ref id=".ORG" name=".ORG"></tt> when <tt/org_per_seg/ is in 2823 effect will only enable absolute mode for the current segment. Dito for 2824 <tt><ref id=".RELOC" name=".RELOC"></tt>. 2825 2826 <tag><tt>pc_assignment</tt><label id="pc_assignment"></tag> 2827 2828 Allow assignments to the PC symbol ('*' or '$' if <tt/dollar_is_pc/ 2829 is enabled). Such an assignment is handled identical to the <tt><ref 2830 id=".ORG" name=".ORG"></tt> command (which is usually not needed, so just 2831 removing the lines with the assignments may also be an option when porting 2832 code written for older assemblers). 2833 2834 <tag><tt>string_escapes</tt><label id="string_escapes"></tag> 2835 2836 Allow C-style backslash escapes within string constants to embed 2837 special characters. The following escapes are accepted: 2838 <itemize> 2839 <item><tt>\\</tt> backslash (<tt>$5C</tt>) 2840 <item><tt>\'</tt> single quote (<tt>$27</tt>) 2841 <item><tt>\"</tt> double quote (<tt>$22</tt>) 2842 <item><tt>\t</tt> tab (<tt>$09</tt>) 2843 <item><tt>\r</tt> carriage return (<tt>$0D</tt>) 2844 <item><tt>\n</tt> newline (<tt>$0A</tt>) 2845 <item><tt>\xNN</tt> (<tt>$NN</tt>) 2846 </itemize> 2847 2848 Note that string escapes are converted to platform-specific characters in 2849 the same way that other characters are converted. 2850 2851 <tag><tt>ubiquitous_idents</tt><label id="ubiquitous_idents"></tag> 2852 2853 Allow the use of instructions names as names for macros and symbols. This 2854 makes it possible to "overload" instructions by defining a macro with the 2855 same name. This does also make it possible to introduce hard to find errors 2856 in your code, so be careful! 2857 2858 <tag><tt>underline_in_numbers</tt><label id="underline_in_numbers"></tag> 2859 2860 Allow underlines within numeric constants. These may be used for grouping 2861 the digits of numbers for easier reading. 2862 Example: 2863 <tscreen><verb> 2864 .feature underline_in_numbers 2865 .word %1100001110100101 2866 .word %1100_0011_1010_0101 ; Identical but easier to read 2867 </verb></tscreen> 2868 2869 </descrip> 2870 2871 It is also possible to specify features on the command line using the 2872 <tt><ref id="option--feature" name="--feature"></tt> command line option. 2873 This is useful when translating sources written for older assemblers, when 2874 you don't want to change the source code. 2875 2876 As an example, to translate sources written for Andre Fachats xa65 2877 assembler, the features 2878 2879 <verb> 2880 labels_without_colons, pc_assignment, loose_char_term 2881 </verb> 2882 2883 may be helpful. They do not make ca65 completely compatible, so you may not 2884 be able to translate the sources without changes, even when enabling these 2885 features. However, I have found several sources that translate without 2886 problems when enabling these features on the command line. 2887 2888 2889<sect1><tt>.FILEOPT, .FOPT</tt><label id=".FOPT"><p> 2890 2891 Insert an option string into the object file. There are two forms of 2892 this command, one specifies the option by a keyword, the second 2893 specifies it as a number. Since usage of the second one needs knowledge 2894 of the internal encoding, its use is not recommended and I will only 2895 describe the first form here. 2896 2897 The command is followed by one of the keywords 2898 2899 <tscreen><verb> 2900 author 2901 comment 2902 compiler 2903 </verb></tscreen> 2904 2905 a comma and a string. The option is written into the object file 2906 together with the string value. This is currently unidirectional and 2907 there is no way to actually use these options once they are in the 2908 object file. 2909 2910 Examples: 2911 2912 <tscreen><verb> 2913 .fileopt comment, "Code stolen from my brother" 2914 .fileopt compiler, "BASIC 2.0" 2915 .fopt author, "J. R. User" 2916 </verb></tscreen> 2917 2918 2919<sect1><tt>.FORCEIMPORT</tt><label id=".FORCEIMPORT"><p> 2920 2921 Import an absolute symbol from another module. The command is followed by a 2922 comma separated list of symbols to import. The command is similar to <tt> 2923 <ref id=".IMPORT" name=".IMPORT"></tt>, but the import reference is always 2924 written to the generated object file, even if the symbol is never referenced 2925 (<tt><ref id=".IMPORT" name=".IMPORT"></tt> will not generate import 2926 references for unused symbols). 2927 2928 Example: 2929 2930 <tscreen><verb> 2931 .forceimport needthisone, needthistoo 2932 </verb></tscreen> 2933 2934 See: <tt><ref id=".IMPORT" name=".IMPORT"></tt> 2935 2936 2937<sect1><tt>.GLOBAL</tt><label id=".GLOBAL"><p> 2938 2939 Declare symbols as global. Must be followed by a comma separated list of 2940 symbols to declare. Symbols from the list, that are defined somewhere in the 2941 source, are exported, all others are imported. Additional <tt><ref 2942 id=".IMPORT" name=".IMPORT"></tt> or <tt><ref id=".EXPORT" 2943 name=".EXPORT"></tt> commands for the same symbol are allowed. 2944 2945 Example: 2946 2947 <tscreen><verb> 2948 .global foo, bar 2949 </verb></tscreen> 2950 2951 2952<sect1><tt>.GLOBALZP</tt><label id=".GLOBALZP"><p> 2953 2954 Declare symbols as global. Must be followed by a comma separated list of 2955 symbols to declare. Symbols from the list, that are defined somewhere in the 2956 source, are exported, all others are imported. Additional <tt><ref 2957 id=".IMPORTZP" name=".IMPORTZP"></tt> or <tt><ref id=".EXPORTZP" 2958 name=".EXPORTZP"></tt> commands for the same symbol are allowed. The symbols 2959 in the list are explicitly marked as zero page symbols. 2960 2961 Example: 2962 2963 <tscreen><verb> 2964 .globalzp foo, bar 2965 </verb></tscreen> 2966 2967<sect1><tt>.HIBYTES</tt><label id=".HIBYTES"><p> 2968 2969 Define byte sized data by extracting only the high byte (that is, bits 8-15) from 2970 each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with 2971 the operator '>' prepended to each expression in its list. 2972 2973 Example: 2974 2975 <tscreen><verb> 2976 .lobytes $1234, $2345, $3456, $4567 2977 .hibytes $fedc, $edcb, $dcba, $cba9 2978 </verb></tscreen> 2979 2980 which is equivalent to 2981 2982 <tscreen><verb> 2983 .byte $34, $45, $56, $67 2984 .byte $fe, $ed, $dc, $cb 2985 </verb></tscreen> 2986 2987 Example: 2988 2989 <tscreen><verb> 2990 .define MyTable TableItem0, TableItem1, TableItem2, TableItem3 2991 2992 TableLookupLo: .lobytes MyTable 2993 TableLookupHi: .hibytes MyTable 2994 </verb></tscreen> 2995 2996 which is equivalent to 2997 2998 <tscreen><verb> 2999 TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3 3000 TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 3001 </verb></tscreen> 3002 3003 See also: <tt><ref id=".BYTE" name=".BYTE"></tt>, 3004 <tt><ref id=".LOBYTES" name=".LOBYTES"></tt>, 3005 <tt><ref id=".BANKBYTES" name=".BANKBYTES"></tt> 3006 3007 3008<sect1><tt>.I16</tt><label id=".I16"><p> 3009 3010 Valid only in 65816 mode. Switch the index registers to 16 bit. 3011 3012 Note: This command will not emit any code, it will tell the assembler to 3013 create 16 bit operands for immediate operands. 3014 3015 See also the <tt><ref id=".I8" name=".I8"></tt> and <tt><ref id=".SMART" 3016 name=".SMART"></tt> commands. 3017 3018 3019<sect1><tt>.I8</tt><label id=".I8"><p> 3020 3021 Valid only in 65816 mode. Switch the index registers to 8 bit. 3022 3023 Note: This command will not emit any code, it will tell the assembler to 3024 create 8 bit operands for immediate operands. 3025 3026 See also the <tt><ref id=".I16" name=".I16"></tt> and <tt><ref id=".SMART" 3027 name=".SMART"></tt> commands. 3028 3029 3030<sect1><tt>.IF</tt><label id=".IF"><p> 3031 3032 Conditional assembly: Evaluate an expression and switch assembler output 3033 on or off depending on the expression. The expression must be a constant 3034 expression, that is, all operands must be defined. 3035 3036 A expression value of zero evaluates to FALSE, any other value evaluates 3037 to TRUE. 3038 3039 3040<sect1><tt>.IFBLANK</tt><label id=".IFBLANK"><p> 3041 3042 Conditional assembly: Check if there are any remaining tokens in this line, 3043 and evaluate to FALSE if this is the case, and to TRUE otherwise. If the 3044 condition is not true, further lines are not assembled until an <tt><ref 3045 id=".ELSE" name=".ELSE"></tt>, <tt><ref id=".ELSEIF" name=".ELSEIF"></tt> or 3046 <tt><ref id=".ENDIF" name=".ENDIF"></tt> directive. 3047 3048 This command is often used to check if a macro parameter was given. Since an 3049 empty macro parameter will evaluate to nothing, the condition will evaluate 3050 to TRUE if an empty parameter was given. 3051 3052 Example: 3053 3054 <tscreen><verb> 3055 .macro arg1, arg2 3056 .ifblank arg2 3057 lda #arg1 3058 .else 3059 lda #arg2 3060 .endif 3061 .endmacro 3062 </verb></tscreen> 3063 3064 See also: <tt><ref id=".BLANK" name=".BLANK"></tt> 3065 3066 3067<sect1><tt>.IFCONST</tt><label id=".IFCONST"><p> 3068 3069 Conditional assembly: Evaluate an expression and switch assembler output 3070 on or off depending on the constness of the expression. 3071 3072 A const expression evaluates to to TRUE, a non const expression (one 3073 containing an imported or currently undefined symbol) evaluates to 3074 FALSE. 3075 3076 See also: <tt><ref id=".CONST" name=".CONST"></tt> 3077 3078 3079<sect1><tt>.IFDEF</tt><label id=".IFDEF"><p> 3080 3081 Conditional assembly: Check if a symbol is defined. Must be followed by 3082 a symbol name. The condition is true if the the given symbol is already 3083 defined, and false otherwise. 3084 3085 See also: <tt><ref id=".DEFINED" name=".DEFINED"></tt> 3086 3087 3088<sect1><tt>.IFNBLANK</tt><label id=".IFNBLANK"><p> 3089 3090 Conditional assembly: Check if there are any remaining tokens in this line, 3091 and evaluate to TRUE if this is the case, and to FALSE otherwise. If the 3092 condition is not true, further lines are not assembled until an <tt><ref 3093 id=".ELSE" name=".ELSE"></tt>, <tt><ref id=".ELSEIF" name=".ELSEIF"></tt> or 3094 <tt><ref id=".ENDIF" name=".ENDIF"></tt> directive. 3095 3096 This command is often used to check if a macro parameter was given. 3097 Since an empty macro parameter will evaluate to nothing, the condition 3098 will evaluate to FALSE if an empty parameter was given. 3099 3100 Example: 3101 3102 <tscreen><verb> 3103 .macro arg1, arg2 3104 lda #arg1 3105 .ifnblank arg2 3106 lda #arg2 3107 .endif 3108 .endmacro 3109 </verb></tscreen> 3110 3111 See also: <tt><ref id=".BLANK" name=".BLANK"></tt> 3112 3113 3114<sect1><tt>.IFNDEF</tt><label id=".IFNDEF"><p> 3115 3116 Conditional assembly: Check if a symbol is defined. Must be followed by 3117 a symbol name. The condition is true if the the given symbol is not 3118 defined, and false otherwise. 3119 3120 See also: <tt><ref id=".DEFINED" name=".DEFINED"></tt> 3121 3122 3123<sect1><tt>.IFNREF</tt><label id=".IFNREF"><p> 3124 3125 Conditional assembly: Check if a symbol is referenced. Must be followed 3126 by a symbol name. The condition is true if if the the given symbol was 3127 not referenced before, and false otherwise. 3128 3129 See also: <tt><ref id=".REFERENCED" name=".REFERENCED"></tt> 3130 3131 3132<sect1><tt>.IFP02</tt><label id=".IFP02"><p> 3133 3134 Conditional assembly: Check if the assembler is currently in 6502 mode 3135 (see <tt><ref id=".P02" name=".P02"></tt> command). 3136 3137 3138<sect1><tt>.IFP4510</tt><label id=".IFP4510"><p> 3139 3140 Conditional assembly: Check if the assembler is currently in 4510 mode 3141 (see <tt><ref id=".P4510" name=".P4510"></tt> command). 3142 3143 3144<sect1><tt>.IFP816</tt><label id=".IFP816"><p> 3145 3146 Conditional assembly: Check if the assembler is currently in 65816 mode 3147 (see <tt><ref id=".P816" name=".P816"></tt> command). 3148 3149 3150<sect1><tt>.IFPC02</tt><label id=".IFPC02"><p> 3151 3152 Conditional assembly: Check if the assembler is currently in 65C02 mode 3153 (see <tt><ref id=".PC02" name=".PC02"></tt> command). 3154 3155 3156<sect1><tt>.IFPSC02</tt><label id=".IFPSC02"><p> 3157 3158 Conditional assembly: Check if the assembler is currently in 65SC02 mode 3159 (see <tt><ref id=".PSC02" name=".PSC02"></tt> command). 3160 3161 3162<sect1><tt>.IFREF</tt><label id=".IFREF"><p> 3163 3164 Conditional assembly: Check if a symbol is referenced. Must be followed 3165 by a symbol name. The condition is true if if the the given symbol was 3166 referenced before, and false otherwise. 3167 3168 This command may be used to build subroutine libraries in include files 3169 (you may use separate object modules for this purpose too). 3170 3171 Example: 3172 3173 <tscreen><verb> 3174 .ifref ToHex ; If someone used this subroutine 3175 ToHex: tay ; Define subroutine 3176 lda HexTab,y 3177 rts 3178 .endif 3179 </verb></tscreen> 3180 3181 See also: <tt><ref id=".REFERENCED" name=".REFERENCED"></tt> 3182 3183 3184<sect1><tt>.IMPORT</tt><label id=".IMPORT"><p> 3185 3186 Import a symbol from another module. The command is followed by a comma 3187 separated list of symbols to import, with each one optionally followed by 3188 an address specification. 3189 3190 Example: 3191 3192 <tscreen><verb> 3193 .import foo 3194 .import bar: zeropage 3195 </verb></tscreen> 3196 3197 See: <tt><ref id=".IMPORTZP" name=".IMPORTZP"></tt> 3198 3199 3200<sect1><tt>.IMPORTZP</tt><label id=".IMPORTZP"><p> 3201 3202 Import a symbol from another module. The command is followed by a comma 3203 separated list of symbols to import. The symbols are explicitly imported 3204 as zero page symbols (that is, symbols with values in byte range). 3205 3206 Example: 3207 3208 <tscreen><verb> 3209 .importzp foo, bar 3210 </verb></tscreen> 3211 3212 See: <tt><ref id=".IMPORT" name=".IMPORT"></tt> 3213 3214 3215<sect1><tt>.INCBIN</tt><label id=".INCBIN"><p> 3216 3217 Include a file as binary data. The command expects a string argument 3218 that is the name of a file to include literally in the current segment. 3219 In addition to that, a start offset and a size value may be specified, 3220 separated by commas. If no size is specified, all of the file from the 3221 start offset to end-of-file is used. If no start position is specified 3222 either, zero is assumed (which means that the whole file is inserted). 3223 3224 Example: 3225 3226 <tscreen><verb> 3227 ; Include whole file 3228 .incbin "sprites.dat" 3229 3230 ; Include file starting at offset 256 3231 .incbin "music.dat", $100 3232 3233 ; Read 100 bytes starting at offset 200 3234 .incbin "graphics.dat", 200, 100 3235 </verb></tscreen> 3236 3237 3238<sect1><tt>.INCLUDE</tt><label id=".INCLUDE"><p> 3239 3240 Include another file. Include files may be nested up to a depth of 16. 3241 3242 Example: 3243 3244 <tscreen><verb> 3245 .include "subs.inc" 3246 </verb></tscreen> 3247 3248 3249<sect1><tt>.INTERRUPTOR</tt><label id=".INTERRUPTOR"><p> 3250 3251 Export a symbol and mark it as an interruptor. This may be used together 3252 with the linker to build a table of interruptor subroutines that are called 3253 in an interrupt. 3254 3255 Note: The linker has a feature to build a table of marked routines, but it 3256 is your code that must call these routines, so just declaring a symbol as 3257 interruptor does nothing by itself. 3258 3259 An interruptor is always exported as an absolute (16 bit) symbol. You don't 3260 need to use an additional <tt/.export/ statement, this is implied by 3261 <tt/.interruptor/. It may have an optional priority that is separated by a 3262 comma. Higher numeric values mean a higher priority. If no priority is 3263 given, the default priority of 7 is used. Be careful when assigning 3264 priorities to your own module constructors so they won't interfere with the 3265 ones in the cc65 library. 3266 3267 Example: 3268 3269 <tscreen><verb> 3270 .interruptor IrqHandler 3271 .interruptor Handler, 16 3272 </verb></tscreen> 3273 3274 See the <tt><ref id=".CONDES" name=".CONDES"></tt> command and the separate 3275 section <ref id="condes" name="Module constructors/destructors"> explaining 3276 the feature in more detail. 3277 3278 3279<sect1><tt>.ISMNEM, .ISMNEMONIC</tt><label id=".ISMNEMONIC"><p> 3280 3281 Builtin function. The function expects an identifier as argument in braces. 3282 The argument is evaluated, and the function yields "true" if the identifier 3283 is defined as an instruction mnemonic that is recognized by the assembler. 3284 Example: 3285 3286 <tscreen><verb> 3287 .if .not .ismnemonic(ina) 3288 .macro ina 3289 clc 3290 adc #$01 3291 .endmacro 3292 .endif 3293 </verb></tscreen> 3294 3295 3296<sect1><tt>.LINECONT</tt><label id=".LINECONT"><p> 3297 3298 Switch on or off line continuations using the backslash character 3299 before a newline. The option is off by default. 3300 Note: Line continuations do not work in a comment. A backslash at the 3301 end of a comment is treated as part of the comment and does not trigger 3302 line continuation. 3303 The command must be followed by a '+' or '-' character to switch the 3304 option on or off respectively. 3305 3306 Example: 3307 3308 <tscreen><verb> 3309 .linecont + ; Allow line continuations 3310 3311 lda \ 3312 #$20 ; This is legal now 3313 </verb></tscreen> 3314 3315 3316<sect1><tt>.LIST</tt><label id=".LIST"><p> 3317 3318 Enable output to the listing. The command must be followed by a boolean 3319 switch ("on", "off", "+" or "-") and will enable or disable listing 3320 output. 3321 The option has no effect if the listing is not enabled by the command line 3322 switch -l. If -l is used, an internal counter is set to 1. Lines are output 3323 to the listing file, if the counter is greater than zero, and suppressed if 3324 the counter is zero. Each use of <tt/.LIST/ will increment or decrement the 3325 counter. 3326 3327 Example: 3328 3329 <tscreen><verb> 3330 .list on ; Enable listing output 3331 </verb></tscreen> 3332 3333 3334<sect1><tt>.LISTBYTES</tt><label id=".LISTBYTES"><p> 3335 3336 Set, how many bytes are shown in the listing for one source line. The 3337 default is 12, so the listing will show only the first 12 bytes for any 3338 source line that generates more than 12 bytes of code or data. 3339 The directive needs an argument, which is either "unlimited", or an 3340 integer constant in the range 4..255. 3341 3342 Examples: 3343 3344 <tscreen><verb> 3345 .listbytes unlimited ; List all bytes 3346 .listbytes 12 ; List the first 12 bytes 3347 .incbin "data.bin" ; Include large binary file 3348 </verb></tscreen> 3349 3350 3351<sect1><tt>.LOBYTES</tt><label id=".LOBYTES"><p> 3352 3353 Define byte sized data by extracting only the low byte (that is, bits 0-7) from 3354 each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with 3355 the operator '<' prepended to each expression in its list. 3356 3357 Example: 3358 3359 <tscreen><verb> 3360 .lobytes $1234, $2345, $3456, $4567 3361 .hibytes $fedc, $edcb, $dcba, $cba9 3362 </verb></tscreen> 3363 3364 which is equivalent to 3365 3366 <tscreen><verb> 3367 .byte $34, $45, $56, $67 3368 .byte $fe, $ed, $dc, $cb 3369 </verb></tscreen> 3370 3371 Example: 3372 3373 <tscreen><verb> 3374 .define MyTable TableItem0, TableItem1, TableItem2, TableItem3 3375 3376 TableLookupLo: .lobytes MyTable 3377 TableLookupHi: .hibytes MyTable 3378 </verb></tscreen> 3379 3380 which is equivalent to 3381 3382 <tscreen><verb> 3383 TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3 3384 TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 3385 </verb></tscreen> 3386 3387 See also: <tt><ref id=".BYTE" name=".BYTE"></tt>, 3388 <tt><ref id=".HIBYTES" name=".HIBYTES"></tt>, 3389 <tt><ref id=".BANKBYTES" name=".BANKBYTES"></tt> 3390 3391 3392<sect1><tt>.LOCAL</tt><label id=".LOCAL"><p> 3393 3394 This command may only be used inside a macro definition. It declares a 3395 list of identifiers as local to the macro expansion. 3396 3397 A problem when using macros are labels: Since they don't change their name, 3398 you get a "duplicate symbol" error if the macro is expanded the second time. 3399 Labels declared with <tt><ref id=".LOCAL" name=".LOCAL"></tt> have their 3400 name mapped to an internal unique name (<tt/___ABCD__/) with each macro 3401 invocation. 3402 3403 Some other assemblers start a new lexical block inside a macro expansion. 3404 This has some drawbacks however, since that will not allow <em/any/ symbol 3405 to be visible outside a macro, a feature that is sometimes useful. The 3406 <tt><ref id=".LOCAL" name=".LOCAL"></tt> command is in my eyes a better way 3407 to address the problem. 3408 3409 You get an error when using <tt><ref id=".LOCAL" name=".LOCAL"></tt> outside 3410 a macro. 3411 3412 3413<sect1><tt>.LOCALCHAR</tt><label id=".LOCALCHAR"><p> 3414 3415 Defines the character that start "cheap" local labels. You may use one 3416 of '@' and '?' as start character. The default is '@'. 3417 3418 Cheap local labels are labels that are visible only between two non 3419 cheap labels. This way you can reuse identifiers like "<tt/loop/" without 3420 using explicit lexical nesting. 3421 3422 Example: 3423 3424 <tscreen><verb> 3425 .localchar '?' 3426 3427 Clear: lda #$00 ; Global label 3428 ?Loop: sta Mem,y ; Local label 3429 dey 3430 bne ?Loop ; Ok 3431 rts 3432 Sub: ... ; New global label 3433 bne ?Loop ; ERROR: Unknown identifier! 3434 </verb></tscreen> 3435 3436 3437<sect1><tt>.MACPACK</tt><label id=".MACPACK"><p> 3438 3439 Insert a predefined macro package. The command is followed by an 3440 identifier specifying the macro package to insert. Available macro 3441 packages are: 3442 3443 <tscreen><verb> 3444 atari Defines the scrcode macro. 3445 cbm Defines the scrcode macro. 3446 cpu Defines constants for the .CPU variable. 3447 generic Defines generic macros like add, sub, and blt. 3448 longbranch Defines conditional long-jump macros. 3449 </verb></tscreen> 3450 3451 Including a macro package twice, or including a macro package that 3452 redefines already existing macros will lead to an error. 3453 3454 Example: 3455 3456 <tscreen><verb> 3457 .macpack longbranch ; Include macro package 3458 3459 cmp #$20 ; Set condition codes 3460 jne Label ; Jump long on condition 3461 </verb></tscreen> 3462 3463 Macro packages are explained in more detail in section <ref 3464 id="macropackages" name="Macro packages">. 3465 3466 3467<sect1><tt>.MAC, .MACRO</tt><label id=".MACRO"><p> 3468 3469 Start a classic macro definition. The command is followed by an identifier 3470 (the macro name) and optionally by a comma separated list of identifiers 3471 that are macro parameters. A macro definition is terminated by <tt><ref 3472 id=".ENDMACRO" name=".ENDMACRO"></tt>. 3473 3474 Example: 3475 3476 <tscreen><verb> 3477 .macro ldax arg ; Define macro ldax 3478 lda arg 3479 ldx arg+1 3480 </verb></tscreen> 3481 3482 See: <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, 3483 <tt><ref id=".ENDMACRO" name=".ENDMACRO"></tt>, 3484 <tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt> 3485 3486 See also section <ref id="macros" name="Macros">. 3487 3488 3489<sect1><tt>.ORG</tt><label id=".ORG"><p> 3490 3491 Start a section of absolute code. The command is followed by a constant 3492 expression that gives the new PC counter location for which the code is 3493 assembled. Use <tt><ref id=".RELOC" name=".RELOC"></tt> to switch back to 3494 relocatable code. 3495 3496 By default, absolute/relocatable mode is global (valid even when switching 3497 segments). Using <tt>.FEATURE <ref id="org_per_seg" name="org_per_seg"></tt> 3498 it can be made segment local. 3499 3500 Please note that you <em/do not need/ <tt/.ORG/ in most cases. Placing 3501 code at a specific address is the job of the linker, not the assembler, so 3502 there is usually no reason to assemble code to a specific address. 3503 3504 Example: 3505 3506 <tscreen><verb> 3507 .org $7FF ; Emit code starting at $7FF 3508 </verb></tscreen> 3509 3510 3511<sect1><tt>.OUT</tt><label id=".OUT"><p> 3512 3513 Output a string to the console without producing an error. This command 3514 is similar to <tt/.ERROR/, however, it does not force an assembler error 3515 that prevents the creation of an object file. 3516 3517 Example: 3518 3519 <tscreen><verb> 3520 .out "This code was written by the codebuster(tm)" 3521 </verb></tscreen> 3522 3523 See also: <tt><ref id=".ERROR" name=".ERROR"></tt>, 3524 <tt><ref id=".FATAL" name=".FATAL"></tt>, 3525 <tt><ref id=".WARNING" name=".WARNING"></tt> 3526 3527 3528<sect1><tt>.P02</tt><label id=".P02"><p> 3529 3530 Enable the 6502 instruction set, disable 65SC02, 65C02 and 65816 3531 instructions. This is the default if not overridden by the 3532 <tt><ref id="option--cpu" name="--cpu"></tt> command line option. 3533 3534 See: <tt><ref id=".PC02" name=".PC02"></tt>, <tt><ref id=".PSC02" 3535 name=".PSC02"></tt>, <tt><ref id=".P816" name=".P816"></tt> and 3536 <tt><ref id=".P4510" name=".P4510"></tt> 3537 3538 3539<sect1><tt>.P4510</tt><label id=".P4510"><p> 3540 3541 Enable the 4510 instruction set. This is a superset of the 65C02 and 3542 6502 instruction sets. 3543 3544 See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02" 3545 name=".PSC02"></tt>, <tt><ref id=".PC02" name=".PC02"></tt> and 3546 <tt><ref id=".P816" name=".P816"></tt> 3547 3548 3549<sect1><tt>.P816</tt><label id=".P816"><p> 3550 3551 Enable the 65816 instruction set. This is a superset of the 65SC02 and 3552 6502 instruction sets. 3553 3554 See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02" 3555 name=".PSC02"></tt>, <tt><ref id=".PC02" name=".PC02"></tt> and 3556 <tt><ref id=".P4510" name=".P4510"></tt> 3557 3558 3559<sect1><tt>.PAGELEN, .PAGELENGTH</tt><label id=".PAGELENGTH"><p> 3560 3561 Set the page length for the listing. Must be followed by an integer 3562 constant. The value may be "unlimited", or in the range 32 to 127. The 3563 statement has no effect if no listing is generated. The default value is -1 3564 (unlimited) but may be overridden by the <tt/--pagelength/ command line 3565 option. Beware: Since ca65 is a one pass assembler, the listing is generated 3566 after assembly is complete, you cannot use multiple line lengths with one 3567 source. Instead, the value set with the last <tt/.PAGELENGTH/ is used. 3568 3569 Examples: 3570 3571 <tscreen><verb> 3572 .pagelength 66 ; Use 66 lines per listing page 3573 3574 .pagelength unlimited ; Unlimited page length 3575 </verb></tscreen> 3576 3577 3578<sect1><tt>.PC02</tt><label id=".PC02"><p> 3579 3580 Enable the 65C02 instructions set. This instruction set includes all 3581 6502 and 65SC02 instructions. 3582 3583 See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02" 3584 name=".PSC02"></tt>, <tt><ref id=".P816" name=".P816"></tt> and 3585 <tt><ref id=".P4510" name=".P4510"></tt> 3586 3587 3588<sect1><tt>.POPCPU</tt><label id=".POPCPU"><p> 3589 3590 Pop the last CPU setting from the stack, and activate it. 3591 3592 This command will switch back to the CPU that was last pushed onto the CPU 3593 stack using the <tt><ref id=".PUSHCPU" name=".PUSHCPU"></tt> command, and 3594 remove this entry from the stack. 3595 3596 The assembler will print an error message if the CPU stack is empty when 3597 this command is issued. 3598 3599 See: <tt><ref id=".CPU" name=".CPU"></tt>, <tt><ref id=".PUSHCPU" 3600 name=".PUSHCPU"></tt>, <tt><ref id=".SETCPU" name=".SETCPU"></tt> 3601 3602 3603<sect1><tt>.POPSEG</tt><label id=".POPSEG"><p> 3604 3605 Pop the last pushed segment from the stack, and set it. 3606 3607 This command will switch back to the segment that was last pushed onto the 3608 segment stack using the <tt><ref id=".PUSHSEG" name=".PUSHSEG"></tt> 3609 command, and remove this entry from the stack. 3610 3611 The assembler will print an error message if the segment stack is empty 3612 when this command is issued. 3613 3614 See: <tt><ref id=".PUSHSEG" name=".PUSHSEG"></tt> 3615 3616 3617<sect1><tt>.PROC</tt><label id=".PROC"><p> 3618 3619 Start a nested lexical level with the given name and adds a symbol with this 3620 name to the enclosing scope. All new symbols from now on are in the local 3621 lexical level and are accessible from outside only via <ref id="scopesyntax" 3622 name="explicit scope specification">. Symbols defined outside this local 3623 level may be accessed as long as their names are not used for new symbols 3624 inside the level. Symbols names in other lexical levels do not clash, so you 3625 may use the same names for identifiers. The lexical level ends when the 3626 <tt><ref id=".ENDPROC" name=".ENDPROC"></tt> command is read. Lexical levels 3627 may be nested up to a depth of 16 (this is an artificial limit to protect 3628 against errors in the source). 3629 3630 Note: Macro names are always in the global level and in a separate name 3631 space. There is no special reason for this, it's just that I've never 3632 had any need for local macro definitions. 3633 3634 Example: 3635 3636 <tscreen><verb> 3637 .proc Clear ; Define Clear subroutine, start new level 3638 lda #$00 3639 L1: sta Mem,y ; L1 is local and does not cause a 3640 ; duplicate symbol error if used in other 3641 ; places 3642 dey 3643 bne L1 ; Reference local symbol 3644 rts 3645 .endproc ; Leave lexical level 3646 </verb></tscreen> 3647 3648 See: <tt/<ref id=".ENDPROC" name=".ENDPROC">/ and <tt/<ref id=".SCOPE" 3649 name=".SCOPE">/ 3650 3651 3652<sect1><tt>.PSC02</tt><label id=".PSC02"><p> 3653 3654 Enable the 65SC02 instructions set. This instruction set includes all 3655 6502 instructions. 3656 3657 See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PC02" 3658 name=".PC02"></tt>, <tt><ref id=".P816" name=".P816"></tt> and 3659 <tt><ref id=".P4510" name=".P4510"></tt> 3660 3661 3662<sect1><tt>.PUSHCPU</tt><label id=".PUSHCPU"><p> 3663 3664 Push the currently active CPU onto a stack. The stack has a size of 8 3665 entries. 3666 3667 <tt/.PUSHCPU/ allows together with <tt><ref id=".POPCPU" 3668 name=".POPCPU"></tt> to switch to another CPU and to restore the old CPU 3669 later, without knowledge of the current CPU setting. 3670 3671 The assembler will print an error message if the CPU stack is already full, 3672 when this command is issued. 3673 3674 See: <tt><ref id=".CPU" name=".CPU"></tt>, <tt><ref id=".POPCPU" 3675 name=".POPCPU"></tt>, <tt><ref id=".SETCPU" name=".SETCPU"></tt> 3676 3677 3678<sect1><tt>.PUSHSEG</tt><label id=".PUSHSEG"><p> 3679 3680 Push the currently active segment onto a stack. The entries on the stack 3681 include the name of the segment and the segment type. The stack has a size 3682 of 16 entries. 3683 3684 <tt/.PUSHSEG/ allows together with <tt><ref id=".POPSEG" name=".POPSEG"></tt> 3685 to switch to another segment and to restore the old segment later, without 3686 even knowing the name and type of the current segment. 3687 3688 The assembler will print an error message if the segment stack is already 3689 full, when this command is issued. 3690 3691 See: <tt><ref id=".POPSEG" name=".POPSEG"></tt> 3692 3693 3694<sect1><tt>.RELOC</tt><label id=".RELOC"><p> 3695 3696 Switch back to relocatable mode. See the <tt><ref id=".ORG" 3697 name=".ORG"></tt> command. 3698 3699 3700<sect1><tt>.REPEAT</tt><label id=".REPEAT"><p> 3701 3702 Repeat all commands between <tt/.REPEAT/ and <tt><ref id=".ENDREPEAT" 3703 name=".ENDREPEAT"></tt> constant number of times. The command is followed by 3704 a constant expression that tells how many times the commands in the body 3705 should get repeated. Optionally, a comma and an identifier may be specified. 3706 If this identifier is found in the body of the repeat statement, it is 3707 replaced by the current repeat count (starting with zero for the first time 3708 the body is repeated). 3709 3710 <tt/.REPEAT/ statements may be nested. If you use the same repeat count 3711 identifier for a nested <tt/.REPEAT/ statement, the one from the inner 3712 level will be used, not the one from the outer level. 3713 3714 Example: 3715 3716 The following macro will emit a string that is "encrypted" in that all 3717 characters of the string are XORed by the value $55. 3718 3719 <tscreen><verb> 3720 .macro Crypt Arg 3721 .repeat .strlen(Arg), I 3722 .byte .strat(Arg, I) ^ $55 3723 .endrep 3724 .endmacro 3725 </verb></tscreen> 3726 3727 See: <tt><ref id=".ENDREPEAT" name=".ENDREPEAT"></tt> 3728 3729 3730<sect1><tt>.RES</tt><label id=".RES"><p> 3731 3732 Reserve storage. The command is followed by one or two constant 3733 expressions. The first one is mandatory and defines, how many bytes of 3734 storage should be defined. The second, optional expression must by a 3735 constant byte value that will be used as value of the data. If there 3736 is no fill value given, the linker will use the value defined in the 3737 linker configuration file (default: zero). 3738 3739 Example: 3740 3741 <tscreen><verb> 3742 ; Reserve 12 bytes of memory with value $AA 3743 .res 12, $AA 3744 </verb></tscreen> 3745 3746 3747<sect1><tt>.RODATA</tt><label id=".RODATA"><p> 3748 3749 Switch to the RODATA segment. The name of the RODATA segment is always 3750 "RODATA", so this is a shortcut for 3751 3752 <tscreen><verb> 3753 .segment "RODATA" 3754 </verb></tscreen> 3755 3756 The RODATA segment is a segment that is used by the compiler for 3757 readonly data like string constants. 3758 3759 See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. 3760 3761 3762<sect1><tt>.SCOPE</tt><label id=".SCOPE"><p> 3763 3764 Start a nested lexical level with the given name. All new symbols from now 3765 on are in the local lexical level and are accessible from outside only via 3766 <ref id="scopesyntax" name="explicit scope specification">. Symbols defined 3767 outside this local level may be accessed as long as their names are not used 3768 for new symbols inside the level. Symbols names in other lexical levels do 3769 not clash, so you may use the same names for identifiers. The lexical level 3770 ends when the <tt><ref id=".ENDSCOPE" name=".ENDSCOPE"></tt> command is 3771 read. Lexical levels may be nested up to a depth of 16 (this is an 3772 artificial limit to protect against errors in the source). 3773 3774 Note: Macro names are always in the global level and in a separate name 3775 space. There is no special reason for this, it's just that I've never 3776 had any need for local macro definitions. 3777 3778 Example: 3779 3780 <tscreen><verb> 3781 .scope Error ; Start new scope named Error 3782 None = 0 ; No error 3783 File = 1 ; File error 3784 Parse = 2 ; Parse error 3785 .endscope ; Close lexical level 3786 3787 ... 3788 lda #Error::File ; Use symbol from scope Error 3789 </verb></tscreen> 3790 3791 See: <tt/<ref id=".ENDSCOPE" name=".ENDSCOPE">/ and <tt/<ref id=".PROC" 3792 name=".PROC">/ 3793 3794 3795<sect1><tt>.SEGMENT</tt><label id=".SEGMENT"><p> 3796 3797 Switch to another segment. Code and data is always emitted into a 3798 segment, that is, a named section of data. The default segment is 3799 "CODE". There may be up to 254 different segments per object file 3800 (and up to 65534 per executable). There are shortcut commands for 3801 the most common segments ("ZEROPAGE", "CODE", "RODATA", "DATA", and "BSS"). 3802 3803 The command is followed by a string containing the segment name (there are 3804 some constraints for the name - as a rule of thumb use only those segment 3805 names that would also be valid identifiers). There may also be an optional 3806 address size separated by a colon. See the section covering <tt/<ref 3807 id="address-sizes" name="address sizes">/ for more information. 3808 3809 The default address size for a segment depends on the memory model specified 3810 on the command line. The default is "absolute", which means that you don't 3811 have to use an address size modifier in most cases. 3812 3813 "absolute" means that the is a segment with 16 bit (absolute) addressing. 3814 That is, the segment will reside somewhere in core memory outside the zero 3815 page. "zeropage" (8 bit) means that the segment will be placed in the zero 3816 page and direct (short) addressing is possible for data in this segment. 3817 3818 Beware: Only labels in a segment with the zeropage attribute are marked 3819 as reachable by short addressing. The '*' (PC counter) operator will 3820 work as in other segments and will create absolute variable values. 3821 3822 Please note that a segment cannot have two different address sizes. A 3823 segment specified as zeropage cannot be declared as being absolute later. 3824 3825 Examples: 3826 3827 <tscreen><verb> 3828 .segment "ROM2" ; Switch to ROM2 segment 3829 .segment "ZP2": zeropage ; New direct segment 3830 .segment "ZP2" ; Ok, will use last attribute 3831 .segment "ZP2": absolute ; Error, redecl mismatch 3832 </verb></tscreen> 3833 3834 See: <tt><ref id=".BSS" name=".BSS"></tt>, <tt><ref id=".CODE" 3835 name=".CODE"></tt>, <tt><ref id=".DATA" name=".DATA"></tt>, <tt><ref 3836 id=".RODATA" name=".RODATA"></tt>, and <tt><ref id=".ZEROPAGE" 3837 name=".ZEROPAGE"></tt> 3838 3839 3840<sect1><tt>.SET</tt><label id=".SET"><p> 3841 3842 <tt/.SET/ is used to assign a value to a variable. See <ref id="variables" 3843 name="Numeric variables"> for a full description. 3844 3845 3846<sect1><tt>.SETCPU</tt><label id=".SETCPU"><p> 3847 3848 Switch the CPU instruction set. The command is followed by a string that 3849 specifies the CPU. Possible values are those that can also be supplied to 3850 the <tt><ref id="option--cpu" name="--cpu"></tt> command line option, 3851 namely: 6502, 6502X, 65SC02, 65C02, 65816, 4510 and HuC6280. 3852 3853 See: <tt><ref id=".CPU" name=".CPU"></tt>, 3854 <tt><ref id=".IFP02" name=".IFP02"></tt>, 3855 <tt><ref id=".IFP816" name=".IFP816"></tt>, 3856 <tt><ref id=".IFPC02" name=".IFPC02"></tt>, 3857 <tt><ref id=".IFPSC02" name=".IFPSC02"></tt>, 3858 <tt><ref id=".P02" name=".P02"></tt>, 3859 <tt><ref id=".P816" name=".P816"></tt>, 3860 <tt><ref id=".P4510" name=".P4510"></tt>, 3861 <tt><ref id=".PC02" name=".PC02"></tt>, 3862 <tt><ref id=".PSC02" name=".PSC02"></tt> 3863 3864 3865<sect1><tt>.SMART</tt><label id=".SMART"><p> 3866 3867 Switch on or off smart mode. The command must be followed by a '+' or '-' 3868 character to switch the option on or off respectively. The default is off 3869 (that is, the assembler doesn't try to be smart), but this default may be 3870 changed by the -s switch on the command line. 3871 3872 In smart mode the assembler will do the following: 3873 3874 <itemize> 3875 <item>Track usage of the <tt/REP/ and <tt/SEP/ instructions in 65816 mode 3876 and update the operand sizes accordingly. If the operand of such an 3877 instruction cannot be evaluated by the assembler (for example, because 3878 the operand is an imported symbol), a warning is issued. Beware: Since 3879 the assembler cannot trace the execution flow this may lead to false 3880 results in some cases. If in doubt, use the <tt/.Inn/ and <tt/.Ann/ 3881 instructions to tell the assembler about the current settings. 3882 <item>In 65816 mode, replace a <tt/RTS/ instruction by <tt/RTL/ if it is 3883 used within a procedure declared as <tt/far/, or if the procedure has 3884 no explicit address specification, but it is <tt/far/ because of the 3885 memory model used. 3886 </itemize> 3887 3888 Example: 3889 3890 <tscreen><verb> 3891 .smart ; Be smart 3892 .smart - ; Stop being smart 3893 </verb></tscreen> 3894 3895 See: <tt><ref id=".A16" name=".A16"></tt>, 3896 <tt><ref id=".A8" name=".A8"></tt>, 3897 <tt><ref id=".I16" name=".I16"></tt>, 3898 <tt><ref id=".I8" name=".I8"></tt> 3899 3900 3901<sect1><tt>.STRUCT</tt><label id=".STRUCT"><p> 3902 3903 Starts a struct definition. Structs are covered in a separate section named 3904 <ref id="structs" name=""Structs and unions"">. 3905 3906 See also: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></tt>, 3907 <tt><ref id=".ENDUNION" name=".ENDUNION"></tt>, 3908 <tt><ref id=".UNION" name=".UNION"></tt> 3909 3910 3911<sect1><tt>.TAG</tt><label id=".TAG"><p> 3912 3913 Allocate space for a struct or union. 3914 3915 Example: 3916 3917 <tscreen><verb> 3918 .struct Point 3919 xcoord .word 3920 ycoord .word 3921 .endstruct 3922 3923 .bss 3924 .tag Point ; Allocate 4 bytes 3925 </verb></tscreen> 3926 3927 3928<sect1><tt>.UNDEF, .UNDEFINE</tt><label id=".UNDEFINE"><p> 3929 3930 Delete a define style macro definition. The command is followed by an 3931 identifier which specifies the name of the macro to delete. Macro 3932 replacement is switched of when reading the token following the command 3933 (otherwise the macro name would be replaced by its replacement list). 3934 3935 See also the <tt><ref id=".DEFINE" name=".DEFINE"></tt> command and 3936 section <ref id="macros" name="Macros">. 3937 3938 3939<sect1><tt>.UNION</tt><label id=".UNION"><p> 3940 3941 Starts a union definition. Unions are covered in a separate section named 3942 <ref id="structs" name=""Structs and unions"">. 3943 3944 See also: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></tt>, 3945 <tt><ref id=".ENDUNION" name=".ENDUNION"></tt>, 3946 <tt><ref id=".STRUCT" name=".STRUCT"></tt> 3947 3948 3949<sect1><tt>.WARNING</tt><label id=".WARNING"><p> 3950 3951 Force an assembly warning. The assembler will output a warning message 3952 preceded by "User warning". This warning will always be output, even if 3953 other warnings are disabled with the <tt><ref id="option-W" name="-W0"></tt> 3954 command line option. 3955 3956 This command may be used to output possible problems when assembling 3957 the source file. 3958 3959 Example: 3960 3961 <tscreen><verb> 3962 .macro jne target 3963 .local L1 3964 .ifndef target 3965 .warning "Forward jump in jne, cannot optimize!" 3966 beq L1 3967 jmp target 3968 L1: 3969 .else 3970 ... 3971 .endif 3972 .endmacro 3973 </verb></tscreen> 3974 3975 See also: <tt><ref id=".ERROR" name=".ERROR"></tt>, 3976 <tt><ref id=".FATAL" name=".FATAL"></tt>, 3977 <tt><ref id=".OUT" name=".OUT"></tt> 3978 3979 3980<sect1><tt>.WORD</tt><label id=".WORD"><p> 3981 3982 Define word sized data. Must be followed by a sequence of (word ranged, 3983 but not necessarily constant) expressions. 3984 3985 Example: 3986 3987 <tscreen><verb> 3988 .word $0D00, $AF13, _Clear 3989 </verb></tscreen> 3990 3991 3992<sect1><tt>.ZEROPAGE</tt><label id=".ZEROPAGE"><p> 3993 3994 Switch to the ZEROPAGE segment and mark it as direct (zeropage) segment. 3995 The name of the ZEROPAGE segment is always "ZEROPAGE", so this is a 3996 shortcut for 3997 3998 <tscreen><verb> 3999 .segment "ZEROPAGE": zeropage 4000 </verb></tscreen> 4001 4002 Because of the "zeropage" attribute, labels declared in this segment are 4003 addressed using direct addressing mode if possible. You <em/must/ instruct 4004 the linker to place this segment somewhere in the address range 0..$FF 4005 otherwise you will get errors. 4006 4007 See: <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> 4008 4009 4010 4011<sect>Macros<label id="macros"><p> 4012 4013 4014<sect1>Introduction<p> 4015 4016Macros may be thought of as "parametrized super instructions". Macros are 4017sequences of tokens that have a name. If that name is used in the source 4018file, the macro is "expanded", that is, it is replaced by the tokens that 4019were specified when the macro was defined. 4020 4021 4022<sect1>Macros without parameters<p> 4023 4024In its simplest form, a macro does not have parameters. Here's an 4025example: 4026 4027<tscreen><verb> 4028.macro asr ; Arithmetic shift right 4029 cmp #$80 ; Put bit 7 into carry 4030 ror ; Rotate right with carry 4031.endmacro 4032</verb></tscreen> 4033 4034The macro above consists of two real instructions, that are inserted into 4035the code, whenever the macro is expanded. Macro expansion is simply done 4036by using the name, like this: 4037 4038<tscreen><verb> 4039 lda $2010 4040 asr 4041 sta $2010 4042</verb></tscreen> 4043 4044 4045<sect1>Parametrized macros<p> 4046 4047When using macro parameters, macros can be even more useful: 4048 4049<tscreen><verb> 4050.macro inc16 addr 4051 clc 4052 lda addr 4053 adc #<$0001 4054 sta addr 4055 lda addr+1 4056 adc #>$0001 4057 sta addr+1 4058.endmacro 4059</verb></tscreen> 4060 4061When calling the macro, you may give a parameter, and each occurrence of 4062the name "addr" in the macro definition will be replaced by the given 4063parameter. So 4064 4065<tscreen><verb> 4066 inc16 $1000 4067</verb></tscreen> 4068 4069will be expanded to 4070 4071<tscreen><verb> 4072 clc 4073 lda $1000 4074 adc #<$0001 4075 sta $1000 4076 lda $1000+1 4077 adc #>$0001 4078 sta $1000+1 4079</verb></tscreen> 4080 4081A macro may have more than one parameter, in this case, the parameters 4082are separated by commas. You are free to give less parameters than the 4083macro actually takes in the definition. You may also leave intermediate 4084parameters empty. Empty parameters are replaced by empty space (that is, 4085they are removed when the macro is expanded). If you have a look at our 4086macro definition above, you will see, that replacing the "addr" parameter 4087by nothing will lead to wrong code in most lines. To help you, writing 4088macros with a variable parameter list, there are some control commands: 4089 4090<tt><ref id=".IFBLANK" name=".IFBLANK"></tt> tests the rest of the line and 4091returns true, if there are any tokens on the remainder of the line. Since 4092empty parameters are replaced by nothing, this may be used to test if a given 4093parameter is empty. <tt><ref id=".IFNBLANK" name=".IFNBLANK"></tt> tests the 4094opposite. 4095 4096Look at this example: 4097 4098<tscreen><verb> 4099.macro ldaxy a, x, y 4100.ifnblank a 4101 lda #a 4102.endif 4103.ifnblank x 4104 ldx #x 4105.endif 4106.ifnblank y 4107 ldy #y 4108.endif 4109.endmacro 4110</verb></tscreen> 4111 4112That macro may be called as follows: 4113 4114<tscreen><verb> 4115 ldaxy 1, 2, 3 ; Load all three registers 4116 4117 ldaxy 1, , 3 ; Load only a and y 4118 4119 ldaxy , , 3 ; Load y only 4120</verb></tscreen> 4121 4122There's another helper command for determining which macro parameters are 4123valid: <tt><ref id=".PARAMCOUNT" name=".PARAMCOUNT"></tt>. That command is 4124replaced by the parameter count given, <em/including/ explicitly empty 4125parameters: 4126 4127<tscreen><verb> 4128 ldaxy 1 ; .PARAMCOUNT = 1 4129 ldaxy 1,,3 ; .PARAMCOUNT = 3 4130 ldaxy 1,2 ; .PARAMCOUNT = 2 4131 ldaxy 1, ; .PARAMCOUNT = 2 4132 ldaxy 1,2,3 ; .PARAMCOUNT = 3 4133</verb></tscreen> 4134 4135Macro parameters may optionally be enclosed into curly braces. This allows the 4136inclusion of tokens that would otherwise terminate the parameter (the comma in 4137case of a macro parameter). 4138 4139<tscreen><verb> 4140.macro foo arg1, arg2 4141 ... 4142.endmacro 4143 4144 foo ($00,x) ; Two parameters passed 4145 foo {($00,x)} ; One parameter passed 4146</verb></tscreen> 4147 4148In the first case, the macro is called with two parameters: '<tt/($00/' 4149and '<tt/x)/'. The comma is not passed to the macro, because it is part of the 4150calling sequence, not the parameters. 4151 4152In the second case, '<tt/($00,x)/' is passed to the macro; this time, 4153including the comma. 4154 4155 4156<sect1>Detecting parameter types<p> 4157 4158Sometimes it is nice to write a macro that acts differently depending on the 4159type of the argument supplied. An example would be a macro that loads a 16 bit 4160value from either an immediate operand, or from memory. The <tt/<ref 4161id=".MATCH" name=".MATCH">/ and <tt/<ref id=".XMATCH" name=".XMATCH">/ 4162functions will allow you to do exactly this: 4163 4164<tscreen><verb> 4165.macro ldax arg 4166 .if (.match (.left (1, {arg}), #)) 4167 ; immediate mode 4168 lda #<(.right (.tcount ({arg})-1, {arg})) 4169 ldx #>(.right (.tcount ({arg})-1, {arg})) 4170 .else 4171 ; assume absolute or zero page 4172 lda arg 4173 ldx 1+(arg) 4174 .endif 4175.endmacro 4176</verb></tscreen> 4177 4178Using the <tt/<ref id=".MATCH" name=".MATCH">/ function, the macro is able to 4179check if its argument begins with a hash mark. If so, two immediate loads are 4180emitted, Otherwise a load from an absolute zero page memory location is 4181assumed. Please note how the curly braces are used to enclose parameters to 4182pseudo functions handling token lists. This is necessary, because the token 4183lists may include commas or parens, which would be treated by the assembler 4184as end-of-list. 4185 4186The macro can be used as 4187 4188<tscreen><verb> 4189foo: .word $5678 4190... 4191 ldax #$1234 ; X=$12, A=$34 4192... 4193 ldax foo ; X=$56, A=$78 4194</verb></tscreen> 4195 4196 4197<sect1>Recursive macros<p> 4198 4199Macros may be used recursively: 4200 4201<tscreen><verb> 4202.macro push r1, r2, r3 4203 lda r1 4204 pha 4205.ifnblank r2 4206 push r2, r3 4207.endif 4208.endmacro 4209</verb></tscreen> 4210 4211There's also a special macro command to help with writing recursive macros: 4212<tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt>. That command will stop macro 4213expansion immediately: 4214 4215<tscreen><verb> 4216.macro push r1, r2, r3, r4, r5, r6, r7 4217.ifblank r1 4218 ; First parameter is empty 4219 .exitmacro 4220.else 4221 lda r1 4222 pha 4223.endif 4224 push r2, r3, r4, r5, r6, r7 4225.endmacro 4226</verb></tscreen> 4227 4228When expanding that macro, the expansion will push all given parameters 4229until an empty one is encountered. The macro may be called like this: 4230 4231<tscreen><verb> 4232 push $20, $21, $32 ; Push 3 ZP locations 4233 push $21 ; Push one ZP location 4234</verb></tscreen> 4235 4236 4237<sect1>Local symbols inside macros<p> 4238 4239Now, with recursive macros, <tt><ref id=".IFBLANK" name=".IFBLANK"></tt> and 4240<tt><ref id=".PARAMCOUNT" name=".PARAMCOUNT"></tt>, what else do you need? 4241Have a look at the inc16 macro above. Here is it again: 4242 4243<tscreen><verb> 4244.macro inc16 addr 4245 clc 4246 lda addr 4247 adc #<$0001 4248 sta addr 4249 lda addr+1 4250 adc #>$0001 4251 sta addr+1 4252.endmacro 4253</verb></tscreen> 4254 4255If you have a closer look at the code, you will notice, that it could be 4256written more efficiently, like this: 4257 4258<tscreen><verb> 4259.macro inc16 addr 4260 inc addr 4261 bne Skip 4262 inc addr+1 4263Skip: 4264.endmacro 4265</verb></tscreen> 4266 4267But imagine what happens, if you use this macro twice? Since the label "Skip" 4268has the same name both times, you get a "duplicate symbol" error. Without a 4269way to circumvent this problem, macros are not as useful, as they could be. 4270One possible solution is the command <tt><ref id=".LOCAL" name=".LOCAL"></tt>. 4271It declares one or more symbols as local to the macro expansion. The names of 4272local variables are replaced by a unique name in each separate macro 4273expansion. So we can solve the problem above by using <tt/.LOCAL/: 4274 4275<tscreen><verb> 4276.macro inc16 addr 4277 .local Skip ; Make Skip a local symbol 4278 inc addr 4279 bne Skip 4280 inc addr+1 4281Skip: ; Not visible outside 4282.endmacro 4283</verb></tscreen> 4284 4285Another solution is of course to start a new lexical block inside the macro 4286that hides any labels: 4287 4288<tscreen><verb> 4289.macro inc16 addr 4290.proc 4291 inc addr 4292 bne Skip 4293 inc addr+1 4294Skip: 4295.endproc 4296.endmacro 4297</verb></tscreen> 4298 4299 4300<sect1>C style macros<p> 4301 4302Starting with version 2.5 of the assembler, there is a second macro type 4303available: C style macros using the <tt/.DEFINE/ directive. These macros are 4304similar to the classic macro type described above, but behaviour is sometimes 4305different: 4306 4307<itemize> 4308 4309<item> Macros defined with <tt><ref id=".DEFINE" name=".DEFINE"></tt> may not 4310 span more than a line. You may use line continuation (see <tt><ref 4311 id=".LINECONT" name=".LINECONT"></tt>) to spread the definition over 4312 more than one line for increased readability, but the macro itself 4313 may not contain an end-of-line token. 4314 4315<item> Macros defined with <tt><ref id=".DEFINE" name=".DEFINE"></tt> share 4316 the name space with classic macros, but they are detected and replaced 4317 at the scanner level. While classic macros may be used in every place, 4318 where a mnemonic or other directive is allowed, <tt><ref id=".DEFINE" 4319 name=".DEFINE"></tt> style macros are allowed anywhere in a line. So 4320 they are more versatile in some situations. 4321 4322<item> <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may take 4323 parameters. While classic macros may have empty parameters, this is 4324 not true for <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros. 4325 For this macro type, the number of actual parameters must match 4326 exactly the number of formal parameters. 4327 4328 To make this possible, formal parameters are enclosed in braces when 4329 defining the macro. If there are no parameters, the empty braces may 4330 be omitted. 4331 4332<item> Since <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may not 4333 contain end-of-line tokens, there are things that cannot be done. They 4334 may not contain several processor instructions for example. So, while 4335 some things may be done with both macro types, each type has special 4336 usages. The types complement each other. 4337 4338<item> Parentheses work differently from C macros. 4339 The common practice of wrapping C macros in parentheses may cause 4340 unintended problems here, such as accidentally implying an 4341 indirect addressing mode. While the definition of a macro requires 4342 parentheses around its argument list, when invoked they should not be 4343 included. 4344 4345</itemize> 4346 4347Let's look at a few examples to make the advantages and disadvantages 4348clear. 4349 4350To emulate assemblers that use "<tt/EQU/" instead of "<tt/=/" you may use the 4351following <tt/.DEFINE/: 4352 4353<tscreen><verb> 4354.define EQU = 4355 4356foo EQU $1234 ; This is accepted now 4357</verb></tscreen> 4358 4359You may use the directive to define string constants used elsewhere: 4360 4361<tscreen><verb> 4362; Define the version number 4363.define VERSION "12.3a" 4364 4365 ; ... and use it 4366 .asciiz VERSION 4367</verb></tscreen> 4368 4369Macros with parameters may also be useful: 4370 4371<tscreen><verb> 4372.define DEBUG(message) .out message 4373 4374 DEBUG "Assembling include file #3" 4375</verb></tscreen> 4376 4377Note that, while formal parameters have to be placed in parentheses, 4378the actual argument used when invoking the macro should not be. 4379The invoked arguments are separated by commas only, if parentheses are 4380used by accident they will become part of the replaced token. 4381 4382If you wish to have an expression follow the macro invocation, the 4383last parameter can be enclosed in curly braces {} to indicate the end of that 4384argument. 4385 4386Examples: 4387 4388<tscreen><verb> 4389.define COMBINE(ta,tb,tc) ta+tb*10+tc*100 4390 4391.word COMBINE 5,6,7 ; 5+6*10+7*100 = 765 4392.word COMBINE(5,6,7) ; (5+6*10+7)*100 = 7200 ; incorrect use of parentheses 4393.word COMBINE 5,6,7+1 ; 5+6*10+7+1*100 = 172 4394.word COMBINE 5,6,{7}+1 ; 5+6*10+7*100+1 = 766 ; {} encloses the argument 4395.word COMBINE 5,6-2,7 ; 5+6-2*10+7*100 = 691 4396.word COMBINE 5,(6-2),7 ; 5+(6-2)*10+7*100 = 745 4397.word COMBINE 5,6,7+COMBINE 0,1,2 ; 5+6*10+7+0+1*10+2*100*100 = 20082 4398.word COMBINE 5,6,{7}+COMBINE 0,1,2 ; 5+6*10+7*100+0+1*10+2*100 = 975 4399</verb></tscreen> 4400 4401With C macros it is common to enclose the results in parentheses to 4402prevent unintended interactions with the text of the arguments, but 4403additional care must be taken in this assembly context where parentheses 4404may alter the meaning of a statement. In particular, indirect addressing modes 4405may be accidentally implied: 4406 4407<tscreen><verb> 4408.define DUO(ta,tb) (ta+(tb*10)) 4409 4410 lda DUO(5,4), Y ; LDA (indirect), Y 4411 lda 0+DUO(5,4), Y ; LDA absolute indexed, Y 4412</verb></tscreen> 4413 4414 4415<sect1>Characters in macros<p> 4416 4417When using the <ref id="option-t" name="-t"> option, characters are translated 4418into the target character set of the specific machine. However, this happens 4419as late as possible. This means that strings are translated if they are part 4420of a <tt><ref id=".BYTE" name=".BYTE"></tt> or <tt><ref id=".ASCIIZ" 4421name=".ASCIIZ"></tt> command. Characters are translated as soon as they are 4422used as part of an expression. 4423 4424This behaviour is very intuitive outside of macros but may be confusing when 4425doing more complex macros. If you compare characters against numeric values, 4426be sure to take the translation into account. 4427 4428 4429<sect1>Deleting macros<p> 4430 4431Macros can be deleted. This will not work if the macro that should be deleted 4432is currently expanded as in the following non-working example: 4433 4434<tscreen><verb> 4435.macro notworking 4436 .delmacro notworking 4437.endmacro 4438 4439 notworking ; Will not work 4440</verb></tscreen> 4441 4442The commands to delete classic and define style macros differ. Classic macros 4443can be deleted by use of <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, while 4444for <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros, <tt><ref 4445id=".UNDEFINE" name=".UNDEFINE"></tt> must be used. Example: 4446 4447<tscreen><verb> 4448.define value 1 4449.macro mac 4450 .byte 2 4451.endmacro 4452 4453 .byte value ; Emit one byte with value 1 4454 mac ; Emit another byte with value 2 4455 4456.undefine value 4457.delmacro mac 4458 4459 .byte value ; Error: Unknown identifier 4460 mac ; Error: Missing ":" 4461</verb></tscreen> 4462 4463A separate command for <tt>.DEFINE</tt> style macros was necessary, because 4464the name of such a macro is replaced by its replacement list on a very low 4465level. To get the actual name, macro replacement has to be switched off when 4466reading the argument to <tt>.UNDEFINE</tt>. This does also mean that the 4467argument to <tt>.UNDEFINE</tt> is not allowed to come from another 4468<tt>.DEFINE</tt>. All this is not necessary for classic macros, so having two 4469different commands increases flexibility. 4470 4471 4472 4473<sect>Macro packages<label id="macropackages"><p> 4474 4475Using the <tt><ref id=".MACPACK" name=".MACPACK"></tt> directive, predefined 4476macro packages may be included with just one command. Available macro packages 4477are: 4478 4479 4480<sect1><tt>.MACPACK generic</tt><p> 4481 4482This macro package defines macros that are useful in almost any program. 4483Currently defined macros are: 4484 4485<tscreen><verb> 4486 .macro add Arg ; add without carry 4487 clc 4488 adc Arg 4489 .endmacro 4490 4491 .macro sub Arg ; subtract without borrow 4492 sec 4493 sbc Arg 4494 .endmacro 4495 4496 .macro bge Arg ; branch on greater-than or equal 4497 bcs Arg 4498 .endmacro 4499 4500 .macro blt Arg ; branch on less-than 4501 bcc Arg 4502 .endmacro 4503 4504 .macro bgt Arg ; branch on greater-than 4505 .local L 4506 beq L 4507 bcs Arg 4508 L: 4509 .endmacro 4510 4511 .macro ble Arg ; branch on less-than or equal 4512 beq Arg 4513 bcc Arg 4514 .endmacro 4515 4516 .macro bnz Arg ; branch on not zero 4517 bne Arg 4518 .endmacro 4519 4520 .macro bze Arg ; branch on zero 4521 beq Arg 4522 .endmacro 4523</verb></tscreen> 4524 4525 4526<sect1><tt>.MACPACK longbranch</tt><p> 4527 4528This macro package defines long conditional jumps. They are named like the 4529short counterpart but with the 'b' replaced by a 'j'. Here is a sample 4530definition for the "<tt/jeq/" macro, the other macros are built using the same 4531scheme: 4532 4533<tscreen><verb> 4534 .macro jeq Target 4535 .if .def(Target) .and ((*+2)-(Target) <= 127) 4536 beq Target 4537 .else 4538 bne *+5 4539 jmp Target 4540 .endif 4541 .endmacro 4542</verb></tscreen> 4543 4544All macros expand to a short branch, if the label is already defined (back 4545jump) and is reachable with a short jump. Otherwise the macro expands to a 4546conditional branch with the branch condition inverted, followed by an absolute 4547jump to the actual branch target. 4548 4549The package defines the following macros: 4550 4551<tscreen><verb> 4552 jeq, jne, jmi, jpl, jcs, jcc, jvs, jvc 4553</verb></tscreen> 4554 4555 4556 4557<sect1><tt>.MACPACK apple2</tt><p> 4558 4559This macro package defines a macro named <tt/scrcode/. It takes a string 4560as argument and places this string into memory translated into screen codes. 4561 4562 4563<sect1><tt>.MACPACK atari</tt><p> 4564 4565This macro package defines a macro named <tt/scrcode/. It takes a string 4566as argument and places this string into memory translated into screen codes. 4567 4568 4569<sect1><tt>.MACPACK cbm</tt><p> 4570 4571This macro package defines a macro named <tt/scrcode/. It takes a string 4572as argument and places this string into memory translated into screen codes. 4573 4574 4575<sect1><tt>.MACPACK cpu</tt><p> 4576 4577This macro package does not define any macros but constants used to examine 4578the value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable. For 4579each supported CPU a constant similar to 4580 4581<tscreen><verb> 4582 CPU_6502 4583 CPU_65SC02 4584 CPU_65C02 4585 CPU_65816 4586 CPU_SWEET16 4587 CPU_HUC6280 4588 CPU_4510 4589</verb></tscreen> 4590 4591is defined. These constants may be used to determine the exact type of the 4592currently enabled CPU. In addition to that, for each CPU instruction set, 4593another constant is defined: 4594 4595<tscreen><verb> 4596 CPU_ISET_6502 4597 CPU_ISET_65SC02 4598 CPU_ISET_65C02 4599 CPU_ISET_65816 4600 CPU_ISET_SWEET16 4601 CPU_ISET_HUC6280 4602 CPU_ISET_4510 4603</verb></tscreen> 4604 4605The value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable may 4606be checked with <tt/<ref id="operators" name=".BITAND">/ to determine if the 4607currently enabled CPU supports a specific instruction set. For example the 460865C02 supports all instructions of the 65SC02 CPU, so it has the 4609<tt/CPU_ISET_65SC02/ bit set in addition to its native <tt/CPU_ISET_65C02/ 4610bit. Using 4611 4612<tscreen><verb> 4613 .if (.cpu .bitand CPU_ISET_65SC02) 4614 lda (sp) 4615 .else 4616 ldy #$00 4617 lda (sp),y 4618 .endif 4619</verb></tscreen> 4620 4621it is possible to determine if the 4622 4623<tscreen><verb> 4624 lda (sp) 4625</verb></tscreen> 4626 4627instruction is supported, which is the case for the 65SC02, 65C02 and 65816 4628CPUs (the latter two are upwards compatible to the 65SC02). 4629 4630 4631<sect1><tt>.MACPACK module</tt><p> 4632 4633This macro package defines a macro named <tt/module_header/. It takes an 4634identifier as argument and is used to define the header of a module both 4635in the dynamic and static variant. 4636 4637 4638 4639<sect>Predefined constants<label id="predefined-constants"><p> 4640 4641For better orthogonality, the assembler defines similar symbols as the 4642compiler, depending on the target system selected: 4643 4644<itemize> 4645<item><tt/__APPLE2__/ - Target system is <tt/apple2/ or <tt/apple2enh/ 4646<item><tt/__APPLE2ENH__/ - Target system is <tt/apple2enh/ 4647<item><tt/__ATARI2600__/ - Target system is <tt/atari2600/ 4648<item><tt/__ATARI5200__/ - Target system is <tt/atari5200/ 4649<item><tt/__ATARI__/ - Target system is <tt/atari/ or <tt/atarixl/ 4650<item><tt/__ATARIXL__/ - Target system is <tt/atarixl/ 4651<item><tt/__ATMOS__/ - Target system is <tt/atmos/ 4652<item><tt/__BBC__/ - Target system is <tt/bbc/ 4653<item><tt/__C128__/ - Target system is <tt/c128/ 4654<item><tt/__C16__/ - Target system is <tt/c16/ or <tt/plus4/ 4655<item><tt/__C64__/ - Target system is <tt/c64/ 4656<item><tt/__CBM__/ - Target is a Commodore or Commodore-alike system 4657<item><tt/__CBM510__/ - Target system is <tt/cbm510/ 4658<item><tt/__CBM610__/ - Target system is <tt/cbm610/ 4659<item><tt/__CX16__/ - Target system is <tt/cx16/ 4660<item><tt/__GEOS__/ - Target is a GEOS system 4661<item><tt/__GEOS_APPLE__/ - Target system is <tt/geos-apple/ 4662<item><tt/__GEOS_CBM__/ - Target system is <tt/geos-cbm/ 4663<item><tt/__LUNIX__/ - Target system is <tt/lunix/ 4664<item><tt/__LYNX__/ - Target system is <tt/lynx/ 4665<item><tt/__NES__/ - Target system is <tt/nes/ 4666<item><tt/__OSIC1P__/ - Target system is <tt/osic1p/ 4667<item><tt/__PET__/ - Target system is <tt/pet/ 4668<item><tt/__PLUS4__/ - Target system is <tt/plus4/ 4669<item><tt/__SIM6502__/ - Target system is <tt/sim6502/ 4670<item><tt/__SIM65C02__/ - Target system is <tt/sim65c02/ 4671<item><tt/__SUPERVISION__/ - Target system is <tt/supervision/ 4672<item><tt/__VIC20__/ - Target system is <tt/vic20/ 4673</itemize> 4674 4675 4676 4677<sect>Structs and unions<label id="structs"><p> 4678 4679<sect1>Structs and unions Overview<p> 4680 4681Structs and unions are special forms of <ref id="scopes" name="scopes">. They 4682are, to some degree, comparable to their C counterparts. Both have a list of 4683members. Each member allocates storage, and optionally may have a name whose 4684value, in the case of a struct, usually is the storage offset from the 4685beginning, and in the case of a union, doesn't change, and usually is zero. 4686 4687 4688<sect1>Declaration<p> 4689 4690Here is an example for a very simple struct with two members and a total size 4691of 4 bytes: 4692<tscreen><verb> 4693 .struct Point 4694 xcoord .word 4695 ycoord .word 4696 .endstruct 4697</verb></tscreen> 4698 4699A union shares the total space between all its members; its size is the same 4700as that of the largest member. The offset of all members relative to the union 4701is zero. 4702<tscreen><verb> 4703 .union Entry 4704 index .word 4705 ptr .addr 4706 .endunion 4707</verb></tscreen> 4708 4709A struct or union may not necessarily have a name. If it is anonymous, no 4710local scope is opened; the identifiers used to name the members are placed 4711into the current scope instead. 4712 4713A struct may contain unnamed members and definitions of local structs/unions. 4714The storage allocators may contain a multiplier, as in the example below: 4715<tscreen><verb> 4716 .struct Circle 4717 .struct Point 4718 .word 2 ; Allocate two words 4719 .endstruct 4720 Radius .word 4721 .endstruct 4722</verb></tscreen> 4723The size of the Circle struct is 6 (three words). 4724 4725 4726<sect1>The storage allocator keywords<p> 4727 4728 <descrip> 4729 4730 <tag/.BYTE, .RES/ 4731 Allocates multiples of 1 byte. <tt/.RES/ requires an operand. 4732 4733 <tag/.DBYTE, .WORD, .ADDR/ 4734 Allocates multiples of 2 bytes. 4735 4736 <tag/.FARADDR/ 4737 Allocates multiples of 3 bytes. 4738 4739 <tag/.DWORD/ 4740 Allocates multiples of 4 bytes. 4741 4742 </descrip> 4743 4744 4745<sect1>The <tt/.ORG/ keyword<p> 4746 4747The <tt/.ORG/ keyword changes the offset value that is assigned to subsequent 4748member names. It's useful when using a struct to define the names of the 4749registers in an I/O chip. Example: 4750<tscreen><verb> 4751; 6551 4752.struct ACIA ; Asynchronous Communications Interface Adapter 4753 .org $031C 4754DATA .byte 4755STATUS .byte 4756CMD .byte ; Command register 4757CTRL .byte ; Control register 4758.endstruct 4759 4760 lda ACIA::DATA ; Get an RS-232 character 4761</verb></tscreen> 4762 4763 4764<sect1>The <tt/.TAG/ keyword<p> 4765 4766By using the <ref id=".TAG" name=".TAG"> keyword, it is possible to reserve 4767space for an already defined struct or union within another struct: 4768<tscreen><verb> 4769 .struct Point 4770 xcoord .word 4771 ycoord .word 4772 .endstruct 4773 4774 .struct Circle 4775 Origin .tag Point 4776 Radius .byte 4777 .endstruct 4778</verb></tscreen> 4779 4780Actual space for a struct or union may be allocated by using the <ref id=".TAG" 4781name=".TAG"> directive. 4782<tscreen><verb> 4783C: .tag Circle 4784</verb></tscreen> 4785 4786Currently, members are just offsets from the start of the struct or union. To 4787access a field of a struct, the member offset must be added to the address of 4788the struct variable itself: 4789<tscreen><verb> 4790 lda C+Circle::Radius ; Load circle radius into A 4791</verb></tscreen> 4792That may change in a future version of the assembler. 4793 4794 4795<sect1>Limitations<p> 4796 4797Structs and unions currently are implemented as nested symbol tables (in fact, 4798they were a by-product of the improved scoping rules). Currently, the 4799assembler has no idea of types. That means that the <ref id=".TAG" 4800name=".TAG"> keyword only will allocate space. You won't be able to initialize 4801variables declared with <ref id=".TAG" name=".TAG">; and, adding an embedded 4802structure to another structure with <ref id=".TAG" name=".TAG"> will not make 4803that added structure accessible by using the '::' operator. 4804 4805 4806 4807<sect>Module constructors/destructors<label id="condes"><p> 4808 4809<em>Note:</em> This section applies mostly to C programs, so the explanation 4810below uses examples from the C libraries. However, the feature may also be 4811useful for assembler programs. 4812 4813 4814<sect1>Module constructors/destructors Overview<p> 4815 4816Using the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref 4817id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR" 4818name=".INTERRUPTOR"></tt> keywords it is possible to export functions in a 4819special way. The linker is able to generate tables with all functions of a 4820specific type. Such a table will <em>only</em> include symbols from object 4821files that are linked into a specific executable. This may be used to add 4822initialization and cleanup code for library modules, or a table of interrupt 4823handler functions. 4824 4825The C heap functions are an example where module initialization code is used. 4826All heap functions (<tt>malloc</tt>, <tt>free</tt>, ...) work with a few 4827variables that contain the start and the end of the heap, pointers to the free 4828list and so on. Since the end of the heap depends on the size and start of the 4829stack, it must be initialized at runtime. However, initializing these 4830variables for programs that do not use the heap are a waste of time and 4831memory. 4832 4833So the central module defines a function that contains initialization code and 4834exports this function using the <tt/.CONSTRUCTOR/ statement. If (and only if) 4835this module is added to an executable by the linker, the initialization 4836function will be placed into the table of constructors by the linker. The C 4837startup code will call all constructors before <tt/main/ and all destructors 4838after <tt/main/, so without any further work, the heap initialization code is 4839called once the module is linked in. 4840 4841While it would be possible to add explicit calls to initialization functions 4842in the startup code, the new approach has several advantages: 4843 4844<enum> 4845<item> 4846If a module is not included, the initialization code is not linked in and not 4847called. So you don't pay for things you don't need. 4848 4849<item> 4850Adding another library that needs initialization does not mean that the 4851startup code has to be changed. Before we had module constructors and 4852destructors, the startup code for all systems had to be adjusted to call the 4853new initialization code. 4854 4855<item> 4856The feature saves memory: Each additional initialization function needs just 4857two bytes in the table (a pointer to the function). 4858 4859</enum> 4860 4861 4862<sect1>Calling order<p> 4863 4864The symbols are sorted in increasing priority order by the linker when using 4865one of the builtin linker configurations, so the functions with lower 4866priorities come first and are followed by those with higher priorities. The C 4867library runtime subroutine that walks over the function tables calls the 4868functions starting from the top of the table - which means that functions with 4869a high priority are called first. 4870 4871So when using the C runtime, functions are called with high priority functions 4872first, followed by low priority functions. 4873 4874 4875<sect1>Pitfalls<p> 4876 4877When using these special symbols, please take care of the following: 4878 4879<itemize> 4880 4881<item> 4882The linker will only generate function tables, it will not generate code to 4883call these functions. If you're using the feature in some other than the 4884existing C environments, you have to write code to call all functions in a 4885linker generated table yourself. See the <tt/condes/ and <tt/callirq/ modules 4886in the C runtime for an example on how to do this. 4887 4888<item> 4889The linker will only add addresses of functions that are in modules linked to 4890the executable. This means that you have to be careful where to place the 4891condes functions. If initialization or an irq handler is needed for a group of 4892functions, be sure to place the function into a module that is linked in 4893regardless of which function is called by the user. 4894 4895<item> 4896The linker will generate the tables only when requested to do so by the 4897<tt/FEATURE CONDES/ statement in the linker config file. Each table has to 4898be requested separately. 4899 4900<item> 4901Constructors and destructors may have priorities. These priorities determine 4902the order of the functions in the table. If your initialization or cleanup code 4903does depend on other initialization or cleanup code, you have to choose the 4904priority for the functions accordingly. 4905 4906<item> 4907Besides the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref 4908id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR" 4909name=".INTERRUPTOR"></tt> statements, there is also a more generic command: 4910<tt><ref id=".CONDES" name=".CONDES"></tt>. This allows to specify an 4911additional type. Predefined types are 0 (constructor), 1 (destructor) and 2 4912(interruptor). The linker generates a separate table for each type on request. 4913 4914</itemize> 4915 4916 4917<sect>Porting sources from other assemblers<p> 4918 4919Sometimes it is necessary to port code written for older assemblers to ca65. 4920In some cases, this can be done without any changes to the source code by 4921using the emulation features of ca65 (see <tt><ref id=".FEATURE" 4922name=".FEATURE"></tt>). In other cases, it is necessary to make changes to the 4923source code. 4924 4925Probably the biggest difference is the handling of the <tt><ref id=".ORG" 4926name=".ORG"></tt> directive. ca65 generates relocatable code, and placement is 4927done by the linker. Most other assemblers generate absolute code, placement is 4928done within the assembler and there is no external linker. 4929 4930In general it is not a good idea to write new code using the emulation 4931features of the assembler, but there may be situations where even this rule is 4932not valid. 4933 4934<sect1>TASS<p> 4935 4936You need to use some of the ca65 emulation features to simulate the behaviour 4937of such simple assemblers. 4938 4939<enum> 4940<item>Prepare your sourcecode like this: 4941 4942<tscreen><verb> 4943 ; if you want TASS style labels without colons 4944 .feature labels_without_colons 4945 4946 ; if you want TASS style character constants 4947 ; ("a" instead of the default 'a') 4948 .feature loose_char_term 4949 4950 .word *+2 ; the cbm load address 4951 4952 [yourcode here] 4953</verb></tscreen> 4954 4955notice that the two emulation features are mostly useful for porting 4956sources originally written in/for TASS, they are not needed for the 4957actual "simple assembler operation" and are not recommended if you are 4958writing new code from scratch. 4959 4960<item>Replace all program counter assignments (which are not possible in ca65 4961by default, and the respective emulation feature works different from what 4962you'd expect) by another way to skip to memory locations, for example the 4963<tt><ref id=".RES" name=".RES"></tt> directive. 4964 4965<tscreen><verb> 4966 ; *=$2000 4967 .res $2000-* ; reserve memory up to $2000 4968</verb></tscreen> 4969 4970Please note that other than the original TASS, ca65 can never move the program 4971counter backwards - think of it as if you are assembling to disk with TASS. 4972 4973<item>Conditional assembly (<tt/.ifeq//<tt/.endif//<tt/.goto/ etc.) must be 4974rewritten to match ca65 syntax. Most importantly notice that due to the lack 4975of <tt/.goto/, everything involving loops must be replaced by 4976<tt><ref id=".REPEAT" name=".REPEAT"></tt>. 4977 4978<item>To assemble code to a different address than it is executed at, use the 4979<tt><ref id=".ORG" name=".ORG"></tt> directive instead of 4980<tt/.offs/-constructs. 4981 4982<tscreen><verb> 4983 .org $1800 4984 4985 [floppy code here] 4986 4987 .reloc ; back to normal 4988</verb></tscreen> 4989 4990<item>Then assemble like this: 4991 4992<tscreen><verb> 4993 cl65 --start-addr 0x0ffe -t none myprog.s -o myprog.prg 4994</verb></tscreen> 4995 4996Note that you need to use the actual start address minus two, since two bytes 4997are used for the cbm load address. 4998 4999</enum> 5000 5001 5002<sect>Copyright<p> 5003 5004ca65 (and all cc65 binutils) are (C) Copyright 1998-2003 Ullrich von 5005Bassewitz. For usage of the binaries and/or sources the following 5006conditions do apply: 5007 5008This software is provided 'as-is', without any expressed or implied 5009warranty. In no event will the authors be held liable for any damages 5010arising from the use of this software. 5011 5012Permission is granted to anyone to use this software for any purpose, 5013including commercial applications, and to alter it and redistribute it 5014freely, subject to the following restrictions: 5015 5016<enum> 5017<item> The origin of this software must not be misrepresented; you must not 5018 claim that you wrote the original software. If you use this software 5019 in a product, an acknowledgment in the product documentation would be 5020 appreciated but is not required. 5021<item> Altered source versions must be plainly marked as such, and must not 5022 be misrepresented as being the original software. 5023<item> This notice may not be removed or altered from any source 5024 distribution. 5025</enum> 5026 5027 5028 5029</article> 5030