<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
--cpu type Set cpu type
--debug-info Add debug info to object file
--feature name Set an emulation feature
+ --forget-inc-paths Forget include search paths
--help Help (this text)
--ignore-case Ignore case of symbols
--include-dir dir Set an include directory search path
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".
command for a list of emulation features.
+ <tag><tt>--forget-inc-paths</tt></tag>
+
+ Forget the builtin include paths. This is most useful when building
+ customized assembler modules, in which case the standard header files should
+ be ignored.
+
+
<label id="option-g">
<tag><tt>-g, --debug-info</tt></tag>
Name a directory which is searched for include files. The option may be
used more than once to specify more than one directory to search. The
current directory is always searched first before considering any
- additional directories.
+ additional directories. See also the section about <ref id="search-paths"
+ name="search paths">.
<tag><tt>-U, --auto-import</tt></tag>
<p>
+
+<sect>Search paths<label id="search-paths"><p>
+
+Include files are searched in the following places:
+
+<enum>
+<item>The current directory.
+<item>A compiled-in directory, which is often <tt>/usr/lib/cc65/asminc</tt>
+ on Linux systems.
+<item>The value of the environment variable <tt/CA65_INC/ if it is defined.
+<item>A subdirectory named <tt/asminc/ of the directory defined in the
+ environment variable <tt/CC65_HOME/, if it is defined.
+<item>Any directory added with the <tt/-I/ option on the command line.
+</enum>
+
+
+
<sect>Input format<p>
<sect1>Assembler syntax<p>
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.
<sect>Symbols and labels<p>
+A symbol or label is an identifier that starts with a letter and is followed
+by letters and digits. Depending on some features enabled (see
+<tt><ref id="at_in_identifiers" name="at_in_identifiers"></tt>,
+<tt><ref id="dollar_in_identifiers" name="dollar_in_identifiers"></tt> and
+<tt><ref id="leading_dot_in_identifiers" name="leading_dot_in_identifiers"></tt>)
+other characters may be present. Use of identifiers consisting of a single
+character will not work in all cases, because some of these identifiers are
+reserved keywords (for example "A" is not a valid identifier for a label,
+because it is the keyword for the accumulator).
+
The assembler allows you to use symbols instead of naked values to make
the source more readable. There are a lot of different ways to define and
use symbols and labels, giving a lot of flexibility.
-
<sect1>Numeric constants<p>
Numeric constants are defined using the equal sign or the label assignment
when the output file is written, and abort with an error if this is not
the case. More complex expressions are possible. The action specifier
<tt/warning/ outputs a warning, while the <tt/error/ specifier outputs
- an error message. In the latter case, generation if the output file is
+ an error message. In the latter case, generation of the output file is
suppressed in both the assembler and linker.
.autoimport + ; Switch on auto import
</verb></tscreen>
+<sect1><tt>.BANKBYTES</tt><label id=".BANKBYTES"><p>
+
+ Define byte sized data by extracting only the bank byte (that is, bits 16-23) from
+ each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with
+ the operator '^' prepended to each expression in its list.
+
+ Example:
+
+ <tscreen><verb>
+ .define MyTable TableItem0, TableItem1, TableItem2, TableItem3
+
+ TableLookupLo: .lobytes MyTable
+ TableLookupHi: .hibytes MyTable
+ TableLookupBank: .bankbytes MyTable
+ </verb></tscreen>
+
+ which is equivalent to
+
+ <tscreen><verb>
+ TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3
+ TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3
+ TableLookupBank: .byte ^TableItem0, ^TableItem1, ^TableItem2, ^TableItem3
+ </verb></tscreen>
+
+ See also: <tt><ref id=".BYTE" name=".BYTE"></tt>,
+ <tt><ref id=".HIBYTES" name=".HIBYTES"></tt>,
+ <tt><ref id=".LOBYTES" name=".LOBYTES"></tt>
+
<sect1><tt>.BSS</tt><label id=".BSS"><p>
<sect1><tt>.EXPORT</tt><label id=".EXPORT"><p>
Make symbols accessible from other modules. Must be followed by a comma
- separated list of symbols to export, with each one optionally followed by
- an address specification. The default is to export the symbol with the
- address size it actually has. The assembler will issue a warning, if the
- symbol is exported with an address size smaller than the actual address
- size.
+ separated list of symbols to export, with each one optionally followed by an
+ address specification and (also optional) an assignment. Using an additional
+ assignment in the export statement allows to define and export a symbol in
+ one statement. The default is to export the symbol with the address size it
+ actually has. The assembler will issue a warning, if the symbol is exported
+ with an address size smaller than the actual address size.
- Example:
+ Examples:
<tscreen><verb>
.export foo
.export bar: far
+ .export foobar: far = foo * bar
+ .export baz := foobar, zap: far = baz - bar
</verb></tscreen>
+ As with constant definitions, using <tt/:=/ instead of <tt/=/ marks the
+ symbols as a label.
+
See: <tt><ref id=".EXPORTZP" name=".EXPORTZP"></tt>
Make symbols accessible from other modules. Must be followed by a comma
separated list of symbols to export. The exported symbols are explicitly
- marked as zero page symbols.
+ marked as zero page symbols. An assignment may be included in the
+ <tt/.EXPORTZP/ statement. This allows to define and export a symbol in one
+ statement.
- Example:
+ Examples:
<tscreen><verb>
.exportzp foo, bar
+ .exportzp baz := $02
</verb></tscreen>
See: <tt><ref id=".EXPORT" name=".EXPORT"></tt>
<descrip>
- <tag><tt>at_in_identifiers</tt></tag>
+ <tag><tt>at_in_identifiers</tt><label id="at_in_identifiers"></tag>
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.
- <tag><tt>dollar_in_identifiers</tt></tag>
+ <tag><tt>c_comments</tt></tag>
+
+ Allow C like comments using <tt>/*</tt> and <tt>*/</tt> as left and right
+ comment terminators. Note that C comments may not be nested. There's also a
+ pitfall when using C like comments: All statements must be terminated by
+ "end-of-line". Using C like comments, it is possible to hide the newline,
+ which results in error messages. See the following non working example:
+
+ <tscreen><verb>
+ lda #$00 /* This comment hides the newline
+*/ sta $82
+ </verb></tscreen>
+
+ <tag><tt>dollar_in_identifiers</tt><label id="dollar_in_identifiers"></tag>
Accept the dollar sign (`$') as a valid character in identifiers. The
- at character is not allowed to start an identifier, even with this
+ dollar character is not allowed to start an identifier, even with this
feature enabled.
<tag><tt>dollar_is_pc</tt></tag>
Allow labels without a trailing colon. These labels are only accepted,
if they start at the beginning of a line (no leading white space).
- <tag><tt>leading_dot_in_identifiers</tt></tag>
+ <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
used for example to create macro names that start with a dot emulating
<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/
.globalzp foo, bar
</verb></tscreen>
+<sect1><tt>.HIBYTES</tt><label id=".HIBYTES"><p>
+
+ Define byte sized data by extracting only the high byte (that is, bits 8-15) from
+ each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with
+ the operator '>' prepended to each expression in its list.
+
+ Example:
+
+ <tscreen><verb>
+ .lobytes $1234, $2345, $3456, $4567
+ .hibytes $fedc, $edcb, $dcba, $cba9
+ </verb></tscreen>
+
+ which is equivalent to
+
+ <tscreen><verb>
+ .byte $34, $45, $56, $67
+ .byte $fe, $ed, $dc, $cb
+ </verb></tscreen>
+
+ Example:
+
+ <tscreen><verb>
+ .define MyTable TableItem0, TableItem1, TableItem2, TableItem3
+
+ TableLookupLo: .lobytes MyTable
+ TableLookupHi: .hibytes MyTable
+ </verb></tscreen>
+
+ which is equivalent to
+
+ <tscreen><verb>
+ TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3
+ TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3
+ </verb></tscreen>
+
+ See also: <tt><ref id=".BYTE" name=".BYTE"></tt>,
+ <tt><ref id=".LOBYTES" name=".LOBYTES"></tt>,
+ <tt><ref id=".BANKBYTES" name=".BANKBYTES"></tt>
+
<sect1><tt>.I16</tt><label id=".I16"><p>
</verb></tscreen>
+<sect1><tt>.LOBYTES</tt><label id=".LOBYTES"><p>
+
+ Define byte sized data by extracting only the low byte (that is, bits 0-7) from
+ each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with
+ the operator '<' prepended to each expression in its list.
+
+ Example:
+
+ <tscreen><verb>
+ .lobytes $1234, $2345, $3456, $4567
+ .hibytes $fedc, $edcb, $dcba, $cba9
+ </verb></tscreen>
+
+ which is equivalent to
+
+ <tscreen><verb>
+ .byte $34, $45, $56, $67
+ .byte $fe, $ed, $dc, $cb
+ </verb></tscreen>
+
+ Example:
+
+ <tscreen><verb>
+ .define MyTable TableItem0, TableItem1, TableItem2, TableItem3
+
+ TableLookupLo: .lobytes MyTable
+ TableLookupHi: .hibytes MyTable
+ </verb></tscreen>
+
+ which is equivalent to
+
+ <tscreen><verb>
+ TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3
+ TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3
+ </verb></tscreen>
+
+ See also: <tt><ref id=".BYTE" name=".BYTE"></tt>,
+ <tt><ref id=".HIBYTES" name=".HIBYTES"></tt>,
+ <tt><ref id=".BANKBYTES" name=".BANKBYTES"></tt>
+
+
<sect1><tt>.LOCAL</tt><label id=".LOCAL"><p>
This command may only be used inside a macro definition. It declares a
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.
+ longbranch Defines conditional long jump macros.
</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>
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
compiler, depending on the target system selected:
<itemize>
-<item><tt/__ACE__/ - Target system is <tt/ace/
-<item><tt/__APPLE2__",/ - Target system is <tt/apple2/
-<item><tt/__APPLE2ENH__",/ - Target system is <tt/apple2enh/
+<item><tt/__APPLE2__/ - Target system is <tt/apple2/
+<item><tt/__APPLE2ENH__/ - Target system is <tt/apple2enh/
<item><tt/__ATARI__/ - Target system is <tt/atari/
-<item><tt/__ATMOS__",/ - Target system is <tt/atmos/
-<item><tt/__BBC__",/ - Target system is <tt/bbc/
+<item><tt/__ATMOS__/ - Target system is <tt/atmos/
+<item><tt/__BBC__/ - Target system is <tt/bbc/
<item><tt/__C128__/ - Target system is <tt/c128/
<item><tt/__C16__/ - Target system is <tt/c16/
<item><tt/__C64__/ - Target system is <tt/c64/
<item><tt/__CBM__/ - Target is a Commodore system
<item><tt/__CBM510__/ - Target system is <tt/cbm510/
<item><tt/__CBM610__/ - Target system is <tt/cbm610/
-<item><tt/__GEOS__",/ - Target system is <tt/geos/
-<item><tt/__LUNIX__",/ - Target system is <tt/lunix/
-<item><tt/__NES__",/ - Target system is <tt/nes/
+<item><tt/__GEOS__/ - Target system is <tt/geos/
+<item><tt/__LUNIX__/ - Target system is <tt/lunix/
+<item><tt/__NES__/ - Target system is <tt/nes/
<item><tt/__PET__/ - Target system is <tt/pet/
<item><tt/__PLUS4__/ - Target system is <tt/plus4/
-<item><tt/__SUPERVISION__",/ - Target system is <tt/supervision/
+<item><tt/__SUPERVISION__/ - Target system is <tt/supervision/
<item><tt/__VIC20__/ - Target system is <tt/vic20/
</itemize>
<sect>Structs and unions<label id="structs"><p>
-<sect1>Overview<p>
+<sect1>
Structs and unions Overview<p>
Structs and unions are special forms of <ref id="scopes" name="scopes">. They
are to some degree comparable to their C counterparts. Both have a list of
useful for assembler programs.
-<sect1>Overview<p>
+<sect1>
Module constructors/destructors Overview<p>
Using the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref
id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR"
projects / cc65 / blobdiff