Merge pull request #2774 from mrdudz/somedocs

Somedocs
2025-07-07 23:27:14 +02:00
parent 7c6efded1c cf89172cf7
commit 593bf159fa
2 changed files with 97 additions and 41 deletions
--- a/doc/ca65.sgml
+++ b/doc/ca65.sgml
@@ -1434,38 +1434,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.

@@ -1483,8 +1451,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>
@@ -3807,7 +3810,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>
@@ -5121,6 +5123,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/
@@ -5133,23 +5136,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>

--- a/doc/cc65.sgml
+++ b/doc/cc65.sgml
@@ -641,7 +641,7 @@ Here is a description of all the command line options:
  <item>pce (PC engine)
  <item>pet (all CBM PET systems except the 2001)
  <item>plus4
-  <item>p6502
+  <item>rp6502
  <item>sim6502
  <item>sim65c02
  <item>supervision
@@ -1112,6 +1112,10 @@ This cc65 version has some extensions to the ISO C standard.
 The compiler defines several macros at startup:

 <descrip>
+  <tag><tt>__AGAT__</tt></tag>
+
+  This macro is defined if the target is the Agat (-t agat).
+
  <tag><tt>__APPLE2__</tt></tag>

  This macro is defined if the target is the Apple ][ (-t apple2) or the enhanced Apple //e (-t apple2enh).
@@ -1122,11 +1126,15 @@ The compiler defines several macros at startup:

  <tag><tt>__ATARI2600__</tt></tag>

-  This macro is defined if the target is the Atari 2600 game console.
+  This macro is defined if the target is the Atari 2600 game console (-t atari2600).

  <tag><tt>__ATARI5200__</tt></tag>

-  This macro is defined if the target is the Atari 5200 game console.
+  This macro is defined if the target is the Atari 5200 game console (-t atari5200).
+
+  <tag><tt>__ATARI7800__</tt></tag>
+
+  This macro is defined if the target is the Atari 7800 game console (-t atari7800).

  <tag><tt>__ATARI__</tt></tag>

@@ -1140,6 +1148,10 @@ The compiler defines several macros at startup:

  This macro is defined if the target is the Oric Atmos (-t atmos).

+  <tag><tt>__BBC__</tt></tag>
+
+  This macro is defined if the target is the BBC (-t bbc).
+
  <tag><tt>__C128__</tt></tag>

  This macro is defined if the target is the Commodore 128 (-t c128).
@@ -1152,6 +1164,10 @@ The compiler defines several macros at startup:

  This macro is defined if the target is the Commodore 64 (-t c64).

+  <tag><tt>__C65__</tt></tag>
+
+  This macro is defined if the target is the Commodore 65 (-t c65).
+
  <tag><tt>__CBM__</tt></tag>

  This macro is defined if the target system is one of the CBM targets.
@@ -1196,10 +1212,8 @@ The compiler defines several macros at startup:
  <label id="macro-CPU">
  <tag><tt>__CPU__</tt></tag>

-  This macro contains a bitset that allows to check if a specific instruction
-  set is supported. For example, the 65C02 CPU supports all instructions of the
-  65SC02. So testing for the instruction set of the 65SC02 using the following
-  check will succeed for both CPUs (and also for the 65816 and HUC6280).
+  This macro contains a bitset that allows to check if a specific group of
+  instructions is supported.

  <tscreen><verb>
  #if (__CPU__ & __CPU_ISET_65SC02__)
@@ -1212,6 +1226,13 @@ The compiler defines several macros at startup:
  given, but can be changed using the <tt/<ref id="option--cpu" name="--cpu">/
  command line option.

+  Note that, since the different CMOS instruction sets are not orthogonal, the
+  following test macros only test for the group of instructions <bf>added</bf>
+  by this particular CPU.
+
+  see <htmlurl url="ca65.html#.CPU" name=".CPU"> for details on the ISET*
+  dilemma.
+
  <tag><tt>__CPU_4510__</tt></tag>

  This macro is defined if the code is compiled for a 4510 CPU.
@@ -1321,6 +1342,10 @@ The compiler defines several macros at startup:
  <tt/<ref id="macro-CPU" name="__CPU__">/ macro for the instruction set
  of the W65C02 CPU.

+  <tag><tt>__CREATIVISION__</tt></tag>
+
+  This macro is defined if the target is the VTech Creativision game console (-t creativision).
+
  <tag><tt>__CX16__</tt></tag>

  This macro is defined if the target is the Commander X16 (-t cx16).
@@ -1339,6 +1364,10 @@ The compiler defines several macros at startup:

  This macro expands to a string containing the name of the C source file.

+  <tag><tt>__GAMATE__</tt></tag>
+
+  This macro is defined if the target is the Gamate handheld (-t gamate).
+
  <tag><tt>__GEOS__</tt></tag>

  This macro is defined if you are compiling for one of the GEOS systems.
@@ -1351,6 +1380,10 @@ The compiler defines several macros at startup:

  This macro is defined if you are compiling for the GEOS 64/128 system (-t geos-cbm).

+  <tag><tt>__KIM1__</tt></tag>
+
+  This macro is defined if the target is the KIM-1 (-t kmi1).
+
  <tag><tt>__LINE__</tt></tag>

  This macro expands to the current line number.
@@ -1363,6 +1396,10 @@ The compiler defines several macros at startup:

  This macro is defined if the target is the Atari Lynx (-t lynx).

+  <tag><tt>__MEGA65__</tt></tag>
+
+  This macro is defined if the target is the Mega 65 (-t mega65).
+
  <tag><tt>__NES__</tt></tag>

  This macro is defined if the target is the Nintendo Entertainment System (-t nes).
@@ -1388,6 +1425,10 @@ The compiler defines several macros at startup:
  This macro is defined if the target is the Ohio Scientific Challenger 1P
  (-t osic1p).

+  <tag><tt>__PCE__</tt></tag>
+
+  This macro is defined if the target is the PC Engine game console (-t pce).
+
  <tag><tt>__PET__</tt></tag>

  This macro is defined if the target is the PET family of computers (-t pet).
@@ -1396,6 +1437,10 @@ The compiler defines several macros at startup:

  This macro is defined if the target is the Commodore Plus/4 (-t plus4).

+  <tag><tt>__RP6502__</tt></tag>
+
+  This macro is defined if the target is the Picocomputer 6502 (-t rp6502).
+
  <tag><tt>__SIM6502__</tt></tag>

  This macro is defined if the target is sim65 in 6502 mode (-t sim6502).