Feature/vscode debugger

.vscode/launch.json

@@ -64,13 +64,48 @@
             "console": "integratedTerminal",
             "stopAtEntry": false
         },
+        {
+            "name": "Avalonia desktop app with TCP debug server",
+            "type": "coreclr",
+            "request": "launch",
+            "preLaunchTask": "build avalonia desktop app",
+            "program": "${workspaceFolder}/src/apps/Avalonia/Highbyte.DotNet6502.App.Avalonia.Desktop/bin/Debug/net10.0/Highbyte.DotNet6502.App.Avalonia.Desktop.dll",
+            "args": ["--enableExternalDebug", "--debug-port", "6502", "--console-log", "-l", "Debug"],
+            "cwd": "${workspaceFolder}/src/apps/Avalonia/Highbyte.DotNet6502.App.Avalonia.Desktop/bin/Debug/net10.0",
+            "console": "integratedTerminal",
+            "stopAtEntry": false
+        },
+        {
+            "name": "Avalonia desktop app with auto starting C64, loading specified program, and enable TCP debug server",
+            "type": "coreclr",
+            "request": "launch",
+            "preLaunchTask": "build avalonia desktop app",
+            "program": "${workspaceFolder}/src/apps/Avalonia/Highbyte.DotNet6502.App.Avalonia.Desktop/bin/Debug/net10.0/Highbyte.DotNet6502.App.Avalonia.Desktop.dll",
+            "args": ["--system", "C64", "--start", "--waitForSystemReady", "--loadPrg", "~/source/repos/dotnet-6502/samples/Assembler/C64/Raster/Build/smooth_scroller_and_raster.prg", "--runLoadedProgram", "--enableExternalDebug", "--debug-port", "6502", "--console-log", "-l", "Debug"],
+            "cwd": "${workspaceFolder}/src/apps/Avalonia/Highbyte.DotNet6502.App.Avalonia.Desktop/bin/Debug/net10.0",
+            "console": "integratedTerminal",
+            "stopAtEntry": false
+        },
+
         {
             "name": "C#: Highbyte.DotNet6502.App.Avalonia.Browser",
             "type": "dotnet",
             "request": "launch",
             "projectPath": "${workspaceFolder}/src/apps/Avalonia/Highbyte.DotNet6502.App.Avalonia.Browser/Highbyte.DotNet6502.App.Avalonia.Browser.csproj",
             "launchConfigurationId": "TargetFramework=;Avalonia.Browser"
         },
+        {
+            "name": "Attach to Avalonia desktop app",
+            "type": "coreclr",
+            "request": "attach",
+            "processName": "Highbyte.DotNet6502.App.Avalonia.Desktop"
+        },
+        {
+            "name": "Attach to DotNet6502 VSCode Debug Adapter ConsoleApp",
+            "type": "coreclr",
+            "request": "attach",
+            "processName": "Highbyte.DotNet6502.DebugAdapter.ConsoleApp"
+        },
         {
             "name": ".NET Core Attach",
             "type": "coreclr",

.vscode/tasks.json

@@ -97,6 +97,22 @@
                 "isDefault": true
             }
         },
