Merge pull request #2591 from sidneycadot/add-tracing-and-cpumode-switching-peripheral

sim65: add tracing, and a sim65 control peripheral for sim65 runtime control

src/sim65.vcxproj

@@ -87,6 +87,7 @@
     <ClInclude Include="sim65\memory.h" />
     <ClInclude Include="sim65\paravirt.h" />
     <ClInclude Include="sim65\peripherals.h" />
+    <ClInclude Include="sim65\trace.h" />
   </ItemGroup>
   <ItemGroup>
     <ClCompile Include="sim65\6502.c" />
@@ -95,6 +96,7 @@
     <ClCompile Include="sim65\memory.c" />
     <ClCompile Include="sim65\paravirt.c" />
     <ClCompile Include="sim65\peripherals.c" />
+    <ClCompile Include="sim65\trace.c" />
   </ItemGroup>
   <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
   <ImportGroup Label="ExtensionTargets">

src/sim65/6502.c

@@ -42,14 +42,16 @@
  * the WAI ($CB) and STP ($DB) instructions are unsupported.
  */
 
-#include <stdbool.h>
 #include <stdint.h>
+#include <stdbool.h>
 
 #include "memory.h"
 #include "peripherals.h"
 #include "error.h"
-#include "6502.h"
 #include "paravirt.h"
+#include "trace.h"
+
+#include "6502.h"
 
 /*
 
@@ -4485,7 +4487,7 @@ static const OPFunc OP65C02Table[256] = {
     OPC_6502_41,
     OPC_65C02_NOP22,    // $42
     OPC_65C02_NOP11,    // $43
-    OPC_6502X_44,        // $44
+    OPC_6502X_44,       // $44
     OPC_6502_45,
     OPC_6502_46,
     OPC_65C02_47,
@@ -4730,6 +4732,10 @@ unsigned ExecuteInsn (void)
     /* If we have an NMI request, handle it */
     if (HaveNMIRequest) {
 
+        if (TraceMode != TRACE_DISABLED) {
+            PrintTraceNMI ();
+        }
+
         HaveNMIRequest = false;
         Peripherals.Counter.NmiEvents += 1;
 
@@ -4746,6 +4752,10 @@ unsigned ExecuteInsn (void)
 
     } else if (HaveIRQRequest && GET_IF () == 0) {
 
+        if (TraceMode != TRACE_DISABLED) {
+            PrintTraceIRQ ();
+        }
+
         HaveIRQRequest = false;
         Peripherals.Counter.IrqEvents += 1;
 
@@ -4765,11 +4775,16 @@ unsigned ExecuteInsn (void)
         /* Normal instruction - read the next opcode */
         uint8_t OPC = MemReadByte (Regs.PC);
 
-        /* Execute it */
+        /* Print a trace line, if trace mode is enabled. */
-        Handlers[CPU][OPC] ();
+        if (TraceMode != TRACE_DISABLED) {
+            PrintTraceInstruction ();
+        }
 
-        /* Increment the instruction counter by one.NMIs and IRQs are counted separately. */
+        /* Increment the instruction counter by one. */
         Peripherals.Counter.CpuInstructions += 1;
+
+        /* Execute the instruction. The handler sets the 'Cycles' variable. */
+        Handlers[CPU][OPC] ();
     }
 
     /* Increment the 64-bit clock cycle counter with the cycle count for the instruction that we just executed. */

src/sim65/6502.h

@@ -48,9 +48,9 @@
 
 /* Supported CPUs */
 typedef enum CPUType {
-    CPU_6502,
+    CPU_6502  = 0,
-    CPU_65C02,
+    CPU_65C02 = 1,
-    CPU_6502X
+    CPU_6502X = 2
 } CPUType;
 
 /* Current CPU */

src/sim65/main.c

@@ -35,6 +35,7 @@
 
 #include <string.h>
 #include <stdlib.h>
+#include <stdbool.h>
 #include <errno.h>
 
 /* common */
@@ -49,6 +50,7 @@
 #include "memory.h"
 #include "peripherals.h"
 #include "paravirt.h"
+#include "trace.h"
 
 
 
@@ -61,6 +63,9 @@
 /* Name of program file */
 const char* ProgramFile;
 
