<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
Usage: ca65 [options] file
Short options:
-D name[=value] Define a symbol
- -I dir Set an include directory search path
- -U Mark unresolved symbols as import
- -V Print the assembler version
- -W n Set warning level n
- -g Add debug info to object file
- -h Help (this text)
- -i Ignore case of symbols
- -l Create a listing if assembly was ok
- -o name Name the output file
- -s Enable smart mode
- -t sys Set the target system
- -v Increase verbosity
+ -I dir Set an include directory search path
+ -U Mark unresolved symbols as import
+ -V Print the assembler version
+ -W n Set warning level n
+ -g Add debug info to object file
+ -h Help (this text)
+ -i Ignore case of symbols
+ -l Create a listing if assembly was ok
+ -mm model Set the memory model
+ -o name Name the output file
+ -s Enable smart mode
+ -t sys Set the target system
+ -v Increase verbosity
Long options:
--auto-import Mark unresolved symbols as import
- --cpu type Set cpu type
+ --cpu type Set cpu type
--debug-info Add debug info to object file
- --feature name Set an emulation feature
- --help Help (this text)
+ --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
- --list-bytes n Maximum number of bytes per listing line
- --listing Create a listing if assembly was ok
+ --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
- --target sys Set the target system
- --verbose Increase verbosity
- --version Print the assembler version
+ --smart Enable smart mode
+ --target sys Set the target system
+ --verbose Increase verbosity
+ --version Print the assembler version
---------------------------------------------------------------------------
</verb></tscreen>
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>
<tag><tt>-i, --ignore-case</tt></tag>
This option makes the assembler case insensitive on identifiers and labels.
- This option will override the default, but may itself be overriden by the
+ This option will override the default, but may itself be overridden by the
<tt><ref id=".CASE" name=".CASE"></tt> control command.
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
+ huge.
+
+
<tag><tt>-o name</tt></tag>
The default output name is the name of the input file with the extension
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 directores.
+ 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>
contain a label (which is identified by a colon), and, in addition to the
label, an assembler mnemonic, a macro, or a control command (see section <ref
id="control-commands" name="Control Commands"> for supported control
-commands). Alternatively, the line may contain a symbol definition using the
-'=' token. Everything after a semicolon is handled as a comment (that is, it
-is ignored).
+commands). Alternatively, the line may contain a symbol definition using
+the '=' token. Everything after a semicolon is handled as a comment (that is,
+it is ignored).
Here are some examples for valid input lines:
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>6502X mode<label id="6502X-mode"><p>
6502X mode is an extension to the normal 6502 mode. In this mode, several
-mnemomics for illegal instructions of the NMOS 6502 CPUs are accepted. Since
+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://oxyron.net/graham/opcodes02.html"
<sect1>Number format<p>
For literal values, the assembler accepts the widely used number formats: A
-preceeding '$' or a trailing 'h' denotes a hex value, a preceeding '%'
-denotes a binary value, and a bare number is interpeted as a decimal. There
+preceding '$' or a trailing 'h' denotes a hex value, a preceding '%'
+denotes a binary value, and a bare number is interpreted as a decimal. There
are currently no octal values and no floats.
In the context of a boolean expression, any non zero value is evaluated as
true, any other value to false. The result of a boolean expression is 1 if
-it's true, and zero if it's false. There are boolean operators with extrem
+it's true, and zero if it's false. There are boolean operators with extreme
low precedence with version 2.x (where x > 0). The <tt/.AND/ and <tt/.OR/
operators are shortcut operators. That is, if the result of the expression is
already known, after evaluating the left hand side, the right hand side is
<sect1>Available operators<label id="operators"><p>
-Available operators sorted by precedence:
-
-<tscreen><verb>
- Op Description Precedence
- -------------------------------------------------------------------
- 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 operator
- .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
-</verb></tscreen>
-
-
-To force a specific order of evaluation, braces may be used as usual.
-
-<p>
+<table>
+<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
+</table>
+
+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
<sect1>Unnamed labels<p>
-If you really want to write messy code, there are also unnamed
-labels. These labels do not have a name (you guessed that already,
-didn't you?). A colon is used to mark the absence of the name.
+If you really want to write messy code, there are also unnamed labels. These
+labels do not have a name (you guessed that already, didn't you?). A colon is
+used to mark the absence of the name.
-Unnamed labels may be accessed by using the colon plus several minus
-or plus characters as a label designator. Using the '-' characters
-will create a back reference (use the n'th label backwards), using
-'+' will create a forward reference (use the n'th label in forward
-direction). An example will help to understand this:
+Unnamed labels may be accessed by using the colon plus several minus or plus
+characters as a label designator. Using the '-' characters will create a back
+reference (use the n'th label backwards), using '+' will create a forward
+reference (use the n'th label in forward direction). An example will help to
+understand this:
<tscreen><verb>
: lda (ptr1),y ; #1
are in global scope.
-<sect1>
A special scope: cheap locals<p>
A special scope is the scope for cheap local symbols. It lasts from one non
local symbol to the next one, without any provisions made by the programmer.
error" is output.
Of course the most simple solution for the problem is to move the definition
-of <tt/foo/ in scope <tt/inner/ upwards, so it preceeds its use. There may be
+of <tt/foo/ in scope <tt/inner/ upwards, so it precedes its use. There may be
rare cases when this cannot be done. In these cases, you can use one of the
address size override operators:
without a name (using the <tt/<ref id=".SCOPE" name=".SCOPE">/ command).
A special syntax is used to specify the global scope: If a symbol or scope is
-preceeded by the namespace token, the global scope is searched:
+preceded by the namespace token, the global scope is searched:
<tscreen><verb>
bar = 3
However, one important thing to note when using explicit scope syntax is, that
a symbol may be accessed before it is defined, but a scope may <bf/not/ be
-used without a preceeding definition. This means that in the following
+used without a preceding definition. This means that in the following
example:
<tscreen><verb>
Builtin string function. The function allows to concatenate a list of string
constants separated by commas. The result is a string constant that is the
- concatentation of all arguments. This function is most useful in macros and
+ concatenation of all arguments. This function is most useful in macros and
when used together with the <tt/.STRING/ builtin function. The function may
be used in any case where a string constant is expected.
See: <tt><ref id=".LOWORD" name=".LOWORD"></tt>
+<sect1><tt>.IDENT</tt><label id=".IDENT"><p>
+
+ The function expects a string as its argument, and converts this argument
+ into an identifier. If the string starts with the current <tt/<ref
+ id=".LOCALCHAR" name=".LOCALCHAR">/, it will be converted into a cheap local
+ identifier, otherwise it will be converted into a normal identifier.
+
+ Example:
+
+ <tscreen><verb>
+ .macro makelabel arg1, arg2
+ .ident (.concat (arg1, arg2)):
+ .endmacro
+
+ makelabel "foo", "bar"
+
+ .word foobar ; Valid label
+ </verb></tscreen>
+
+
<sect1><tt>.LEFT</tt><label id=".LEFT"><p>
Builtin function. Extracts the left part of a given token list.
Example:
To check in a macro if the given argument has a '#' as first token
- (immidiate addressing mode), use something like this:
+ (immediate addressing mode), use something like this:
<tscreen><verb>
.macro ldax arg
...
.if (.match (.left (1, {arg}), #))
- ; ldax called with immidiate operand
+ ; ldax called with immediate operand
...
.endif
Example:
To check in a macro if the given argument has a '<tt/#/' as first token
- (immidiate addressing mode), use something like this:
+ (immediate addressing mode), use something like this:
<tscreen><verb>
.macro ldax arg
...
.if (.match (.mid (0, 1, {arg}), #))
- ; ldax called with immidiate operand
+ ; ldax called with immediate operand
...
.endif
Please note that a symbol or scope must exist, before it is used together with
<tt/.SIZEOF/ (this may get relaxed later, but will always be true for scopes).
A scope has preference over a symbol with the same name, so if the last part
- of a name represents both, a scope and a symbol, the scope is choosen over the
+ of a name represents both, a scope and a symbol, the scope is chosen over the
symbol.
After the following code:
</verb></tscreen>
+<sect1><tt>.SPRINTF</tt><label id=".SPRINTF"><p>
+
+ Builtin function. It expects a format string as first argument. The number
+ and type of the following arguments depend on the format string. The format
+ string is similar to the one of the C <tt/printf/ function. Missing things
+ are: Length modifiers, variable width.
+
+ The result of the function is a string.
+
+ Example:
+
+ <tscreen><verb>
+ num = 3
+
+ ; Generate an identifier:
+ .ident (.sprintf ("%s%03d", "label", num)):
+ </verb></tscreen>
+
+
<sect1><tt>.STRING</tt><label id=".STRING"><p>
Builtin function. The function accepts an argument in braces and converts
<sect1><tt>.STRLEN</tt><label id=".STRLEN"><p>
Builtin function. The function accepts a string argument in braces and
- eveluates to the length of the string.
+ evaluates to the length of the string.
Example:
Example:
- The <tt/ldax/ macro accepts the '#' token to denote immidiate addressing (as
+ The <tt/ldax/ macro accepts the '#' token to denote immediate addressing (as
with the normal 6502 instructions). To translate it into two separate 8 bit
load instructions, the '#' token has to get stripped from the argument:
<tscreen><verb>
.macro ldax arg
.if (.match (.mid (0, 1, {arg}), #))
- ; ldax called with immidiate operand
+ ; ldax called with immediate operand
lda #<(.right (.tcount ({arg})-1, {arg}))
ldx #>(.right (.tcount ({arg})-1, {arg}))
.else
Valid only in 65816 mode. Switch the accumulator to 16 bit.
Note: This command will not emit any code, it will tell the assembler to
- create 16 bit operands for immediate accumulator adressing mode.
+ create 16 bit operands for immediate accumulator addressing mode.
See also: <tt><ref id=".SMART" name=".SMART"></tt>
Valid only in 65816 mode. Switch the accumulator to 8 bit.
Note: This command will not emit any code, it will tell the assembler to
- create 8 bit operands for immediate accu adressing mode.
+ create 8 bit operands for immediate accu addressing mode.
See also: <tt><ref id=".SMART" name=".SMART"></tt>
<sect1><tt>.ASSERT</tt><label id=".ASSERT"><p>
Add an assertion. The command is followed by an expression, an action
- specifier and a message that is output in case the assertion fails. The
- action specifier may be one of <tt/warning/ or <tt/error/. The assertion
- is passed to the linker and will be evaluated when segment placement has
- been done.
+ specifier, and an optional message that is output in case the assertion
+ fails. If no message was given, the string "Assertion failed" is used. The
+ action specifier may be one of <tt/warning/ or <tt/error/. The assertion is
+ evaluated by the assembler if possible, and also passed to the linker in the
+ object file (if one is generated). The linker will then evaluate the
+ expression when segment placement has been done.
Example:
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
- suppressed.
+ an error message. In the latter case, generation of the output file is
+ suppressed in both the assembler and linker.
<sect1><tt>.AUTOIMPORT</tt><label id=".AUTOIMPORT"><p>
giving errors. When switched off (which is the default so this does not
make much sense), this does not happen and an error message is
displayed. The state of the autoimport flag is evaluated when the
- complete source was translated, before outputing actual code, so it is
+ complete source was translated, before outputting actual code, so it is
<em/not/ possible to switch this feature on or off for separate sections
of code. The last setting is used for all symbols.
.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>
<tt/.CONDES/ is followed by the type, which may be <tt/constructor/,
<tt/destructor/ or a numeric value between 0 and 6 (where 0 is the same as
- specifiying <tt/constructor/ and 1 is equal to specifying <tt/destructor/).
+ specifying <tt/constructor/ and 1 is equal to specifying <tt/destructor/).
The <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref
id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR"
- name=".INTERRUPTORCONSTRUCTOR"></tt>commands are actually shortcuts
- for <tt/.CONDES/ with a type of <tt/constructor/ resp. <tt/destructor/ or
- <tt/interruptor/.
+ name=".INTERRUPTOR"></tt> commands are actually shortcuts for <tt/.CONDES/
+ with a type of <tt/constructor/ resp. <tt/destructor/ or <tt/interruptor/.
After the type, an optional priority may be specified. Higher numeric values
mean higher priority. If no priority is given, the default priority of 7 is
See the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref
id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR"
- name=".INTERRUPTOR"></tt>commands and the separate section <ref id="condes"
+ name=".INTERRUPTOR"></tt> commands and the separate section <ref id="condes"
name="Module constructors/destructors"> explaining the feature in more
detail.
otherwise the enumeration members are placed in the enclosing scope.
In the enumeration body, symbols are declared. The first symbol has a value
- of zero, and each following symbol will get the value of the preceeding plus
- one. This behaviour may be overriden by an explicit assignment. Two symbols
+ of zero, and each following symbol will get the value of the preceding plus
+ one. This behaviour may be overridden by an explicit assignment. Two symbols
may have the same value.
Example:
<sect1><tt>.ERROR</tt><label id=".ERROR"><p>
Force an assembly error. The assembler will output an error message
- preceeded by "User error" and will <em/not/ produce an object file.
+ preceded by "User error" and will <em/not/ produce an object file.
This command may be used to check for initial conditions that must be
set before assembling a source file.
<sect1><tt>.EXITMAC, .EXITMACRO</tt><label id=".EXITMACRO"><p>
- Abort a macro expansion immidiately. This command is often useful in
+ Abort a macro expansion immediately. This command is often useful in
recursive macros. See separate section <ref id="macros" name="Macros">.
<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 symols.
+ 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
lda #'a
</verb></tscreen>
<bf/Note:/ This does not work in conjunction with <tt/.FEATURE
- loose_string_term/, since in this case the input would be ambigous.
+ 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>
source, are exported, all others are imported. Additional <tt><ref
id=".IMPORTZP" name=".IMPORTZP"></tt> or <tt><ref id=".EXPORTZP"
name=".EXPORTZP"></tt> commands for the same symbol are allowed. The symbols
- in the list are explicitly marked as zero page symols.
+ in the list are explicitly marked as zero page symbols.
Example:
.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>
<sect1><tt>.IF</tt><label id=".IF"><p>
- Conditional assembly: Evalute an expression and switch assembler output
+ Conditional assembly: Evaluate an expression and switch assembler output
on or off depending on the expression. The expression must be a constant
expression, that is, all operands must be defined.
</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
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>
<sect1><tt>.OUT</tt><label id=".OUT"><p>
Output a string to the console without producing an error. This command
- is similiar to <tt/.ERROR/, however, it does not force an assembler error
+ is similar to <tt/.ERROR/, however, it does not force an assembler error
that prevents the creation of an object file.
Example:
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>,
<sect1><tt>.SMART</tt><label id=".SMART"><p>
- Switch on or off smart mode. The command must be followed by a '+' or
- '-' character to switch the option on or off respectively. The default
- is off (that is, the assembler doesn't try to be smart), but this
- default may be changed by the -s switch on the command line.
+ Switch on or off smart mode. The command must be followed by a '+' or '-'
+ character to switch the option on or off respectively. The default is off
+ (that is, the assembler doesn't try to be smart), but this default may be
+ changed by the -s switch on the command line.
In smart mode the assembler will do the following:
<sect1><tt>.WARNING</tt><label id=".WARNING"><p>
Force an assembly warning. The assembler will output a warning message
- preceeded by "User warning". This warning will always be output, even if
+ preceded by "User warning". This warning will always be output, even if
other warnings are disabled with the <tt><ref id="option-W" name="-W0"></tt>
command line option.
.endmacro
</verb></tscreen>
-When calling the macro, you may give a parameter, and each occurence of
+When calling the macro, you may give a parameter, and each occurrence of
the name "addr" in the macro definition will be replaced by the given
parameter. So
are separated by commas. You are free to give less parameters than the
macro actually takes in the definition. You may also leave intermediate
parameters empty. Empty parameters are replaced by empty space (that is,
-they are removed when the macro is exanded). If you have a look at our
+they are removed when the macro is expanded). If you have a look at our
macro definition above, you will see, that replacing the "addr" parameter
by nothing will lead to wrong code in most lines. To help you, writing
macros with a variable parameter list, there are some control commands:
There's also a special macro to help writing recursive macros: <tt><ref
id=".EXITMACRO" name=".EXITMACRO"></tt> This command will stop macro expansion
-immidiately:
+immediately:
<tscreen><verb>
.macro push r1, r2, r3, r4, r5, r6, r7
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"
-name=".INTERRUPTOR"></tt>keywords it it possible to export functions in a
+name=".INTERRUPTOR"></tt> keywords it it 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
<item>
Constructors and destructors may have priorities. These priorities determine
-the order of the functions in the table. If your intialization or cleanup code
+the order of the functions in the table. If your initialization or cleanup code
does depend on other initialization or cleanup code, you have to choose the
priority for the functions accordingly.
<item>
Besides the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref
id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR"
-name=".INTERRUPTOR"></tt>statements, there is also a more generic command:
+name=".INTERRUPTOR"></tt> statements, there is also a more generic command:
<tt><ref id=".CONDES" name=".CONDES"></tt>. This allows to specify an
additional type. Predefined types are 0 (constructor), 1 (destructor) and 2
(interruptor). The linker generates a separate table for each type on request.
<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>
projects / cc65 / blobdiff