+        {
+            "label": "build simple debug adapter console host",
+            "command": "dotnet",
+            "type": "process",
+            "args": [
+                "build",
+                "${workspaceFolder}/src/apps/Highbyte.DotNet6502.DebugAdapter/Highbyte.DotNet6502.DebugAdapter.ConsoleApp.csproj",
+                "/property:GenerateFullPaths=true",
+                "/consoleloggerparameters:NoSummary"
+            ],
+            "problemMatcher": "$msCompile",
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
         {
             "label": "test",
             "command": "dotnet",

Directory.Packages.props

@@ -75,6 +75,8 @@
     <PackageVersion Include="SkiaSharp.Views.Blazor" Version="3.119.1" />
     <!-- SourceLink -->
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
+    <!-- StreamJsonRpc for Debug Adapter Protocol -->
+    <PackageVersion Include="StreamJsonRpc" Version="2.19.27" />
     <!-- System packages -->
     <PackageVersion Include="System.CommandLine" Version="2.0.0-beta4.22272.1" />
     <PackageVersion Include="System.Net.Http.Json" Version="10.0.0" />

README.md

@@ -45,6 +45,12 @@
 
 See [Desktop Apps](doc/DESKTOP_APPS.md) for download links for pre-built executables and instructions for Windows, Linux, and macOS.
 
+## VS Code debugger extension
+
+| [VSCode source debugging](tools/vscode-extension/README.md)| [VSCode disassembly debugging](tools/vscode-extension/README.md) |
+| ----------------------------------------------- | ------------------------------------------------- |
+| <img src="doc/Screenshots/VSCode_source_debug.png" title="VSCode source debug"/> | <img src="doc/Screenshots/VSCode_disassembly_debug.png" title="VSCode disassembly debug"/> | 
+
 ## Other features
 
 | [Run 6502 machine code in your own .NET apps](doc/CPU_LIBRARY.md)  | [Machine code monitor](doc/MONITOR.md) | [C64 Basic AI code completion](doc/SYSTEMS_C64_AI_CODE_COMPLETION.md) | 

benchmarks/Highbyte.DotNet6502.Benchmarks/Commodore64/C64ExecuteFrameBenchmark.cs

@@ -1,6 +1,5 @@
 using System.Runtime.InteropServices;
 using BenchmarkDotNet.Attributes;
-using BenchmarkDotNet.Engines;
 using BenchmarkDotNet.Jobs;
 using Highbyte.DotNet6502.Systems;
 using Highbyte.DotNet6502.Systems.Commodore64;
@@ -17,8 +16,6 @@ public class C64ExecuteFrameBenchmark
 {
     private C64 _c64WithInstrumentation = default!;
     private C64 _c64WithoutInstrumentation = default!;
-    private SystemRunner _systemRunnerWithInstrumentation = default!;
-    private SystemRunner _systemRunnerWithoutInstrumentation = default!;
     private ushort _startAddress;
 
     [Params(1)]
@@ -50,8 +47,6 @@ public void Setup()
         LoadProgram(_c64WithInstrumentation.Mem, _startAddress);
         LoadProgram(_c64WithoutInstrumentation.Mem, _startAddress);
 
-        _systemRunnerWithInstrumentation = new SystemRunner(_c64WithInstrumentation);
-        _systemRunnerWithoutInstrumentation = new SystemRunner(_c64WithoutInstrumentation);
     }
 
     private void LoadProgram(Memory mem, ushort startAddress)
@@ -96,7 +91,7 @@ public void ExecFrameWithoutInstrumentation()
         _c64WithoutInstrumentation.CPU.PC = _startAddress;
         for (var i = 0; i < NumberOfFramesToExecute; i++)
         {
-            var execEvaluatorTriggerResult = _c64WithoutInstrumentation.ExecuteOneFrame(_systemRunnerWithoutInstrumentation);
+            var execEvaluatorTriggerResult = _c64WithoutInstrumentation.ExecuteOneFrame();
         }
     }
 
@@ -106,7 +101,7 @@ public void ExecFrameWithInstrumentation()
         _c64WithInstrumentation.CPU.PC = _startAddress;
         for (var i = 0; i < NumberOfFramesToExecute; i++)
         {
-            var execEvaluatorTriggerResult = _c64WithInstrumentation.ExecuteOneFrame(_systemRunnerWithInstrumentation);
+            var execEvaluatorTriggerResult = _c64WithInstrumentation.ExecuteOneFrame();
         }
     }
 }

benchmarks/Highbyte.DotNet6502.Benchmarks/Commodore64/C64ExecuteInstructionBenchmark.cs

@@ -1,6 +1,5 @@
 using System.Runtime.InteropServices;
 using BenchmarkDotNet.Attributes;
-using BenchmarkDotNet.Engines;
 using BenchmarkDotNet.Jobs;
 using Highbyte.DotNet6502.Systems;
 using Highbyte.DotNet6502.Systems.Commodore64;
