@henols/c64-re-tools 2.0.0-rc.2 → 2.0.0-rc.20

package/src/protocol/vice.ts

@@ -94,6 +94,8 @@ export const MAX_WATCH_SIZE = 256;
 export interface Breakpoint {
   id: number;
   address: number;
+  /** A range from address: the CPU stops at the first instruction it executes in it (D43). One address when not given. */
+  size?: number;
   space: Space;
   enabled: boolean;
   /** The condition given at add, when there was one. */
@@ -112,15 +114,23 @@ export interface Watchpoint {
 }
 
 export type BreakpointParams =
-  | { action: "add"; address: number; space: Space; condition?: Condition }
-  | { action: "remove" | "enable" | "disable"; id: number }
+  | { action: "add"; address: number; size?: number; space: Space; condition?: Condition }
+  | { action: "remove"; id: number }
+  | { action: "enable" | "disable"; id: number }
   | { action: "list" };
 
 export type WatchpointParams =
   | { action: "add"; address: number; size: number; access: WatchAccess; space: Space; condition?: Condition }
-  | { action: "remove" | "enable" | "disable"; id: number }
+  | { action: "remove"; id: number }
+  | { action: "enable" | "disable"; id: number }
   | { action: "list" };
 
+/** The result of remove: the point is gone, so only its id comes back. */
+export interface PointRemoved {
+  removed: true;
+  id: number;
+}
+
 // Chip state
 
 export const VICII_MODES = ["text", "multicolor-text", "extended-color-text", "bitmap", "multicolor-bitmap", "invalid"] as const;
@@ -158,9 +168,14 @@ export interface CiaState {
   ddrB: number;
   timerA: number;
   timerB: number;
+  /** The values that a timer loads at an underflow: write-only on the chip, from VICE's dump (D63). */
+  latchA: number;
+  latchB: number;
   controlA: number;
   controlB: number;
   interruptStatus: number;
+  /** The interrupt sources that are on: bits 0-4 of a write to $xd0d with bit 7 set. */
+  interruptMask: number;
   tod: { hours: number; minutes: number; seconds: number; tenths: number };
 }
 
@@ -202,6 +217,50 @@ export interface HistoryEntry {
   rasterCycle?: number;
 }
 
+// Traces (D76): checkpoints that record each hit and let the program run on.
+
+export const TRACE_KINDS = ["exec", "read", "write"] as const;
+export type TraceKind = (typeof TRACE_KINDS)[number];
+export const MAX_TRACE_POINTS = 8;
+export const MAX_TRACE_FRAMES = 3000;
+export const MAX_TRACE_HITS = 20_000;
+export const TRACE_ENDS = ["frames", "hits", "breakpoint", "watchpoint", "jam"] as const;
+
+export interface TracePoint {
+  kind: TraceKind;
+  start: number;
+  end: number;
+}
+
+/** One hit of a trace: the instruction that executed or made the access, the registers before it, and where the raster was. */
+export interface TraceHit {
+  /** The index of the point in the request. */
+  point: number;
+  /** The address of the instruction. */
+  pc: number;
+  bytes: string;
+  text: string;
+  a: number;
+  x: number;
+  y: number;
+  sp: number;
+  /** The frame of the trace, from 0, and the raster position when the instruction started. */
+  frame: number;
+  rasterLine: number;
+  rasterCycle: number;
+  /** read and write: the address that the instruction used, when its mode tells it, and the byte there after the access. */
+  address?: number;
+  value?: number;
+}
+
+export interface TraceResult {
+  hits: TraceHit[];
+  frames: number;
+  /** frames: the frame limit; hits: the hit limit; breakpoint, watchpoint or jam: the program stopped there. */
+  end: (typeof TRACE_ENDS)[number];
+  pc: number;
+}
+
 export interface BacktraceFrame {
   /** The routine's entry address. */
   address: number;
@@ -223,12 +282,11 @@ export interface ProfileEntry {
   percent: number;
 }
 
+/** Addresses with the same access flags: the coverage byte of src/c64.ts (D40), RAM, ROM and I/O apart. */
 export interface MemmapRange {
   start: number;
   end: number;
-  execute: boolean;
-  read: boolean;
-  write: boolean;
+  flags: number;
 }
 
 // Screen baselines and snapshots
@@ -247,9 +305,29 @@ export interface Rectangle {
   height: number;
 }
 
+/** The visible frame with normal borders that a screen capture holds, in pixels. */
+export const FRAME_SIZE: Record<VideoStandard, { width: number; height: number }> = {
+  pal: { width: 384, height: 272 },
+  ntsc: { width: 384, height: 247 },
+};
+
+/** True when the mask rectangles leave no pixel of the frame to compare. */
+export function maskCoversFrame(mask: readonly Rectangle[], standard: VideoStandard): boolean {
+  const { width, height } = FRAME_SIZE[standard];
+  const masked = new Uint8Array(width * height);
+  for (const rectangle of mask) {
+    for (let y = rectangle.y; y < Math.min(height, rectangle.y + rectangle.height); y++) {
+      if (rectangle.x < width) masked.fill(1, y * width + rectangle.x, y * width + Math.min(width, rectangle.x + rectangle.width));
+    }
+  }
+  return !masked.includes(0);
+}
+
 export interface ScreenComparison {
   match: boolean;
   mismatchingPixels: number;
+  /** Pixels compared: the frame minus the masked ones; always at least 1. */
+  comparedPixels: number;
   mismatchRatio: number;
   /** Absent when no pixel differs. */
   bounds?: Rectangle;
@@ -301,8 +379,18 @@ export interface MachineStatus {
   window: boolean;
   /** Present only while the C64 CPU is stopped. */
   pc?: number;
+  /** True while a cartridge from an autostart is attached (D64). */
+  cartridge: boolean;
+  /** Present only while stopped by a user breakpoint or watchpoint, or by a JAM. */
+  stopReason?: PointStopReason;
+  /** The id of the breakpoint or watchpoint that stopped the machine. */
+  pointId?: number;
 }
 
+/** What stopped the machine outside a request that stops it. */
+export const POINT_STOP_REASONS = ["breakpoint", "watchpoint", "jam"] as const;
+export type PointStopReason = (typeof POINT_STOP_REASONS)[number];
+
 export interface MemoryReadParams {
   address: number;
   size: number;
@@ -357,6 +445,12 @@ export interface ExecutionParams {
   /** step and next: defaults to 1; advance-frames: required. */
   count?: number;
   space: Space;
+  /**
+   * advance-frames only: the raster position that ends a frame, instead of the
+   * position where this call starts. Runs that stop between frames then keep
+   * the frames of one timeline (D62).
+   */
+  anchor?: { line: number; cycle: number };
 }
 
 export interface ExecutionResult {
@@ -364,6 +458,10 @@ export interface ExecutionResult {
   pc?: number;
   executed?: number;
   advancedFrames?: number;
+  /** advance-frames only: frames when all frames ran, else what stopped the run early. */
+  stopReason?: "frames" | PointStopReason;
+  /** The id of the breakpoint or watchpoint that stopped the run. */
+  pointId?: number;
 }
 
 /** c64_run_until targets. */
@@ -380,12 +478,18 @@ export interface RunUntilResult {
   reached: boolean;
   stopReason: StopReason;
   state: RunState;
+  /** The PC of the CPU in `space`: the CPU that stopped. */
   pc: number;
+  space: Space;
+  /** The id of the breakpoint or watchpoint that stopped the run. */
+  pointId?: number;
 }
 
 export interface ViceOperations {
   status: { params: Record<string, never>; result: MachineStatus };
   memoryRead: { params: MemoryReadParams; result: MemoryReadResult };
+  /** The I/O registers at $d000-$dfff as the chips hold them, whatever the CPU banks in, without side effects (D43). */
+  ioRead: { params: { address: number; size: number }; result: MemoryReadResult };
   registersGet: { params: { space: Space }; result: Registers };
   memoryWrite: { params: MemoryWriteParams; result: { address: number; bytesWritten: number } };
   /** `pattern`: bytes, with null as a wildcard. */
@@ -403,25 +507,33 @@ export interface ViceOperations {
   runUntil: { params: { target: RunTarget; timeoutFrames: number }; result: RunUntilResult };
   /** Attachment: the PRG bytes, load address first. */
   programLoad: { params: { address?: number }; result: { state: RunState; loadAddress: number; size: number } };
-  /** Attachment: the program or image bytes; `type` is the file's extension. */
-  autostart: { params: { type: string; index: number; run: boolean }; result: { state: RunState } };
+  /** Attachment: the program or image bytes; `type` is the file's extension. `index` is VICE's file number: 0 loads "*", 1 is the first directory entry. */
+  /**
+   * `emulatorFlaw`: for a tape image, a known flaw of the host's VICE version that a tape load meets (D56).
+   * `joysticksCentred`: the control ports that held a direction or fire and were centred first (R3-05).
+   */
+  autostart: { params: { type: string; index: number; run: boolean }; result: { state: RunState; emulatorFlaw?: string; joysticksCentred?: Array<1 | 2> } };
   /** Attachment: the disk image bytes; `type` is the file's extension. */
   diskAttach: { params: { type: string }; result: { attached: boolean } };
   /** pc is the reset vector when run is false: the CPU stops there. */
   reset: { params: { mode: ResetMode; run: boolean }; result: { state: RunState; pc?: number } };
   /** `data`: PETSCII bytes as lowercase hex. */
-  keyboard: { params: { data: string }; result: { queuedBytes: number } };
-  joystick: { params: JoystickState; result: JoystickState };
-  breakpoint: { params: BreakpointParams; result: Breakpoint | { breakpoints: Breakpoint[] } };
-  watchpoint: { params: WatchpointParams; result: Watchpoint | { watchpoints: Watchpoint[] } };
+  /** `emulatorFlaw`: a known flaw of the host's VICE version that this input meets (D56). */
+  keyboard: { params: { data: string }; result: { queuedBytes: number; emulatorFlaw?: string } };
+  joystick: { params: JoystickState; result: JoystickState & { emulatorFlaw?: string } };
+  breakpoint: { params: BreakpointParams; result: Breakpoint | PointRemoved | { breakpoints: Breakpoint[] } };
+  watchpoint: { params: WatchpointParams; result: Watchpoint | PointRemoved | { watchpoints: Watchpoint[] } };
   cpuHistory: { params: { limit: number; space: Space }; result: { entries: HistoryEntry[] } };
+  trace: { params: { points: TracePoint[]; frames: number; maxHits: number }; result: TraceResult };
   backtrace: { params: { depth: number; space: Space }; result: { frames: BacktraceFrame[] } };
   /** `cycles` is a decimal string. */
   timing: { params: { action: (typeof TIMING_ACTIONS)[number] }; result: { started: boolean } | { cycles: string } };
-  profile: { params: { limit: number }; result: { entries: ProfileEntry[] } };
+  /** clear starts the profiler again from zero. */
+  profile: { params: { action: "read"; limit: number } | { action: "clear" }; result: { entries: ProfileEntry[] } | { cleared: boolean } };
   memmap: {
     params: { action: "read"; start: number; end: number; maxRanges: number } | { action: "clear" };
-    result: { ranges: MemmapRange[] } | { cleared: boolean };
+    /** `next`: more ranges follow from this address; read again from there. */
+    result: { ranges: MemmapRange[]; next?: number } | { cleared: boolean };
   };
   vicii: { params: Record<string, never>; result: ViciiState };
   /** `indexes`: unique sprite numbers 0-7, in the order to report them. */
@@ -440,6 +552,14 @@ export interface ViceOperations {
     params: { action: "save" | "restore" | "discard"; name: string } | { action: "list" };
     result: { saved: boolean; name: string } | { restored: boolean; state: RunState } | { snapshots: string[] } | { discarded: boolean };
   };
+  /**
+   * Snapshot files (D41): export sends the bytes of a named snapshot back as
+   * one attachment; restore takes the bytes of a .vsf as one attachment.
+   */
+  snapshotFile: {
+    params: { action: "export"; name: string } | { action: "restore" };
+    result: { exported: boolean; bytes: number } | { restored: boolean; state: RunState };
+  };
   screenDiscard: { params: { baseline: string }; result: { discarded: boolean } };
   warp: { params: { enabled: boolean }; result: { enabled: boolean } };
   window: { params: { action: (typeof WINDOW_ACTIONS)[number] }; result: WindowResult };
@@ -469,7 +589,10 @@ export const VICE_OPERATIONS = [
   "screenBaselines",
   "screenDiscard",
   "snapshot",
+  "snapshotFile",
+  "ioRead",
   "cpuHistory",
+  "trace",
   "backtrace",
   "timing",
   "profile",
@@ -483,8 +606,9 @@ export const VICE_OPERATIONS = [
   "window",
 ] as const satisfies readonly ViceOperation[];
 
-/** How many attachments each operation takes. */
-export function attachmentCount(op: ViceOperation): number {
+/** How many attachments an operation takes; a snapshotFile restore takes the .vsf. */
+export function attachmentCount(op: ViceOperation, params?: unknown): number {
+  if (op === "snapshotFile") return isObject(params) && params.action === "restore" ? 1 : 0;
   return op === "programLoad" || op === "autostart" || op === "diskAttach" ? 1 : 0;
 }
 
@@ -514,6 +638,15 @@ export function validateViceParams<O extends ViceOperation>(op: O, params: unkno
       }
       return { action: params.action, name: validName(params.name, "name") } as ViceOperations[O]["params"];
     }
+    case "snapshotFile": {
+      if (params.action === "restore") {
+        onlyFields(params, ["action"]);
+        return { action: "restore" } as ViceOperations[O]["params"];
+      }
+      if (params.action !== "export") invalid("action must be export or restore");
+      onlyFields(params, ["action", "name"]);
+      return { action: "export", name: validName(params.name, "name") } as ViceOperations[O]["params"];
+    }
     case "screenCompare": {
       onlyFields(params, ["baseline", "maxMismatchRatio", "mask", "includeDiff"]);
       const ratio = params.maxMismatchRatio;
@@ -535,6 +668,20 @@ export function validateViceParams<O extends ViceOperation>(op: O, params: unkno
       if (!isOneOf(SPACES, params.space)) invalid("space must be c64 or drive8");
       return { limit: params.limit, space: params.space } as ViceOperations[O]["params"];
     }
+    case "trace": {
+      onlyFields(params, ["points", "frames", "maxHits"]);
+      if (!Array.isArray(params.points) || params.points.length === 0 || params.points.length > MAX_TRACE_POINTS) invalid(`points must be a list of 1 to ${MAX_TRACE_POINTS} points`);
+      const points = (params.points as unknown[]).map((point) => {
+        if (!isObject(point)) return invalid("a point is an object with kind, start and end");
+        onlyFields(point, ["kind", "start", "end"]);
+        if (!isOneOf(TRACE_KINDS, point.kind)) invalid("a point kind must be exec, read or write");
+        if (!isInteger(point.start, 0, 0xffff) || !isInteger(point.end, point.start as number, 0xffff)) invalid("a point needs start and end from $0000 to $ffff, the end not before the start");
+        return { kind: point.kind, start: point.start, end: point.end } as TracePoint;
+      });
+      if (!isInteger(params.frames, 1, MAX_TRACE_FRAMES)) invalid(`frames must be an integer from 1 to ${MAX_TRACE_FRAMES}`);
+      if (!isInteger(params.maxHits, 1, MAX_TRACE_HITS)) invalid(`maxHits must be an integer from 1 to ${MAX_TRACE_HITS}`);
+      return { points, frames: params.frames, maxHits: params.maxHits } as ViceOperations[O]["params"];
+    }
     case "backtrace": {
       onlyFields(params, ["depth", "space"]);
       if (!isInteger(params.depth, 1, MAX_BACKTRACE)) invalid(`depth must be an integer from 1 to ${MAX_BACKTRACE}`);
@@ -574,9 +721,11 @@ export function validateViceParams<O extends ViceOperation>(op: O, params: unkno
       return result as ViceOperations[O]["params"];
     }
     case "profile": {
-      onlyFields(params, ["limit"]);
+      onlyFields(params, params.action === "clear" ? ["action"] : ["action", "limit"]);
+      if (params.action === "clear") return { action: "clear" } as ViceOperations[O]["params"];
+      if (params.action !== "read") invalid("action must be read or clear");
       if (!isInteger(params.limit, 1, MAX_PROFILE)) invalid(`limit must be an integer from 1 to ${MAX_PROFILE}`);
-      return { limit: params.limit } as ViceOperations[O]["params"];
+      return { action: "read", limit: params.limit } as ViceOperations[O]["params"];
     }
     case "memmap": {
       onlyFields(params, params.action === "clear" ? ["action"] : ["action", "start", "end", "maxRanges"]);
@@ -609,6 +758,12 @@ export function validateViceParams<O extends ViceOperation>(op: O, params: unkno
       const result: MemoryReadParams = { address: params.address, size: params.size, space: params.space, view: params.view };
       return result as ViceOperations[O]["params"];
     }
+    case "ioRead": {
+      onlyFields(params, ["address", "size"]);
+      if (!isInteger(params.address, 0xd000, 0xdfff)) invalid("address must be in the I/O area $d000-$dfff");
+      if (!isInteger(params.size, 1, 0x1000) || params.address + params.size > 0xe000) invalid("the range must stay inside $d000-$dfff");
+      return { address: params.address, size: params.size } as ViceOperations[O]["params"];
+    }
     case "registersGet": {
       onlyFields(params, ["space"]);
       if (!isOneOf(SPACES, params.space)) invalid("space must be c64 or drive8");
@@ -702,7 +857,7 @@ export function validateViceParams<O extends ViceOperation>(op: O, params: unkno
       return { space: params.space, values: result } as ViceOperations[O]["params"];
     }
     case "execution": {
-      onlyFields(params, ["action", "space", "count"]);
+      onlyFields(params, ["action", "space", "count", "anchor"]);
       if (!isOneOf(EXECUTION_ACTIONS, params.action)) invalid(`action must be one of ${EXECUTION_ACTIONS.join(", ")}`);
       if (!isOneOf(SPACES, params.space)) invalid("space must be c64 or drive8");
       const counted = params.action === "step" || params.action === "next" || params.action === "advance-frames";
@@ -714,6 +869,13 @@ export function validateViceParams<O extends ViceOperation>(op: O, params: unkno
       }
       const result: ExecutionParams = { action: params.action, space: params.space };
       if (counted) result.count = (params.count as number | undefined) ?? 1;
+      if (params.anchor !== undefined) {
+        if (params.action !== "advance-frames") invalid(`anchor is not used with action ${params.action}`);
+        const anchor = params.anchor;
+        if (!isObject(anchor) || !isInteger(anchor.line, 0, 511) || !isInteger(anchor.cycle, 0, 127)) invalid("anchor needs line from 0 to 511 and cycle from 0 to 127");
+        onlyFields(anchor as Record<string, unknown>, ["line", "cycle"]);
+        result.anchor = { line: anchor.line as number, cycle: anchor.cycle as number };
+      }
       return result as ViceOperations[O]["params"];
     }
     case "runUntil": {
@@ -765,7 +927,7 @@ export function validateViceParams<O extends ViceOperation>(op: O, params: unkno
         if (!isInteger(params.id, 1, 0xffff_ffff)) invalid("id must be a positive integer");
         return { action: params.action, id: params.id } as ViceOperations[O]["params"];
       }
-      onlyFields(params, op === "watchpoint" ? ["action", "address", "space", "size", "access", "condition"] : ["action", "address", "space", "condition"]);
+      onlyFields(params, op === "watchpoint" ? ["action", "address", "space", "size", "access", "condition"] : ["action", "address", "space", "size", "condition"]);
       if (!isInteger(params.address, 0, 0xffff)) invalid("address must be an integer from 0 to 65535");
       if (!isOneOf(SPACES, params.space)) invalid("space must be c64 or drive8");
       const added: Record<string, unknown> = { action: "add", address: params.address, space: params.space };
@@ -775,6 +937,9 @@ export function validateViceParams<O extends ViceOperation>(op: O, params: unkno
         if (!isOneOf(WATCH_ACCESS, params.access)) invalid("access must be read, write or read-write");
         added.size = params.size;
         added.access = params.access;
+      } else if (params.size !== undefined) {
+        if (!isInteger(params.size, 1, 0x10000) || params.address + params.size > 0x10000) invalid("size must keep the range inside $0000-$ffff");
+        added.size = params.size;
       }
       if (params.condition !== undefined) added.condition = validateCondition(params.condition);
       return added as ViceOperations[O]["params"];
@@ -868,11 +1033,16 @@ function validateRunTarget(value: unknown): RunTarget {
   return invalid("target kind must be address, memory or raster");
 }
 
+function isRemoved(value: unknown): value is PointRemoved {
+  return isObject(value) && value.removed === true && isInteger(value.id, 1, 0xffff_ffff) && Object.keys(value).length === 2;
+}
+
 function isBreakpoint(value: unknown): value is Breakpoint {
   return (
     isObject(value) &&
     isInteger(value.id, 1, 0xffff_ffff) &&
     isInteger(value.address, 0, 0xffff) &&
+    (value.size === undefined || isInteger(value.size, 1, 0x10000)) &&
     isOneOf(SPACES, value.space) &&
     typeof value.enabled === "boolean" &&
     (value.condition === undefined || isCondition(value.condition))
@@ -917,13 +1087,17 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         isOneOf(VIDEO_STANDARDS, value.videoStandard) &&
         typeof value.warp === "boolean" &&
         typeof value.window === "boolean" &&
-        (value.pc === undefined || isInteger(value.pc, 0, 0xffff));
+        (value.pc === undefined || isInteger(value.pc, 0, 0xffff)) &&
+        typeof value.cartridge === "boolean" &&
+        (value.stopReason === undefined || isOneOf(POINT_STOP_REASONS, value.stopReason)) &&
+        (value.pointId === undefined || isInteger(value.pointId, 1, Number.MAX_SAFE_INTEGER));
       if (!ok) throw new ProtocolError("status result is malformed");
       break;
     }
-    case "memoryRead": {
+    case "memoryRead":
+    case "ioRead": {
       if (!isInteger(value.address, 0, 0xffff) || !isHexData(value.data)) {
-        throw new ProtocolError("memoryRead result is malformed");
+        throw new ProtocolError(`${op} result is malformed`);
       }
       break;
     }
@@ -984,7 +1158,9 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         typeof value.reached === "boolean" &&
         isOneOf(STOP_REASONS, value.stopReason) &&
         isOneOf(RUN_STATES, value.state) &&
-        isInteger(value.pc, 0, 0xffff);
+        isInteger(value.pc, 0, 0xffff) &&
+        isOneOf(SPACES, value.space) &&
+        (value.pointId === undefined || isInteger(value.pointId, 1, Number.MAX_SAFE_INTEGER));
       if (!ok) throw new ProtocolError("runUntil result is malformed");
       break;
     }
@@ -993,7 +1169,9 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         isOneOf(RUN_STATES, value.state) &&
         (value.pc === undefined || isInteger(value.pc, 0, 0xffff)) &&
         (value.executed === undefined || isInteger(value.executed, 0, MAX_EXECUTION_COUNT)) &&
-        (value.advancedFrames === undefined || isInteger(value.advancedFrames, 0, MAX_EXECUTION_COUNT));
+        (value.advancedFrames === undefined || isInteger(value.advancedFrames, 0, MAX_EXECUTION_COUNT)) &&
+        (value.stopReason === undefined || value.stopReason === "frames" || isOneOf(POINT_STOP_REASONS, value.stopReason)) &&
+        (value.pointId === undefined || isInteger(value.pointId, 1, Number.MAX_SAFE_INTEGER));
       if (!ok) throw new ProtocolError("execution result is malformed");
       break;
     }
@@ -1001,6 +1179,10 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
     case "autostart": {
       if (!isOneOf(RUN_STATES, value.state)) throw new ProtocolError(`${op} result is malformed`);
       if (op === "reset" && value.pc !== undefined && !isInteger(value.pc, 0, 0xffff)) throw new ProtocolError("reset result is malformed");
+      if (op === "autostart" && !(value.emulatorFlaw === undefined || typeof value.emulatorFlaw === "string")) throw new ProtocolError("autostart result is malformed");
+      if (op === "autostart" && !(value.joysticksCentred === undefined || (Array.isArray(value.joysticksCentred) && value.joysticksCentred.every((port) => port === 1 || port === 2)))) {
+        throw new ProtocolError("autostart result is malformed");
+      }
       break;
     }
     case "programLoad": {
@@ -1013,16 +1195,16 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
       break;
     }
     case "keyboard": {
-      if (!isInteger(value.queuedBytes, 1, MAX_KEYBOARD_BYTES)) throw new ProtocolError("keyboard result is malformed");
+      if (!isInteger(value.queuedBytes, 1, MAX_KEYBOARD_BYTES) || !(value.emulatorFlaw === undefined || typeof value.emulatorFlaw === "string")) throw new ProtocolError("keyboard result is malformed");
       break;
     }
     case "breakpoint": {
-      const ok = Array.isArray(value.breakpoints) ? value.breakpoints.every(isBreakpoint) : isBreakpoint(value);
+      const ok = Array.isArray(value.breakpoints) ? value.breakpoints.every(isBreakpoint) : isRemoved(value) || isBreakpoint(value);
       if (!ok) throw new ProtocolError("breakpoint result is malformed");
       break;
     }
     case "watchpoint": {
-      const ok = Array.isArray(value.watchpoints) ? value.watchpoints.every(isWatchpoint) : isWatchpoint(value);
+      const ok = Array.isArray(value.watchpoints) ? value.watchpoints.every(isWatchpoint) : isRemoved(value) || isWatchpoint(value);
       if (!ok) throw new ProtocolError("watchpoint result is malformed");
       break;
     }
@@ -1031,6 +1213,8 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
       const ok =
         typeof value.match === "boolean" &&
         isInteger(value.mismatchingPixels, 0, 1 << 20) &&
+        isInteger(value.comparedPixels, 1, 1 << 20) &&
+        (value.mismatchingPixels as number) <= (value.comparedPixels as number) &&
         typeof value.mismatchRatio === "number" &&
         value.mismatchRatio >= 0 &&
         value.mismatchRatio <= 1 &&
@@ -1059,6 +1243,11 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
       if (!ok) throw new ProtocolError("snapshot result is malformed");
       break;
     }
+    case "snapshotFile": {
+      const ok = (value.exported === true && isInteger(value.bytes, 1, 0xffff_ffff)) || (value.restored === true && isOneOf(RUN_STATES, value.state));
+      if (!ok) throw new ProtocolError("snapshotFile result is malformed");
+      break;
+    }
     case "cpuHistory": {
       const ok =
         Array.isArray(value.entries) &&
@@ -1075,6 +1264,29 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
       if (!ok) throw new ProtocolError("cpuHistory result is malformed");
       break;
     }
+    case "trace": {
+      const ok =
+        Array.isArray(value.hits) &&
+        isInteger(value.frames, 0, MAX_TRACE_FRAMES) &&
+        isOneOf(TRACE_ENDS, value.end) &&
+        isInteger(value.pc, 0, 0xffff) &&
+        value.hits.every(
+          (hit) =>
+            isObject(hit) &&
+            isInteger(hit.point, 0, MAX_TRACE_POINTS - 1) &&
+            isInteger(hit.pc, 0, 0xffff) &&
+            isHexData(hit.bytes) &&
+            typeof hit.text === "string" &&
+            (["a", "x", "y", "sp"] as const).every((name) => isInteger(hit[name], 0, 0xff)) &&
+            isInteger(hit.frame, 0, MAX_TRACE_FRAMES) &&
+            isInteger(hit.rasterLine, 0, 511) &&
+            isInteger(hit.rasterCycle, 0, 127) &&
+            (hit.address === undefined || isInteger(hit.address, 0, 0xffff)) &&
+            (hit.value === undefined || isInteger(hit.value, 0, 0xff)),
+        );
+      if (!ok) throw new ProtocolError("trace result is malformed");
+      break;
+    }
     case "backtrace": {
       const ok =
         Array.isArray(value.frames) &&
@@ -1091,6 +1303,10 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
       break;
     }
     case "profile": {
+      if ("cleared" in value) {
+        if (value.cleared !== true) throw new ProtocolError("profile result is malformed");
+        break;
+      }
       const ok =
         Array.isArray(value.entries) &&
         value.entries.every(
@@ -1111,8 +1327,10 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         isObject(range) &&
         isInteger(range.start, 0, 0xffff) &&
         isInteger(range.end, 0, 0xffff) &&
-        (["execute", "read", "write"] as const).every((flag) => typeof range[flag] === "boolean");
-      const ok = Array.isArray(value.ranges) ? value.ranges.every(isRange) : value.cleared === true;
+        isInteger(range.flags, 1, 0xff);
+      const ok = Array.isArray(value.ranges)
+        ? value.ranges.every(isRange) && (value.next === undefined || isInteger(value.next, 0, 0xffff))
+        : value.cleared === true;
       if (!ok) throw new ProtocolError("memmap result is malformed");
       break;
     }
@@ -1168,8 +1386,8 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         isObject(chip) &&
         (chip.id === 1 || chip.id === 2) &&
         (["portA", "portB", "ddrA", "ddrB", "controlA", "controlB", "interruptStatus"] as const).every((name) => isInteger(chip[name], 0, 0xff)) &&
-        isInteger(chip.timerA, 0, 0xffff) &&
-        isInteger(chip.timerB, 0, 0xffff) &&
+        isInteger(chip.interruptMask, 0, 0x1f) &&
+        (["timerA", "timerB", "latchA", "latchB"] as const).every((name) => isInteger(chip[name], 0, 0xffff)) &&
         isObject(chip.tod) &&
         isInteger(chip.tod.hours, 0, 23) &&
         isInteger(chip.tod.minutes, 0, 99) &&
@@ -1211,7 +1429,11 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
       break;
     }
     case "joystick": {
-      const ok = (value.port === 1 || value.port === 2) && isOneOf(JOYSTICK_DIRECTIONS, value.direction) && typeof value.fire === "boolean";
+      const ok =
+        (value.port === 1 || value.port === 2) &&
+        isOneOf(JOYSTICK_DIRECTIONS, value.direction) &&
+        typeof value.fire === "boolean" &&
+        (value.emulatorFlaw === undefined || typeof value.emulatorFlaw === "string");
       if (!ok) throw new ProtocolError("joystick result is malformed");
       break;
     }