From a985c074a412ee4e37edde083ffe1c56ae20b934 Mon Sep 17 00:00:00 2001
From: Simen Svale <simen@sanity.io>
Date: Tue, 30 Dec 2025 03:23:58 +0100
Subject: [PATCH] Comprehensive protocol fix from official VICE docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Audited all codes against https://vice-emu.sourceforge.io/vice_13.html

Command code fixes:
- Added ExecuteUntilReturn (0x73)
- Fixed BanksAvailable (0x82, was 0x83)
- Added RegistersAvailable (0x83)
- Added ViceInfo (0x85)
- Added PaletteGet (0x91)
- Added JoyportSet (0xa2), UserportSet (0xb2)
- Use Exit (0xaa) for continue/resume

Response type fixes:
- Added JAM (0x61) async event
- Clarified which responses are command echoes vs async events

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 src/protocol/client.ts |  3 ++-
 src/protocol/types.ts  | 56 +++++++++++++++++++++++++-----------------
 2 files changed, 35 insertions(+), 24 deletions(-)

diff --git a/src/protocol/client.ts b/src/protocol/client.ts
index 05e9f45..f23d3a9 100644
--- a/src/protocol/client.ts
+++ b/src/protocol/client.ts
@@ -475,7 +475,8 @@ export class ViceClient {
   }
 
   async continue(): Promise<void> {
-    await this.sendCommand(Command.Continue);
+    // Exit command (0xaa) resumes execution
+    await this.sendCommand(Command.Exit);
     this.state.running = true;
   }
 
diff --git a/src/protocol/types.ts b/src/protocol/types.ts
index 830e21c..b90d192 100644
--- a/src/protocol/types.ts
+++ b/src/protocol/types.ts
@@ -4,7 +4,7 @@
 export const STX = 0x02;
 export const API_VERSION = 0x01; // VICE 3.x uses API v1
 
-// Command codes (per official VICE manual)
+// Command codes (per official VICE manual: https://vice-emu.sourceforge.io/vice_13.html)
 export enum Command {
   // Memory operations
   MemoryGet = 0x01,
@@ -32,24 +32,28 @@ export enum Command {
   ResourceGet = 0x51,
   ResourceSet = 0x52,
 
-  // Advance instructions
+  // Advance/step instructions
   AdvanceInstructions = 0x71,
   KeyboardFeed = 0x72,
+  ExecuteUntilReturn = 0x73,
+
+  // Info/query commands
+  Ping = 0x81,
+  BanksAvailable = 0x82,
+  RegistersAvailable = 0x83,
+  DisplayGet = 0x84,
+  ViceInfo = 0x85,
+
+  // Palette
+  PaletteGet = 0x91,
+
+  // Joyport/Userport
+  JoyportSet = 0xa2,
+  UserportSet = 0xb2,
 
   // Execution control
-  Step = 0x81,
-  Continue = 0x82,  // Also called "Exit" - resumes execution
-  Ping = 0x81,      // Same as step with count=0
-
-  // Display
-  DisplayGet = 0x84,
-
-  // Banks
-  BanksAvailable = 0x83,
-
-  // Exit/Quit
-  Exit = 0xaa,
-  Quit = 0xbb,
+  Exit = 0xaa,       // Resumes execution (continue)
+  Quit = 0xbb,       // Terminates VICE
 
   // Reset
   Reset = 0xcc,
@@ -58,20 +62,26 @@ export enum Command {
   AutoStart = 0xdd,
 }
 
-// Response types (per official VICE manual)
+// Response types (per official VICE manual: https://vice-emu.sourceforge.io/vice_13.html)
+// Note: Most commands echo back with the same response code as the command
+// These are the ASYNC event response types that VICE sends unprompted:
 export enum ResponseType {
   Invalid = 0x00,
-  MemoryGet = 0x01,    // Memory read response
-  MemorySet = 0x02,    // Memory write response
-  CheckpointResponse = 0x11, // Checkpoint set/get/delete response
-  CheckpointInfo = 0x12,     // Checkpoint info
-  RegisterInfo = 0x31,       // Register info (async event when stopped)
+
+  // Command response codes (echoed from command)
+  MemoryGet = 0x01,
+  MemorySet = 0x02,
+  CheckpointInfo = 0x11,
+  RegisterInfo = 0x31,
   Dump = 0x41,
   Undump = 0x42,
   ResourceGet = 0x51,
   ResourceSet = 0x52,
-  Stopped = 0x62,            // Stopped event (async)
-  Resumed = 0x63,            // Resumed event (async)
+
+  // Async event codes (sent by VICE unprompted)
+  JAM = 0x61,                // CPU jam event
+  Stopped = 0x62,            // Execution stopped
+  Resumed = 0x63,            // Execution resumed
 }
 
 // Memory spaces