@@ -17,8 +16,6 @@ public class C64ExecuteInstructionBenchmark
 {
     private C64 _c64WithInstrumentation = default!;
     private C64 _c64WithoutInstrumentation = default!;
-    private SystemRunner _systemRunnerWithInstrumentation = default!;
-    private SystemRunner _systemRunnerWithoutInstrumentation = default!;
     private ushort _startAddress;
 
     //[Params(1)]
@@ -50,8 +47,6 @@ public void Setup()
         LoadProgram(_c64WithInstrumentation.Mem, _startAddress);
         LoadProgram(_c64WithoutInstrumentation.Mem, _startAddress);
 
-        _systemRunnerWithInstrumentation = new SystemRunner(_c64WithInstrumentation);
-        _systemRunnerWithoutInstrumentation = new SystemRunner(_c64WithoutInstrumentation);
     }
 
     private void LoadProgram(Memory mem, ushort startAddress)
@@ -96,7 +91,7 @@ public void ExecInsWithoutInstrumentation()
         _c64WithoutInstrumentation.CPU.PC = _startAddress;
         for (var i = 0; i < NumberOfInstructionsToExecute; i++)
         {
-            _c64WithoutInstrumentation.ExecuteOneInstruction(_systemRunnerWithoutInstrumentation, out InstructionExecResult instructionExecResult);
+            _c64WithoutInstrumentation.ExecuteOneInstruction(out InstructionExecResult instructionExecResult);
         }
     }
 
@@ -106,7 +101,7 @@ public void ExecInsWithInstrumentation()
         _c64WithInstrumentation.CPU.PC = _startAddress;
         for (var i = 0; i < NumberOfInstructionsToExecute; i++)
         {
-            _c64WithInstrumentation.ExecuteOneInstruction(_systemRunnerWithInstrumentation, out InstructionExecResult instructionExecResult);
+            _c64WithInstrumentation.ExecuteOneInstruction(out InstructionExecResult instructionExecResult);
         }
     }
 }

doc/APPS_CONSOLE_MONITOR.md

@@ -5,6 +5,8 @@ Cross-platform desktop console application with a only UI being a machine code m
 
 <img align="top" src="Screenshots/ConsoleMonitor.png" width="25%" height="25%" title="Machine code monitor native console host window" />
 
+> Note: There is also the [VS Code debugger extension](../tools/vscode-extension/README.md) that can be used for debugging both assembly source and raw disassembly. It's a lost more powerful than the built-in machine code monitor described here.
+
 Technologies
   - UI: standard .NET console.
   - Input: standard .NET console.

doc/DEBUG_ADAPTER_TCP.md

