A Macro Crossassembler for the 6502/65C02/65816 CPUs
- (C) Copyright 1998-1999 Ullrich von Bassewitz
+ (C) Copyright 1998-2000 Ullrich von Bassewitz
(uz@musoftware.de)
this decision, but I've written several multipass assemblers, and it
started to get boring. A one pass assembler needs much more elaborated
data structures, and because of that it's much more fun:-)
- There is one drawback with this point: It is nearly impossible to
- generate a listing when reading the source file only once without
- storing the source file in memory. Consequently, the assembler is not
- able to produce a listing. This could be added by reading the source
- file a second time if a listing was requested, but I didn't see an
- urgent need for a listing, so this was not a disadvantage for me.
* Non-GPLed code that may be used in any project without restrictions or
fear of "GPL infecting" other code.
The assembler accepts the following options:
- -g Generate debug info
- -i Ignore case of symbols
- -l Create a listing if assembly was ok
- -o name Name the output file
- -s Enable smart mode
- -v Increase verbosity
- -D name[=value] Define a symbol
- -U Mark unresolved symbols as import
- -V Print the assembler version
- -W n Set warning level n
- --cpu type Set cpu type
- --pagelength n Set the page length for the listing
- --smart Enable smart mode
-
-When the -g option (or the equivalent control command .DEBUGINFO) is used,
-the assembler will add a section to the object file that contains all
-symbols (including local ones) together with the symbol values and source
-file positions. The linker will put these additional symbols into the
-VICE label file, so even local symbols can be seen in the VICE monitor.
-
-The option -i makes the assembler case insensitive on identifiers and
-labels. This option will override the default, but may itself be overriden
-by the .CASE control command (see section 6).
-
-The default output name is the name of the input file with the extension
-replaced by ".o". If you don't like that, you may give another name with
-the -o option. The output file will be placed in the same directory as the
-source file, or, if -o is given, the full path in this name is used.
-
-In smart mode (enabled by -s or the .SMART pseudo instruction) the
-assembler will track usage of the REP and SEP instructions in 65816 mode
-and update the operand sizes accordingly. If the operand of such an
-instruction cannot be evaluated by the assembler (for example, because the
-operand is an imported symbol), a warning is issued. Beware: Since the
-assembler cannot trace the execution flow this may lead to false results
-in some cases. If in doubt, use the .ixx and .axx instructions to tell the
-assembler about the current settings. Smart mode is off by default.
-
--v does increase the assembler verbosity and is usually only needed for
-debugging purposes. You may use this option more than one time for even
-more verbose output.
-
--D allows you to predefine symbols on the command line. Without a value,
-the symbol is defined with the value zero. When giving a value, you may
-use the '$' prefix for hexadecimal symbols. Please note that for some
-operating systems, '$' has a special meaning, so you may have to quote
-the expression.
-
--U marks symbols that are not defined in the sources as imported symbols.
-This should be used with care since it delays error messages about typos
-and such until the linker is run. The compiler uses the equivalent of
-this switch (.AUTOIMPORT, see control command section below) to enable
-auto imported symbols for the runtime library. However, the compiler is
-supposed to generate code that runs through the assembler without
-problems, something which is not always true for assembler programmers.
-
--V prints the version number of the assembler. If you send any suggestions
-or bugfixes, please include your version number.
-
--Wn sets the warning level for the assembler. Using -W2 the assembler will
-even warn about such things like unused imported symbols. The default
-warning level is 1, and it would probably be silly to set it to something
-lower.
-
---cpu sets the default for the CPU type. The option takes a parameter,
-which may be one of
-
- 6502, 65C02, 65816 and sunplus
-
-(the latter is not available in the freeware version).
-
---pagelength sets the length of a listing page in lines. See the
-.PAGELENGTH directive for more information.
-
---smart is identical to -s - see there.
+---------------------------------------------------------------------------
+Usage: ca65 [options] file
+Short options:
+ -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
+ -v Increase verbosity
+ -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
+
+Long options:
+ --auto-import Mark unresolved symbols as import
+ --cpu type Set cpu type
+ --debug-info Add debug info to object file
+ --help Help (this text)
+ --ignore-case Ignore case of symbols
+ --include-dir dir Set an include directory search path
+ --listing Create a listing if assembly was ok
+ --pagelength n Set the page length for the listing
+ --smart Enable smart mode
+ --verbose Increase verbosity
+ --version Print the assembler version
+---------------------------------------------------------------------------
+
+Here is a description of all the command line options:
+
+
+ --cpu type
+
+ Set the default for the CPU type. The option takes a parameter, which
+ may be one of
+
+ 6502, 65C02, 65816 and sunplus
+
+ (the latter is not available in the freeware version).
+
+
+ -g
+ --debug-info
+
+ When this option (or the equivalent control command .DEBUGINFO) is used,
+ the assembler will add a section to the object file that contains all
+ symbols (including local ones) together with the symbol values and
+ source file positions. The linker will put these additional symbols into
+ the VICE label file, so even local symbols can be seen in the VICE
+ monitor.
+
+
+ -h
+ --help
+
+ Print the short option summary shown above.
+
+
+ -i
+ --ignore-case
+
+ This option makes the assembler case insensitive on identifiers and
+ labels. This option will override the default, but may itself be
+ overriden by the .CASE control command (see section 6).
+
+
+ -l
+ --listing
+
+ Generate an assembler listing. The listing file will always have the
+ name of the main input file with the extension replaced by ".lst". This
+ may change in future versions.
+
+
+ -o name
+
+ The default output name is the name of the input file with the extension
+ replaced by ".o". If you don't like that, you may give another name with
+ the -o option. The output file will be placed in the same directory as
+ the source file, or, if -o is given, the full path in this name is used.
+
+
+ --pagelength n
+
+ sets the length of a listing page in lines. See the .PAGELENGTH
+ directive for more information.
+
+
+ -s
+ --smart-mode
+
+ In smart mode (enabled by -s or the .SMART pseudo instruction) the
+ assembler will track usage of the REP and SEP instructions in 65816 mode
+ and update the operand sizes accordingly. If the operand of such an
+ instruction cannot be evaluated by the assembler (for example, because
+ the operand is an imported symbol), a warning is issued.
+
+ Beware: Since the assembler cannot trace the execution flow this may
+ lead to false results in some cases. If in doubt, use the .ixx and .axx
+ instructions to tell the assembler about the current settings. Smart
+ mode is off by default.
+
+
+ -v
+ -verbose
+
+ Increase the assembler verbosity. Usually only needed for debugging
+ purposes. You may use this option more than one time for even more
+ verbose output.
+
+
+ -D
+
+ This option allows you to define symbols on the command line. Without a
+ value, the symbol is defined with the value zero. When giving a value,
+ you may use the '$' prefix for hexadecimal symbols. Please note that for
+ some operating systems, '$' has a special meaning, so you may have to
+ quote the expression.
+
+
+ -I dir
+ --include-dir dir
+
+ 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.
+
+
+ -U
+ --auto-import
+
+ Mark symbols that are not defined in the sources as imported symbols.
+ This should be used with care since it delays error messages about typos
+ and such until the linker is run. The compiler uses the equivalent of
+ this switch (.AUTOIMPORT, see control command section below) to enable
+ auto imported symbols for the runtime library. However, the compiler is
+ supposed to generate code that runs through the assembler without
+ problems, something which is not always true for assembler programmers.
+
+
+ -V
+ --version
+
+ Print the version number of the assembler. If you send any suggestions
+ or bugfixes, please include the version number.
+
+
+ -Wn
+
+ Set the warning level for the assembler. Using -W2 the assembler will
+ even warn about such things like unused imported symbols. The default
+ warning level is 1, and it would probably be silly to set it to
+ something lower.
.CONST Builtin function 1
.CPU Builtin pseudo variable (r/o) 1
.DEFINED Builtin function 1
+ .LEFT Builtin function 1
.MATCH Builtin function 1
+ .MID Builtin function 1
.XMATCH Builtin function 1
.PARAMCOUNT Builtin pseudo variable (r/o) 1
.REFERENCED Builtin function 1
+ .RIGHT Builtin function 1
.STRING Builtin function 1
:: Global namespace override 1
+ Unary plus 1
<< Shift left operator 2
.SHL Shift left operator 2
>> Shift right operator 2
- .SHR Shift right operator 2
+ .SHR Shift right operator 2
+ Binary plus 3
- Binary minus 3
.include "subs.inc"
+.LEFT
+
+ Builtin function. Extracts the left part of a given token list.
+
+ Syntax:
+
+ .LEFT (<int expr>, <token list>)
+
+ The first integer expression gives the number of tokens to extract from
+ the token list. The second argument is the token list itself.
+
+ Example:
+
+ To check in a macro if the given argument has a '#' as first token
+ (immidiate addressing mode), use something like this:
+
+ .macro ldax arg
+ ...
+ .if (.match (.left (1, arg), #))
+
+ ; ldax called with immidiate operand
+ ...
+
+ .endif
+ ...
+ .endmacro
+
+ See also the .MID and .RIGHT builtin functions.
+
+
.LINECONT
Switch on or off line continuations using the backslash character
be the reserved keyword "A".
+.MID
+
+ Builtin function. Takes a starting index, a count and a token list as
+ arguments. Will return part of the token list.
+
+ Syntax:
+
+ .MID (<int expr>, <int expr>, <token list>)
+
+ The first integer expression gives the starting token in the list (the
+ first token has index 0). The second integer expression gives the number
+ of tokens to extract from the token list. The third argument is the
+ token list itself.
+
+ Example:
+
+ To check in a macro if the given argument has a '#' as first token
+ (immidiate addressing mode), use something like this:
+
+ .macro ldax arg
+ ...
+ .if (.match (.mid (0, 1, arg), #))
+
+ ; ldax called with immidiate operand
+ ...
+
+ .endif
+ ...
+ .endmacro
+
+ See also the .LEFT and .RIGHT builtin functions.
+
+
.ORG
Start a section of absolute code. The command is followed by a constant
storage should be defined. The second, optional expression must by a
constant byte value that will be used as value of the data. If there
is no fill value given, the linker will use the value defined in the
- linker configuration file (default: zero).
+ linker configuration file (default: zero).
Example:
.res 12, $AA
+.RIGHT
+
+ Builtin function. Extracts the right part of a given token list.
+
+ Syntax:
+
+ .RIGHT (<int expr>, <token list>)
+
+ The first integer expression gives the number of tokens to extract from
+ the token list. The second argument is the token list itself.
+
+ See also the .LEFT and .MID builtin functions.
+
+
.RODATA
Switch to the RODATA segment. The name of the RODATA segment is always
.define DEBUG(message) .out message
DEBUG "Assembling include file #3"
-
+
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
10. Copyright
-------------
-ca65 (and all cc65 binutils) are (C) Copyright 1998 Ullrich von Bassewitz.
-For usage of the binaries and/or sources the following conditions do
-apply:
+ca65 (and all cc65 binutils) are (C) Copyright 1998-2000 Ullrich von
+Bassewitz. For usage of the binaries and/or sources the following
+conditions do apply:
This software is provided 'as-is', without any expressed or implied
warranty. In no event will the authors be held liable for any damages
projects / cc65 / commitdiff