ca65 Users Guide
,
-2016-06-11
ca65 is a powerful macro assembler for the 6502, 65C02, and 65816 CPUs. It is
@@ -1187,7 +1186,21 @@ an explanation on how this is done.
Address sizes of symbols
+The address size of a symbol can be specified with a prefix:
+
+z: zeropage addressing (8 bits).
+a: absolute addressing (16 bits).
+f: far addressing (24 bits).
+
+
+The zeropage addressing override can be used to ensure the use of optimal
+zeropage instructions, or correct cases where the size isn't yet known
+due to the single-pass assembly model.
+
+The larger addressing overrides can be used to promote a smaller address
+to absolute or far addressing, instead of being automatically fit into
+a smaller addressing type.
Memory models
@@ -1636,7 +1649,7 @@ either a string or an expression.
; Reserve space for the larger of two data blocks
- savearea: .max (.sizeof (foo), .sizeof (bar))
+ savearea: .res .max (.sizeof (foo), .sizeof (bar))
See:
@@ -1695,8 +1708,8 @@ either a string or an expression.
Example:
- ; Reserve space for some data, but 256 bytes minimum
- savearea: .min (.sizeof (foo), 256)
+ ; Reserve space for some data, but 256 bytes maximum
+ savearea: .res .min (.sizeof (foo), 256)
See:
@@ -2717,7 +2730,7 @@ Here's a list of all control commands and a description, what they do:
at_in_identifiers
- Accept the at character (`@') as a valid character in identifiers. The
+ Accept the at character ('@') as a valid character in identifiers. The
at character is not allowed to start an identifier, even with this
feature enabled.
@@ -2752,13 +2765,13 @@ Here's a list of all control commands and a description, what they do:
dollar_in_identifiers
- Accept the dollar sign (`$') as a valid character in identifiers. The
+ Accept the dollar sign ('$') as a valid character in identifiers. The
dollar character is not allowed to start an identifier, even with this
feature enabled.
dollar_is_pc
- The dollar sign may be used as an alias for the star (`*'), which
+ The dollar sign may be used as an alias for the star ('*'), which
gives the value of the current PC in expressions.
Note: Assignment to the pseudo variable is not allowed.
@@ -2776,7 +2789,7 @@ Here's a list of all control commands and a description, what they do:
leading_dot_in_identifiers
- Accept the dot (`.') as the first character of an identifier. This may be
+ Accept the dot ('.') as the first character of an identifier. This may be
used for example to create macro names that start with a dot emulating
control directives of other assemblers. Note however, that none of the
reserved keywords built into the assembler, that starts with a dot, may be
@@ -2812,7 +2825,7 @@ Here's a list of all control commands and a description, what they do:
pc_assignment
- Allow assignments to the PC symbol (`*' or `$' if command (which is usually not needed, so just
removing the lines with the assignments may also be an option when porting
@@ -3786,7 +3799,7 @@ Here's a list of all control commands and a description, what they do:
page and direct (short) addressing is possible for data in this segment.
Beware: Only labels in a segment with the zeropage attribute are marked
- as reachable by short addressing. The `*' (PC counter) operator will
+ as reachable by short addressing. The '*' (PC counter) operator will
work as in other segments and will create absolute variable values.
Please note that a segment cannot have two different address sizes. A
@@ -4305,6 +4318,13 @@ different:
some things may be done with both macro types, each type has special
usages. The types complement each other.
+ Parentheses work differently from C macros.
+ The common practice of wrapping C macros in parentheses may cause
+ unintended problems here, such as accidentally implying an
+ indirect addressing mode. While the definition of a macro requires
+ parentheses around its argument list, when invoked they should not be
+ included.
+
Let's look at a few examples to make the advantages and disadvantages
@@ -4337,18 +4357,42 @@ Macros with parameters may also be useful:
DEBUG "Assembling include file #3"
-Note that, while formal parameters have to be placed in braces, this is
-not true for the actual parameters. Beware: Since the assembler cannot
-detect the end of one parameter, only the first token is used. If you
-don't like that, use classic macros instead:
+Note that, while formal parameters have to be placed in parentheses,
+the actual argument used when invoking the macro should not be.
+The invoked arguments are separated by commas only, if parentheses are
+used by accident they will become part of the replaced token.
+
+If you wish to have an expression follow the macro invocation, the
+last parameter can be enclosed in curly braces {} to indicate the end of that
+argument.
+
+Examples:
-.macro DEBUG message
- .out message
-.endmacro
+.define COMBINE(ta,tb,tc) ta+tb*10+tc*100
+
+.word COMBINE 5,6,7 ; 5+6*10+7*100 = 765
+.word COMBINE(5,6,7) ; (5+6*10+7)*100 = 7200 ; incorrect use of parentheses
+.word COMBINE 5,6,7+1 ; 5+6*10+7+1*100 = 172
+.word COMBINE 5,6,{7}+1 ; 5+6*10+7*100+1 = 766 ; {} encloses the argument
+.word COMBINE 5,6-2,7 ; 5+6-2*10+7*100 = 691
+.word COMBINE 5,(6-2),7 ; 5+(6-2)*10+7*100 = 745
+.word COMBINE 5,6,7+COMBINE 0,1,2 ; 5+6*10+7+0+1*10+2*100*100 = 20082
+.word COMBINE 5,6,{7}+COMBINE 0,1,2 ; 5+6*10+7*100+0+1*10+2*100 = 975
-(That is an example where a problem can be solved with both macro types).
+With C macros it is common to enclose the results in parentheses to
+prevent unintended interactions with the text of the arguments, but
+additional care must be taken in this assembly context where parentheses
+may alter the meaning of a statement. In particular, indirect addressing modes
+may be accidentally implied:
+
+
+.define DUO(ta,tb) (ta+(tb*10))
+
+ lda DUO(5,4), Y ; LDA (indirect), Y
+ lda 0+DUO(5,4), Y ; LDA absolute indexed, Y
+Characters in macros
@@ -4583,6 +4627,7 @@ compiler, depending on the target system selected: