Merge branch 'master' into seglist

doc/ca65.sgml

@@ -107,6 +107,7 @@ Short options:
 Long options:
   --auto-import                 Mark unresolved symbols as import
   --bin-include-dir dir         Set a search path for binary includes
+  --color [on|auto|off]         Color diagnostics (default: auto)
   --cpu type                    Set cpu type
   --create-dep name             Create a make dependency file
   --create-full-dep name        Create a full make dependency file
@@ -120,6 +121,7 @@ Long options:
   --listing name                Create a listing file if assembly was ok
   --list-bytes n                Maximum number of bytes per listing line
   --memory-model model          Set the memory model
+  --no-utf8                     Disable use of UTF-8 in diagnostics
   --pagelength n                Set the page length for the listing
   --relax-checks                Disables some error checks
   --segment-list                Generate segment offsets in listing
@@ -148,6 +150,14 @@ Here is a description of all the command line options:
   name="search paths">.
 
 
+  <label id="option--color">
+  <tag><tt>--color</tt></tag>
+
+  This option controls if the assembler will use colors when printing
+  diagnostics. The default is "auto" which will enable colors if the output
+  goes to a terminal (not to a file).
+
+
   <label id="option--cpu">
   <tag><tt>--cpu type</tt></tag>
 
@@ -261,6 +271,14 @@ Here is a description of all the command line options:
   huge.
 
 
+  <label id="option--no-utf8">
+  <tag><tt>--no-utf8</tt></tag>
+
+  Disable the use of UTF-8 characters in diagnostics. This might be necessary
+  if auto detection fails or if the output is captured for processing with a
+  tool that is not UTF-8 capable.
+
+
   <label id="option-o">
   <tag><tt>-o name</tt></tag>
 
@@ -920,6 +938,7 @@ See the description of the <tt><ref id=".PROC" name=".PROC"></tt>
 directive for more information.
 
 
+<label id=cheap-locals>
 <sect1>Cheap local labels<p>
 
 Cheap local labels are defined like standard labels, but the name of the
@@ -1435,38 +1454,6 @@ constant is defined:
     CPU_ISET_M740
 </verb></tscreen>
 
-<!-- Sorry but explaining these with the changes from #2751 is too cringy for
-     me - must be done by someone else. The remainder is from the old
-     ".macpack cpu" section"
-
-The value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable may
-be checked with <tt/<ref id="operators" name=".BITAND">/ to determine if the
-currently enabled CPU supports a specific instruction set. For example the
-65C02 supports all instructions of the 65SC02 CPU, so it has the
-<tt/CPU_ISET_65SC02/ bit set in addition to its native <tt/CPU_ISET_65C02/
-bit. Using
-
-<tscreen><verb>
-        .if (.cpu .bitand CPU_ISET_65SC02)
-                lda     (c_sp)
-        .else
-                ldy     #$00
-                lda     (c_sp),y
-        .endif
-</verb></tscreen>
-
-it is possible to determine if the
-
-<tscreen><verb>
-                lda     (c_sp)
-</verb></tscreen>
-
-instruction is supported, which is the case for the 65SC02, 65C02 and 65816
-CPUs (the latter two are upwards compatible to the 65SC02).
-
-see section <ref id="6502-mode" name="6502 format"> and following.
--->
-
   <tt/.CPU/ may be used to replace the .IFPxx pseudo instructions or to
   construct even more complex expressions.
 
@@ -1484,8 +1471,43 @@ see section <ref id="6502-mode" name="6502 format"> and following.
         .endif
   </verb></tscreen>
 
-  See also: <tt><ref id=".CAP" name=".CAP"></tt>
+<bf>The dilemma:</bf>
 
+The original design of this feature was made under the assumption, that any
+"higher" CPU will support the entire instruction set of the "lower" CPU. For
+example: the WDC W65C02 supports all instructions of the 65C02, which again
+support all instructions of the 65SC02. Unfortunately this is not true for all
+CMOS CPUs - when the 65CE02 was made, some instructions were changed, and a new
+addressingmode was added. As a result all CPUS after (and including) 65CE02
+are no more (source code) compatible with all instructions originally introduced
+by the 65SC02.
+
+Because of this, the .CPU function and the ISET* macros were repurposed to
+indicate <em>groups of instructions</em> only, ie only the set of instructions
+that was added by that particular CPU. In the value returned by .CPU only the
+bits will be set, that refer to the groups of instructions that are completely
+supported by that CPU.
+
+The advantage of this is, that the mechanism keeps working for all new CPUs
+added. The inevitable disadvantage is that you now have to know exactly which
+CPU added which instructions (look <htmlurl url="cpus.html" name="here"> for reference).
+
+<tscreen><verb>
+        .if (.cpu .bitand CPU_ISET_65SC02)
+                ; This will be assembled for the W65C02, 65C02, 65SC02, 65816, HUC6820
+                lda     (c_sp)
+        .elseif (.cpu .bitand CPU_ISET_65CE02)
+                ; This will be assembled for the 65CE02, 4510, 45GS02
+                ldz     #$00
+                lda     (c_sp),z
+        .else
+                ldy     #$00
+                lda     (c_sp),y
+        .endif
+</verb></tscreen>
+
+  See also: <tt><ref id=".CAP" name=".CAP"></tt>, which is a similar mechanism,
+  but without the problem outlined above.
 
 
 <sect1><tt>.ISIZE</tt><label id=".ISIZE"><p>
@@ -3753,20 +3775,23 @@ See: <tt><ref id=".ASCIIZ" name=".ASCIIZ"></tt>,<tt><ref id=".BYTE" name=".BYTE"
 
 <sect1><tt>.LOCAL</tt><label id=".LOCAL"><p>
 
-  This command may only be used inside a macro definition. It declares a
-  list of identifiers as local to the macro expansion.
+  This command may only be used inside a macro definition. It declares a list
+  of identifiers as local to the macro expansion. The identifers may be
+  standard identifiers or cheap local identifiers depending on the planed use.
 
   A problem when using macros are labels: Since they don't change their name,
   you get a "duplicate symbol" error if the macro is expanded the second time.
   Labels declared with <tt><ref id=".LOCAL" name=".LOCAL"></tt> have their
-  name mapped to an internal unique name (<tt/___ABCD__/) with each macro
+  name replaced by an internally generated unique name for each macro
   invocation.
 
-  Some other assemblers start a new lexical block inside a macro expansion.
-  This has some drawbacks however, since that will not allow <em/any/ symbol
-  to be visible outside a macro, a feature that is sometimes useful. The
-  <tt><ref id=".LOCAL" name=".LOCAL"></tt> command is in my eyes a better way
-  to address the problem.
+  Please note that while the generated names are unique and guaranteed to not
+  clash with any user generated names, they are still regular symbols and
+  added to the current scope. This means that a local macro label will start a
+  new scope for cheap locals whenever the macro is expanded. To avoid that,
+  you may also use a <ref id="cheap-locals" name="cheap local symbol"> for the
+  name. In this case the assembler will generate unique cheap local
+  identifiers instead of standard ones.
 
   You get an error when using <tt><ref id=".LOCAL" name=".LOCAL"></tt> outside
   a macro.
@@ -3805,7 +3830,6 @@ See: <tt><ref id=".ASCIIZ" name=".ASCIIZ"></tt>,<tt><ref id=".BYTE" name=".BYTE"
   <tscreen><verb>
         atari           Defines the scrcode macro.
         cbm             Defines the scrcode macro.
-        cpu             Defines constants for the .CPU variable.
         generic         Defines generic macros like add, sub, and blt.
         longbranch      Defines conditional long-jump macros.
   </verb></tscreen>
@@ -5119,6 +5143,7 @@ For better orthogonality, the assembler defines similar symbols as the
 compiler, depending on the target system selected:
 
 <itemize>
+<item><tt/__AGAT__/ - Target system is <tt/agat/
 <item><tt/__APPLE2__/ - Target system is <tt/apple2/ or <tt/apple2enh/
 <item><tt/__APPLE2ENH__/ - Target system is <tt/apple2enh/
 <item><tt/__ATARI2600__/ - Target system is <tt/atari2600/
@@ -5131,23 +5156,31 @@ compiler, depending on the target system selected:
 <item><tt/__C128__/ - Target system is <tt/c128/
 <item><tt/__C16__/ - Target system is <tt/c16/ or <tt/plus4/
 <item><tt/__C64__/ - Target system is <tt/c64/
+<item><tt/__C65__/ - Target system is <tt/c65/
 <item><tt/__CBM__/ - Target is a Commodore or Commodore-alike system
 <item><tt/__CBM510__/ - Target system is <tt/cbm510/
 <item><tt/__CBM610__/ - Target system is <tt/cbm610/
+<item><tt/__CREATIVISION__/ - Target system is <tt/creativision/
 <item><tt/__CX16__/ - Target system is <tt/cx16/
+<item><tt/__GAMATE__/ - Target system is <tt/gamate/
 <item><tt/__GEOS__/ - Target is a GEOS system
 <item><tt/__GEOS_APPLE__/ - Target system is <tt/geos-apple/
 <item><tt/__GEOS_CBM__/ - Target system is <tt/geos-cbm/
+<item><tt/__KIM1__/ - Target system is <tt/kim1/
 <item><tt/__LUNIX__/ - Target system is <tt/lunix/
 <item><tt/__LYNX__/ - Target system is <tt/lynx/
+<item><tt/__MEGA65__/ - Target system is <tt/mega65/
 <item><tt/__NES__/ - Target system is <tt/nes/
 <item><tt/__OSIC1P__/ - Target system is <tt/osic1p/
+<item><tt/__PCE__/ - Target system is <tt/pce/
 <item><tt/__PET__/ - Target system is <tt/pet/
 <item><tt/__PLUS4__/ - Target system is <tt/plus4/
+<item><tt/__RP6502__/ - Target system is <tt/rp6502/
 <item><tt/__SIM6502__/ - Target system is <tt/sim6502/
 <item><tt/__SIM65C02__/ - Target system is <tt/sim65c02/
 <item><tt/__SUPERVISION__/ - Target system is <tt/supervision/
 <item><tt/__SYM1__/ - Target system is <tt/sym1/
+<item><tt/__TELESTRAT__/ - Target system is <tt/telestrat/
 <item><tt/__VIC20__/ - Target system is <tt/vic20/
 </itemize>