@@ -0,0 +1,169 @@
+# TCP Debug Adapter Integration
+
+## Overview
+
+The debug adapter now supports TCP transport in addition to STDIN/STDOUT, enabling debugging of desktop GUI applications like the Avalonia Desktop app.
+
+## Architecture
+
+### Library Structure
+
+- **Highbyte.DotNet6502.DebugAdapter** (library)
+  - `IDebugAdapterTransport` - Interface for transport implementations
+  - `StdioTransport` - STDIN/STDOUT implementation for console apps
+  - `TcpTransport` - TCP socket implementation for network connections
+  - `TcpDebugAdapterServer` - TCP listener that accepts debug connections
+  - `DapProtocol` - Debug Adapter Protocol message handling
+  - `DebugAdapterLogic` - Core DAP request/response logic
+  - `Ca65DbgParser` - Debug symbol parser
+
+### Console Application
+
+- **Highbyte.DotNet6502.DebugAdapter.ConsoleApp**
+  - Uses `StdioTransport` for VSCode extension integration
+  - Launched by VSCode extension as a child process
+  - Maintains backward compatibility with existing VSCode extension
+
+### Desktop Application Integration
+
+- **Highbyte.DotNet6502.App.Avalonia.Desktop**
+  - Integrated `TcpDebugAdapterServer` for TCP-based debugging
+  - Accepts `--debug-port <port>` command-line argument
+  - Accepts `--debug-wait` flag to wait for debugger connection before starting
+  - Runs debug adapter server on background thread
+
+## Usage
+
+### Avalonia Desktop App with TCP Debug Adapter
+
+Start the Avalonia Desktop app with debug adapter enabled:
+
+```bash
+./Highbyte.DotNet6502.App.Avalonia.Desktop --debug-port 6502
+```
+
+To wait for the debugger to connect before starting:
+
+```bash
+./Highbyte.DotNet6502.App.Avalonia.Desktop --debug-port 6502 --debug-wait
+```
+
+Combined with console logging:
+
+```bash
+./Highbyte.DotNet6502.App.Avalonia.Desktop --debug-port 6502 --console-log -l Debug
+```
+
+### VSCode Configuration
+
+To debug the Avalonia Desktop app from VSCode, you'll need to add a launch configuration that connects to the TCP port:
+
+```json
+{
+    "type": "dotnet6502-debug",
+    "request": "attach",
+    "name": "Attach to Avalonia Desktop",
+    "debugServer": 6502,
+    "program": "${workspaceFolder}/samples/Assembler/GenericComputer/snake6502/build/snake6502.prg",
+    "stopOnEntry": true,
+    "trace": true
+}
+```
+
+**Note:** The VSCode extension may need updates to support the `debugServer` configuration property for TCP connections.
+
+## Implementation Details
+
+### TCP Transport
+
+The `TcpTransport` class implements `IDebugAdapterTransport` using a `TcpClient` and `NetworkStream`:
+
+- Reads DAP messages with Content-Length headers
+- Writes DAP messages with proper framing
+- Fires `Disconnected` event when connection is closed
+
+### TCP Debug Adapter Server
+
+The `TcpDebugAdapterServer` class:
+
+- Listens on `IPAddress.Loopback` (localhost only)
+- Accepts a single client connection at a time
+- Fires `ClientConnected` event with a `TcpTransport` instance
+- Supports port 0 for random port assignment
+
+### Avalonia Desktop Integration
+
+The Avalonia Desktop app:
+
+1. Parses `--debug-port` and `--debug-wait` command-line arguments
+2. Creates a `TcpDebugAdapterServer` when debug port is specified
+3. Handles `ClientConnected` event by:
+   - Creating `DapProtocol` and `DebugAdapterLogic` instances
+   - Starting a message loop on a background thread
+   - Logging to a separate file in the temp directory
+4. Optionally waits for debugger connection (30 second timeout)
+5. Continues with normal application startup
+
+### Debug Logging
+
+Debug adapter activity is logged to:
+
+```
+$TMPDIR/dotnet6502-debugadapter-avalonia-{timestamp}.log
+```
+
+This log file contains:
+- Connection events
+- DAP messages sent/received
+- Errors and exceptions
+
+## Future Enhancements
+
+1. **VSCode Extension Updates**
+   - Add support for `debugServer` configuration property
+   - Allow attaching to running desktop applications
+   - Provide UI for discovering running instances
+
+2. **Multiple Client Support**
+   - Allow multiple simultaneous debug connections
+   - Share breakpoints and state across clients
+
+3. **Auto-Discovery**
+   - Broadcast availability on local network
+   - Allow VSCode to discover running instances
+
+4. **Security**
+   - Add authentication token support
+   - Support remote debugging with encryption
+
+## Testing
+
+### Manual Testing
+
+1. Start the Avalonia Desktop app with debug port:
+   ```bash
+   ./Highbyte.DotNet6502.App.Avalonia.Desktop --debug-port 6502 --debug-wait --console-log
+   ```
+
+2. Connect with a TCP client (e.g., `nc`):
+   ```bash
+   nc localhost 6502
+   ```
+
+3. Send a DAP initialize request:
+   ```
+   Content-Length: 122
+
+   {"seq":1,"type":"request","command":"initialize","arguments":{"adapterID":"dotnet6502","pathFormat":"path"}}
+   ```
+
+4. Verify response is received
+
+### Automated Testing
+
+Future work: Add integration tests that:
+- Start the desktop app with debug port
+- Connect via TCP
+- Send DAP requests
+- Verify responses
+- Test breakpoint functionality