-<!doctype linuxdoc system>
+<!doctype linuxdoc system> <!-- -*- text-mode -*- -->
<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">
+<date>2014-04-24
<abstract>
ca65 is a powerful macro assembler for the 6502, 65C02 and 65816 CPUs. It is
-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, 65SC02, 65C02, 65816, sweet16, HuC6280
<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=".PC02" name=".PC02"></tt> command was given).
<item>all valid 65618 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).
</itemize>
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.
][ 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>
</verb></tscreen>
-<label id=".SET">
+<label id="variables">
<sect1>Numeric variables<p>
Within macros and other control structures (<tt><ref id=".REPEAT"
prefer the "cheap" local labels). Nevertheless, unnamed labels are
convenient in some situations, so it's your decision.
+<em/Note:/ <ref id="scopes" name="Scopes"> organize named symbols, not
+unnamed ones, so scopes don't have an effect on unnamed labels.
+
+
<sect1>Using macros to define labels and constants<p>
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"">).
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/.
<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
- a mapping table specified with the <tt><ref id="option-t" name="-t"></tt>
+ numbers. The first one is the index of the source character (range 1..255),
+ the second one is the mapping (range 0..255). The mapping applies to all
+ character and string constants when they generate output, and overrides a
+ mapping table specified with the <tt><ref id="option-t" name="-t"></tt>
command line switch.
Example:
and unions"">.
+<sect1><tt>.ENDUNION</tt><label id=".ENDUNION"><p>
+
+ Ends a union definition. See the <tt/<ref id=".UNION" name=".UNION">/
+ command and the separate section named <ref id="structs" name=""Structs
+ and unions"">.
+
+
<sect1><tt>.ENUM</tt><label id=".ENUM"><p>
Start an enumeration. This directive is very similar to the C <tt/enum/
<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>
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
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:
id=".RODATA" name=".RODATA"></tt>
+<sect1><tt>.SET</tt><label id=".SET"><p>
+
+ <tt/.SET/ is used to assign a value to a variable. See <ref id="variables"
+ name="Numeric variables"> for a full description.
+
+
<sect1><tt>.SETCPU</tt><label id=".SETCPU"><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 and HuC6280.
See: <tt><ref id=".CPU" name=".CPU"></tt>,
<tt><ref id=".IFP02" name=".IFP02"></tt>,
Starts a struct definition. Structs are covered in a separate section named
<ref id="structs" name=""Structs and unions"">.
- See: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></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>
+ See also: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></tt>,
+ <tt><ref id=".ENDUNION" name=".ENDUNION"></tt>,
+ <tt><ref id=".UNION" name=".UNION"></tt>
<sect1><tt>.TAG</tt><label id=".TAG"><p>
section <ref id="macros" name="Macros">.
+<sect1><tt>.UNION</tt><label id=".UNION"><p>
+
+ Starts a union definition. Unions are covered in a separate section named
+ <ref id="structs" name=""Structs and unions"">.
+
+ See also: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></tt>,
+ <tt><ref id=".ENDUNION" name=".ENDUNION"></tt>,
+ <tt><ref id=".STRUCT" name=".STRUCT"></tt>
+
+
<sect1><tt>.WARNING</tt><label id=".WARNING"><p>
Force an assembly warning. The assembler will output a warning message
.endmacro
</verb></tscreen>
- See also: <tt><ref id=".ERROR" name=".ERROR"></tt>
+ See also: <tt><ref id=".ERROR" name=".ERROR"></tt>,
<tt><ref id=".FATAL" name=".FATAL"></tt>,
<tt><ref id=".OUT" name=".OUT"></tt>
.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
+ .local Skip ; Make Skip a local symbol
+ inc addr
+ bne Skip
+ inc addr+1
+ Skip: ; Not visible outside
+ .endmacro
+</verb></tscreen>
+
+Another solution is of course to start a new lexical block inside the macro
+that hides any labels:
<tscreen><verb>
.macro inc16 addr
.proc
- inc addr
+ inc addr
bne Skip
inc addr+1
Skip:
.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/:
-
-<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
-</verb></tscreen>
-
<sect1>C style macros<p>
don't like that, use classic macros instead:
<tscreen><verb>
- .macro message
+ .macro DEBUG message
.out message
.endmacro
</verb></tscreen>
beq Arg
bcc Arg
.endmacro
+
+ .macro bnz Arg
+ bne Arg
+ .endmacro
+
+ .macro bze Arg
+ beq Arg
+ .endmacro
+
</verb></tscreen>
CPU_65SC02
CPU_65C02
CPU_65816
- CPU_SUNPLUS
CPU_SWEET16
CPU_HUC6280
</verb></tscreen>
CPU_ISET_65SC02
CPU_ISET_65C02
CPU_ISET_65816
- CPU_ISET_SUNPLUS
CPU_ISET_SWEET16
CPU_ISET_HUC6280
</verb></tscreen>
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/__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/__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>
</verb></tscreen>
A union shares the total space between all its members, its size is the same
-as that of the largest member.
+as that of the largest member. The offset of all members relative to the union
+is zero.
+
+<tscreen><verb>
+ .union Entry
+ index .word
+ ptr .addr
+ .endunion
+</verb></tscreen>
A struct or union must not necessarily have a name. If it is anonymous, no
local scope is opened, the identifiers used to name the members are placed
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
projects / cc65 / blobdiff