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
+ --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".
<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.
<tag><tt>-U, --auto-import</tt></tag>
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:
<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
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>
-
+<table>
+<tabular ca="llc">
+Op|Description|Precedence@<hline>
+ |Builtin string functions|0@
+ |Builtin pseudo variables|1@
+ |Builtin pseudo functions|1@
++|Unary plus|1@
+-|Unary minus|1@
+˜|Unary bitwise not|1@
+.BITNOT|Unary bitwise not|1@
+<|Low byte operator|1@
+>|High byte operator|1@
+^|Bank byte operator|1@
+*|Multiplication|2@
+/|Division|2@
+.MOD|Modulo operation|2@
+&|Bitwise and|2@
+.BITAND|Bitwise and|2@
+^|Bitwise xor|2@
+.BITXOR|Bitwise xor|2@
+<<|Shift left operator|2@
+.SHL|Shift left operator|2@
+>>|Shift right operato|r@
+.SHR|Shift right operator|2@
++|Binary plus|3@
+-|Binary minus|3@
+||Binary or|3@
+.BITOR|Binary or|3@
+=|Compare operation (equal)|4@
+<>|Compare operation (not equal)|4@
+<|Compare operation (less)|4@
+>|Compare operation (greater)|4@
+<=|Compare operation (less or equal)|4@
+>=|Compare operation (greater or equal)|4@
+&&|Boolean and|5@
+.AND|Boolean and|5@
+.XOR|Boolean xor|5@
+|||Boolean or|6@
+.OR|Boolean or|6@
+!|Boolean not|7@
+.NOT|Boolean not|7@
+</tabular>
+<caption>Available operators sorted by precedence
+</table>
To force a specific order of evaluation, braces may be used as usual.
-
<p>
<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>
+<sect1>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>
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.
<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=".INTERRUPTOR"></tt> commands are actually shortcuts for <tt/.CONDES/
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">.
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.
Example:
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>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:
<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.
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
<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
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
<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>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>