<article>
<title>ca65 Users Guide
-<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
-<date>2000-07-19, 2000-11-29, 2001-10-02, 2005-09-08
+<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
+<url url="mailto:greg.king5@verizon.net" name="Greg King">
<abstract>
-ca65 is a powerful macro assembler for the 6502, 65C02 and 65816 CPUs. It is
+ca65 is a powerful macro assembler for the 6502, 65C02, and 65816 CPUs. It is
used as a companion assembler for the cc65 crosscompiler, but it may also be
used as a standalone product.
</abstract>
-U Mark unresolved symbols as import
-V Print the assembler version
-W n Set warning level n
+ -d Debug mode
-g Add debug info to object file
-h Help (this text)
-i Ignore case of symbols
--cpu type Set cpu type
--create-dep name Create a make dependency file
--create-full-dep name Create a full make dependency file
+ --debug Debug mode
--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
--large-alignment Don't warn about large alignments
--listing name Create a listing file 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
+ --relax-checks Relax some checks (see docs)
--smart Enable smart mode
--target sys Set the target system
--verbose Increase verbosity
Set the default for the CPU type. The option takes a parameter, which
may be one of
- 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".
+ 6502, 6502X, 65SC02, 65C02, 65816, sweet16, HuC6280, 4510
<label id="option-create-dep">
information to the assembler.
+ <tag><tt>-d, --debug</tt></tag>
+
+ Enables debug mode, something that should not be needed for mere
+ mortals:-)
+
+
<label id="option--feature">
<tag><tt>--feature name</tt></tag>
command for a list of emulation features.
- <label id="option--forget-inc-paths">
- <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>
number of printed bytes.
- <label id="option--macpack-dir">
- <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.
-
-
<label id="option-mm">
<tag><tt>-mm model, --memory-model model</tt></tag>
id=".PAGELENGTH" name=".PAGELENGTH"></tt> directive for more information.
+ <label id="option--relax-checks">
+ <tag><tt>--relax-checks</tt></tag>
+
+ Relax some checks done by the assembler. This will allow code that is an
+ error in most cases and flagged as such by the assembler, but can be valid
+ in special situations.
+
+ Examples are:
+<itemize>
+<item>Short branches between two different segments.
+<item>Byte sized address loads where the address is not a zeropage address.
+</itemize>
+
+
<label id="option-s">
<tag><tt>-s, --smart-mode</tt></tag>
Normal 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 current file's directory.
+<item>Any directory added with the <tt/<ref id="option-I" name="-I">/ option
+on the command line.
<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/<ref id="option-I" name="-I">/ option
-on the command line.
+<item>An optionally compiled-in directory.
</enum>
Binary include files are searched in the following places:
<enum>
-<item>The current directory.
+<item>The current file's directory.
<item>Any directory added with the <tt/<ref id="option--bin-include-dir"
name="--bin-include-dir">/ option on the command line.
</enum>
<tt><ref id=".PSC02" name=".PSC02"></tt> command was given).
<item>all valid 65C02 mnemonics when in 65C02 mode (after the
<tt><ref id=".PC02" name=".PC02"></tt> command was given).
-<item>all valid 65618 mnemonics when in 65816 mode (after the
+<item>all valid 65816 mnemonics when in 65816 mode (after the
<tt><ref id=".P816" name=".P816"></tt> command was given).
-<item>all valid SunPlus mnemonics when in SunPlus mode (after the
- <tt><ref id=".SUNPLUS" name=".SUNPLUS"></tt> command was given).
+<item>all valid 4510 mnemonics when in 4510 mode (after the
+ <tt><ref id=".P4510" name=".P4510"></tt> command was given).
</itemize>
<sect1>65816 mode<p>
-In 65816 mode several aliases are accepted in addition to the official
+In 65816 mode, several aliases are accepted, in addition to the official
mnemonics:
-<tscreen><verb>
- BGE is an alias for BCS
- BLT is an alias for BCC
- CPA is an alias for CMP
- 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
- TAS is an alias for TCS
- TDA is an alias for TDC
- TSA is an alias for TSC
-</verb></tscreen>
-
+<itemize>
+<item><tt>CPA</tt> is an alias for <tt>CMP</tt>
+<item><tt>DEA</tt> is an alias for <tt>DEC A</tt>
+<item><tt>INA</tt> is an alias for <tt>INC A</tt>
+<item><tt>SWA</tt> is an alias for <tt>XBA</tt>
+<item><tt>TAD</tt> is an alias for <tt>TCD</tt>
+<item><tt>TAS</tt> is an alias for <tt>TCS</tt>
+<item><tt>TDA</tt> is an alias for <tt>TDC</tt>
+<item><tt>TSA</tt> is an alias for <tt>TSC</tt>
+</itemize>
<sect1>6502X mode<label id="6502X-mode"><p>
6502X mode is an extension to the normal 6502 mode. In this mode, several
mnemonics for illegal instructions of the NMOS 6502 CPUs are accepted. Since
these instructions are illegal, there are no official mnemonics for them. The
-unofficial ones are taken from <htmlurl
-url="http://www.oxyron.de/html/opcodes02.html"
-name="http://www.oxyron.de/html/opcodes02.html">. Please note that only the
+unofficial ones are taken from <url
+url="http://www.oxyron.de/html/opcodes02.html">. Please note that only the
ones marked as "stable" are supported. The following table uses information
from the mentioned web page, for more information, see there.
</itemize>
+<sect1>4510 mode<p>
+
+The 4510 is a microcontroller that is the core of the Commodore C65 aka C64DX.
+It contains among other functions a slightly modified 65CE02/4502 CPU, to allow
+address mapping for 20 bits of address space (1 megabyte addressable area).
+As compared to the description of the CPU in the
+<url url="http://www.zimmers.net/anonftp/pub/cbm/c65/c65manualupdated.txt.gz"
+name="C65 System Specification">
+<url url="https://raw.githubusercontent.com/MEGA65/c65-specifications/master/c65manualupdated.txt"
+name="(updated version)"> uses these changes:
+<itemize>
+<item><tt>LDA (d,SP),Y</tt> may also be written as <tt>LDA (d,S),Y</tt>
+(matching the 65816 notataion).
+<item>All branch instruction allow now 16 bit offsets. To use a 16 bit
+branch you have to prefix these with an "L" (e.g. "<tt>LBNE</tt>" instead of
+"<tt>BNE</tt>"). This might change at a later implementation of the assembler.
+</itemize>
+For more information about the Commodore C65/C64DX and the 4510 CPU, see
+<url url="http://www.zimmers.net/anonftp/pub/cbm/c65/"> and
+<url url="https://en.wikipedia.org/wiki/Commodore_65" name="Wikipedia">.
+
<sect1>sweet16 mode<label id="sweet16-mode"><p>
][ programmers do probably know how to use sweet16 mode.
For more information about SWEET 16, see
-<htmlurl url="http://www.6502.org/source/interpreters/sweet16.htm"
-name="http://www.6502.org/source/interpreters/sweet16.htm">.
+<url url="http://www.6502.org/source/interpreters/sweet16.htm">.
<sect1>Number format<p>
prefer the "cheap" local labels). Nevertheless, unnamed labels are
convenient in some situations, so it's your decision.
-<bf/Note:/ <ref id="scopes" name="Scopes"> organize named symbols, not
+<em/Note:/ <ref id="scopes" name="Scopes"> organize named symbols, not
unnamed ones, so scopes don't have an effect on unnamed labels.
This is the reason why a procedure must have a name. If you want a scope
without a name, use <tt/<ref id=".SCOPE" name=".SCOPE">/.
-<bf/Note:/ As you can see from the example above, scopes and symbols live in
+<em/Note:/ As you can see from the example above, scopes and symbols live in
different namespaces. There can be a symbol named <tt/foo/ and a scope named
<tt/foo/ without any conflicts (but see the section titled <ref
id="scopesearch" name=""Scope search order"">).
<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>
assignments to <tt/*/, use <tt/<ref id=".ORG" name=".ORG">/ instead.
+<sect1><tt>.ASIZE</tt><label id=".ASIZE"><p>
+
+ Reading this pseudo variable will return the current size of the
+ Accumulator in bits.
+
+ For the 65816 instruction set .ASIZE will return either 8 or 16, depending
+ on the current size of the operand in immediate accu addressing mode.
+
+ For all other CPU instruction sets, .ASIZE will always return 8.
+
+ Example:
+
+ <tscreen><verb>
+ ; Reverse Subtract with Accumulator
+ ; A = memory - A
+ .macro rsb param
+ .if .asize = 8
+ eor #$ff
+ .else
+ eor #$ffff
+ .endif
+ sec
+ adc param
+ .endmacro
+ </verb></tscreen>
+
+ See also: <tt><ref id=".ISIZE" name=".ISIZE"></tt>
+
+
<sect1><tt>.CPU</tt><label id=".CPU"><p>
Reading this pseudo variable will give a constant integer value that
</verb></tscreen>
+<sect1><tt>.ISIZE</tt><label id=".ISIZE"><p>
+
+ Reading this pseudo variable will return the current size of the Index
+ register in bits.
+
+ For the 65816 instruction set .ISIZE will return either 8 or 16, depending
+ on the current size of the operand in immediate index addressing mode.
+
+ For all other CPU instruction sets, .ISIZE will always return 8.
+
+ See also: <tt><ref id=".ASIZE" name=".ASIZE"></tt>
+
+
<sect1><tt>.PARAMCOUNT</tt><label id=".PARAMCOUNT"><p>
This builtin pseudo variable is only available in macros. It is replaced by
Reading this pseudo variable will give the assembler version according to
the following formula:
- VER_MAJOR*$100 + VER_MINOR*$10 + VER_PATCH
+ VER_MAJOR*$100 + VER_MINOR*$10
It may be used to encode the assembler version or check the assembler for
special features not available with older versions.
Example:
- Version 2.11.1 of the assembler will return $2B1 as numerical constant when
+ Version 2.14 of the assembler will return $2E0 as numerical constant when
reading the pseudo variable <tt/.VERSION/.
either a string or an expression.
+<sect1><tt>.ADDRSIZE</tt><label id=".ADDRSIZE"><p>
+
+ The <tt/.ADDRSIZE/ function is used to return the interal address size
+ associated with a symbol. This can be helpful in macros when knowing the address
+ size of symbol can help with custom instructions.
+
+ Example:
+
+ <tscreen><verb>
+ .macro myLDA foo
+ .if .ADDRSIZE(foo) = 1
+ ;do custom command based on zeropage addressing:
+ .byte 0A5h, foo
+ .elseif .ADDRSIZE(foo) = 2
+ ;do custom command based on absolute addressing:
+ .byte 0ADh
+ .word foo
+ .elseif .ADDRSIZE(foo) = 0
+ ; no address size defined for this symbol:
+ .out .sprintf("Error, address size unknown for symbol %s", .string(foo))
+ .endif
+ .endmacro
+ </verb></tscreen>
+
+ This command is new and must be enabled with the <tt/.FEATURE addrsize/ command.
+
+ See: <tt><ref id=".FEATURE" name=".FEATURE"></tt>
+
+
<sect1><tt>.BANK</tt><label id=".BANK"><p>
The <tt/.BANK/ function is used to support systems with banked memory. The
<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>
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>
<tscreen><verb>
.struct Point ; Struct size = 4
xcoord .word
- xcoord .word
+ ycoord .word
.endstruct
P: .tag Point ; Declare a point
<sect1><tt>.CHARMAP</tt><label id=".CHARMAP"><p>
Apply a custom mapping for characters. The command is followed by two
- numbers in the range 1..255. The first one is the index of the source
- character, the second one is the mapping. The mapping applies to all
- character and string constants when they generate output, and overrides
+ numbers. The first one is the index of the source character (range 0..255);
+ the second one is the mapping (range 0..255). The mapping applies to all
+ character and string constants <em/when/ they generate output; and, overrides
a mapping table specified with the <tt><ref id="option-t" name="-t"></tt>
command line switch.
Example:
-
<tscreen><verb>
- .charmap $41, $61 ; Map 'A' to 'a'
+ .charmap $41, $61 ; Map 'A' to 'a'
</verb></tscreen>
</verb></tscreen>
+<sect1><tt>.DEFINEDMACRO</tt><label id=".DEFINEDMACRO"><p>
+
+ Builtin function. The function expects an identifier as argument in braces.
+ The argument is evaluated, and the function yields "true" if the identifier
+ has already been defined as the name of a macro. Otherwise the function yields
+ false. Example:
+
+ <tscreen><verb>
+ .macro add foo
+ clc
+ adc foo
+ .endmacro
+
+ .if .definedmacro(add)
+ add #$01
+ .else
+ clc
+ adc #$01
+ .endif
+ </verb></tscreen>
+
+
<sect1><tt>.DESTRUCTOR</tt><label id=".DESTRUCTOR"><p>
Export a symbol and mark it as a module destructor. This may be used
<descrip>
+ <tag><tt>addrsize</tt><label id="addrsize"></tag>
+
+ Enables the .ADDRSIZE pseudo function. This function is experimental and not enabled by default.
+
+ See also: <tt><ref id=".ADDRSIZE" name=".ADDRSIZE"></tt>
+
<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.
+ <tag><tt>bracket_as_indirect</tt><label id="bracket_as_indirect"></tag>
+
+ Use <tt>[]</tt> instead of <tt>()</tt> for the indirect addressing modes.
+ Example:
+
+ <tscreen><verb>
+ lda [$82]
+ lda [$82,x]
+ lda [$82],y
+ jmp [$fffe]
+ jmp [table,x]
+ </verb></tscreen>
+ <em/Note:/ This should not be used in 65186 mode because it conflicts with
+ the 65816 instruction syntax for far addressing. See the section covering
+ <tt/<ref id="address-sizes" name="address sizes">/ for more information.
+
<tag><tt>c_comments</tt><label id="c_comments"></tag>
Allow C like comments using <tt>/*</tt> and <tt>*/</tt> as left and right
<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.
<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
<tscreen><verb>
lda #'a
</verb></tscreen>
- <bf/Note:/ This does not work in conjunction with <tt/.FEATURE
+ <em/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>
<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
same name. This does also make it possible to introduce hard to find errors
in your code, so be careful!
+ <tag><tt>underline_in_numbers</tt><label id="underline_in_numbers"></tag>
+
+ Allow underlines within numeric constants. These may be used for grouping
+ the digits of numbers for easier reading.
+ Example:
+ <tscreen><verb>
+ .feature underline_in_numbers
+ .word %1100001110100101
+ .word %1100_0011_1010_0101 ; Identical but easier to read
+ </verb></tscreen>
+
</descrip>
It is also possible to specify features on the command line using the
Conditional assembly: Check if there are any remaining tokens in this line,
and evaluate to FALSE if this is the case, and to TRUE otherwise. If the
condition is not true, further lines are not assembled until an <tt><ref
- id=".ELSE" name=".ESLE"></tt>, <tt><ref id=".ELSEIF" name=".ELSEIF"></tt> or
+ id=".ELSE" name=".ELSE"></tt>, <tt><ref id=".ELSEIF" name=".ELSEIF"></tt> or
<tt><ref id=".ENDIF" name=".ENDIF"></tt> directive.
This command is often used to check if a macro parameter was given. Since an
empty macro parameter will evaluate to nothing, the condition will evaluate
- to FALSE if an empty parameter was given.
+ to TRUE if an empty parameter was given.
Example:
(see <tt><ref id=".P02" name=".P02"></tt> command).
+<sect1><tt>.IFP4510</tt><label id=".IFP4510"><p>
+
+ Conditional assembly: Check if the assembler is currently in 4510 mode
+ (see <tt><ref id=".P4510" name=".P4510"></tt> command).
+
+
<sect1><tt>.IFP816</tt><label id=".IFP816"><p>
Conditional assembly: Check if the assembler is currently in 65816 mode
the feature in more detail.
+<sect1><tt>.ISMNEM, .ISMNEMONIC</tt><label id=".ISMNEMONIC"><p>
+
+ Builtin function. The function expects an identifier as argument in braces.
+ The argument is evaluated, and the function yields "true" if the identifier
+ is defined as an instruction mnemonic that is recognized by the assembler.
+ Example:
+
+ <tscreen><verb>
+ .if .not .ismnemonic(ina)
+ .macro ina
+ clc
+ adc #$01
+ .endmacro
+ .endif
+ </verb></tscreen>
+
+
<sect1><tt>.LINECONT</tt><label id=".LINECONT"><p>
Switch on or off line continuations using the backslash character
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.
+ generic Defines generic macroes like add, sub, and blt.
+ longbranch Defines conditional long-jump macroes.
</verb></tscreen>
Including a macro package twice, or including a macro package that
<tt><ref id="option--cpu" name="--cpu"></tt> command line option.
See: <tt><ref id=".PC02" name=".PC02"></tt>, <tt><ref id=".PSC02"
- name=".PSC02"></tt> and <tt><ref id=".P816" name=".P816"></tt>
+ name=".PSC02"></tt>, <tt><ref id=".P816" name=".P816"></tt> and
+ <tt><ref id=".P4510" name=".P4510"></tt>
+
+
+<sect1><tt>.P4510</tt><label id=".P4510"><p>
+
+ Enable the 4510 instruction set. This is a superset of the 65C02 and
+ 6502 instruction sets.
+
+ See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02"
+ name=".PSC02"></tt>, <tt><ref id=".PC02" name=".PC02"></tt> and
+ <tt><ref id=".P816" name=".P816"></tt>
<sect1><tt>.P816</tt><label id=".P816"><p>
6502 instruction sets.
See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02"
- name=".PSC02"></tt> and <tt><ref id=".PC02" name=".PC02"></tt>
+ name=".PSC02"></tt>, <tt><ref id=".PC02" name=".PC02"></tt> and
+ <tt><ref id=".P4510" name=".P4510"></tt>
<sect1><tt>.PAGELEN, .PAGELENGTH</tt><label id=".PAGELENGTH"><p>
6502 and 65SC02 instructions.
See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02"
- name=".PSC02"></tt> and <tt><ref id=".P816" name=".P816"></tt>
+ name=".PSC02"></tt>, <tt><ref id=".P816" name=".P816"></tt> and
+ <tt><ref id=".P4510" name=".P4510"></tt>
<sect1><tt>.POPCPU</tt><label id=".POPCPU"><p>
6502 instructions.
See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PC02"
- name=".PC02"></tt> and <tt><ref id=".P816" name=".P816"></tt>
+ name=".PC02"></tt>, <tt><ref id=".P816" name=".P816"></tt> and
+ <tt><ref id=".P4510" name=".P4510"></tt>
<sect1><tt>.PUSHCPU</tt><label id=".PUSHCPU"><p>
segment, that is, a named section of data. The default segment is
"CODE". There may be up to 254 different segments per object file
(and up to 65534 per executable). There are shortcut commands for
- the most common segments ("CODE", "DATA" and "BSS").
+ the most common segments ("ZEROPAGE", "CODE", "RODATA", "DATA", and "BSS").
The command is followed by a string containing the segment name (there are
some constraints for the name - as a rule of thumb use only those segment
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
</verb></tscreen>
See: <tt><ref id=".BSS" name=".BSS"></tt>, <tt><ref id=".CODE"
- name=".CODE"></tt>, <tt><ref id=".DATA" name=".DATA"></tt> and <tt><ref
- id=".RODATA" name=".RODATA"></tt>
+ name=".CODE"></tt>, <tt><ref id=".DATA" name=".DATA"></tt>, <tt><ref
+ id=".RODATA" name=".RODATA"></tt>, and <tt><ref id=".ZEROPAGE"
+ name=".ZEROPAGE"></tt>
<sect1><tt>.SET</tt><label id=".SET"><p>
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, 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".
+ namely: 6502, 6502X, 65SC02, 65C02, 65816, 4510 and HuC6280.
See: <tt><ref id=".CPU" name=".CPU"></tt>,
<tt><ref id=".IFP02" name=".IFP02"></tt>,
<tt><ref id=".IFPSC02" name=".IFPSC02"></tt>,
<tt><ref id=".P02" name=".P02"></tt>,
<tt><ref id=".P816" name=".P816"></tt>,
+ <tt><ref id=".P4510" name=".P4510"></tt>,
<tt><ref id=".PC02" name=".PC02"></tt>,
<tt><ref id=".PSC02" name=".PSC02"></tt>
<tt><ref id=".UNION" name=".UNION"></tt>
-<sect1><tt>.SUNPLUS</tt><label id=".SUNPLUS"><p>
-
- Enable the SunPlus instructions set. This command will not work in the
- freeware version of the assembler, because the instruction set is
- "proprietary and confidential".
-
- See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02"
- name=".PSC02"></tt>, <tt><ref id=".PC02" name=".PC02"></tt>, and
- <tt><ref id=".P816" name=".P816"></tt>
-
-
<sect1><tt>.TAG</tt><label id=".TAG"><p>
Allocate space for a struct or union.
shortcut for
<tscreen><verb>
- .segment "ZEROPAGE", zeropage
+ .segment "ZEROPAGE": zeropage
</verb></tscreen>
Because of the "zeropage" attribute, labels declared in this segment are
example:
<tscreen><verb>
- .macro asr ; Arithmetic shift right
- cmp #$80 ; Put bit 7 into carry
- ror ; Rotate right with carry
- .endmacro
+.macro asr ; Arithmetic shift right
+ cmp #$80 ; Put bit 7 into carry
+ ror ; Rotate right with carry
+.endmacro
</verb></tscreen>
The macro above consists of two real instructions, that are inserted into
by using the name, like this:
<tscreen><verb>
- lda $2010
- asr
- sta $2010
+ lda $2010
+ asr
+ sta $2010
</verb></tscreen>
When using macro parameters, macros can be even more useful:
<tscreen><verb>
- .macro inc16 addr
- clc
- lda addr
- adc #$01
- sta addr
- lda addr+1
- adc #$00
- sta addr+1
- .endmacro
+.macro inc16 addr
+ clc
+ lda addr
+ adc #<$0001
+ sta addr
+ lda addr+1
+ adc #>$0001
+ sta addr+1
+.endmacro
</verb></tscreen>
When calling the macro, you may give a parameter, and each occurrence of
parameter. So
<tscreen><verb>
- inc16 $1000
+ inc16 $1000
</verb></tscreen>
will be expanded to
<tscreen><verb>
- clc
- lda $1000
- adc #$01
- sta $1000
- lda $1000+1
- adc #$00
- sta $1000+1
+ clc
+ lda $1000
+ adc #<$0001
+ sta $1000
+ lda $1000+1
+ adc #>$0001
+ sta $1000+1
</verb></tscreen>
A macro may have more than one parameter, in this case, the parameters
Look at this example:
<tscreen><verb>
- .macro ldaxy a, x, y
- .ifnblank a
- lda #a
- .endif
- .ifnblank x
- ldx #x
- .endif
- .ifnblank y
- ldy #y
- .endif
- .endmacro
+.macro ldaxy a, x, y
+.ifnblank a
+ lda #a
+.endif
+.ifnblank x
+ ldx #x
+.endif
+.ifnblank y
+ ldy #y
+.endif
+.endmacro
</verb></tscreen>
-This macro may be called as follows:
+That macro may be called as follows:
<tscreen><verb>
- ldaxy 1, 2, 3 ; Load all three registers
+ ldaxy 1, 2, 3 ; Load all three registers
- ldaxy 1, , 3 ; Load only a and y
+ ldaxy 1, , 3 ; Load only a and y
- ldaxy , , 3 ; Load y only
+ ldaxy , , 3 ; Load y only
</verb></tscreen>
-There's another helper command for determining, which macro parameters are
-valid: <tt><ref id=".PARAMCOUNT" name=".PARAMCOUNT"></tt> This command is
-replaced by the parameter count given, <em/including/ intermediate empty macro
+There's another helper command for determining which macro parameters are
+valid: <tt><ref id=".PARAMCOUNT" name=".PARAMCOUNT"></tt>. That command is
+replaced by the parameter count given, <em/including/ explicitly empty
parameters:
<tscreen><verb>
- ldaxy 1 ; .PARAMCOUNT = 1
- ldaxy 1,,3 ; .PARAMCOUNT = 3
- ldaxy 1,2 ; .PARAMCOUNT = 2
- ldaxy 1, ; .PARAMCOUNT = 2
- ldaxy 1,2,3 ; .PARAMCOUNT = 3
+ ldaxy 1 ; .PARAMCOUNT = 1
+ ldaxy 1,,3 ; .PARAMCOUNT = 3
+ ldaxy 1,2 ; .PARAMCOUNT = 2
+ ldaxy 1, ; .PARAMCOUNT = 2
+ ldaxy 1,2,3 ; .PARAMCOUNT = 3
</verb></tscreen>
Macro parameters may optionally be enclosed into curly braces. This allows the
case of a macro parameter).
<tscreen><verb>
- .macro foo arg1, arg2
- ...
- .endmacro
+.macro foo arg1, arg2
+ ...
+.endmacro
- foo ($00,x) ; Two parameters passed
- foo {($00,x)} ; One parameter passed
+ foo ($00,x) ; Two parameters passed
+ foo {($00,x)} ; One parameter passed
</verb></tscreen>
In the first case, the macro is called with two parameters: '<tt/($00/'
-and 'x)'. The comma is not passed to the macro, since it is part of the
+and '<tt/x)/'. The comma is not passed to the macro, because it is part of the
calling sequence, not the parameters.
-In the second case, '($00,x)' is passed to the macro, this time
+In the second case, '<tt/($00,x)/' is passed to the macro; this time,
including the comma.
functions will allow you to do exactly this:
<tscreen><verb>
- .macro ldax arg
- .if (.match (.left (1, {arg}), #))
- ; immediate mode
- lda #<(.right (.tcount ({arg})-1, {arg}))
- ldx #>(.right (.tcount ({arg})-1, {arg}))
- .else
- ; assume absolute or zero page
- lda arg
- ldx 1+(arg)
- .endif
- .endmacro
+.macro ldax arg
+ .if (.match (.left (1, {arg}), #))
+ ; immediate mode
+ lda #<(.right (.tcount ({arg})-1, {arg}))
+ ldx #>(.right (.tcount ({arg})-1, {arg}))
+ .else
+ ; assume absolute or zero page
+ lda arg
+ ldx 1+(arg)
+ .endif
+.endmacro
</verb></tscreen>
Using the <tt/<ref id=".MATCH" name=".MATCH">/ function, the macro is able to
The macro can be used as
<tscreen><verb>
- foo: .word $5678
- ...
- ldax #$1234 ; X=$12, A=$34
- ...
- ldax foo ; X=$56, A=$78
+foo: .word $5678
+...
+ ldax #$1234 ; X=$12, A=$34
+...
+ ldax foo ; X=$56, A=$78
</verb></tscreen>
Macros may be used recursively:
<tscreen><verb>
- .macro push r1, r2, r3
- lda r1
- pha
- .if .paramcount > 1
- push r2, r3
- .endif
- .endmacro
+.macro push r1, r2, r3
+ lda r1
+ pha
+.ifnblank r2
+ push r2, r3
+.endif
+.endmacro
</verb></tscreen>
-There's also a special macro to help writing recursive macros: <tt><ref
-id=".EXITMACRO" name=".EXITMACRO"></tt> This command will stop macro expansion
-immediately:
+There's also a special macro command to help with writing recursive macros:
+<tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt>. That command will stop macro
+expansion immediately:
<tscreen><verb>
- .macro push r1, r2, r3, r4, r5, r6, r7
- .ifblank r1
- ; First parameter is empty
- .exitmacro
- .else
- lda r1
- pha
- .endif
- push r2, r3, r4, r5, r6, r7
- .endmacro
+.macro push r1, r2, r3, r4, r5, r6, r7
+.ifblank r1
+ ; First parameter is empty
+ .exitmacro
+.else
+ lda r1
+ pha
+.endif
+ push r2, r3, r4, r5, r6, r7
+.endmacro
</verb></tscreen>
-When expanding this macro, the expansion will push all given parameters
+When expanding that macro, the expansion will push all given parameters
until an empty one is encountered. The macro may be called like this:
<tscreen><verb>
- push $20, $21, $32 ; Push 3 ZP locations
- push $21 ; Push one ZP location
+ push $20, $21, $32 ; Push 3 ZP locations
+ push $21 ; Push one ZP location
</verb></tscreen>
Have a look at the inc16 macro above. Here is it again:
<tscreen><verb>
- .macro inc16 addr
- clc
- lda addr
- adc #$01
- sta addr
- lda addr+1
- adc #$00
- sta addr+1
- .endmacro
+.macro inc16 addr
+ clc
+ lda addr
+ adc #<$0001
+ sta addr
+ lda addr+1
+ adc #>$0001
+ sta addr+1
+.endmacro
</verb></tscreen>
If you have a closer look at the code, you will notice, that it could be
written more efficiently, like this:
<tscreen><verb>
- .macro inc16 addr
- inc addr
- bne Skip
- inc addr+1
- Skip:
- .endmacro
+.macro inc16 addr
+ inc addr
+ bne Skip
+ inc addr+1
+Skip:
+.endmacro
</verb></tscreen>
-But imagine what happens, if you use this macro twice? Since the label
-"Skip" has the same name both times, you get a "duplicate symbol" error.
-Without a way to circumvent this problem, macros are not as useful, as
-they could be. One solution is, to start a new lexical block inside the
-macro:
+But imagine what happens, if you use this macro twice? Since the label "Skip"
+has the same name both times, you get a "duplicate symbol" error. Without a
+way to circumvent this problem, macros are not as useful, as they could be.
+One possible solution is the command <tt><ref id=".LOCAL" name=".LOCAL"></tt>.
+It declares one or more symbols as local to the macro expansion. The names of
+local variables are replaced by a unique name in each separate macro
+expansion. So we can solve the problem above by using <tt/.LOCAL/:
<tscreen><verb>
- .macro inc16 addr
- .proc
- inc addr
- bne Skip
- inc addr+1
- Skip:
- .endproc
- .endmacro
+.macro inc16 addr
+ .local Skip ; Make Skip a local symbol
+ inc addr
+ bne Skip
+ inc addr+1
+Skip: ; Not visible outside
+.endmacro
</verb></tscreen>
-Now the label is local to the block and not visible outside. However,
-sometimes you want a label inside the macro to be visible outside. To make
-that possible, there's a new command that's only usable inside a macro
-definition: <tt><ref id=".LOCAL" name=".LOCAL"></tt>. <tt/.LOCAL/ declares one
-or more symbols as local to the macro expansion. The names of local variables
-are replaced by a unique name in each separate macro expansion. So we could
-also solve the problem above by using <tt/.LOCAL/:
+Another solution is of course to start a new lexical block inside the macro
+that hides any labels:
<tscreen><verb>
- .macro inc16 addr
- .local Skip ; Make Skip a local symbol
- clc
- lda addr
- adc #$01
- sta addr
- bcc Skip
- inc addr+1
- Skip: ; Not visible outside
- .endmacro
+.macro inc16 addr
+.proc
+ inc addr
+ bne Skip
+ inc addr+1
+Skip:
+.endproc
+.endmacro
</verb></tscreen>
be omitted.
<item> Since <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may not
- contain end-of-line tokens, there are things that cannot be done. They
+ contain end-of-line tokens, there are things that cannot be done. They
may not contain several processor instructions for example. So, while
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
following <tt/.DEFINE/:
<tscreen><verb>
- .define EQU =
+.define EQU =
- foo EQU $1234 ; This is accepted now
+foo EQU $1234 ; This is accepted now
</verb></tscreen>
You may use the directive to define string constants used elsewhere:
<tscreen><verb>
- ; Define the version number
- .define VERSION "12.3a"
+; Define the version number
+.define VERSION "12.3a"
- ; ... and use it
- .asciiz VERSION
+ ; ... and use it
+ .asciiz VERSION
</verb></tscreen>
Macros with parameters may also be useful:
<tscreen><verb>
- .define DEBUG(message) .out message
+.define DEBUG(message) .out message
- DEBUG "Assembling include file #3"
+ 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 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>
-(This 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>
<sect1>Deleting macros<p>
Macros can be deleted. This will not work if the macro that should be deleted
-is currently expanded as in the following non working example:
+is currently expanded as in the following non-working example:
<tscreen><verb>
- .macro notworking
- .delmacro notworking
- .endmacro
+.macro notworking
+ .delmacro notworking
+.endmacro
notworking ; Will not work
</verb></tscreen>
id=".UNDEFINE" name=".UNDEFINE"></tt> must be used. Example:
<tscreen><verb>
- .define value 1
- .macro mac
- .byte 2
- .endmacro
+.define value 1
+.macro mac
+ .byte 2
+.endmacro
- .byte value ; Emit one byte with value 1
- mac ; Emit another byte with value 2
+ .byte value ; Emit one byte with value 1
+ mac ; Emit another byte with value 2
- .undefine value
- .delmacro mac
+.undefine value
+.delmacro mac
- .byte value ; Error: Unknown identifier
- mac ; Error: Missing ":"
+ .byte value ; Error: Unknown identifier
+ mac ; Error: Missing ":"
</verb></tscreen>
A separate command for <tt>.DEFINE</tt> style macros was necessary, because
different commands increases flexibility.
+
<sect>Macro packages<label id="macropackages"><p>
Using the <tt><ref id=".MACPACK" name=".MACPACK"></tt> directive, predefined
<sect1><tt>.MACPACK generic</tt><p>
-This macro package defines macros that are useful in almost any program.
-Currently defined macros are:
+This macro package defines macroes that are useful in almost any program.
+Currently defined macroes are:
<tscreen><verb>
- .macro add Arg
+ .macro add Arg ; add without carry
clc
adc Arg
.endmacro
- .macro sub Arg
+ .macro sub Arg ; subtract without borrow
sec
sbc Arg
.endmacro
- .macro bge Arg
+ .macro bge Arg ; branch on greater-than or equal
bcs Arg
.endmacro
- .macro blt Arg
+ .macro blt Arg ; branch on less-than
bcc Arg
.endmacro
- .macro bgt Arg
+ .macro bgt Arg ; branch on greater-than
.local L
beq L
bcs Arg
L:
.endmacro
- .macro ble Arg
+ .macro ble Arg ; branch on less-than or equal
beq Arg
bcc Arg
.endmacro
+
+ .macro bnz Arg ; branch on not zero
+ bne Arg
+ .endmacro
+
+ .macro bze Arg ; branch on zero
+ beq Arg
+ .endmacro
</verb></tscreen>
+<sect1><tt>.MACPACK apple2</tt><p>
+
+This macro package defines a macro named <tt/scrcode/. It takes a string
+as argument and places this string into memory translated into screen codes.
+
+
<sect1><tt>.MACPACK atari</tt><p>
-The atari macro package will define a macro named <tt/scrcode/. It takes a
-string as argument and places this string into memory translated into screen
-codes.
+This macro package defines a macro named <tt/scrcode/. It takes a string
+as argument and places this string into memory translated into screen codes.
<sect1><tt>.MACPACK cbm</tt><p>
-The cbm macro package will define a macro named <tt/scrcode/. It takes a
-string as argument and places this string into memory translated into screen
-codes.
+This macro package defines a macro named <tt/scrcode/. It takes a string
+as argument and places this string into memory translated into screen codes.
<sect1><tt>.MACPACK cpu</tt><p>
CPU_65SC02
CPU_65C02
CPU_65816
- CPU_SUNPLUS
CPU_SWEET16
CPU_HUC6280
+ CPU_4510
</verb></tscreen>
is defined. These constants may be used to determine the exact type of the
CPU_ISET_65SC02
CPU_ISET_65C02
CPU_ISET_65816
- CPU_ISET_SUNPLUS
CPU_ISET_SWEET16
CPU_ISET_HUC6280
+ CPU_ISET_4510
</verb></tscreen>
The value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable may
CPUs (the latter two are upwards compatible to the 65SC02).
+<sect1><tt>.MACPACK module</tt><p>
+
+This macro package defines a macro named <tt/module_header/. It takes an
+identifier as argument and is used to define the header of a module both
+in the dynamic and static variant.
+
+
<sect>Predefined constants<label id="predefined-constants"><p>
compiler, depending on the target system selected:
<itemize>
-<item><tt/__APPLE2__/ - Target system is <tt/apple2/
+<item><tt/__APPLE2__/ - Target system is <tt/apple2/ or <tt/apple2enh/
<item><tt/__APPLE2ENH__/ - Target system is <tt/apple2enh/
-<item><tt/__ATARI__/ - Target system is <tt/atari/
+<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/
<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/__C16__/ - Target system is <tt/c16/ or <tt/plus4/
<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/__GEOS__/ - Target is a GEOS system
+<item><tt/__GEOS_APPLE__/ - Target system is <tt/geos-apple/
+<item><tt/__GEOS_CBM__/ - Target system is <tt/geos-cbm/
<item><tt/__LUNIX__/ - Target system is <tt/lunix/
+<item><tt/__LYNX__/ - Target system is <tt/lynx/
<item><tt/__NES__/ - Target system is <tt/nes/
+<item><tt/__OSIC1P__/ - Target system is <tt/osic1p/
<item><tt/__PET__/ - Target system is <tt/pet/
<item><tt/__PLUS4__/ - Target system is <tt/plus4/
+<item><tt/__SIM6502__/ - Target system is <tt/sim6502/
+<item><tt/__SIM65C02__/ - Target system is <tt/sim65c02/
<item><tt/__SUPERVISION__/ - Target system is <tt/supervision/
<item><tt/__VIC20__/ - Target system is <tt/vic20/
</itemize>
Using the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref
id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR"
-name=".INTERRUPTOR"></tt> keywords it it possible to export functions in a
+name=".INTERRUPTOR"></tt> keywords it is possible to export functions in a
special way. The linker is able to generate tables with all functions of a
specific type. Such a table will <em>only</em> include symbols from object
files that are linked into a specific executable. This may be used to add
</enum>
-<sect>Bugs/Feedback<p>
-
-If you have problems using the assembler, if you find any bugs, or if
-you're doing something interesting with the assembler, I would be glad to
-hear from you. Feel free to contact me by email
-(<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">).
-
-
-
<sect>Copyright<p>
ca65 (and all cc65 binutils) are (C) Copyright 1998-2003 Ullrich von
</article>
-
-
-
projects / cc65 / blobdiff