--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
--pagelength n Set the page length for the listing
--smart Enable smart mode
Set the default for the CPU type. The option takes a parameter, which
may be one of
- 6502, 65SC02, 65C02, 65816 and sunplus
+ 6502, 65SC02, 65C02, 65816, sunplus, sweet16
- The last one (sunplus) is not available in the freeware version, because the
- instruction set of the sunplus CPU is "proprietary and confidential".
+ The sunplus cpu is not available in the freeware version, because the
+ instruction set is "proprietary and confidential".
<label id="option--feature">
may change in future versions.
+ <tag><tt>--list-bytes n</tt></tag>
+
+ Set the maximum number of bytes printed in the listing for one line of
+ input. See the <tt><ref id=".LISTBYTES" name=".LISTBYTES"></tt> directive
+ for more information. The value zero can be used to encode an unlimited
+ number of printed bytes.
+
+
<tag><tt>-o name</tt></tag>
The default output name is the name of the input file with the extension
<itemize>
<item>all valid 6502 mnemonics when in 6502 mode (the default or after the
<tt><ref id=".P02" name=".P02"></tt> command was given).
+<item>all valid 6502 mnemonics plus a set of illegal instructions when in
+ <ref id="6502X-mode" name="6502X mode">.
<item>all valid 65SC02 mnemonics when in 65SC02 mode (after the
<tt><ref id=".PSC02" name=".PSC02"></tt> command was given).
<item>all valid 65C02 mnemonics when in 65C02 mode (after the
TSA is an alias for TSC
</verb></tscreen>
-Evaluation of banked expressions in 65816 mode differs slightly from the
-official syntax:
-Instead of accepting a 24 bit address (something that is difficult for
-the assembler to determine and would have required one more special
-.import command), the bank and the absolute address in that bank are
-separated by a dot:
-<tscreen><verb>
- jsl 3.$1234 ; Call subroutine at $1234 in bank 3
-</verb></tscreen>
+<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
+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"
+name="http://oxyron.net/graham/opcodes02.html">. Please note that only the
+ones marked as "stable" are supported. The following table uses information
+from the mentioned web page, for more information, see there.
+
+<itemize>
+<item><tt>ALR: A:=(A and #{imm})*2;</tt>
+<item><tt>ANC: A:=A and #{imm};</tt> Generates opcode $0B.
+<item><tt>ARR: A:=(A and #{imm})/2;</tt>
+<item><tt>AXS: X:=A and X-#{imm};</tt>
+<item><tt>DCP: {adr}:={adr}-1; A-{adr};</tt>
+<item><tt>ISC: {adr}:={adr}+1; A:=A-{adr};</tt>
+<item><tt>LAS: A,X,S:={adr} and S;</tt>
+<item><tt>LAX: A,X:={adr};</tt>
+<item><tt>RLA: {adr}:={adr}rol; A:=A and {adr};</tt>
+<item><tt>RRA: {adr}:={adr}ror; A:=A adc {adr};</tt>
+<item><tt>SAX: {adr}:=A and X;</tt>
+<item><tt>SLO: {adr}:={adr}*2; A:=A or {adr};</tt>
+<item><tt>SRE: {adr}:={adr}/2; A:=A xor {adr};</tt>
+</itemize>
+
+
+
+<sect1>sweet16 mode<label id="sweet16-mode"><p>
+
+SWEET 16 is an interpreter for a pseudo 16 bit CPU written by Steve Wozniak
+for the Apple ][ machines. It is available in the Apple ][ ROM. ca65 can
+generate code for this pseudo CPU when switched into sweet16 mode. The
+following is special in sweet16 mode:
+
+<itemize>
+
+<item>The '@' character denotes indirect addressing and is no longer available
+for cheap local labels. If you need cheap local labels, you will have to
+switch to another lead character using the <tt/<ref id=".LOCALCHAR"
+name=".LOCALCHAR">/ command.
+
+<item>Registers are specified using <tt/R0/ .. <tt/R15/. In sweet16 mode,
+these identifiers are reserved words.
+
+</itemize>
+
+Please note that the assembler does neither supply the interpreter needed for
+SWEET 16 code, nor the zero page locations needed for the SWEET 16 registers,
+nor does it call the interpreter. All this must be done by your program. Apple
+][ 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">.
+
<sect1>Number format<p>
-For literal values, the assembler accepts the widely used number formats:
-A preceeding '$' denotes a hex value, a preceeding '%' denotes a
-binary value, and a bare number is interpeted as a decimal. There are
-currently no octal values and no floats.
+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
+are currently no octal values and no floats.
<sect1>Conditional assembly<p>
</verb></tscreen>
-<sect>Address sizes<label id="address-sizes"><p>
+<sect>Address sizes and memory models<label id="address-sizes"><p>
+
+<sect1>Address sizes<p>
+
+ca65 assigns each segment and each symbol an address size. This is true, even
+if the symbol is not used as an address. You may also think of a value range
+of the symbol instead of an address size.
+
+Possible address sizes are:
+
+<itemize>
+<item>Zeropage or direct (8 bits)
+<item>Absolute (16 bits)
+<item>Far (24 bits)
+<item>Long (32 bits)
+</itemize>
+
+Since the assembler uses default address sizes for the segments and symbols,
+it is usually not necessary to override the default behaviour. In cases, where
+it is necessary, the following keywords may be used to specify address sizes:
+
+<itemize>
+<item>DIRECT, ZEROPAGE or ZP for zeropage addressing (8 bits).
+<item>ABSOLUTE, ABS or NEAR for absolute addressing (16 bits).
+<item>FAR for far addressing (24 bits).
+<item>LONG or DWORD for long addressing (32 bits).
+</itemize>
+
+
+<sect1>Address sizes of segments<p>
+
+The assembler assigns an address size to each segment. Since the
+representation of a label within this segment is "segment start + offset",
+labels will inherit the address size of the segment they are declared in.
+
+The address size of a segment may be changed, by using an optional address
+size modifier. See the <tt/<ref id=".SEGMENT" name="segment directive">/ for
+an explanation on how this is done.
+
+
+<sect1>Address sizes of symbols<p>
+
+
+
+
+<sect1>Memory models<p>
+
+The default address size of a segment depends on the memory model used. Since
+labels inherit the address size from the segment they are declared in,
+changing the memory model is an easy way to change the address size of many
+symbols at once.
+
<sect1><tt>.BLANK</tt><label id=".BLANK"><p>
- Builtin function. The function evaluates its argument in braces and
- yields "false" if the argument is non blank (there is an argument), and
- "true" if there is no argument. As an example, the <tt/.IFBLANK/ statement
- may be replaced by
+ Builtin function. The function evaluates its argument in braces and yields
+ "false" if the argument is non blank (there is an argument), and "true" if
+ there is no argument. The token list that makes up the function argument
+ may optionally be enclosed in curly braces. This allows the inclusion of
+ tokens that would otherwise terminate the list (the closing right
+ parenthesis). The curly braces are not considered part of the list, a list
+ just consisting of curly braces is considered to be empty.
+
+ As an example, the <tt/.IFBLANK/ statement may be replaced by
<tscreen><verb>
- .if .blank(arg)
+ .if .blank({arg})
</verb></tscreen>
+
<sect1><tt>.CONCAT</tt><label id=".CONCAT"><p>
Builtin string function. The function allows to concatenate a list of string
</verb></tscreen>
The first integer expression gives the number of tokens to extract from
- the token list. The second argument is the token list itself.
+ the token list. The second argument is the token list itself. The token
+ list may optionally be enclosed into curly braces. This allows the
+ inclusion of tokens that would otherwise terminate the list (the closing
+ right paren in the given case).
Example:
<tscreen><verb>
.macro ldax arg
...
- .if (.match (.left (1, arg), #))
+ .if (.match (.left (1, {arg}), #))
; ldax called with immidiate operand
...
<item>end-of-file
</itemize>
- Often a macro parameter is used for any of the token lists.
+ The token lists may optionally be enclosed into curly braces. This allows
+ the inclusion of tokens that would otherwise terminate the list (the closing
+ right paren in the given case). Often a macro parameter is used for any of
+ the token lists.
Please note that the function does only compare tokens, not token
attributes. So any number is equal to any other number, regardless of the
<tscreen><verb>
.macro asr arg
- .if (.not .blank(arg)) .and (.not .match (arg, a))
+ .if (.not .blank(arg)) .and (.not .match ({arg}, a))
.error "Syntax error"
.endif
.MID (<int expr>, <int expr>, <token list>)
</verb></tscreen>
- 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.
+ 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.
+ The token list may optionally be enclosed into curly braces. This allows the
+ inclusion of tokens that would otherwise terminate the list (the closing
+ right paren in the given case).
Example:
<tscreen><verb>
.macro ldax arg
...
- .if (.match (.mid (0, 1, arg), #))
+ .if (.match (.mid (0, 1, {arg}), #))
; ldax called with immidiate operand
...
.RIGHT (<int expr>, <token list>)
</verb></tscreen>
- The first integer expression gives the number of tokens to extract from
- the token list. The second argument is the token list itself.
+ The first integer expression gives the number of tokens to extract from the
+ token list. The second argument is the token list itself. The token list
+ may optionally be enclosed into curly braces. This allows the inclusion of
+ tokens that would otherwise terminate the list (the closing right paren in
+ the given case).
See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".MID"
name=".MID"></tt> builtin functions.
<sect1><tt>.TCOUNT</tt><label id=".TCOUNT"><p>
- Builtin function. The function accepts a token list in braces. The
- function result is the number of tokens given as argument.
+ Builtin function. The function accepts a token list in braces. The function
+ result is the number of tokens given as argument. The token list may
+ optionally be enclosed into curly braces which are not considered part of
+ the list and not counted. Enclosement in curly braces allows the inclusion
+ of tokens that would otherwise terminate the list (the closing right paren
+ in the given case).
Example:
<tscreen><verb>
.macro ldax arg
- .if (.match (.mid (0, 1, arg), #))
+ .if (.match (.mid (0, 1, {arg}), #))
; ldax called with immidiate operand
- lda #<(.right (.tcount (arg)-1, arg))
- ldx #>(.right (.tcount (arg)-1, arg))
+ lda #<(.right (.tcount ({arg})-1, {arg}))
+ ldx #>(.right (.tcount ({arg})-1, {arg}))
.else
...
.endif
<item>end-of-file
</itemize>
- Often a macro parameter is used for any of the token lists.
+ The token lists may optionally be enclosed into curly braces. This allows
+ the inclusion of tokens that would otherwise terminate the list (the closing
+ right paren in the given case). Often a macro parameter is used for any of
+ the token lists.
The function compares tokens <em/and/ token values. If you need a function
that just compares the type of tokens, have a look at the <tt><ref
<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/).
- The <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> and <tt><ref
- id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> commands are actually shortcuts
- for <tt/.CONDES/ with a type of <tt/constructor/ resp. <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/.
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
.condes ModInit, 0, 16
</verb></tscreen>
- See the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> and <tt><ref
- id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> commands and the separate section
- <ref id="condes" name="Module constructors/destructors"> explaining the
- feature in more detail.
+ 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="Module constructors/destructors"> explaining the feature in more
+ detail.
<sect1><tt>.CONSTRUCTOR</tt><label id=".CONSTRUCTOR"><p>
<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.
+ 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.
Example:
<tscreen><verb>
- .export foo, bar
+ .export foo
+ .export bar: far
</verb></tscreen>
See: <tt><ref id=".EXPORTZP" name=".EXPORTZP"></tt>
<descrip>
+ <tag><tt>at_in_identifiers</tt></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>
+
+ Accept the dollar sign (`$') as a valid character in identifiers. The
+ at character is not allowed to start an identifier, even with this
+ feature enabled.
+
<tag><tt>dollar_is_pc</tt></tag>
The dollar sign may be used as an alias for the star (`*'), which
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>loose_string_term</tt></tag>
+ <tag><tt>leading_dot_in_identifiers</tt></tag>
- Accept single quotes as well as double quotes as terminators for string
- constants.
+ Accept the dot (`.') as the first character of an identifier. This may be
+ used for example to create macro names that start with a dot emulating
+ control directives of other assemblers. Note however, that none of the
+ reserved keywords built into the assembler, that starts with a dot, may be
+ overridden. When using this feature, you may also get into trouble if
+ later versions of the assembler define new keywords starting with a dot.
<tag><tt>loose_char_term</tt></tag>
Accept single quotes as well as double quotes as terminators for char
constants.
- <tag><tt>at_in_identifiers</tt></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>loose_string_term</tt></tag>
- Accept the dollar sign (`$') as a valid character in identifiers. The
- at character is not allowed to start an identifier, even with this
- feature enabled.
+ Accept single quotes as well as double quotes as terminators for string
+ constants.
- <tag><tt>leading_dot_in_identifiers</tt></tag>
+ <tag><tt>missing_char_term</tt></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
- control directives of other assemblers. Note however, that none of the
- reserved keywords built into the assembler, that starts with a dot, may be
- overridden. When using this feature, you may also get into trouble if
- later versions of the assembler define new keywords starting with a dot.
+ Accept single quoted character constants where the terminating quote is
+ missing.
+ <tscreen><verb>
+ 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.
<tag><tt>pc_assignment</tt></tag>
removing the lines with the assignments may also be an option when porting
code written for older assemblers).
+ <tag><tt>ubiquitous_idents</tt></tag>
+
+ Allow the use of instructions names as names for macros and symbols. This
+ makes it possible to "overload" instructions by defining a macro with the
+ same name. This does also make it possible to introduce hard to find errors
+ in your code, so be careful!
+
</descrip>
It is also possible to specify features on the command line using the
<sect1><tt>.IMPORT</tt><label id=".IMPORT"><p>
Import a symbol from another module. The command is followed by a comma
- separated list of symbols to import.
+ separated list of symbols to import, with each one optionally followed by
+ an address specification.
Example:
<tscreen><verb>
- .import foo, bar
+ .import foo
+ .import bar: zeropage
</verb></tscreen>
See: <tt><ref id=".IMPORTZP" name=".IMPORTZP"></tt>
In addition to that, a start offset and a size value may be specified,
separated by commas. If no size is specified, all of the file from the
start offset to end-of-file is used. If no start position is specified
- either, zero is assume (which means that the whole file is inserted).
+ either, zero is assumed (which means that the whole file is inserted).
Example:
</verb></tscreen>
+<sect1><tt>.INTERRUPTOR</tt><label id=".INTERRUPTOR"><p>
+
+ Export a symbol and mark it as an interruptor. This may be used together
+ with the linker to build a table of interruptor subroutines that are called
+ in an interrupt.
+
+ Note: The linker has a feature to build a table of marked routines, but it
+ is your code that must call these routines, so just declaring a symbol as
+ interruptor does nothing by itself.
+
+ An interruptor is always exported as an absolute (16 bit) symbol. You don't
+ need to use an additional <tt/.export/ statement, this is implied by
+ <tt/.interruptor/. It may have an optional priority that is separated by a
+ comma. Higher numeric values mean a higher priority. If no priority is
+ given, the default priority of 7 is used. Be careful when assigning
+ priorities to your own module constructors so they won't interfere with the
+ ones in the cc65 library.
+
+ Example:
+
+ <tscreen><verb>
+ .interruptor IrqHandler
+ .interruptor Handler, 16
+ </verb></tscreen>
+
+ See the <tt><ref id=".CONDES" name=".CONDES"></tt> command and the separate
+ section <ref id="condes" name="Module constructors/destructors"> explaining
+ the feature in more detail.
+
+
<sect1><tt>.LINECONT</tt><label id=".LINECONT"><p>
Switch on or off line continuations using the backslash character
<tscreen><verb>
.macro Crypt Arg
.repeat .strlen(Arg), I
- .byte .strat(Arg, I) .xor $55
+ .byte .strat(Arg, I) ^ $55
.endrep
.endmacro
</verb></tscreen>
(and up to 65534 per executable). There are shortcut commands for
the most common segments ("CODE", "DATA" and "BSS").
- The command is followed by a string containing the segment name (there
- are some constraints for the name - as a rule of thumb use only those
- segment names that would also be valid identifiers). There may also be
- an optional attribute separated by a comma. Valid attributes are
- "<tt/zeropage/" and "<tt/absolute/".
+ The command is followed by a string containing the segment name (there are
+ some constraints for the name - as a rule of thumb use only those segment
+ names that would also be valid identifiers). There may also be an optional
+ address size separated by a colon. See the section covering <tt/<ref
+ id="address-sizes" name="address sizes">/ for more information.
- When specifying a segment for the first time, "absolute" is the
- default. For all other uses, the attribute specified the first time
- is the default.
+ The default address size for a segment depends on the memory model specified
+ on the command line. The default is "absolute", which means that you don't
+ have to use an address size modifier in most cases.
- "absolute" means that this is a segment with absolute addressing. That
- is, the segment will reside somewhere in core memory outside the zero
- page. "zeropage" means the opposite: The segment will be placed in the
- zero page and direct (short) addressing is possible for data in this
- segment.
+ "absolute" means that the is a segment with 16 bit (absolute) addressing.
+ That is, the segment will reside somewhere in core memory outside the zero
+ page. "zeropage" (8 bit) means that the segment will be placed in the zero
+ page and direct (short) addressing is possible for data in this segment.
Beware: Only labels in a segment with the zeropage attribute are marked
as reachable by short addressing. The `*' (PC counter) operator will
work as in other segments and will create absolute variable values.
- Example:
+ Please note that a segment cannot have two different address sizes. A
+ segment specified as zeropage cannot be declared as being absolute later.
+
+ Examples:
<tscreen><verb>
.segment "ROM2" ; Switch to ROM2 segment
- .segment "ZP2", zeropage ; New direct segment
- .segment "ZP2" ; Ok, will use last attribute
- .segment "ZP2", absolute ; Error, redecl mismatch
+ .segment "ZP2": zeropage ; New direct segment
+ .segment "ZP2" ; Ok, will use last attribute
+ .segment "ZP2": absolute ; Error, redecl mismatch
</verb></tscreen>
See: <tt><ref id=".BSS" name=".BSS"></tt>, <tt><ref id=".CODE"
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, 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 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".
See: <tt><ref id=".CPU" name=".CPU"></tt>,
<tt><ref id=".IFP02" name=".IFP02"></tt>,
ldaxy 1,2,3 ; .PARAMCOUNT = 3
</verb></tscreen>
+Macro parameters may optionally be enclosed into curly braces. This allows the
+inclusion of tokens that would otherwise terminate the parameter (the comma in
+case of a macro parameter).
+
+<tscreen><verb>
+ .macro foo arg1, arg2
+ ...
+ .endmacro
+
+ foo ($00,x) ; Two parameters passed
+ foo {($00,x)} ; One parameter passed
+</verb></tscreen>
+
+In the first case, the macro is called with two parameters: '<tt/($00/'
+and 'x)'. The comma is not passed to the macro, since it is part of the
+calling sequence, not the parameters.
+
+In the second case, '($00,x)' is passed to the macro, this time
+including the comma.
+
<sect1>Detecting parameter types<p>
<tscreen><verb>
.macro ldax arg
- .if (.match (.left (1, arg), #))
+ .if (.match (.left (1, {arg}), #))
; immediate mode
- lda #<(.right (.tcount (arg)-1, arg))
- ldx #>(.right (.tcount (arg)-1, arg))
+ lda #<(.right (.tcount ({arg})-1, {arg}))
+ ldx #>(.right (.tcount ({arg})-1, {arg}))
.else
; assume absolute or zero page
lda arg
Using the <tt/<ref id=".MATCH" name=".MATCH">/ function, the macro is able to
check if its argument begins with a hash mark. If so, two immediate loads are
emitted, Otherwise a load from an absolute zero page memory location is
-assumed. So this macro can be used as
+assumed. Please note how the curly braces are used to enclose parameters to
+pseudo functions handling token lists. This is necessary, because the token
+lists may include commas or parens, which would be treated by the assembler
+as end-of-list.
+
+The macro can be used as
<tscreen><verb>
foo: .word $5678
CPU_65C02
CPU_65816
CPU_SUNPLUS
+ CPU_SWEET16
</verb></tscreen>
is defined. These constants may be used to determine the exact type of the
CPU_ISET_65C02
CPU_ISET_65816
CPU_ISET_SUNPLUS
+ CPU_ISET_SWEET16
</verb></tscreen>
The value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable may
+<sect>Predefined constants<label id="predefined-constants"><p>
+
+For better orthogonality, the assembler defines similar symbols as the
+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/__ATARI__/ - Target system is <tt/atari/
+<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/__PET__/ - Target system is <tt/pet/
+<item><tt/__PLUS4__/ - Target system is <tt/plus4/
+<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>
Structs and unions are special forms of <ref id="scopes" name="scopes">. They
useful for assembler programs.
-<sect1>Module overview<p>
+<sect1>Overview<p>
-Using the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> and <tt><ref
-id=".DESTRUCTOR" name=".DESTRUCTOR"></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 initialization and cleanup code for library modules.
+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
+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
+initialization and cleanup code for library modules, or a table of interrupt
+handler functions.
The C heap functions are an example where module initialization code is used.
All heap functions (<tt>malloc</tt>, <tt>free</tt>, ...) work with a few
<sect1>Calling order<p>
-Both, constructors and destructors are sorted in increasing priority order by
-the linker when using one of the builtin linker configurations, so the
-functions with lower priorities come first and are followed by those with
-higher priorities. The C library runtime subroutine that walks over the
-constructor and destructor tables calls the functions starting from the top of
-the table - which means that functions with a high priority are called first.
+The symbols are sorted in increasing priority order by the linker when using
+one of the builtin linker configurations, so the functions with lower
+priorities come first and are followed by those with higher priorities. The C
+library runtime subroutine that walks over the function tables calls the
+functions starting from the top of the table - which means that functions with
+a high priority are called first.
-So when using the C runtime, both constructors and destructors are called with
-high priority functions first, followed by low priority functions.
+So when using the C runtime, functions are called with high priority functions
+first, followed by low priority functions.
<sect1>Pitfalls<p>
-When creating and using module constructors and destructors, please take care
-of the following:
+When using these special symbols, please take care of the following:
<itemize>
The linker will only generate function tables, it will not generate code to
call these functions. If you're using the feature in some other than the
existing C environments, you have to write code to call all functions in a
-linker generated table yourself. See the <tt>condes</tt> module in the C
-runtime for an example on how to do this.
+linker generated table yourself. See the <tt/condes/ and <tt/callirq/ modules
+in the C runtime for an example on how to do this.
<item>
The linker will only add addresses of functions that are in modules linked to
the executable. This means that you have to be careful where to place the
-condes functions. If initialization is needed for a group of functions, be
-sure to place the initialization function into a module that is linked in
+condes functions. If initialization or an irq handler is needed for a group of
+functions, be sure to place the function into a module that is linked in
regardless of which function is called by the user.
<item>
priority for the functions accordingly.
<item>
-Besides the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> and <tt><ref
-id=".DESTRUCTOR" name=".DESTRUCTOR"></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) and 1
-(destructor). The linker generates a separate table for each type on request.
+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:
+<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.
</itemize>