X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fca65.sgml;h=444f9e34189b3efe2c7df66f717871ada2b55d4e;hb=84be7444189a9a274d5cc3927cf7a2b08165ede2;hp=72679f3233689441cd43eacfbf4d3480e0105098;hpb=5c63b08d26cf167bfe8ef1a52f6e6f1dd0746a83;p=cc65

diff --git a/doc/ca65.sgml b/doc/ca65.sgml
index 72679f323..444f9e341 100644
--- 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
+  --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
@@ -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
 
-       	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">
@@ -179,6 +180,14 @@ Here is a description of all the command line options:
   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
@@ -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).
+<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
@@ -329,24 +340,72 @@ mnemonics:
   	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>
 
-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>
@@ -909,7 +968,58 @@ if you want to access the "other" symbol <tt/bar/, you would have to write:
 </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>
 
-  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
@@ -1094,7 +1210,10 @@ either a string or an expression.
   </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:
 
@@ -1104,7 +1223,7 @@ either a string or an expression.
   <tscreen><verb>
     	.macro 	ldax	arg
     	       	...
-    	       	.if (.match (.left (1, arg), #))
+    	       	.if (.match (.left (1, {arg}), #))
 
     	       	; ldax called with immidiate operand
     	       	...
@@ -1154,7 +1273,10 @@ either a string or an expression.
   <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
@@ -1173,7 +1295,7 @@ either a string or an expression.
   <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
 
@@ -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>
 
-  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:
 
@@ -1213,7 +1337,7 @@ either a string or an expression.
     <tscreen><verb>
   	.macro	ldax	arg
     		...
-    		.if (.match (.mid (0, 1, arg), #))
+    		.if (.match (.mid (0, 1, {arg}), #))
 
     		; 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>
 
-  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.
@@ -1389,8 +1516,12 @@ either a string or an expression.
 
 <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:
 
@@ -1400,10 +1531,10 @@ either a string or an expression.
 
   <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
@@ -1431,7 +1562,10 @@ either a string or an expression.
   <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
@@ -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/).
-  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
@@ -1666,10 +1802,11 @@ Here's a list of all control commands and a description, what they do:
 	.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>
@@ -2025,27 +2162,6 @@ Here's a list of all control commands and a description, what they do:
 
   <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
@@ -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.
 
+  <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
@@ -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.
 
-  <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>
 
@@ -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.
 
+  <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
@@ -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
-  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:
 
@@ -2419,6 +2563,36 @@ Here's a list of all control commands and a description, what they do:
   </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
@@ -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
-		.byte  	.strat(Arg, I) .xor $55
+		.byte  	.strat(Arg, I) ^ $55
 		.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").
 
-  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"
@@ -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,
-  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>,
@@ -3134,6 +3311,26 @@ parameters:
   	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>
 
@@ -3145,10 +3342,10 @@ functions will allow you to do exactly this:
 
 <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
@@ -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
-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
@@ -3455,6 +3657,7 @@ each supported CPU a constant similar to
     CPU_65C02
     CPU_65816
     CPU_SUNPLUS
+    CPU_SWEET16
 </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_SWEET16
 </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
@@ -3573,14 +3805,16 @@ below uses examples from the C libraries. However, the feature may also be
 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
@@ -3621,21 +3855,20 @@ two bytes in the table (a pointer to the function).
 
 <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>
 
@@ -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
-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>
@@ -3665,11 +3898,12 @@ does depend on other initialization or cleanup code, you have to choose the
 priority for the functions accordingly.
 
 <item>
-Besides the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> 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>