Moved additional zeropage variables into an extra module.

[cc65] / doc / ca65.sgml

diff --git a/doc/ca65.sgml b/doc/ca65.sgml
index 72679f3233689441cd43eacfbf4d3480e0105098..444f9e34189b3efe2c7df66f717871ada2b55d4e 100644 (file)
--- a/doc/ca65.sgml
+++ b/doc/ca65.sgml
@@ -109,6 +109,7 @@ Long options:
   --help               Help (this text)
   --ignore-case                Ignore case of symbols
   --include-dir dir    Set an include directory search path
   --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
   --listing            Create a listing if assembly was ok
   --pagelength n       Set the page length for the listing
   --smart              Enable smart mode


@@ -131,10 +132,10 @@ Here is a description of all the command line options:
   Set the default for the CPU type. The option takes a parameter, which
   may be one of
 
   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">
 
 
   <label id="option--feature">


@@ -179,6 +180,14 @@ Here is a description of all the command line options:
   may change in future versions.
 
 
   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
   <tag><tt>-o name</tt></tag>
 
   The default output name is the name of the input file with the extension


@@ -300,6 +309,8 @@ The assembler accepts
 <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).
 <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
 <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


@@ -329,24 +340,72 @@ mnemonics:
        TSA is an alias for TSC
 </verb></tscreen>
 
        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 &dollar;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>
 
 
 <sect1>Number format<p>
 

-For literal values, the assembler accepts the widely used number formats:
-A preceeding '&dollar;' 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 '&dollar;' 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>
 
 
 <sect1>Conditional assembly<p>


@@ -909,7 +968,58 @@ if you want to access the "other" symbol <tt/bar/, you would have to write:
 </verb></tscreen>
 
 
 </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.
+

 
 
 
 
 
 


@@ -1024,16 +1134,22 @@ either a string or an expression.
 
 <sect1><tt>.BLANK</tt><label id=".BLANK"><p>
 
 
 <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>
 
   <tscreen><verb>

-       .if     .blank(arg)
+       .if     .blank({arg})

   </verb></tscreen>
 
 
   </verb></tscreen>
 
 

+

 <sect1><tt>.CONCAT</tt><label id=".CONCAT"><p>
 
   Builtin string function. The function allows to concatenate a list of string
 <sect1><tt>.CONCAT</tt><label id=".CONCAT"><p>
 
   Builtin string function. The function allows to concatenate a list of string


@@ -1094,7 +1210,10 @@ either a string or an expression.
   </verb></tscreen>
 
   The first integer expression gives the number of tokens to extract from
   </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:
 
 
   Example:
 


@@ -1104,7 +1223,7 @@ either a string or an expression.
   <tscreen><verb>
        .macro  ldax    arg
                ...
   <tscreen><verb>
        .macro  ldax    arg
                ...

