1 <!doctype linuxdoc system>
4 <title>ca65 Users Guide
5 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
6 <date>19.07.2000, 29.11.2000, 02.10.2001
9 ca65 is a powerful macro assembler for the 6502, 65C02 and 65816 CPUs. It is
10 used as a companion assembler for the cc65 crosscompiler, but it may also be
11 used as a standalone product.
14 <!-- Table of contents -->
17 <!-- Begin the document -->
21 ca65 is a replacement for the ra65 assembler that was part of the cc65 C
22 compiler, originally developed by John R. Dunning. I had some problems with
23 ra65 and the copyright does not permit some things which I wanted to be
24 possible, so I decided to write a completely new assembler/linker/archiver
25 suite for the cc65 compiler. ca65 is part of this suite.
27 Some parts of the assembler (code generation and some routines for symbol
28 table handling) are taken from an older crossassembler named a816 written
29 by me a long time ago.
32 <sect1>Design criteria<p>
34 Here's a list of the design criteria, that I considered important for the
39 <item> The assembler must support macros. Macros are not essential, but they
40 make some things easier, especially when you use the assembler in the
41 backend of a compiler.
42 <item> The assembler must support the newer 65C02 and 65816 CPUs. I have been
43 thinking about a 65816 backend for the C compiler, and even my old
44 a816 assembler had support for these CPUs, so this wasn't really a
46 <item> The assembler must produce relocatable code. This is necessary for the
47 compiler support, and it is more convenient.
48 <item> Conditional assembly must be supported. This is a must for bigger
49 projects written in assembler (like Elite128).
50 <item> The assembler must support segments, and it must support more than
51 three segments (this is the count, most other assemblers support).
52 Having more than one code segments helps developing code for systems
53 with a divided ROM area (like the C64).
54 <item> The linker must be able to resolve arbitrary expressions. It should
55 be able to get things like
62 <item> True lexical nesting for symbols. This is very convenient for larger
64 <item> "Cheap" local symbols without lexical nesting for those quick, late
66 <item> I liked the idea of "options" as Anre Fachats .o65 format has it, so I
67 introduced the concept into the object file format use by the new cc65
69 <item> The assembler will be a one pass assembler. There was no real need for
70 this decision, but I've written several multipass assemblers, and it
71 started to get boring. A one pass assembler needs much more elaborated
72 data structures, and because of that it's much more fun:-)
73 <item> Non-GPLed code that may be used in any project without restrictions or
74 fear of "GPL infecting" other code.
82 <sect1>Command line option overview<p>
84 The assembler accepts the following options:
87 ---------------------------------------------------------------------------
88 Usage: ca65 [options] file
90 -D name[=value] Define a symbol
91 -I dir Set an include directory search path
92 -U Mark unresolved symbols as import
93 -V Print the assembler version
94 -W n Set warning level n
95 -g Add debug info to object file
97 -i Ignore case of symbols
98 -l Create a listing if assembly was ok
99 -o name Name the output file
101 -t sys Set the target system
102 -v Increase verbosity
105 --auto-import Mark unresolved symbols as import
106 --cpu type Set cpu type
107 --debug-info Add debug info to object file
108 --feature name Set an emulation feature
109 --help Help (this text)
110 --ignore-case Ignore case of symbols
111 --include-dir dir Set an include directory search path
112 --listing Create a listing if assembly was ok
113 --pagelength n Set the page length for the listing
114 --smart Enable smart mode
115 --target sys Set the target system
116 --verbose Increase verbosity
117 --version Print the assembler version
118 ---------------------------------------------------------------------------
122 <sect1>Command line options in detail<p>
124 Here is a description of all the command line options:
128 <label id="option--cpu">
129 <tag><tt>--cpu type</tt></tag>
131 Set the default for the CPU type. The option takes a parameter, which
134 6502, 65SC02, 65C02, 65816 and sunplus
136 The last one (sunplus) is not available in the freeware version, because the
137 instruction set of the sunplus CPU is "proprietary and confidential".
140 <label id="option--feature">
141 <tag><tt>--feature name</tt></tag>
143 Enable an emulation feature. This is identical as using <tt/.FEATURE/
144 in the source with two exceptions: Feature names must be lower case, and
145 each feature must be specified by using an extra <tt/--feature/ option,
146 comma separated lists are not allowed.
148 See the discussion of the <tt><ref id=".FEATURE" name=".FEATURE"></tt>
149 command for a list of emulation features.
152 <label id="option-g">
153 <tag><tt>-g, --debug-info</tt></tag>
155 When this option (or the equivalent control command <tt/.DEBUGINFO/) is
156 used, the assembler will add a section to the object file that contains
157 all symbols (including local ones) together with the symbol values and
158 source file positions. The linker will put these additional symbols into
159 the VICE label file, so even local symbols can be seen in the VICE
163 <tag><tt>-h, --help</tt></tag>
165 Print the short option summary shown above.
168 <tag><tt>-i, --ignore-case</tt></tag>
170 This option makes the assembler case insensitive on identifiers and labels.
171 This option will override the default, but may itself be overriden by the
172 <tt><ref id=".CASE" name=".CASE"></tt> control command.
175 <tag><tt>-l, --listing</tt></tag>
177 Generate an assembler listing. The listing file will always have the
178 name of the main input file with the extension replaced by ".lst". This
179 may change in future versions.
182 <tag><tt>-o name</tt></tag>
184 The default output name is the name of the input file with the extension
185 replaced by ".o". If you don't like that, you may give another name with
186 the -o option. The output file will be placed in the same directory as
187 the source file, or, if -o is given, the full path in this name is used.
190 <tag><tt>--pagelength n</tt></tag>
192 sets the length of a listing page in lines. See the <tt><ref
193 id=".PAGELENGTH" name=".PAGELENGTH"></tt> directive for more information.
196 <tag><tt>-s, --smart-mode</tt></tag>
198 In smart mode (enabled by -s or the <tt><ref id=".SMART" name=".SMART"></tt>
199 pseudo instruction) the assembler will track usage of the <tt/REP/ and
200 <tt/SEP/ instructions in 65816 mode and update the operand sizes
201 accordingly. If the operand of such an instruction cannot be evaluated by
202 the assembler (for example, because the operand is an imported symbol), a
205 Beware: Since the assembler cannot trace the execution flow this may
206 lead to false results in some cases. If in doubt, use the .ixx and .axx
207 instructions to tell the assembler about the current settings. Smart
208 mode is off by default.
211 <label id="option-t">
212 <tag><tt>-t sys, --target sys</tt></tag>
214 Set the target system. This will enable translation of character strings
215 and character constants into the character set of the target platform.
216 The default for the target system is "none", which means that no translation
217 will take place. The assembler supports the same target systems as the
218 compiler, see there for a list.
221 <tag><tt>-v, --verbose</tt></tag>
223 Increase the assembler verbosity. Usually only needed for debugging
224 purposes. You may use this option more than one time for even more
228 <tag><tt>-D</tt></tag>
230 This option allows you to define symbols on the command line. Without a
231 value, the symbol is defined with the value zero. When giving a value,
232 you may use the '$' prefix for hexadecimal symbols. Please note
233 that for some operating systems, '$' has a special meaning, so
234 you may have to quote the expression.
237 <tag><tt>-I dir, --include-dir dir</tt></tag>
239 Name a directory which is searched for include files. The option may be
240 used more than once to specify more than one directory to search. The
241 current directory is always searched first before considering any
242 additional directores.
245 <tag><tt>-U, --auto-import</tt></tag>
247 Mark symbols that are not defined in the sources as imported symbols. This
248 should be used with care since it delays error messages about typos and such
249 until the linker is run. The compiler uses the equivalent of this switch
250 (<tt><ref id=".AUTOIMPORT" name=".AUTOIMPORT"></tt>) to enable auto imported
251 symbols for the runtime library. However, the compiler is supposed to
252 generate code that runs through the assembler without problems, something
253 which is not always true for assembler programmers.
256 <tag><tt>-V, --version</tt></tag>
258 Print the version number of the assembler. If you send any suggestions
259 or bugfixes, please include the version number.
262 <label id="option-W">
263 <tag><tt>-Wn</tt></tag>
265 Set the warning level for the assembler. Using -W2 the assembler will
266 even warn about such things like unused imported symbols. The default
267 warning level is 1, and it would probably be silly to set it to
274 <sect>Input format<p>
276 The assembler accepts the standard 6502/65816 assembler syntax. One line may
277 contain a label (which is identified by a colon), and, in addition to the
278 label, an assembler mnemonic, a macro, or a control command (see section <ref
279 id="control-commands" name="Control Commands"> for supported control
280 commands). Alternatively, the line may contain a symbol definition using the
281 '=' token. Everything after a semicolon is handled as a comment (that is, it
284 Here are some examples for valid input lines:
287 Label: ; A label and a comment
288 lda #$20 ; A 6502 instruction plus comment
289 L1: ldx #$20 ; Same with label
290 L2: .byte "Hello world" ; Label plus control command
291 mymac $20 ; Macro expansion
292 MySym = 3*L1 ; Symbol definition
293 MaSym = Label ; Another symbol
296 The assembler accepts
299 <item>all valid 6502 mnemonics when in 6502 mode (the default or after the
300 <tt><ref id=".P02" name=".P02"></tt> command was given).
301 <item>all valid 65SC02 mnemonics when in 65SC02 mode (after the
302 <tt><ref id=".PSC02" name=".PSC02"></tt> command was given).
303 <item>all valid 65C02 mnemonics when in 65C02 mode (after the
304 <tt><ref id=".PC02" name=".PC02"></tt> command was given).
305 <item>all valid 65618 mnemonics when in 65816 mode (after the
306 <tt><ref id=".P816" name=".P816"></tt> command was given).
307 <item>all valid SunPlus mnemonics when in SunPlus mode (after the
308 <tt><ref id=".SUNPLUS" name=".SUNPLUS"></tt> command was given).
311 In 65816 mode several aliases are accepted in addition to the official
315 BGE is an alias for BCS
316 BLT is an alias for BCC
317 CPA is an alias for CMP
318 DEA is an alias for DEC A
319 INA is an alias for INC A
320 SWA is an alias for XBA
321 TAD is an alias for TCD
322 TAS is an alias for TCS
323 TDA is an alias for TDC
324 TSA is an alias for TSC
327 Evaluation of banked expressions in 65816 mode differs slightly from the
330 Instead of accepting a 24 bit address (something that is difficult for
331 the assembler to determine and would have required one more special
332 .import command), the bank and the absolute address in that bank are
336 jsl 3.$1234 ; Call subroutine at $1234 in bank 3
339 For literal values, the assembler accepts the widely used number formats:
340 A preceeding '$' denotes a hex value, a preceeding '%' denotes a
341 binary value, and a bare number is interpeted as a decimal. There are
342 currently no octal values and no floats.
349 <sect1>Expression evaluation<p>
351 All expressions are evaluated with (at least) 32 bit precision. An
352 expression may contain constant values and any combination of internal and
353 external symbols. Expressions that cannot be evaluated at assembly time
354 are stored inside the object file for evaluation by the linker.
355 Expressions referencing imported symbols must always be evaluated by the
359 <sect1>Size of an expressions result<p>
361 Sometimes, the assembler must know about the size of the value that is the
362 result of an expression. This is usually the case, if a decision has to be
363 made, to generate a zero page or an absolute memory references. In this
364 case, the assembler has to make some assumptions about the result of an
368 <item> If the result of an expression is constant, the actual value is
369 checked to see if it's a byte sized expression or not.
370 <item> If the expression is explicitly casted to a byte sized expression by
371 one of the '>'/'<' operators, it is a byte expression.
372 <item> If this is not the case, and the expression contains a symbol,
373 explicitly declared as zero page symbol (by one of the .importzp or
374 .exportzp instructions), then the whole expression is assumed to be
376 <item> If the expression contains symbols that are not defined, and these
377 symbols are local symbols, the enclosing scopes are searched for a
378 symbol with the same name. If one exists and this symbol is defined,
379 it's attributes are used to determine the result size.
380 <item> In all other cases the expression is assumed to be word sized.
383 Note: If the assembler is not able to evaluate the expression at assembly
384 time, the linker will evaluate it and check for range errors as soon as
388 <sect1>Boolean expressions<p>
390 In the context of a boolean expression, any non zero value is evaluated as
391 true, any other value to false. The result of a boolean expression is 1 if
392 it's true, and zero if it's false. There are boolean operators with extrem
393 low precedence with version 2.x (where x > 0). The <tt/.AND/ and <tt/.OR/
394 operators are shortcut operators. That is, if the result of the expression is
395 already known, after evaluating the left hand side, the right hand side is
399 <sect1>Available operators<p>
401 Available operators sorted by precedence:
404 Op Description Precedence
405 -------------------------------------------------------------------
406 .CONCAT Builtin function 0
407 .LEFT Builtin function 0
408 .MID Builtin function 0
409 .RIGHT Builtin function 0
410 .STRING Builtin function 0
412 * Builtin pseudo variable (r/o) 1
413 .BLANK Builtin function 1
414 .CONST Builtin function 1
415 .CPU Builtin pseudo variable (r/o) 1
416 .DEFINED Builtin function 1
417 .MATCH Builtin function 1
418 .TCOUNT Builtin function 1
419 .TIME Builtin function 1
420 .VERSION Builtin function 1
421 .XMATCH Builtin function 1
422 .PARAMCOUNT Builtin pseudo variable (r/o) 1
423 .REFERENCED Builtin function 1
424 :: Global namespace override 1
427 ~ Unary bitwise not 1
428 .BITNOT Unary bitwise not 1
429 < Low byte operator 1
430 > High byte operator 1
434 .MOD Modulo operation 2
436 .BITAND Bitwise and 2
438 .BITXOR Bitwise xor 2
439 << Shift left operator 2
440 .SHL Shift left operator 2
441 >> Shift right operator
442 .SHR Shift right operator 2
449 = Compare operation (equal) 4
450 <> Compare operation (not equal) 4
451 < Compare operation (less) 4
452 > Compare operation (greater) 4
453 <= Compare operation (less or equal) 4
454 >= Compare operation (greater or equal) 4
456 && Boolean and 5
468 To force a specific order of evaluation, braces may be used as usual.
470 Some of the pseudo variables mentioned above need some more explanation:
473 * This symbol is replaced by the value of the program
474 counter at start of the current instruction. Note, that
475 '*' yields a rvalue, that means, you cannot assign to it.
476 Use <tt/.ORG/ to set the program counter in sections with
483 <sect>Symbols and labels<p>
485 The assembler allows you to use symbols instead of naked values to make
486 the source more readable. There are a lot of different ways to define and
487 use symbols and labels, giving a lot of flexibility.
490 <sect1>Numeric constants<p>
492 Numeric constants are defined using the equal sign. After doing
498 may use the symbol "two" in every place where a number is expected, and it is
499 evaluated to the value 2 in this context. An example would be
506 <sect1>Standard labels<p>
508 A label is defined by writing the name of the label at the start of the line
509 (before any instruction mnemonic, macro or pseudo directive), followed by a
510 colon. This will declare a symbol with the given name and the value of the
511 current program counter.
514 <sect1>Local labels and symbols<p>
516 Using the <tt><ref id=".PROC" name=".PROC"></tt> directive, it is possible to
517 create regions of code where the names of labels and symbols are local to this
518 region. They are not known outside of this region and cannot be accessed from
519 there. Such regions may be nested like PROCEDUREs in Pascal.
521 See the description of the <tt><ref id=".PROC" name=".PROC"></tt>
522 directive for more information.
525 <sect1>Cheap local labels<p>
527 Cheap local labels are defined like standard labels, but the name of the
528 label must begin with a special symbol (usually '@', but this can be
529 changed by the <tt><ref id=".LOCALCHAR" name=".LOCALCHAR"></tt>
532 Cheap local labels are visible only between two non cheap labels. As soon as a
533 standard symbol is encountered (this may also be a local symbol if inside a
534 region defined with the <tt><ref id=".PROC" name=".PROC"></tt> directive), the
535 cheap local symbol goes out of scope.
537 You may use cheap local labels as an easy way to reuse common label
538 names like "Loop". Here is an example:
541 Clear: lda #$00 ; Global label
543 @Loop: sta Mem,y ; Local label
547 Sub: ... ; New global label
548 bne @Loop ; ERROR: Unknown identifier!
551 <sect1>Unnamed labels<p>
553 If you really want to write messy code, there are also unnamed
554 labels. These labels do not have a name (you guessed that already,
555 didn't you?). A colon is used to mark the absence of the name.
557 Unnamed labels may be accessed by using the colon plus several minus
558 or plus characters as a label designator. Using the '-' characters
559 will create a back reference (use the n'th label backwards), using
560 '+' will create a forward reference (use the n'th label in forward
561 direction). An example will help to understand this:
583 As you can see from the example, unnamed labels will make even short
584 sections of code hard to understand, because you have to count labels
585 to find branch targets (this is the reason why I for my part do
586 prefer the "cheap" local labels). Nevertheless, unnamed labels are
587 convenient in some situations, so it's your decision.
590 <sect1>Using macros to define labels and constants<p>
592 While there are drawbacks with this approach, it may be handy in some
593 situations. Using <tt><ref id=".DEFINE" name=".DEFINE"></tt>, it is
594 possible to define symbols or constants that may be used elsewhere. Since
595 the macro facility works on a very low level, there is no scoping. On the
596 other side, you may also define string constants this way (this is not
597 possible with the other symbol types).
603 .DEFINE version "SOS V2.3"
605 four = two * two ; Ok
608 .PROC ; Start local scope
609 two = 3 ; Will give "2 = 3" - invalid!
614 <sect1>Symbols and <tt>.DEBUGINFO</tt><p>
616 If <tt><ref id=".DEBUGINFO" name=".DEBUGINFO"></tt> is enabled (or <ref
617 id="option-g" name="-g"> is given on the command line), global, local and
618 cheap local labels are written to the object file and will be available in the
619 symbol file via the linker. Unnamed labels are not written to the object file,
620 because they don't have a name which would allow to access them.
624 <sect>Control commands<label id="control-commands">
627 Here's a list of all control commands and a description, what they do:
630 <sect1><tt>.A16</tt><label id=".A16"><p>
632 Valid only in 65816 mode. Switch the accumulator to 16 bit.
634 Note: This command will not emit any code, it will tell the assembler to
635 create 16 bit operands for immediate accumulator adressing mode.
637 See also: <tt><ref id=".SMART" name=".SMART"></tt>
640 <sect1><tt>.A8</tt><label id=".A8"><p>
642 Valid only in 65816 mode. Switch the accumulator to 8 bit.
644 Note: This command will not emit any code, it will tell the assembler to
645 create 8 bit operands for immediate accu adressing mode.
647 See also: <tt><ref id=".SMART" name=".SMART"></tt>
650 <sect1><tt>.ADDR</tt><label id=".ADDR"><p>
652 Define word sized data. In 6502 mode, this is an alias for <tt/.WORD/ and
653 may be used for better readability if the data words are address values. In
654 65816 mode, the address is forced to be 16 bit wide to fit into the current
655 segment. See also <tt><ref id=".FARADDR" name=".FARADDR"></tt>. The command
656 must be followed by a sequence of (not necessarily constant) expressions.
661 .addr $0D00, $AF13, _Clear
664 See: <tt><ref id=".FARADDR" name=".FARADDR"></tt>, <tt><ref id=".WORD"
668 <sect1><tt>.ALIGN</tt><label id=".ALIGN"><p>
670 Align data to a given boundary. The command expects a constant integer
671 argument that must be a power of two, plus an optional second argument
672 in byte range. If there is a second argument, it is used as fill value,
673 otherwise the value defined in the linker configuration file is used
674 (the default for this value is zero).
676 Since alignment depends on the base address of the module, you must
677 give the same (or a greater) alignment for the segment when linking.
678 The linker will give you a warning, if you don't do that.
687 <sect1><tt>.ASCIIZ</tt><label id=".ASCIIZ"><p>
689 Define a string with a trailing zero.
694 Msg: .asciiz "Hello world"
697 This will put the string "Hello world" followed by a binary zero into
698 the current segment. There may be more strings separated by commas, but
699 the binary zero is only appended once (after the last one).
702 <sect1><tt>.ASSERT</tt><label id=".ASSERT"><p>
704 Add an assertion. The command is followed by an expression, an action
705 specifier and a message that is output in case the assertion fails. The
706 action specifier may be one of <tt/warning/ or <tt/error/. The assertion
707 is passed to the linker and will be evaluated when segment placement has
713 .assert * = $8000, error, "Code not at $8000"
716 The example assertion will check that the current location is at $8000,
717 when the output file is written, and abort with an error if this is not
718 the case. More complex expressions are possible. The action specifier
719 <tt/warning/ outputs a warning, while the <tt/error/ specifier outputs
720 an error message. In the latter case, generation if the output file is
724 <sect1><tt>.AUTOIMPORT</tt><label id=".AUTOIMPORT"><p>
726 Is followed by a plus or a minus character. When switched on (using a
727 +), undefined symbols are automatically marked as import instead of
728 giving errors. When switched off (which is the default so this does not
729 make much sense), this does not happen and an error message is
730 displayed. The state of the autoimport flag is evaluated when the
731 complete source was translated, before outputing actual code, so it is
732 <em/not/ possible to switch this feature on or off for separate sections
733 of code. The last setting is used for all symbols.
735 You should probably not use this switch because it delays error
736 messages about undefined symbols until the link stage. The cc65
737 compiler (which is supposed to produce correct assembler code in all
738 circumstances, something which is not true for most assembler
739 programmers) will insert this command to avoid importing each and every
740 routine from the runtime library.
745 .autoimport + ; Switch on auto import
749 <sect1><tt>.BLANK</tt><label id=".BLANK"><p>
751 Builtin function. The function evaluates its argument in braces and
752 yields "false" if the argument is non blank (there is an argument), and
753 "true" if there is no argument. As an example, the <tt/.IFBLANK/ statement
761 <sect1><tt>.BSS</tt><label id=".BSS"><p>
763 Switch to the BSS segment. The name of the BSS segment is always "BSS",
764 so this is a shortcut for
770 See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command.
773 <sect1><tt>.BYT, .BYTE</tt><label id=".BYTE"><p>
775 Define byte sized data. Must be followed by a sequence of (byte ranged)
776 expressions or strings.
782 .byt "world", $0D, $00
786 <sect1><tt>.CASE</tt><label id=".CASE"><p>
788 Switch on or off case sensitivity on identifiers. The default is off
789 (that is, identifiers are case sensitive), but may be changed by the
790 -i switch on the command line.
791 The command must be followed by a '+' or '-' character to switch the
792 option on or off respectively.
797 .case - ; Identifiers are not case sensitive
801 <sect1><tt>.CHARMAP</tt><label id=".CHARMAP"><p>
803 Apply a custom mapping for characters. The command is followed by two
804 numbers in the range 1..255. The first one is the index of the source
805 character, the second one is the mapping. The mapping applies to all
806 character and string constants when they generate output, and overrides
807 a mapping table specified with the <tt><ref id="option-t" name="-t"></tt>
813 .charmap $41, $61 ; Map 'A' to 'a'
817 <sect1><tt>.CODE</tt><label id=".CODE"><p>
819 Switch to the CODE segment. The name of the CODE segment is always
820 "CODE", so this is a shortcut for
826 See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command.
829 <sect1><tt>.CONDES</tt><label id=".CONDES"><p>
831 Export a symbol and mark it in a special way. The linker is able to build
832 tables of all such symbols. This may be used to automatically create a list
833 of functions needed to initialize linked library modules.
835 Note: The linker has a feature to build a table of marked routines, but it
836 is your code that must call these routines, so just declaring a symbol with
837 <tt/.CONDES/ does nothing by itself.
839 All symbols are exported as an absolute (16 bit) symbol. You don't need to
840 use an additional <tt><ref id=".EXPORT" name=".EXPORT"></tt> statement, this
841 is implied by <tt/.CONDES/.
843 <tt/.CONDES/ is followed by the type, which may be <tt/constructor/,
844 <tt/destructor/ or a numeric value between 0 and 6 (where 0 is the same as
845 specifiying <tt/constructor/ and 1 is equal to specifying <tt/destructor/).
846 The <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> and <tt><ref
847 id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> commands are actually shortcuts
848 for <tt/.CONDES/ with a type of <tt/constructor/ resp. <tt/destructor/.
850 After the type, an optional priority may be specified. Higher numeric values
851 mean higher priority. If no priority is given, the default priority of 7 is
852 used. Be careful when assigning priorities to your own module constructors
853 so they won't interfere with the ones in the cc65 library.
858 .condes ModuleInit, constructor
859 .condes ModInit, 0, 16
862 See the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> and <tt><ref
863 id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> commands and the separate section
864 <ref id="condes" name="Module constructors/destructors"> explaining the
865 feature in more detail.
868 <sect1><tt>.CONCAT</tt><label id=".CONCAT"><p>
870 Builtin function. The function allows to concatenate a list of string
871 constants separated by commas. The result is a string constant that
872 is the concatentation of all arguments. This function is most useful
873 in macros and when used together with the <tt/.STRING/ builtin function.
874 The function may be used in any case where a string constant is
880 .include .concat ("myheader", ".", "inc")
883 This is the same as the command
886 .include "myheader.inc"
890 <sect1><tt>.CONST</tt><label id=".CONST"><p>
892 Builtin function. The function evaluates its argument in braces and
893 yields "true" if the argument is a constant expression (that is, an
894 expression that yields a constant value at assembly time) and "false"
895 otherwise. As an example, the .IFCONST statement may be replaced by
902 <sect1><tt>.CONSTRUCTOR</tt><label id=".CONSTRUCTOR"><p>
904 Export a symbol and mark it as a module constructor. This may be used
905 together with the linker to build a table of constructor subroutines that
906 are called by the startup code.
908 Note: The linker has a feature to build a table of marked routines, but it
909 is your code that must call these routines, so just declaring a symbol as
910 constructor does nothing by itself.
912 A constructor is always exported as an absolute (16 bit) symbol. You don't
913 need to use an additional <tt/.export/ statement, this is implied by
914 <tt/.constructor/. It may have an optional priority that is separated by a
915 comma. Higher numeric values mean a higher priority. If no priority is
916 given, the default priority of 7 is used. Be careful when assigning
917 priorities to your own module constructors so they won't interfere with the
918 ones in the cc65 library.
923 .constructor ModuleInit
924 .constructor ModInit, 16
927 See the <tt><ref id=".CONDES" name=".CONDES"></tt> and <tt><ref
928 id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> commands and the separate section
929 <ref id="condes" name="Module constructors/destructors"> explaining the
930 feature in more detail.
933 <sect1><tt>.CPU</tt><label id=".CPU"><p>
935 Reading this pseudo variable will give a constant integer value that
936 tells which instruction set is currently enabled. Possible values are:
946 It may be used to replace the .IFPxx pseudo instructions or to construct
947 even more complex expressions.
952 .if (.cpu = 0) .or (.cpu = 1) .or (.cpu = 2)
964 <sect1><tt>.DATA</tt><label id=".DATA"><p>
966 Switch to the DATA segment. The name of the DATA segment is always
967 "DATA", so this is a shortcut for
973 See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command.
976 <sect1><tt>.DBYT</tt><label id=".DBYT"><p>
978 Define word sized data with the hi and lo bytes swapped (use <tt/.WORD/ to
979 create word sized data in native 65XX format). Must be followed by a
980 sequence of (word ranged) expressions.
988 This will emit the bytes
994 into the current segment in that order.
997 <sect1><tt>.DEBUGINFO</tt><label id=".DEBUGINFO"><p>
999 Switch on or off debug info generation. The default is off (that is,
1000 the object file will not contain debug infos), but may be changed by the
1001 -g switch on the command line.
1002 The command must be followed by a '+' or '-' character to switch the
1003 option on or off respectively.
1008 .debuginfo + ; Generate debug info
1012 <sect1><tt>.DEFINE</tt><label id=".DEFINE"><p>
1014 Start a define style macro definition. The command is followed by an
1015 identifier (the macro name) and optionally by a list of formal arguments
1017 See section <ref id="macros" name="Macros">.
1020 <sect1><tt>.DEF, .DEFINED</tt><label id=".DEFINED"><p>
1022 Builtin function. The function expects an identifier as argument in braces.
1023 The argument is evaluated, and the function yields "true" if the identifier
1024 is a symbol that is already defined somewhere in the source file up to the
1025 current position. Otherwise the function yields false. As an example, the
1026 <tt><ref id=".IFDEF" name=".IFDEF"></tt> statement may be replaced by
1033 <sect1><tt>.DESTRUCTOR</tt><label id=".DESTRUCTOR"><p>
1035 Export a symbol and mark it as a module destructor. This may be used
1036 together with the linker to build a table of destructor subroutines that
1037 are called by the startup code.
1039 Note: The linker has a feature to build a table of marked routines, but it
1040 is your code that must call these routines, so just declaring a symbol as
1041 constructor does nothing by itself.
1043 A destructor is always exported as an absolute (16 bit) symbol. You don't
1044 need to use an additional <tt/.export/ statement, this is implied by
1045 <tt/.destructor/. It may have an optional priority that is separated by a
1046 comma. Higher numerical values mean a higher priority. If no priority is
1047 given, the default priority of 7 is used. Be careful when assigning
1048 priorities to your own module destructors so they won't interfere with the
1049 ones in the cc65 library.
1054 .destructor ModuleDone
1055 .destructor ModDone, 16
1058 See the <tt><ref id=".CONDES" name=".CONDES"></tt> and <tt><ref
1059 id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> commands and the separate
1060 section <ref id="condes" name="Module constructors/destructors"> explaining
1061 the feature in more detail.
1064 <sect1><tt>.DWORD</tt><label id=".DWORD"><p>
1066 Define dword sized data (4 bytes) Must be followed by a sequence of
1072 .dword $12344512, $12FA489
1076 <sect1><tt>.ELSE</tt><label id=".ELSE"><p>
1078 Conditional assembly: Reverse the current condition.
1081 <sect1><tt>.ELSEIF</tt><label id=".ELSEIF"><p>
1083 Conditional assembly: Reverse current condition and test a new one.
1086 <sect1><tt>.END</tt><label id=".END"><p>
1088 Forced end of assembly. Assembly stops at this point, even if the command
1089 is read from an include file.
1092 <sect1><tt>.ENDIF</tt><label id=".ENDIF"><p>
1094 Conditional assembly: Close a <tt><ref id=".IF" name=".IF..."></tt> or
1095 <tt><ref id=".ELSE" name=".ELSE"></tt> branch.
1098 <sect1><tt>.ENDMAC, .ENDMACRO</tt><label id=".ENDMACRO"><p>
1100 End of macro definition (see section <ref id="macros" name="Macros">).
1103 <sect1><tt>.ENDPROC</tt><label id=".ENDPROC"><p>
1105 End of local lexical level (see <tt><ref id=".PROC" name=".PROC"></tt>).
1108 <sect1><tt>.ENDREP, .ENDREPEAT</tt><label id=".ENDREPEAT"><p>
1110 End a <tt><ref id=".REPEAT" name=".REPEAT"></tt> block.
1113 <sect1><tt>.ERROR</tt><label id=".ERROR"><p>
1115 Force an assembly error. The assembler will output an error message
1116 preceeded by "User error" and will <em/not/ produce an object file.
1118 This command may be used to check for initial conditions that must be
1119 set before assembling a source file.
1129 .error "Must define foo or bar!"
1133 See also the <tt><ref id=".WARNING" name=".WARNING"></tt> and <tt><ref
1134 id=".OUT" name=".OUT"></tt> directives.
1137 <sect1><tt>.EXITMAC, .EXITMACRO</tt><label id=".EXITMACRO"><p>
1139 Abort a macro expansion immidiately. This command is often useful in
1140 recursive macros. See separate section <ref id="macros" name="Macros">.
1143 <sect1><tt>.EXPORT</tt><label id=".EXPORT"><p>
1145 Make symbols accessible from other modules. Must be followed by a comma
1146 separated list of symbols to export.
1154 See: <tt><ref id=".EXPORTZP" name=".EXPORTZP"></tt>
1157 <sect1><tt>.EXPORTZP</tt><label id=".EXPORTZP"><p>
1159 Make symbols accessible from other modules. Must be followed by a comma
1160 separated list of symbols to export. The exported symbols are explicitly
1161 marked as zero page symols.
1169 See: <tt><ref id=".EXPORT" name=".EXPORT"></tt>
1172 <sect1><tt>.FARADDR</tt><label id=".FARADDR"><p>
1174 Define far (24 bit) address data. The command must be followed by a
1175 sequence of (not necessarily constant) expressions.
1180 .faraddr DrawCircle, DrawRectangle, DrawHexagon
1183 See: <tt><ref id=".ADDR" name=".ADDR"></tt>
1186 <sect1><tt>.FEATURE</tt><label id=".FEATURE"><p>
1188 This directive may be used to enable one or more compatibility features
1189 of the assembler. While the use of <tt/.FEATURE/ should be avoided when
1190 possible, it may be useful when porting sources written for other
1191 assemblers. There is no way to switch a feature off, once you have
1192 enabled it, so using
1198 will enable the feature until end of assembly is reached.
1200 The following features are available:
1204 <tag><tt>dollar_is_pc</tt></tag>
1206 The dollar sign may be used as an alias for the star (`*'), which
1207 gives the value of the current PC in expressions.
1208 Note: Assignment to the pseudo variable is not allowed.
1210 <tag><tt>labels_without_colons</tt></tag>
1212 Allow labels without a trailing colon. These labels are only accepted,
1213 if they start at the beginning of a line (no leading white space).
1215 <tag><tt>loose_string_term</tt></tag>
1217 Accept single quotes as well as double quotes as terminators for string
1220 <tag><tt>loose_char_term</tt></tag>
1222 Accept single quotes as well as double quotes as terminators for char
1225 <tag><tt>at_in_identifiers</tt></tag>
1227 Accept the at character (`@') as a valid character in identifiers. The
1228 at character is not allowed to start an identifier, even with this
1231 <tag><tt>dollar_in_identifiers</tt></tag>
1233 Accept the dollar sign (`$') as a valid character in identifiers. The
1234 at character is not allowed to start an identifier, even with this
1237 <tag><tt>leading_dot_in_identifiers</tt></tag>
1239 Accept the dot (`.') as the first character of an identifier. This may be
1240 used for example to create macro names that start with a dot emulating
1241 control directives of other assemblers. Note however, that none of the
1242 reserved keywords built into the assembler, that starts with a dot, may be
1243 overridden. When using this feature, you may also get into trouble if
1244 later versions of the assembler define new keywords starting with a dot.
1246 <tag><tt>pc_assignment</tt></tag>
1248 Allow assignments to the PC symbol (`*' or `$' if <tt/dollar_is_pc/
1249 is enabled). Such an assignment is handled identical to the <tt><ref
1250 id=".ORG" name=".ORG"></tt> command (which is usually not needed, so just
1251 removing the lines with the assignments may also be an option when porting
1252 code written for older assemblers).
1256 It is also possible to specify features on the command line using the
1257 <tt><ref id="option--feature" name="--feature"></tt> command line option.
1258 This is useful when translating sources written for older assemblers, when
1259 you don't want to change the source code.
1261 As an example, to translate sources written for Andre Fachats xa65
1262 assembler, the features
1265 labels_without_colons, pc_assignment, loose_char_term
1268 may be helpful. They do not make ca65 completely compatible, so you may not
1269 be able to translate the sources without changes, even when enabling these
1270 features. However, I have found several sources that translate without
1271 problems when enabling these features on the command line.
1274 <sect1><tt>.FILEOPT, .FOPT</tt><label id=".FOPT"><p>
1276 Insert an option string into the object file. There are two forms of
1277 this command, one specifies the option by a keyword, the second
1278 specifies it as a number. Since usage of the second one needs knowledge
1279 of the internal encoding, its use is not recommended and I will only
1280 describe the first form here.
1282 The command is followed by one of the keywords
1290 a comma and a string. The option is written into the object file
1291 together with the string value. This is currently unidirectional and
1292 there is no way to actually use these options once they are in the
1298 .fileopt comment, "Code stolen from my brother"
1299 .fileopt compiler, "BASIC 2.0"
1300 .fopt author, "J. R. User"
1304 <sect1><tt>.FORCEIMPORT</tt><label id=".FORCEIMPORT"><p>
1306 Import an absolute symbol from another module. The command is followed by a
1307 comma separated list of symbols to import. The command is similar to <tt>
1308 <ref id=".IMPORT" name=".IMPORT"></tt>, but the import reference is always
1309 written to the generated object file, even if the symbol is never referenced
1310 (<tt><ref id=".IMPORT" name=".IMPORT"></tt> will not generate import
1311 references for unused symbols).
1316 .forceimport needthisone, needthistoo
1319 See: <tt><ref id=".IMPORT" name=".IMPORT"></tt>
1322 <sect1><tt>.GLOBAL</tt><label id=".GLOBAL"><p>
1324 Declare symbols as global. Must be followed by a comma separated list of
1325 symbols to declare. Symbols from the list, that are defined somewhere in the
1326 source, are exported, all others are imported. Additional <tt><ref
1327 id=".IMPORT" name=".IMPORT"></tt> or <tt><ref id=".EXPORT"
1328 name=".EXPORT"></tt> commands for the same symbol are allowed.
1337 <sect1><tt>.GLOBALZP</tt><label id=".GLOBALZP"><p>
1339 Declare symbols as global. Must be followed by a comma separated list of
1340 symbols to declare. Symbols from the list, that are defined somewhere in the
1341 source, are exported, all others are imported. Additional <tt><ref
1342 id=".IMPORTZP" name=".IMPORTZP"></tt> or <tt><ref id=".EXPORTZP"
1343 name=".EXPORTZP"></tt> commands for the same symbol are allowed. The symbols
1344 in the list are explicitly marked as zero page symols.
1353 <sect1><tt>.I16</tt><label id=".I16"><p>
1355 Valid only in 65816 mode. Switch the index registers to 16 bit.
1357 Note: This command will not emit any code, it will tell the assembler to
1358 create 16 bit operands for immediate operands.
1360 See also the <tt><ref id=".I8" name=".I8"></tt> and <tt><ref id=".SMART"
1361 name=".SMART"></tt> commands.
1364 <sect1><tt>.I8</tt><label id=".I8"><p>
1366 Valid only in 65816 mode. Switch the index registers to 8 bit.
1368 Note: This command will not emit any code, it will tell the assembler to
1369 create 8 bit operands for immediate operands.
1371 See also the <tt><ref id=".I16" name=".I16"></tt> and <tt><ref id=".SMART"
1372 name=".SMART"></tt> commands.
1375 <sect1><tt>.IF</tt><label id=".IF"><p>
1377 Conditional assembly: Evalute an expression and switch assembler output
1378 on or off depending on the expression. The expression must be a constant
1379 expression, that is, all operands must be defined.
1381 A expression value of zero evaluates to FALSE, any other value evaluates
1385 <sect1><tt>.IFBLANK</tt><label id=".IFBLANK"><p>
1387 Conditional assembly: Check if there are any remaining tokens in this line,
1388 and evaluate to FALSE if this is the case, and to TRUE otherwise. If the
1389 condition is not true, further lines are not assembled until an <tt><ref
1390 id=".ELSE" name=".ESLE"></tt>, <tt><ref id=".ELSEIF" name=".ELSEIF"></tt> or
1391 <tt><ref id=".ENDIF" name=".ENDIF"></tt> directive.
1393 This command is often used to check if a macro parameter was given. Since an
1394 empty macro parameter will evaluate to nothing, the condition will evaluate
1395 to FALSE if an empty parameter was given.
1409 See also: <tt><ref id=".BLANK" name=".BLANK"></tt>
1412 <sect1><tt>.IFCONST</tt><label id=".IFCONST"><p>
1414 Conditional assembly: Evaluate an expression and switch assembler output
1415 on or off depending on the constness of the expression.
1417 A const expression evaluates to to TRUE, a non const expression (one
1418 containing an imported or currently undefined symbol) evaluates to
1421 See also: <tt><ref id=".CONST" name=".CONST"></tt>
1424 <sect1><tt>.IFDEF</tt><label id=".IFDEF"><p>
1426 Conditional assembly: Check if a symbol is defined. Must be followed by
1427 a symbol name. The condition is true if the the given symbol is already
1428 defined, and false otherwise.
1430 See also: <tt><ref id=".DEFINED" name=".DEFINED"></tt>
1433 <sect1><tt>.IFNBLANK</tt><label id=".IFNBLANK"><p>
1435 Conditional assembly: Check if there are any remaining tokens in this line,
1436 and evaluate to TRUE if this is the case, and to FALSE otherwise. If the
1437 condition is not true, further lines are not assembled until an <tt><ref
1438 id=".ELSE" name=".ELSE"></tt>, <tt><ref id=".ELSEIF" name=".ELSEIF"></tt> or
1439 <tt><ref id=".ENDIF" name=".ENDIF"></tt> directive.
1441 This command is often used to check if a macro parameter was given.
1442 Since an empty macro parameter will evaluate to nothing, the condition
1443 will evaluate to FALSE if an empty parameter was given.
1456 See also: <tt><ref id=".BLANK" name=".BLANK"></tt>
1459 <sect1><tt>.IFNDEF</tt><label id=".IFNDEF"><p>
1461 Conditional assembly: Check if a symbol is defined. Must be followed by
1462 a symbol name. The condition is true if the the given symbol is not
1463 defined, and false otherwise.
1465 See also: <tt><ref id=".DEFINED" name=".DEFINED"></tt>
1468 <sect1><tt>.IFNREF</tt><label id=".IFNREF"><p>
1470 Conditional assembly: Check if a symbol is referenced. Must be followed
1471 by a symbol name. The condition is true if if the the given symbol was
1472 not referenced before, and false otherwise.
1474 See also: <tt><ref id=".REFERENCED" name=".REFERENCED"></tt>
1477 <sect1><tt>.IFP02</tt><label id=".IFP02"><p>
1479 Conditional assembly: Check if the assembler is currently in 6502 mode
1480 (see <tt><ref id=".P02" name=".P02"></tt> command).
1483 <sect1><tt>.IFP816</tt><label id=".IFP816"><p>
1485 Conditional assembly: Check if the assembler is currently in 65816 mode
1486 (see <tt><ref id=".P816" name=".P816"></tt> command).
1489 <sect1><tt>.IFPC02</tt><label id=".IFPC02"><p>
1491 Conditional assembly: Check if the assembler is currently in 65C02 mode
1492 (see <tt><ref id=".PC02" name=".PC02"></tt> command).
1495 <sect1><tt>.IFPSC02</tt><label id=".IFPSC02"><p>
1497 Conditional assembly: Check if the assembler is currently in 65SC02 mode
1498 (see <tt><ref id=".PSC02" name=".PSC02"></tt> command).
1501 <sect1><tt>.IFREF</tt><label id=".IFREF"><p>
1503 Conditional assembly: Check if a symbol is referenced. Must be followed
1504 by a symbol name. The condition is true if if the the given symbol was
1505 referenced before, and false otherwise.
1507 This command may be used to build subroutine libraries in include files
1508 (you may use separate object modules for this purpose too).
1513 .ifref ToHex ; If someone used this subroutine
1514 ToHex: tay ; Define subroutine
1520 See also: <tt><ref id=".REFERENCED" name=".REFERENCED"></tt>
1523 <sect1><tt>.IMPORT</tt><label id=".IMPORT"><p>
1525 Import a symbol from another module. The command is followed by a comma
1526 separated list of symbols to import.
1534 See: <tt><ref id=".IMPORTZP" name=".IMPORTZP"></tt>
1537 <sect1><tt>.IMPORTZP</tt><label id=".IMPORTZP"><p>
1539 Import a symbol from another module. The command is followed by a comma
1540 separated list of symbols to import. The symbols are explicitly imported
1541 as zero page symbols (that is, symbols with values in byte range).
1549 See: <tt><ref id=".IMPORT" name=".IMPORT"></tt>
1552 <sect1><tt>.INCBIN</tt><label id=".INCBIN"><p>
1554 Include a file as binary data. The command expects a string argument
1555 that is the name of a file to include literally in the current segment.
1556 In addition to that, a start offset and a size value may be specified,
1557 separated by commas. If no size is specified, all of the file from the
1558 start offset to end-of-file is used. If no start position is specified
1559 either, zero is assume (which means that the whole file is inserted).
1564 ; Include whole file
1565 .incbin "sprites.dat"
1567 ; Include file starting at offset 256
1568 .incbin "music.dat", $100
1570 ; Read 100 bytes starting at offset 200
1571 .incbin "graphics.dat", 200, 100
1575 <sect1><tt>.INCLUDE</tt><label id=".INCLUDE"><p>
1577 Include another file. Include files may be nested up to a depth of 16.
1586 <sect1><tt>.LEFT</tt><label id=".LEFT"><p>
1588 Builtin function. Extracts the left part of a given token list.
1593 .LEFT (<int expr>, <token list>)
1596 The first integer expression gives the number of tokens to extract from
1597 the token list. The second argument is the token list itself.
1601 To check in a macro if the given argument has a '#' as first token
1602 (immidiate addressing mode), use something like this:
1607 .if (.match (.left (1, arg), #))
1609 ; ldax called with immidiate operand
1617 See also the <tt><ref id=".MID" name=".MID"></tt> and <tt><ref id=".RIGHT"
1618 name=".RIGHT"></tt> builtin functions.
1621 <sect1><tt>.LINECONT</tt><label id=".LINECONT"><p>
1623 Switch on or off line continuations using the backslash character
1624 before a newline. The option is off by default.
1625 Note: Line continuations do not work in a comment. A backslash at the
1626 end of a comment is treated as part of the comment and does not trigger
1628 The command must be followed by a '+' or '-' character to switch the
1629 option on or off respectively.
1634 .linecont + ; Allow line continuations
1637 #$20 ; This is legal now
1641 <sect1><tt>.LIST</tt><label id=".LIST"><p>
1643 Enable output to the listing. The command must be followed by a boolean
1644 switch ("on", "off", "+" or "-") and will enable or disable listing
1646 The option has no effect if the listing is not enabled by the command line
1647 switch -l. If -l is used, an internal counter is set to 1. Lines are output
1648 to the listing file, if the counter is greater than zero, and suppressed if
1649 the counter is zero. Each use of <tt/.LIST/ will increment or decrement the
1655 .list on ; Enable listing output
1659 <sect1><tt>.LISTBYTES</tt><label id=".LISTBYTES"><p>
1661 Set, how many bytes are shown in the listing for one source line. The
1662 default is 12, so the listing will show only the first 12 bytes for any
1663 source line that generates more than 12 bytes of code or data.
1664 The directive needs an argument, which is either "unlimited", or an
1665 integer constant in the range 4..255.
1670 .listbytes unlimited ; List all bytes
1671 .listbytes 12 ; List the first 12 bytes
1672 .incbin "data.bin" ; Include large binary file
1676 <sect1><tt>.LOCAL</tt><label id=".LOCAL"><p>
1678 This command may only be used inside a macro definition. It declares a
1679 list of identifiers as local to the macro expansion.
1681 A problem when using macros are labels: Since they don't change their name,
1682 you get a "duplicate symbol" error if the macro is expanded the second time.
1683 Labels declared with <tt><ref id=".LOCAL" name=".LOCAL"></tt> have their
1684 name mapped to an internal unique name (<tt/___ABCD__/) with each macro
1687 Some other assemblers start a new lexical block inside a macro expansion.
1688 This has some drawbacks however, since that will not allow <em/any/ symbol
1689 to be visible outside a macro, a feature that is sometimes useful. The
1690 <tt><ref id=".LOCAL" name=".LOCAL"></tt> command is in my eyes a better way
1691 to address the problem.
1693 You get an error when using <tt><ref id=".LOCAL" name=".LOCAL"></tt> outside
1697 <sect1><tt>.LOCALCHAR</tt><label id=".LOCALCHAR"><p>
1699 Defines the character that start "cheap" local labels. You may use one
1700 of '@' and '?' as start character. The default is '@'.
1702 Cheap local labels are labels that are visible only between two non
1703 cheap labels. This way you can reuse identifiers like "<tt/loop/" without
1704 using explicit lexical nesting.
1711 Clear: lda #$00 ; Global label
1712 ?Loop: sta Mem,y ; Local label
1716 Sub: ... ; New global label
1717 bne ?Loop ; ERROR: Unknown identifier!
1721 <sect1><tt>.MACPACK</tt><label id=".MACPACK"><p>
1723 Insert a predefined macro package. The command is followed by an
1724 identifier specifying the macro package to insert. Available macro
1728 generic Defines generic macros like add and sub.
1729 longbranch Defines conditional long jump macros.
1732 Including a macro package twice, or including a macro package that
1733 redefines already existing macros will lead to an error.
1738 .macpack longbranch ; Include macro package
1740 cmp #$20 ; Set condition codes
1741 jne Label ; Jump long on condition
1744 Macro packages are explained in more detail in section <ref
1745 id="macropackages" name="Macro packages">.
1748 <sect1><tt>.MAC, .MACRO</tt><label id=".MAC"><p>
1750 Start a classic macro definition. The command is followed by an identifier
1751 (the macro name) and optionally by a comma separated list of identifiers
1752 that are macro parameters.
1754 See section <ref id="macros" name="Macros">.
1757 <sect1><tt>.MATCH</tt><label id=".MATCH"><p>
1759 Builtin function. Matches two token lists against each other. This is
1760 most useful within macros, since macros are not stored as strings, but
1766 .MATCH(<token list #1>, <token list #2>)
1769 Both token list may contain arbitrary tokens with the exception of the
1770 terminator token (comma resp. right parenthesis) and
1777 Often a macro parameter is used for any of the token lists.
1779 Please note that the function does only compare tokens, not token
1780 attributes. So any number is equal to any other number, regardless of the
1781 actual value. The same is true for strings. If you need to compare tokens
1782 <em/and/ token attributes, use the <tt><ref id=".XMATCH"
1783 name=".XMATCH"></tt> function.
1787 Assume the macro <tt/ASR/, that will shift right the accumulator by one,
1788 while honoring the sign bit. The builtin processor instructions will allow
1789 an optional "A" for accu addressing for instructions like <tt/ROL/ and
1790 <tt/ROR/. We will use the <tt><ref id=".MATCH" name=".MATCH"></tt> function
1791 to check for this and print and error for invalid calls.
1796 .if (.not .blank(arg)) .and (.not .match (arg, a))
1797 .error "Syntax error"
1800 cmp #$80 ; Bit 7 into carry
1801 lsr a ; Shift carry into bit 7
1806 The macro will only accept no arguments, or one argument that must be the
1807 reserved keyword "A".
1809 See: <tt><ref id=".XMATCH" name=".XMATCH"></tt>
1812 <sect1><tt>.MID</tt><label id=".MID"><p>
1814 Builtin function. Takes a starting index, a count and a token list as
1815 arguments. Will return part of the token list.
1820 .MID (<int expr>, <int expr>, <token list>)
1823 The first integer expression gives the starting token in the list (the
1824 first token has index 0). The second integer expression gives the number
1825 of tokens to extract from the token list. The third argument is the
1830 To check in a macro if the given argument has a '<tt/#/' as first token
1831 (immidiate addressing mode), use something like this:
1836 .if (.match (.mid (0, 1, arg), #))
1838 ; ldax called with immidiate operand
1846 See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".RIGHT"
1847 name=".RIGHT"></tt> builtin functions.
1850 <sect1><tt>.ORG</tt><label id=".ORG"><p>
1852 Start a section of absolute code. The command is followed by a constant
1853 expression that gives the new PC counter location for which the code is
1854 assembled. Use <tt><ref id=".RELOC" name=".RELOC"></tt> to switch back to
1857 Please note that you <em/do not need/ this command in most cases. Placing
1858 code at a specific address is the job of the linker, not the assembler, so
1859 there is usually no reason to assemble code to a specific address.
1861 You may not switch segments while inside a section of absolute code.
1866 .org $7FF ; Emit code starting at $7FF
1870 <sect1><tt>.OUT</tt><label id=".OUT"><p>
1872 Output a string to the console without producing an error. This command
1873 is similiar to <tt/.ERROR/, however, it does not force an assembler error
1874 that prevents the creation of an object file.
1879 .out "This code was written by the codebuster(tm)"
1882 See also the <tt><ref id=".WARNING" name=".WARNING"></tt> and <tt><ref
1883 id=".ERROR" name=".ERROR"></tt> directives.
1886 <sect1><tt>.P02</tt><label id=".P02"><p>
1888 Enable the 6502 instruction set, disable 65SC02, 65C02 and 65816
1889 instructions. This is the default if not overridden by the
1890 <tt><ref id="option--cpu" name="--cpu"></tt> command line option.
1892 See: <tt><ref id=".PC02" name=".PC02"></tt>, <tt><ref id=".PSC02"
1893 name=".PSC02"></tt> and <tt><ref id=".P816" name=".P816"></tt>
1896 <sect1><tt>.P816</tt><label id=".P816"><p>
1898 Enable the 65816 instruction set. This is a superset of the 65SC02 and
1899 6502 instruction sets.
1901 See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02"
1902 name=".PSC02"></tt> and <tt><ref id=".PC02" name=".PC02"></tt>
1905 <sect1><tt>.PAGELEN, .PAGELENGTH</tt><label id=".PAGELENGTH"><p>
1907 Set the page length for the listing. Must be followed by an integer
1908 constant. The value may be "unlimited", or in the range 32 to 127. The
1909 statement has no effect if no listing is generated. The default value is -1
1910 (unlimited) but may be overridden by the <tt/--pagelength/ command line
1911 option. Beware: Since ca65 is a one pass assembler, the listing is generated
1912 after assembly is complete, you cannot use multiple line lengths with one
1913 source. Instead, the value set with the last <tt/.PAGELENGTH/ is used.
1918 .pagelength 66 ; Use 66 lines per listing page
1920 .pagelength unlimited ; Unlimited page length
1924 <sect1><tt>.PARAMCOUNT</tt><label id=".PARAMCOUNT"><p>
1926 This builtin pseudo variable is only available in macros. It is replaced by
1927 the actual number of parameters that were given in the macro invocation.
1932 .macro foo arg1, arg2, arg3
1933 .if .paramcount <> 3
1934 .error "Too few parameters for macro foo"
1940 See section <ref id="macros" name="Macros">.
1943 <sect1><tt>.PC02</tt><label id=".PC02"><p>
1945 Enable the 65C02 instructions set. This instruction set includes all
1946 6502 and 65SC02 instructions.
1948 See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02"
1949 name=".PSC02"></tt> and <tt><ref id=".P816" name=".P816"></tt>
1952 <sect1><tt>.POPSEG</tt><label id=".POPSEG"><p>
1954 Pop the last pushed segment from the stack, and set it.
1956 This command will switch back to the segment that was last pushed onto the
1957 segment stack using the <tt><ref id=".PUSHSEG" name=".PUSHSEG"></tt>
1958 command, and remove this entry from the stack.
1960 The assembler will print an error message if the segment stack is empty
1961 when this command is issued.
1963 See: <tt><ref id=".PUSHSEG" name=".PUSHSEG"></tt>
1966 <sect1><tt>.PROC</tt><label id=".PROC"><p>
1968 Start a nested lexical level. All new symbols from now on are in the local
1969 lexical level and are not accessible from outside. Symbols defined outside
1970 this local level may be accessed as long as their names are not used for new
1971 symbols inside the level. Symbols names in other lexical levels do not
1972 clash, so you may use the same names for identifiers. The lexical level ends
1973 when the <tt><ref id=".ENDPROC" name=".ENDPROC"></tt> command is read.
1974 Lexical levels may be nested up to a depth of 16.
1976 The command may be followed by an identifier, in this case the
1977 identifier is declared in the outer level as a label having the value of
1978 the program counter at the start of the lexical level.
1980 Note: Macro names are always in the global level and in a separate name
1981 space. There is no special reason for this, it's just that I've never
1982 had any need for local macro definitions.
1987 .proc Clear ; Define Clear subroutine, start new level
1989 L1: sta Mem,y ; L1 is local and does not cause a
1990 ; duplicate symbol error if used in other
1993 bne L1 ; Reference local symbol
1995 .endproc ; Leave lexical level
1998 See: <tt><ref id=".ENDPROC" name=".ENDPROC"></tt>
2001 <sect1><tt>.PSC02</tt><label id=".PSC02"><p>
2003 Enable the 65SC02 instructions set. This instruction set includes all
2006 See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PC02"
2007 name=".PC02"></tt> and <tt><ref id=".P816" name=".P816"></tt>
2010 <sect1><tt>.PUSHSEG</tt><label id=".PUSHSEG"><p>
2012 Push the currently active segment onto a stack. The entries on the stack
2013 include the name of the segment and the segment type. The stack has a size
2016 <tt/.PUSHSEG/ allows together with <tt><ref id=".POPSEG" name=".POPSEG"></tt>
2017 to switch to another segment and to restore the old segment later, without
2018 even knowing the name and type of the current segment.
2020 The assembler will print an error message if the segment stack is already
2021 full, when this command is issued.
2023 See: <tt><ref id=".POPSEG" name=".POPSEG"></tt>
2026 <sect1><tt>.REF, .REFERENCED</tt><label id=".REFERENCED"><p>
2028 Builtin function. The function expects an identifier as argument in braces.
2029 The argument is evaluated, and the function yields "true" if the identifier
2030 is a symbol that has already been referenced somewhere in the source file up
2031 to the current position. Otherwise the function yields false. As an example,
2032 the <tt><ref id=".IFREF" name=".IFREF"></tt> statement may be replaced by
2038 See: <tt><ref id=".DEFINED" name=".DEFINED"></tt>
2041 <sect1><tt>.REPEAT</tt><label id=".REPEAT"><p>
2043 Repeat all commands between <tt/.REPEAT/ and <tt><ref id=".ENDREPEAT"
2044 name=".ENDREPEAT"></tt> constant number of times. The command is followed by
2045 a constant expression that tells how many times the commands in the body
2046 should get repeated. Optionally, a comma and an identifier may be specified.
2047 If this identifier is found in the body of the repeat statement, it is
2048 replaced by the current repeat count (starting with zero for the first time
2049 the body is repeated).
2051 <tt/.REPEAT/ statements may be nested. If you use the same repeat count
2052 identifier for a nested <tt/.REPEAT/ statement, the one from the inner
2053 level will be used, not the one from the outer level.
2057 The following macro will emit a string that is "encrypted" in that all
2058 characters of the string are XORed by the value $55.
2062 .repeat .strlen(Arg), I
2063 .byte .strat(Arg, I) .xor $55
2068 See: <tt><ref id=".ENDREPEAT" name=".ENDREPEAT"></tt>
2071 <sect1><tt>.RELOC</tt><label id=".RELOC"><p>
2073 Switch back to relocatable mode. See the <tt><ref id=".ORG"
2074 name=".ORG"></tt> command.
2077 <sect1><tt>.RES</tt><label id=".RES"><p>
2079 Reserve storage. The command is followed by one or two constant
2080 expressions. The first one is mandatory and defines, how many bytes of
2081 storage should be defined. The second, optional expression must by a
2082 constant byte value that will be used as value of the data. If there
2083 is no fill value given, the linker will use the value defined in the
2084 linker configuration file (default: zero).
2089 ; Reserve 12 bytes of memory with value $AA
2094 <sect1><tt>.RIGHT</tt><label id=".RIGHT"><p>
2096 Builtin function. Extracts the right part of a given token list.
2101 .RIGHT (<int expr>, <token list>)
2104 The first integer expression gives the number of tokens to extract from
2105 the token list. The second argument is the token list itself.
2107 See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".MID"
2108 name=".MID"></tt> builtin functions.
2111 <sect1><tt>.RODATA</tt><label id=".RODATA"><p>
2113 Switch to the RODATA segment. The name of the RODATA segment is always
2114 "RODATA", so this is a shortcut for
2120 The RODATA segment is a segment that is used by the compiler for
2121 readonly data like string constants.
2123 See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command.
2126 <sect1><tt>.SEGMENT</tt><label id=".SEGMENT"><p>
2128 Switch to another segment. Code and data is always emitted into a
2129 segment, that is, a named section of data. The default segment is
2130 "CODE". There may be up to 254 different segments per object file
2131 (and up to 65534 per executable). There are shortcut commands for
2132 the most common segments ("CODE", "DATA" and "BSS").
2134 The command is followed by a string containing the segment name (there
2135 are some constraints for the name - as a rule of thumb use only those
2136 segment names that would also be valid identifiers). There may also be
2137 an optional attribute separated by a comma. Valid attributes are
2138 "<tt/zeropage/" and "<tt/absolute/".
2140 When specifying a segment for the first time, "absolute" is the
2141 default. For all other uses, the attribute specified the first time
2144 "absolute" means that this is a segment with absolute addressing. That
2145 is, the segment will reside somewhere in core memory outside the zero
2146 page. "zeropage" means the opposite: The segment will be placed in the
2147 zero page and direct (short) addressing is possible for data in this
2150 Beware: Only labels in a segment with the zeropage attribute are marked
2151 as reachable by short addressing. The `*' (PC counter) operator will
2152 work as in other segments and will create absolute variable values.
2157 .segment "ROM2" ; Switch to ROM2 segment
2158 .segment "ZP2", zeropage ; New direct segment
2159 .segment "ZP2" ; Ok, will use last attribute
2160 .segment "ZP2", absolute ; Error, redecl mismatch
2163 See: <tt><ref id=".BSS" name=".BSS"></tt>, <tt><ref id=".CODE"
2164 name=".CODE"></tt>, <tt><ref id=".DATA" name=".DATA"></tt> and <tt><ref
2165 id=".RODATA" name=".RODATA"></tt>
2168 <sect1><tt>.SETCPU</tt><label id=".SETCPU"><p>
2170 Switch the CPU instruction set. The command is followed by a string that
2171 specifies the CPU. Possible values are those that can also be supplied to
2172 the <tt><ref id="option--cpu" name="--cpu"></tt> command line option,
2173 namely: 6502, 65SC02, 65C02, 65816 and sunplus. Please note that support
2174 for the sunplus CPU is not available in the freeware version, because the
2175 instruction set of the sunplus CPU is "proprietary and confidential".
2177 See: <tt><ref id=".CPU" name=".CPU"></tt>,
2178 <tt><ref id=".IFP02" name=".IFP02"></tt>,
2179 <tt><ref id=".IFP816" name=".IFP816"></tt>,
2180 <tt><ref id=".IFPC02" name=".IFPC02"></tt>,
2181 <tt><ref id=".IFPSC02" name=".IFPSC02"></tt>,
2182 <tt><ref id=".P02" name=".P02"></tt>,
2183 <tt><ref id=".P816" name=".P816"></tt>,
2184 <tt><ref id=".PC02" name=".PC02"></tt>,
2185 <tt><ref id=".PSC02" name=".PSC02"></tt>
2188 <sect1><tt>.SMART</tt><label id=".SMART"><p>
2190 Switch on or off smart mode. The command must be followed by a '+' or
2191 '-' character to switch the option on or off respectively. The default
2192 is off (that is, the assembler doesn't try to be smart), but this
2193 default may be changed by the -s switch on the command line.
2195 In smart mode the assembler will track usage of the <tt/REP/ and <tt/SEP/
2196 instructions in 65816 mode and update the operand sizes accordingly. If
2197 the operand of such an instruction cannot be evaluated by the assembler
2198 (for example, because the operand is an imported symbol), a warning is
2199 issued. Beware: Since the assembler cannot trace the execution flow this
2200 may lead to false results in some cases. If in doubt, use the <tt/.Inn/ and
2201 <tt/.Ann/ instructions to tell the assembler about the current settings.
2207 .smart - ; Stop being smart
2211 <sect1><tt>.STRAT</tt><label id=".STRAT"><p>
2213 Builtin function. The function accepts a string and an index as
2214 arguments and returns the value of the character at the given position
2215 as an integer value. The index is zero based.
2221 ; Check if the argument string starts with '#'
2222 .if (.strat (Arg, 0) = '#')
2229 <sect1><tt>.STRING</tt><label id=".STRING"><p>
2231 Builtin function. The function accepts an argument in braces and converts
2232 this argument into a string constant. The argument may be an identifier, or
2233 a constant numeric value.
2235 Since you can use a string in the first place, the use of the function may
2236 not be obvious. However, it is useful in macros, or more complex setups.
2241 ; Emulate other assemblers:
2243 .segment .string(name)
2248 <sect1><tt>.STRLEN</tt><label id=".STRLEN"><p>
2250 Builtin function. The function accepts a string argument in braces and
2251 eveluates to the length of the string.
2255 The following macro encodes a string as a pascal style string with
2256 a leading length byte.
2260 .byte .strlen(Arg), Arg
2265 <sect1><tt>.SUNPLUS</tt><label id=".SUNPLUS"><p>
2267 Enable the SunPlus instructions set. This command will not work in the
2268 freeware version of the assembler, because the instruction set is
2269 "proprietary and confidential".
2271 See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02"
2272 name=".PSC02"></tt>, <tt><ref id=".PC02" name=".PC02"></tt>, and
2273 <tt><ref id=".P816" name=".P816"></tt>
2276 <sect1><tt>.TCOUNT</tt><label id=".TCOUNT"><p>
2278 Builtin function. The function accepts a token list in braces. The
2279 function result is the number of tokens given as argument.
2283 The <tt/ldax/ macro accepts the '#' token to denote immidiate addressing (as
2284 with the normal 6502 instructions). To translate it into two separate 8 bit
2285 load instructions, the '#' token has to get stripped from the argument:
2289 .if (.match (.mid (0, 1, arg), #))
2290 ; ldax called with immidiate operand
2291 lda #<(.right (.tcount (arg)-1, arg))
2292 ldx #>(.right (.tcount (arg)-1, arg))
2300 <sect1><tt>.TIME</tt><label id=".TIME"><p>
2302 Reading this pseudo variable will give a constant integer value that
2303 represents the current time in POSIX standard (as seconds since the
2306 It may be used to encode the time of translation somewhere in the created
2312 .dword .time ; Place time here
2316 <sect1><tt>.VERSION</tt><label id=".VERSION"><p>
2318 Reading this pseudo variable will give the assembler version according to
2319 the following formula:
2321 VER_MAJOR*$100 + VER_MINOR*$10 + VER_PATCH
2323 It may be used to encode the assembler version or check the assembler for
2324 special features not available with older versions.
2328 Version 2.11.1 of the assembler will return $2B1 as numerical constant when
2329 reading the pseudo variable <tt/.VERSION/.
2332 <sect1><tt>.WARNING</tt><label id=".WARNING"><p>
2334 Force an assembly warning. The assembler will output a warning message
2335 preceeded by "User warning". This warning will always be output, even if
2336 other warnings are disabled with the <tt><ref id="option-W" name="-W0"></tt>
2337 command line option.
2339 This command may be used to output possible problems when assembling
2348 .warning "Forward jump in jne, cannot optimize!"
2358 See also the <tt><ref id=".ERROR" name=".ERROR"></tt> and <tt><ref id=".OUT"
2359 name=".OUT"></tt> directives.
2362 <sect1><tt>.WORD</tt><label id=".WORD"><p>
2364 Define word sized data. Must be followed by a sequence of (word ranged,
2365 but not necessarily constant) expressions.
2370 .word $0D00, $AF13, _Clear
2374 <sect1><tt>.XMATCH</tt><label id=".XMATCH"><p>
2376 Builtin function. Matches two token lists against each other. This is
2377 most useful within macros, since macros are not stored as strings, but
2383 .XMATCH(<token list #1>, <token list #2>)
2386 Both token list may contain arbitrary tokens with the exception of the
2387 terminator token (comma resp. right parenthesis) and
2394 Often a macro parameter is used for any of the token lists.
2396 The function compares tokens <em/and/ token values. If you need a function
2397 that just compares the type of tokens, have a look at the <tt><ref
2398 id=".MATCH" name=".MATCH"></tt> function.
2400 See: <tt><ref id=".MATCH" name=".MATCH"></tt>
2403 <sect1><tt>.ZEROPAGE</tt><label id=".ZEROPAGE"><p>
2405 Switch to the ZEROPAGE segment and mark it as direct (zeropage) segment.
2406 The name of the ZEROPAGE segment is always "ZEROPAGE", so this is a
2410 .segment "ZEROPAGE", zeropage
2413 Because of the "zeropage" attribute, labels declared in this segment are
2414 addressed using direct addressing mode if possible. You <em/must/ instruct
2415 the linker to place this segment somewhere in the address range 0..$FF
2416 otherwise you will get errors.
2418 See: <tt><ref id=".SEGMENT" name=".SEGMENT"></tt>
2422 <sect>Macros<label id="macros"><p>
2425 <sect1>Introduction<p>
2427 Macros may be thought of as "parametrized super instructions". Macros are
2428 sequences of tokens that have a name. If that name is used in the source
2429 file, the macro is "expanded", that is, it is replaced by the tokens that
2430 were specified when the macro was defined.
2433 <sect1>Macros without parameters<p>
2435 In it's simplest form, a macro does not have parameters. Here's an
2439 .macro asr ; Arithmetic shift right
2440 cmp #$80 ; Put bit 7 into carry
2441 ror ; Rotate right with carry
2445 The macro above consists of two real instructions, that are inserted into
2446 the code, whenever the macro is expanded. Macro expansion is simply done
2447 by using the name, like this:
2456 <sect1>Parametrized macros<p>
2458 When using macro parameters, macros can be even more useful:
2472 When calling the macro, you may give a parameter, and each occurence of
2473 the name "addr" in the macro definition will be replaced by the given
2492 A macro may have more than one parameter, in this case, the parameters
2493 are separated by commas. You are free to give less parameters than the
2494 macro actually takes in the definition. You may also leave intermediate
2495 parameters empty. Empty parameters are replaced by empty space (that is,
2496 they are removed when the macro is exanded). If you have a look at our
2497 macro definition above, you will see, that replacing the "addr" parameter
2498 by nothing will lead to wrong code in most lines. To help you, writing
2499 macros with a variable parameter list, there are some control commands:
2501 <tt><ref id=".IFBLANK" name=".IFBLANK"></tt> tests the rest of the line and
2502 returns true, if there are any tokens on the remainder of the line. Since
2503 empty parameters are replaced by nothing, this may be used to test if a given
2504 parameter is empty. <tt><ref id=".IFNBLANK" name=".IFNBLANK"></tt> tests the
2507 Look at this example:
2510 .macro ldaxy a, x, y
2523 This macro may be called as follows:
2526 ldaxy 1, 2, 3 ; Load all three registers
2528 ldaxy 1, , 3 ; Load only a and y
2530 ldaxy , , 3 ; Load y only
2533 There's another helper command for determining, which macro parameters are
2534 valid: <tt><ref id=".PARAMCOUNT" name=".PARAMCOUNT"></tt> This command is
2535 replaced by the parameter count given, <em/including/ intermediate empty macro
2539 ldaxy 1 ; .PARAMCOUNT = 1
2540 ldaxy 1,,3 ; .PARAMCOUNT = 3
2541 ldaxy 1,2 ; .PARAMCOUNT = 2
2542 ldaxy 1, ; .PARAMCOUNT = 2
2543 ldaxy 1,2,3 ; .PARAMCOUNT = 3
2547 <sect1>Recursive macros<p>
2549 Macros may be used recursively:
2552 .macro push r1, r2, r3
2561 There's also a special macro to help writing recursive macros: <tt><ref
2562 id=".EXITMACRO" name=".EXITMACRO"></tt> This command will stop macro expansion
2566 .macro push r1, r2, r3, r4, r5, r6, r7
2568 ; First parameter is empty
2574 push r2, r3, r4, r5, r6, r7
2578 When expanding this macro, the expansion will push all given parameters
2579 until an empty one is encountered. The macro may be called like this:
2582 push $20, $21, $32 ; Push 3 ZP locations
2583 push $21 ; Push one ZP location
2587 <sect1>Local symbols inside macros<p>
2589 Now, with recursive macros, <tt><ref id=".IFBLANK" name=".IFBLANK"></tt> and
2590 <tt><ref id=".PARAMCOUNT" name=".PARAMCOUNT"></tt>, what else do you need?
2591 Have a look at the inc16 macro above. Here is it again:
2605 If you have a closer look at the code, you will notice, that it could be
2606 written more efficiently, like this:
2617 But imagine what happens, if you use this macro twice? Since the label
2618 "Skip" has the same name both times, you get a "duplicate symbol" error.
2619 Without a way to circumvent this problem, macros are not as useful, as
2620 they could be. One solution is, to start a new lexical block inside the
2634 Now the label is local to the block and not visible outside. However,
2635 sometimes you want a label inside the macro to be visible outside. To make
2636 that possible, there's a new command that's only usable inside a macro
2637 definition: <tt><ref id=".LOCAL" name=".LOCAL"></tt>. <tt/.LOCAL/ declares one
2638 or more symbols as local to the macro expansion. The names of local variables
2639 are replaced by a unique name in each separate macro expansion. So we could
2640 also solve the problem above by using <tt/.LOCAL/:
2644 .local Skip ; Make Skip a local symbol
2651 Skip: ; Not visible outside
2656 <sect1>C style macros<p>
2658 Starting with version 2.5 of the assembler, there is a second macro type
2659 available: C style macros using the <tt/.DEFINE/ directive. These macros are
2660 similar to the classic macro type described above, but behaviour is sometimes
2665 <item> Macros defined with <tt><ref id=".DEFINE" name=".DEFINE"></tt> may not
2666 span more than a line. You may use line continuation (see <tt><ref
2667 id=".LINECONT" name=".LINECONT"></tt>) to spread the definition over
2668 more than one line for increased readability, but the macro itself
2669 may not contain an end-of-line token.
2671 <item> Macros defined with <tt><ref id=".DEFINE" name=".DEFINE"></tt> share
2672 the name space with classic macros, but they are detected and replaced
2673 at the scanner level. While classic macros may be used in every place,
2674 where a mnemonic or other directive is allowed, <tt><ref id=".DEFINE"
2675 name=".DEFINE"></tt> style macros are allowed anywhere in a line. So
2676 they are more versatile in some situations.
2678 <item> <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may take
2679 parameters. While classic macros may have empty parameters, this is
2680 not true for <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros.
2681 For this macro type, the number of actual parameters must match
2682 exactly the number of formal parameters.
2684 To make this possible, formal parameters are enclosed in braces when
2685 defining the macro. If there are no parameters, the empty braces may
2688 <item> Since <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may not
2689 contain end-of-line tokens, there are things that cannot be done. They
2690 may not contain several processor instructions for example. So, while
2691 some things may be done with both macro types, each type has special
2692 usages. The types complement each other.
2696 Let's look at a few examples to make the advantages and disadvantages
2699 To emulate assemblers that use "<tt/EQU/" instead of "<tt/=/" you may use the
2700 following <tt/.DEFINE/:
2705 foo EQU $1234 ; This is accepted now
2708 You may use the directive to define string constants used elsewhere:
2711 ; Define the version number
2712 .define VERSION "12.3a"
2718 Macros with parameters may also be useful:
2721 .define DEBUG(message) .out message
2723 DEBUG "Assembling include file #3"
2726 Note that, while formal parameters have to be placed in braces, this is
2727 not true for the actual parameters. Beware: Since the assembler cannot
2728 detect the end of one parameter, only the first token is used. If you
2729 don't like that, use classic macros instead:
2737 (This is an example where a problem can be solved with both macro types).
2740 <sect1>Characters in macros<p>
2742 When using the <ref id="option-t" name="-t"> option, characters are translated
2743 into the target character set of the specific machine. However, this happens
2744 as late as possible. This means that strings are translated if they are part
2745 of a <tt><ref id=".BYTE" name=".BYTE"></tt> or <tt><ref id=".ASCIIZ"
2746 name=".ASCIIZ"></tt> command. Characters are translated as soon as they are
2747 used as part of an expression.
2749 This behaviour is very intuitive outside of macros but may be confusing when
2750 doing more complex macros. If you compare characters against numeric values,
2751 be sure to take the translation into account.
2756 <sect>Macro packages<label id="macropackages"><p>
2758 Using the <tt><ref id=".MACPACK" name=".MACPACK"></tt> directive, predefined
2759 macro packages may be included with just one command. Available macro packages
2763 <sect1><tt>.MACPACK generic</tt><p>
2765 This macro package defines macros that are useful in almost any program.
2766 Currently, two macros are defined:
2781 <sect1><tt>.MACPACK longbranch</tt><p>
2783 This macro package defines long conditional jumps. They are named like the
2784 short counterpart but with the 'b' replaced by a 'j'. Here is a sample
2785 definition for the "<tt/jeq/" macro, the other macros are built using the same
2790 .if .def(Target) .and ((*+2)-(Target) <= 127)
2799 All macros expand to a short branch, if the label is already defined (back
2800 jump) and is reachable with a short jump. Otherwise the macro expands to a
2801 conditional branch with the branch condition inverted, followed by an absolute
2802 jump to the actual branch target.
2804 The package defines the following macros:
2807 jeq, jne, jmi, jpl, jcs, jcc, jvs, jvc
2812 <sect>Module constructors/destructors<label id="condes"><p>
2814 <em>Note:</em> This section applies mostly to C programs, so the explanation
2815 below uses examples from the C libraries. However, the feature may also be
2816 useful for assembler programs.
2819 <sect1>Module overview<p>
2821 Using the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> and <tt><ref
2822 id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> keywords it it possible to export
2823 functions in a special way. The linker is able to generate tables with all
2824 functions of a specific type. Such a table will <em>only</em> include symbols
2825 from object files that are linked into a specific executable. This may be used
2826 to add initialization and cleanup code for library modules.
2828 The C heap functions are an example where module initialization code is used.
2829 All heap functions (<tt>malloc</tt>, <tt>free</tt>, ...) work with a few
2830 variables that contain the start and the end of the heap, pointers to the free
2831 list and so on. Since the end of the heap depends on the size and start of the
2832 stack, it must be initialized at runtime. However, initializing these
2833 variables for programs that do not use the heap are a waste of time and
2836 So the central module defines a function that contains initialization code and
2837 exports this function using the <tt/.CONSTRUCTOR/ statement. If (and only if)
2838 this module is added to an executable by the linker, the initialization
2839 function will be placed into the table of constructors by the linker. The C
2840 startup code will call all constructors before <tt/main/ and all destructors
2841 after <tt/main/, so without any further work, the heap initialization code is
2842 called once the module is linked in.
2844 While it would be possible to add explicit calls to initialization functions
2845 in the startup code, the new approach has several advantages:
2849 If a module is not included, the initialization code is not linked in and not
2850 called. So you don't pay for things you don't need.
2853 Adding another library that needs initialization does not mean that the
2854 startup code has to be changed. Before we had module constructors and
2855 destructors, the startup code for all systems had to be adjusted to call the
2856 new initialization code.
2859 The feature saves memory: Each additional initialization function needs just
2860 two bytes in the table (a pointer to the function).
2865 <sect1>Calling order<p>
2867 Both, constructors and destructors are sorted in increasing priority order by
2868 the linker when using one of the builtin linker configurations, so the
2869 functions with lower priorities come first and are followed by those with
2870 higher priorities. The C library runtime subroutine that walks over the
2871 constructor and destructor tables calls the functions starting from the top of
2872 the table - which means that functions with a high priority are called first.
2874 So when using the C runtime, both constructors and destructors are called with
2875 high priority functions first, followed by low priority functions.
2880 When creating and using module constructors and destructors, please take care
2886 The linker will only generate function tables, it will not generate code to
2887 call these functions. If you're using the feature in some other than the
2888 existing C environments, you have to write code to call all functions in a
2889 linker generated table yourself. See the <tt>condes</tt> module in the C
2890 runtime for an example on how to do this.
2893 The linker will only add addresses of functions that are in modules linked to
2894 the executable. This means that you have to be careful where to place the
2895 condes functions. If initialization is needed for a group of functions, be
2896 sure to place the initialization function into a module that is linked in
2897 regardless of which function is called by the user.
2900 The linker will generate the tables only when requested to do so by the
2901 <tt/FEATURE CONDES/ statement in the linker config file. Each table has to
2902 be requested separately.
2905 Constructors and destructors may have priorities. These priorities determine
2906 the order of the functions in the table. If your intialization or cleanup code
2907 does depend on other initialization or cleanup code, you have to choose the
2908 priority for the functions accordingly.
2911 Besides the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> and <tt><ref
2912 id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> statements, there is also a more
2913 generic command: <tt><ref id=".CONDES" name=".CONDES"></tt>. This allows to
2914 specify an additional type. Predefined types are 0 (constructor) and 1
2915 (destructor). The linker generates a separate table for each type on request.
2923 <sect>Bugs/Feedback<p>
2925 If you have problems using the assembler, if you find any bugs, or if
2926 you're doing something interesting with the assembler, I would be glad to
2927 hear from you. Feel free to contact me by email
2928 (<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">).
2934 ca65 (and all cc65 binutils) are (C) Copyright 1998-2001 Ullrich von
2935 Bassewitz. For usage of the binaries and/or sources the following
2936 conditions do apply:
2938 This software is provided 'as-is', without any expressed or implied
2939 warranty. In no event will the authors be held liable for any damages
2940 arising from the use of this software.
2942 Permission is granted to anyone to use this software for any purpose,
2943 including commercial applications, and to alter it and redistribute it
2944 freely, subject to the following restrictions:
2947 <item> The origin of this software must not be misrepresented; you must not
2948 claim that you wrote the original software. If you use this software
2949 in a product, an acknowledgment in the product documentation would be
2950 appreciated but is not required.
2951 <item> Altered source versions must be plainly marked as such, and must not
2952 be misrepresented as being the original software.
2953 <item> This notice may not be removed or altered from any source