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