-               .if (.match (.left (1, arg), #))
+               .if (.match (.left (1, {arg}), #))

 
                ; ldax called with immidiate operand
                ...
 
                ; ldax called with immidiate operand
                ...


@@ -1154,7 +1273,10 @@ either a string or an expression.
   <item>end-of-file
   </itemize>
 
   <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
 
   Please note that the function does only compare tokens, not token
   attributes. So any number is equal to any other number, regardless of the


@@ -1173,7 +1295,7 @@ either a string or an expression.
   <tscreen><verb>
        .macro  asr     arg
 
   <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
 
                .error "Syntax error"
                .endif
 


@@ -1200,10 +1322,12 @@ either a string or an expression.
                .MID (&lt;int expr&gt;, &lt;int expr&gt;, &lt;token list&gt;)
   </verb></tscreen>
 
                .MID (&lt;int expr&gt;, &lt;int expr&gt;, &lt;token list&gt;)
   </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:
 
 
   Example:
 


@@ -1213,7 +1337,7 @@ either a string or an expression.
     <tscreen><verb>
        .macro  ldax    arg
                ...
     <tscreen><verb>
        .macro  ldax    arg
                ...

-               .if (.match (.mid (0, 1, arg), #))
+               .if (.match (.mid (0, 1, {arg}), #))

 
                ; ldax called with immidiate operand
                ...
 
                ; ldax called with immidiate operand
                ...


@@ -1252,8 +1376,11 @@ either a string or an expression.
                .RIGHT (&lt;int expr&gt;, &lt;token list&gt;)
   </verb></tscreen>
 
                .RIGHT (&lt;int expr&gt;, &lt;token list&gt;)
   </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.
 
   See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".MID"
   name=".MID"></tt> builtin functions.


@@ -1389,8 +1516,12 @@ either a string or an expression.
 
 <sect1><tt>.TCOUNT</tt><label id=".TCOUNT"><p>
 
 
 <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:
 
 
   Example:
 


@@ -1400,10 +1531,10 @@ either a string or an expression.
 
   <tscreen><verb>
        .macro  ldax    arg
 
   <tscreen><verb>
        .macro  ldax    arg

-               .if (.match (.mid (0, 1, arg), #))
+               .if (.match (.mid (0, 1, {arg}), #))

                ; ldax called with immidiate operand
                ; 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
                .else
                ...
                .endif


@@ -1431,7 +1562,10 @@ either a string or an expression.
   <item>end-of-file
   </itemize>
 
   <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
 
   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


@@ -1650,9 +1784,11 @@ Here's a list of all control commands and a description, what they do:
   <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/).
   <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
 
   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


@@ -1666,10 +1802,11 @@ Here's a list of all control commands and a description, what they do:
        .condes         ModInit, 0, 16
   </verb></tscreen>
 
        .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>.CONSTRUCTOR</tt><label id=".CONSTRUCTOR"><p>


@@ -2025,27 +2162,6 @@ Here's a list of all control commands and a description, what they do:
 
   <descrip>
 
 
   <descrip>
 

-  <tag><tt>dollar_is_pc</tt></tag>
-
-    The dollar sign may be used as an alias for the star (`*'), which
-    gives the value of the current PC in expressions.
-    Note: Assignment to the pseudo variable is not allowed.
-
-  <tag><tt>labels_without_colons</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>loose_string_term</tt></tag>
-
-    Accept single quotes as well as double quotes as terminators for string
-    constants.
-
-  <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
   <tag><tt>at_in_identifiers</tt></tag>
 
     Accept the at character (`@') as a valid character in identifiers. The


@@ -2058,6 +2174,17 @@ Here's a list of all control commands and a description, what they do:
     at character is not allowed to start an identifier, even with this
     feature enabled.
 
     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
+    gives the value of the current PC in expressions.
+    Note: Assignment to the pseudo variable is not allowed.
+
+  <tag><tt>labels_without_colons</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>
 
     Accept the dot (`.') as the first character of an identifier. This may be
   <tag><tt>leading_dot_in_identifiers</tt></tag>
 
     Accept the dot (`.') as the first character of an identifier. This may be


@@ -2067,13 +2194,15 @@ Here's a list of all control commands and a description, what they do:
     overridden. When using this feature, you may also get into trouble if
     later versions of the assembler define new keywords starting with a dot.
 
     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>pc_assignment</tt></tag>
+  <tag><tt>loose_char_term</tt></tag>

 
 

-    Allow assignments to the PC symbol (`*' or `&dollar;' if <tt/dollar_is_pc/
-    is enabled). Such an assignment is handled identical to the <tt><ref
-    id=".ORG" name=".ORG"></tt> command (which is usually not needed, so just
-    removing the lines with the assignments may also be an option when porting
-    code written for older assemblers).
+    Accept single quotes as well as double quotes as terminators for char
+    constants.
+
+  <tag><tt>loose_string_term</tt></tag>
+
+    Accept single quotes as well as double quotes as terminators for string
+    constants.

 
   <tag><tt>missing_char_term</tt></tag>
 
 
   <tag><tt>missing_char_term</tt></tag>
 


@@ -2085,6 +2214,21 @@ Here's a list of all control commands and a description, what they do:
     <bf/Note:/ This does not work in conjunction with <tt/.FEATURE
     loose_string_term/, since in this case the input would be ambigous.
 
     <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>
+
+    Allow assignments to the PC symbol (`*' or `&dollar;' if <tt/dollar_is_pc/
+    is enabled). Such an assignment is handled identical to the <tt><ref
+    id=".ORG" name=".ORG"></tt> command (which is usually not needed, so just
+    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
   </descrip>
 
   It is also possible to specify features on the command line using the


@@ -2392,7 +2536,7 @@ Here's a list of all control commands and a description, what they do:
   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
   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:
 
 
   Example:
 


@@ -2419,6 +2563,36 @@ Here's a list of all control commands and a description, what they do:
   </verb></tscreen>
 
 
   </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
 <sect1><tt>.LINECONT</tt><label id=".LINECONT"><p>
 
   Switch on or off line continuations using the backslash character


@@ -2736,7 +2910,7 @@ Here's a list of all control commands and a description, what they do:
   <tscreen><verb>
        .macro  Crypt   Arg
                .repeat .strlen(Arg), I
   <tscreen><verb>
        .macro  Crypt   Arg
                .repeat .strlen(Arg), I

-               .byte   .strat(Arg, I) .xor $55
+               .byte   .strat(Arg, I) ^ $55

                .endrep
        .endmacro
   </verb></tscreen>
                .endrep
        .endmacro
   </verb></tscreen>


@@ -2823,33 +2997,35 @@ Here's a list of all control commands and a description, what they do:
   (and up to 65534 per executable). There are shortcut commands for
   the most common segments ("CODE", "DATA" and "BSS").
 
   (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.
 
 
   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
 
   <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"
   </verb></tscreen>
 
   See: <tt><ref id=".BSS" name=".BSS"></tt>, <tt><ref id=".CODE"


@@ -2862,9 +3038,10 @@ Here's a list of all control commands and a description, what they do:
   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,
   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>,
 
   See: <tt><ref id=".CPU" name=".CPU"></tt>,
        <tt><ref id=".IFP02" name=".IFP02"></tt>,


@@ -3134,6 +3311,26 @@ parameters:
        ldaxy   1,2,3           ; .PARAMCOUNT = 3
 </verb></tscreen>
 
        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/(&dollar;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, '(&dollar;00,x)' is passed to the macro, this time
+including the comma.
+

 
 <sect1>Detecting parameter types<p>
 
 
 <sect1>Detecting parameter types<p>
 


@@ -3145,10 +3342,10 @@ functions will allow you to do exactly this:
 
 <tscreen><verb>
         .macro  ldax    arg
 
 <tscreen><verb>
         .macro  ldax    arg

-                .if (.match (.left (1, arg), #))
+                .if (.match (.left (1, {arg}), #))

                     ; immediate mode
                     ; 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
                 .else
                     ; assume absolute or zero page
                     lda     arg


@@ -3160,7 +3357,12 @@ functions will allow you to do exactly this:
 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
 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
 
 <tscreen><verb>
         foo:    .word   $5678


@@ -3455,6 +3657,7 @@ each supported CPU a constant similar to
     CPU_65C02
     CPU_65816
     CPU_SUNPLUS
     CPU_65C02
     CPU_65816
     CPU_SUNPLUS

+    CPU_SWEET16

 </verb></tscreen>
 
 is defined. These constants may be used to determine the exact type of the
 </verb></tscreen>
 
 is defined. These constants may be used to determine the exact type of the


@@ -3467,6 +3670,7 @@ another constant is defined:
     CPU_ISET_65C02
     CPU_ISET_65816
     CPU_ISET_SUNPLUS
     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
 </verb></tscreen>
 
 The value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable may


@@ -3496,6 +3700,34 @@ CPUs (the latter two are upwards compatible to the 65SC02).
 
 
 
 
 
 

+<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
 <sect>Structs and unions<label id="structs"><p>
 
 Structs and unions are special forms of <ref id="scopes" name="scopes">.  They


@@ -3573,14 +3805,16 @@ below uses examples from the C libraries. However, the feature may also be
 useful for assembler programs.
 
 
 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
 
 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


@@ -3621,21 +3855,20 @@ two bytes in the table (a pointer to the function).
 
 <sect1>Calling order<p>
 
 
 <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>
 
 
 
 <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>
 
 
 <itemize>
 


@@ -3643,14 +3876,14 @@ of the following:
 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
 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
 
 <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>
 regardless of which function is called by the user.
 
 <item>


@@ -3665,11 +3898,12 @@ does depend on other initialization or cleanup code, you have to choose the
 priority for the functions accordingly.
 
 <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>
 
 
 </itemize>