X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fca65.sgml;h=1f8f2f0d3a6dcb1bdce0e41cf81a8d0ed2b2c7c4;hb=a6b04f6e97b59ca0ad1cc98dbd91ad600c0414a8;hp=2c43a9b50534cffac49f777244e182b3f2f60573;hpb=1fc2dfb64f6a02c30be199f22b1bd7fe123e3847;p=cc65 diff --git a/doc/ca65.sgml b/doc/ca65.sgml index 2c43a9b50..1f8f2f0d3 100644 --- a/doc/ca65.sgml +++ b/doc/ca65.sgml @@ -4,7 +4,6 @@ ca65 Users Guide <author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline> <url url="mailto:greg.king5@verizon.net" name="Greg King"> -<date>2016-06-11 <abstract> 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. <sect1>Address sizes of symbols<p> +The address size of a symbol can be specified with a prefix: +<itemize> +<item>z: zeropage addressing (8 bits). +<item>a: absolute addressing (16 bits). +<item>f: far addressing (24 bits). +</itemize> + +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. <sect1>Memory models<p> @@ -1636,7 +1649,7 @@ either a string or an expression. <tscreen><verb> ; Reserve space for the larger of two data blocks - savearea: .max (.sizeof (foo), .sizeof (bar)) + savearea: .res .max (.sizeof (foo), .sizeof (bar)) </verb></tscreen> See: <tt><ref id=".MIN" name=".MIN"></tt> @@ -1695,8 +1708,8 @@ either a string or an expression. Example: <tscreen><verb> - ; 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) </verb></tscreen> See: <tt><ref id=".MAX" name=".MAX"></tt> @@ -2717,7 +2730,7 @@ Here's a list of all control commands and a description, what they do: <tag><tt>at_in_identifiers</tt><label id="at_in_identifiers"></tag> - 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: <tag><tt>dollar_in_identifiers</tt><label id="dollar_in_identifiers"></tag> - 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. <tag><tt>dollar_is_pc</tt><label id="dollar_is_pc"></tag> - 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: <tag><tt>leading_dot_in_identifiers</tt><label id="leading_dot_in_identifiers"></tag> - 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: <tag><tt>pc_assignment</tt><label id="pc_assignment"></tag> - Allow assignments to the PC symbol (`*' or `$' if <tt/dollar_is_pc/ + Allow assignments to the PC symbol ('*' or '$' if <tt/dollar_is_pc/ is enabled). Such an assignment is handled identical to the <tt><ref id=".ORG" name=".ORG"></tt> 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. +<item> 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. + </itemize> 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" </verb></tscreen> -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: <tscreen><verb> -.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 </verb></tscreen> -(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: + +<tscreen><verb> +.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 +</verb></tscreen> <sect1>Characters in macros<p> @@ -4583,6 +4627,7 @@ compiler, depending on the target system selected: <itemize> <item><tt/__APPLE2__/ - Target system is <tt/apple2/ or <tt/apple2enh/ <item><tt/__APPLE2ENH__/ - Target system is <tt/apple2enh/ +<item><tt/__ATARI2600__/ - Target system is <tt/atari2600/ <item><tt/__ATARI5200__/ - Target system is <tt/atari5200/ <item><tt/__ATARI__/ - Target system is <tt/atari/ or <tt/atarixl/ <item><tt/__ATARIXL__/ - Target system is <tt/atarixl/