+/* Set to True if CPU mode override is in effect. If set, the CPU is not read from the program file. */
+static bool CPUOverrideActive = false;
+
 /* exit simulator after MaxCycles Cccles */
 unsigned long long MaxCycles = 0;
 
@@ -95,6 +100,8 @@ static void Usage (void)
             "Long options:\n"
             "  --help\t\tHelp (this text)\n"
             "  --cycles\t\tPrint amount of executed CPU cycles\n"
+            "  --cpu <type>\t\tOverride CPU type (6502, 65C02, 6502X)\n"
+            "  --trace\t\tEnable CPU trace\n"
             "  --verbose\t\tIncrease verbosity\n"
             "  --version\t\tPrint the simulator version number\n",
             ProgName);
@@ -112,6 +119,35 @@ static void OptHelp (const char* Opt attribute ((unused)),
 
 
 
+static void OptCPU (const char* Opt, const char* Arg)
+/* Set CPU type */
+{
+    /* Don't use FindCPU here. Enum constants would clash. */
+    if (strcmp(Arg, "6502") == 0) {
+        CPU = CPU_6502;
+        CPUOverrideActive = true;
+    } else if (strcmp(Arg, "65C02") == 0 || strcmp(Arg, "65c02") == 0) {
+        CPU = CPU_65C02;
+        CPUOverrideActive = true;
+    } else if (strcmp(Arg, "6502X") == 0 || strcmp(Arg, "6502x") == 0) {
+        CPU = CPU_6502X;
+        CPUOverrideActive = true;
+    } else {
+        AbEnd ("Invalid argument for %s: '%s'", Opt, Arg);
+    }
+}
+
+
+
+static void OptTrace (const char* Opt attribute ((unused)),
+                      const char* Arg attribute ((unused)))
+/* Enable trace mode */
+{
+    TraceMode = TRACE_ENABLE_FULL; /* Enable full trace mode. */
+}
+
+
+
 static void OptVerbose (const char* Opt attribute ((unused)),
                         const char* Arg attribute ((unused)))
 /* Increase verbosity */
@@ -135,16 +171,20 @@ static void OptVersion (const char* Opt attribute ((unused)),
 /* Print the simulator version */
 {
     fprintf (stderr, "%s V%s\n", ProgName, GetVersionAsString ());
-    exit(EXIT_SUCCESS);
+    exit (EXIT_SUCCESS);
 }
 
+
+
 static void OptQuitXIns (const char* Opt attribute ((unused)),
-                        const char* Arg attribute ((unused)))
+                        const char* Arg)
-/* quit after MaxCycles cycles */
+/* Quit after MaxCycles cycles */
 {
     MaxCycles = strtoull(Arg, NULL, 0);
 }
 
+
+
 static unsigned char ReadProgramFile (void)
 /* Load program into memory */
 {
@@ -173,17 +213,20 @@ static unsigned char ReadProgramFile (void)
         Error ("'%s': Invalid header version.", ProgramFile);
     }
 
-    /* Get the CPU type from the file header */
+    /* Get the CPU type from the file header.
+     * Use it to set the CPU type, unless CPUOverrideActive is set.
+     */
     if ((Val = fgetc(F)) != EOF) {
-        switch (Val) {
+        if (!CPUOverrideActive) {
-        case CPU_6502:
+            switch (Val) {
-        case CPU_65C02:
+            case CPU_6502:
-        case CPU_6502X:
+            case CPU_65C02:
-            CPU = Val;
+            case CPU_6502X:
-            break;
+                CPU = Val;
-
+                break;
-        default:
+            default:
-            Error ("'%s': Invalid CPU type", ProgramFile);
+                Error ("'%s': Invalid CPU type", ProgramFile);
+            }
         }
     }
 
@@ -238,16 +281,22 @@ int main (int argc, char* argv[])
 {
     /* Program long options */
     static const LongOpt OptTab[] = {
-        { "--help",             0,      OptHelp                 },
+        { "--help",             0,      OptHelp      },
-        { "--cycles",           0,      OptCycles               },
+        { "--cycles",           0,      OptCycles    },
-        { "--verbose",          0,      OptVerbose              },
+        { "--cpu",              1,      OptCPU       },
-        { "--version",          0,      OptVersion              },
+        { "--trace",            0,      OptTrace     },
+        { "--verbose",          0,      OptVerbose   },
+        { "--version",          0,      OptVersion   },
     };
 
     unsigned I;
     unsigned char SPAddr;
     unsigned int Cycles;
 
+    /* Set reasonable defaults. */
+    CPU = CPU_6502;
+    TraceMode = TRACE_DISABLED; /* Disabled by default */
+
     /* Initialize the cmdline module */
     InitCmdLine (&argc, &argv, "sim65");
 
@@ -302,16 +351,29 @@ int main (int argc, char* argv[])
     }
 
     /* Do we have a program file? */
-    if (ProgramFile == 0) {
+    if (ProgramFile == NULL) {
         AbEnd ("No program file");
     }
 
+    /* Reset memory */
     MemInit ();
+
+    /* Reset peripherals. */
     PeripheralsInit ();
 
+    /* Read program file into memory.
+     * This also sets the CPU type, unless a CPU override is in effect.
+     */
     SPAddr = ReadProgramFile ();
+
+    /* Initialize the paravirtualization subsystem. It requires the stack pointer address, to be able to
+     * simulate 6502 subroutine calls.
+     */
+
+    TraceInit(SPAddr);
     ParaVirtInit (I, SPAddr);
 
+    /* Reset the CPU */
     Reset ();
 
     RemainCycles = MaxCycles;

src/sim65/paravirt.h

@@ -32,11 +32,12 @@
 /*****************************************************************************/
 
 
-
 #ifndef PARAVIRT_H
 #define PARAVIRT_H
 
 
+#include "6502.h"
+
 
 /*****************************************************************************/
 /*                                   Data                                    */

src/sim65/peripherals.c

@@ -37,6 +37,8 @@
 
 
 #include "peripherals.h"
+#include "trace.h"
+#include "6502.h"
 
 
 /*****************************************************************************/
@@ -146,6 +148,20 @@ void PeripheralsWriteByte (uint8_t Addr, uint8_t Val)
             break;
         }
 
+        /* Handle writes to the SimControl peripheral. */
+
+        case PERIPHERALS_SIMCONTROL_ADDRESS_OFFSET_CPUMODE: {
+            if (Val == CPU_6502 || Val == CPU_65C02 || Val == CPU_6502X) {
+                CPU = Val;
+            }
+            break;
+        }
+
+        case PERIPHERALS_SIMCONTROL_ADDRESS_OFFSET_TRACEMODE: {
+            TraceMode = Val;
+            break;
+        }
+
         /* Handle writes to unused and read-only peripheral addresses. */
 
         default: {
@@ -192,6 +208,16 @@ uint8_t PeripheralsReadByte (uint8_t Addr)
             return (uint8_t)(Value >> (SelectedByteIndex * 8));
         }
 
+        /* Handle reads from the SimControl peripheral. */
+
+        case PERIPHERALS_SIMCONTROL_ADDRESS_OFFSET_CPUMODE: {
+            return CPU;
+        }
+
+        case PERIPHERALS_SIMCONTROL_ADDRESS_OFFSET_TRACEMODE: {
+            return TraceMode;
+        }
+
         /* Handle reads from unused peripheral and write-only addresses. */
 
         default: {

src/sim65/peripherals.h

@@ -38,9 +38,9 @@
 /* The memory range where the memory-mapped peripherals can be accessed. */
 
 #define PERIPHERALS_APERTURE_BASE_ADDRESS  0xffc0
-#define PERIPHERALS_APERTURE_LAST_ADDRESS  0xffc9
+#define PERIPHERALS_APERTURE_LAST_ADDRESS  0xffcb
 
-/* Declarations for the COUNTER peripheral (currently the only peripheral). */
+/* Declarations for the COUNTER peripheral */
 
 #define PERIPHERALS_COUNTER_ADDRESS_OFFSET_LATCH   0x00
 #define PERIPHERALS_COUNTER_ADDRESS_OFFSET_SELECT  0x01
@@ -84,13 +84,18 @@ typedef struct {
     uint8_t LatchedValueSelected;
 } CounterPeripheral;
 
+/* Declarations for the SIMCONTROL peripheral. */
 
+#define PERIPHERALS_SIMCONTROL_ADDRESS_OFFSET_CPUMODE   0x0A
+#define PERIPHERALS_SIMCONTROL_ADDRESS_OFFSET_TRACEMODE 0x0B
+
+#define PERIPHERALS_SIMCONTROL_CPUMODE   (PERIPHERALS_APERTURE_BASE_ADDRESS + PERIPHERALS_SIMCONTROL_ADDRESS_OFFSET_CPUMODE)
+#define PERIPHERALS_SIMCONTROL_TRACEMODE (PERIPHERALS_APERTURE_BASE_ADDRESS + PERIPHERALS_SIMCONTROL_ADDRESS_OFFSET_TRACEMODE)
 
 /* Declare the 'Sim65Peripherals' type and its single instance 'Peripherals'. */
 
 typedef struct {
-    /* State of the peripherals available in sim65.
+    /* State of the peripherals available in sim65. */
-     * Currently, there is only one peripheral: the Counter. */
     CounterPeripheral Counter;
 } Sim65Peripherals;
 

src/sim65/trace.h

@@ -0,0 +1,89 @@
+/*****************************************************************************/
+/*                                                                           */
+/*                                 trace.h                                   */
+/*                                                                           */
+/*             Instruction tracing functionality sim65 6502 simulator        */
+/*                                                                           */
+/*                                                                           */
+/*                                                                           */
+/* (C) 2025, Sidney Cadot                                                    */
+/*                                                                           */
+/*                                                                           */
+/* This software is provided 'as-is', without any expressed or implied       */
+/* warranty.  In no event will the authors be held liable for any damages    */
+/* arising from the use of this software.                                    */
+/*                                                                           */
+/* Permission is granted to anyone to use this software for any purpose,     */
+/* including commercial applications, and to alter it and redistribute it    */
+/* freely, subject to the following restrictions:                            */
+/*                                                                           */
+/* 1. The origin of this software must not be misrepresented; you must not   */
+/*    claim that you wrote the original software. If you use this software   */
+/*    in a product, an acknowledgment in the product documentation would be  */
+/*    appreciated but is not required.                                       */
+/* 2. Altered source versions must be plainly marked as such, and must not   */
+/*    be misrepresented as being the original software.                      */
+/* 3. This notice may not be removed or altered from any source              */
+/*    distribution.                                                          */
+/*                                                                           */
+/*****************************************************************************/
+
+
+#ifndef TRACE_H
+#define TRACE_H
+
+
+#include <stdint.h>
+
+
+#include "6502.h"
+
+/* The trace mode is a bitfield that determines how trace lines are displayed.
+ *
+ * The value zero indicates that tracing is disabled (the default).
+ *
+ * In case TraceMode is not equal to zero, the value is interpreted as a bitfield:
+ *
+ * Bit    Bit value     Enables
+ * ---    -----------   -------------------------------
+ *  6      0x40 ( 64)   Print the instruction counter.
+ *  5      0x20 ( 32)   Print the clock cycle counter.
+ *  4      0x10 ( 16)   Print the PC (program counter).
+ *  3      0x08 (  8)   Print the instruction bytes.
+ *  2      0x04 (  4)   Print the instruction assembly.
+ *  1      0x02 (  2)   Print the CPU registers.
+ *  0      0x01 (  1)   Print the CC65 stack pointer.
+ *
+ */
+
+#define TRACE_FIELD_INSTR_COUNTER   0x40
+#define TRACE_FIELD_CLOCK_COUNTER   0x20
+#define TRACE_FIELD_PC              0x10
+#define TRACE_FIELD_INSTR_BYTES     0x08
+#define TRACE_FIELD_INSTR_ASSEMBLY  0x04
+#define TRACE_FIELD_CPU_REGISTERS   0x02
+#define TRACE_FIELD_CC65_SP         0x01
+
+#define TRACE_DISABLED              0x00
+#define TRACE_ENABLE_FULL           0x7f
+
+/* Currently active tracing mode. */
+extern uint8_t TraceMode;
+
+void TraceInit (uint8_t SPAddr);
+/* Initialize the trace subsystem. */
+
+void PrintTraceNMI(void);
+/* Print trace line for an NMI interrupt. */
+
+void PrintTraceIRQ(void);
+/* Print trace line for an IRQ interrupt. */
+
+void PrintTraceInstruction (void);
+/* Print trace line for the instruction at the currrent program counter. */
+
+
+
+/* End of trace.h */
+
+#endif