<article>
<title>ca65 Users Guide
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
-<date>19.07.2000, 29.11.2000, 02.10.2001
+<date>2000-07-19, 2000-11-29, 2001-10-02, 2005-09-08
<abstract>
ca65 is a powerful macro assembler for the 6502, 65C02 and 65816 CPUs. It is
--include-dir dir Set an include directory search path
--listing Create a listing if assembly was ok
--list-bytes n Maximum number of bytes per listing line
+ --macpack-dir dir Set a macro package directory
--memory-model model Set the memory model
--pagelength n Set the page length for the listing
--smart Enable smart mode
Set the default for the CPU type. The option takes a parameter, which
may be one of
- 6502, 65SC02, 65C02, 65816, sunplus, sweet16
+ 6502, 65SC02, 65C02, 65816, sunplus, sweet16, HuC6280
The sunplus cpu is not available in the freeware version, because the
instruction set is "proprietary and confidential".
number of printed bytes.
+ <tag><tt>--macpack-dir dir</tt></tag>
+
+ This options allows to specify a directory containing macro files that are
+ used instead of the builtin images when a <tt><ref id=".MACPACK"
+ name=".MACPACK"></tt> directive is encountered. If <tt>--macpack-dir</tt>
+ was specified, a <tt>.mac</tt> extension is added to the package name and
+ the resulting file is loaded from the given directory. This is most useful
+ when debugging the builtin macro packages.
+
+
<tag><tt>-mm model, --memory-model model</tt></tag>
Define the default memory model. Possible model specifiers are near, far and
DEA is an alias for DEC A
INA is an alias for INC A
SWA is an alias for XBA
- TAD is an alias for TCD
+ TAD is an alias for TCD
TAS is an alias for TCS
TDA is an alias for TDC
TSA is an alias for TSC
<sect1>Available operators<label id="operators"><p>
-Available operators sorted by precedence:
-
<table>
-<tabular ca="llc">
-Op|Description|Precedence@<hline>
- |Builtin string functions|0@
- |Builtin pseudo variables|1@
- |Builtin pseudo functions|1@
-+|Unary plus|1@
--|Unary minus|1@
-˜|Unary bitwise not|1@
-.BITNOT|Unary bitwise not|1@
-<|Low byte operator|1@
->|High byte operator|1@
-^|Bank byte operator|1@
-*|Multiplication|2@
-/|Division|2@
-.MOD|Modulo operation|2@
-&|Bitwise and|2@
-.BITAND|Bitwise and|2@
-^|Bitwise xor|2@
-.BITXOR|Bitwise xor|2@
-<<|Shift left operator|2@
-.SHL|Shift left operator|2@
->>|Shift right operato|r@
-.SHR|Shift right operator|2@
-+|Binary plus|3@
--|Binary minus|3@
-||Binary or|3@
-.BITOR|Binary or|3@
-=|Compare operation (equal)|4@
-<>|Compare operation (not equal)|4@
-<|Compare operation (less)|4@
->|Compare operation (greater)|4@
-<=|Compare operation (less or equal)|4@
->=|Compare operation (greater or equal)|4@
-&&|Boolean and|5@
-.AND|Boolean and|5@
-.XOR|Boolean xor|5@
-|||Boolean or|6@
-.OR|Boolean or|6@
-!|Boolean not|7@
-.NOT|Boolean not|7@
+<tabular ca="clc">
+<bf/Operator/| <bf/Description/| <bf/Precedence/@<hline>
+| Built-in string functions| 0@
+||~@
+| Built-in pseudo-variables| 1@
+| Built-in pseudo-functions| 1@
++| Unary positive| 1@
+-| Unary negative| 1@
+˜<newline>
+.BITNOT| Unary bitwise not| 1@
+<<newline>
+.LOBYTE| Unary low-byte operator| 1@
+><newline>
+.HIBYTE| Unary high-byte operator| 1@
+^<newline>
+.BANKBYTE| Unary bank-byte operator| 1@
+||~@
+*| Multiplication| 2@
+/| Division| 2@
+.MOD| Modulo operator| 2@
+&<newline>
+.BITAND| Bitwise and| 2@
+^<newline>
+.BITXOR| Binary bitwise xor| 2@
+<<<newline>
+.SHL| Shift-left operator| 2@
+>><newline>
+.SHR| Shift-right operator| 2@
+||~@
++| Binary addition| 3@
+-| Binary subtraction| 3@
+|<newline>
+.BITOR| Bitwise or| 3@
+||~@
+= | Compare operator (equal)| 4@
+<>| Compare operator (not equal)| 4@
+<| Compare operator (less)| 4@
+>| Compare operator (greater)| 4@
+<=| Compare operator (less or equal)| 4@
+>=| Compare operator (greater or equal)| 4@
+||~@
+&&<newline>
+.AND| Boolean and| 5@
+.XOR| Boolean xor| 5@
+||~@
+||<newline>
+.OR| Boolean or| 6@
+||~@
+!<newline>
+.NOT| Boolean not| 7@<hline>
</tabular>
-<caption>Available operators sorted by precedence
+<caption>Available operators, sorted by precedence
</table>
-To force a specific order of evaluation, braces may be used as usual.
-<p>
+To force a specific order of evaluation, parentheses may be used, as usual.
<bf/Note:/ This does not work in conjunction with <tt/.FEATURE
loose_string_term/, since in this case the input would be ambiguous.
+ <tag><tt>org_per_seg</tt><label id="org_per_seg"></tag>
+
+ This feature makes relocatable/absolute mode local to the current segment.
+ Using <tt><ref id=".ORG" name=".ORG"></tt> when <tt/org_per_seg/ is in
+ effect will only enable absolute mode for the current segment. Dito for
+ <tt><ref id=".RELOC" name=".RELOC"></tt>.
+
<tag><tt>pc_assignment</tt></tag>
Allow assignments to the PC symbol (`*' or `$' if <tt/dollar_is_pc/
packages are:
<tscreen><verb>
+ atari Defines the scrcode macro.
+ cbm Defines the scrcode macro.
+ cpu Defines constants for the .CPU variable.
generic Defines generic macros like add and sub.
longbranch Defines conditional long jump macros.
- cbm Defines the scrcode macro
- cpu Defines constants for the .CPU variable
</verb></tscreen>
Including a macro package twice, or including a macro package that
assembled. Use <tt><ref id=".RELOC" name=".RELOC"></tt> to switch back to
relocatable code.
- Please note that you <em/do not need/ this command in most cases. Placing
+ By default, absolute/relocatable mode is global (valid even when switching
+ segments). Using <tt>.FEATURE <ref id="org_per_seg" name="org_per_seg"></tt>
+ it can be made segment local.
+
+ Please note that you <em/do not need/ <tt/.ORG/ in most cases. Placing
code at a specific address is the job of the linker, not the assembler, so
there is usually no reason to assemble code to a specific address.
- You may not switch segments while inside a section of absolute code.
-
Example:
<tscreen><verb>
See: <tt><ref id=".POPSEG" name=".POPSEG"></tt>
+<sect1><tt>.RELOC</tt><label id=".RELOC"><p>
+
+ Switch back to relocatable mode. See the <tt><ref id=".ORG"
+ name=".ORG"></tt> command.
+
+
<sect1><tt>.REPEAT</tt><label id=".REPEAT"><p>
Repeat all commands between <tt/.REPEAT/ and <tt><ref id=".ENDREPEAT"
See: <tt><ref id=".ENDREPEAT" name=".ENDREPEAT"></tt>
-<sect1><tt>.RELOC</tt><label id=".RELOC"><p>
-
- Switch back to relocatable mode. See the <tt><ref id=".ORG"
- name=".ORG"></tt> command.
-
-
<sect1><tt>.RES</tt><label id=".RES"><p>
Reserve storage. The command is followed by one or two constant
None = 0 ; No error
File = 1 ; File error
Parse = 2 ; Parse error
- .endproc ; Close lexical level
+ .endscope ; Close lexical level
...
lda #Error::File ; Use symbol from scope Error
Switch the CPU instruction set. The command is followed by a string that
specifies the CPU. Possible values are those that can also be supplied to
the <tt><ref id="option--cpu" name="--cpu"></tt> command line option,
- namely: 6502, 6502X, 65SC02, 65C02, 65816 and sunplus. Please note that
- support for the sunplus CPU is not available in the freeware version,
- because the instruction set of the sunplus CPU is "proprietary and
- confidential".
+ namely: 6502, 6502X, 65SC02, 65C02, 65816, sunplus and HuC6280. Please
+ note that support for the sunplus CPU is not available in the freeware
+ version, because the instruction set of the sunplus CPU is "proprietary
+ and confidential".
See: <tt><ref id=".CPU" name=".CPU"></tt>,
<tt><ref id=".IFP02" name=".IFP02"></tt>,
CPU_65816
CPU_SUNPLUS
CPU_SWEET16
+ CPU_HUC6280
</verb></tscreen>
is defined. These constants may be used to determine the exact type of the
CPU_ISET_65816
CPU_ISET_SUNPLUS
CPU_ISET_SWEET16
+ CPU_ISET_HUC6280
</verb></tscreen>
The value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable may
<item>Replace all program counter assignments (which are not possible in ca65
by default, and the respective emulation feature works different from what
-you'd expect) by another way to skip to another memory location, for example
-the <tt><ref id=".RES" name=".RES"></tt>directive.
+you'd expect) by another way to skip to memory locations, for example the
+<tt><ref id=".RES" name=".RES"></tt> directive.
<tscreen><verb>
; *=$2000
.res $2000-* ; reserve memory up to $2000
</verb></tscreen>
-notice that other than the original TASS, ca65 can never move the
-programmcounter backwards - think of it as if you are assembling to disc with
-TASS.
+Please note that other than the original TASS, ca65 can never move the program
+counter backwards - think of it as if you are assembling to disk with TASS.
<item>Conditional assembly (<tt/.ifeq//<tt/.endif//<tt/.goto/ etc.) must be
rewritten to match ca65 syntax. Most importantly notice that due to the lack
cl65 --start-addr 0x0ffe -t none myprog.s -o myprog.prg
</verb></tscreen>
-notice that you need to use the actual start address minus two, since two
-bytes are used for the cbm load address.
+Note that you need to use the actual start address minus two, since two bytes
+are used for the cbm load address.
</enum>