@henols/c64-re-tools 2.0.0-rc.13 → 2.0.0-rc.16

package/src/mcp/tools/machine.ts

@@ -3,8 +3,9 @@
 import { z } from "zod";
 
 import { formatC64Address } from "../../c64.ts";
+import { PACKAGE } from "../../package.ts";
 import { VIDEO_STANDARDS } from "../../protocol/messages.ts";
-import { RESET_MODES, RUN_STATES, WINDOW_ACTIONS } from "../../protocol/vice.ts";
+import { POINT_STOP_REASONS, RESET_MODES, RUN_STATES, WINDOW_ACTIONS } from "../../protocol/vice.ts";
 import { AddressOutput, defineTool } from "../server.ts";
 
 export const c64Status = defineTool({
@@ -14,7 +15,9 @@ export const c64Status = defineTool({
     "Get the state of the C64. The result tells if the CPU runs or has stopped, the video standard (pal or ntsc), " +
     "and if warp mode is on. It also tells if the emulator window is open (window). " +
     "When the CPU has stopped, the result also gives the program counter (pc). " +
-    "cartridge is true while a cartridge from c64_autostart is attached: a reset keeps it, and an autostart of another file detaches it.",
+    "When a breakpoint, a watchpoint or a JAM opcode stopped the CPU, stopReason tells which, and pointId gives the id of the breakpoint or watchpoint. " +
+    "cartridge is true while a cartridge from c64_autostart is attached: a reset keeps it, and an autostart of another file detaches it. " +
+    "version is the c64-re-tools version of this MCP server.",
   inputSchema: z.object({}).strict(),
   outputSchema: z.object({
     state: z.enum(RUN_STATES),
@@ -22,7 +25,10 @@ export const c64Status = defineTool({
     warp: z.boolean(),
     window: z.boolean().describe("true when the emulator window is open (c64_window)"),
     pc: AddressOutput.optional().describe("program counter. Only when the CPU is stopped"),
+    stopReason: z.enum(POINT_STOP_REASONS).optional().describe("what stopped the CPU. Only when a breakpoint, a watchpoint or a JAM opcode stopped it"),
+    pointId: z.number().int().min(1).optional().describe("the id of the breakpoint or watchpoint that stopped the CPU"),
     cartridge: z.boolean().describe("true while a cartridge from c64_autostart is attached"),
+    version: z.string().describe("the c64-re-tools version of this MCP server"),
   }),
   readOnly: true,
   async run(_input, session) {
@@ -33,7 +39,10 @@ export const c64Status = defineTool({
       warp: status.warp,
       window: status.window,
       cartridge: status.cartridge,
+      version: PACKAGE.version,
       ...(status.pc === undefined ? {} : { pc: formatC64Address(status.pc) }),
+      ...(status.stopReason === undefined ? {} : { stopReason: status.stopReason }),
+      ...(status.pointId === undefined ? {} : { pointId: status.pointId }),
     };
   },
 });

package/src/mcp/tools/media.ts

@@ -23,6 +23,7 @@ export const c64Autostart = defineTool({
     "A cartridge stays in the C64 through every reset, as on a real C64. An autostart of a file that is not a cartridge detaches it first. " +
     "Both joysticks are centred first: joystick port 1 uses the keyboard lines, and a held direction changes the RUN that the autostart types. " +
     "Without index, a disk image loads like LOAD\"*\",8,1. index selects one directory entry by its number in the c64-disk directory list (0 is the first entry). " +
+      "The tool refuses an index of a DEL entry, or an index after the last entry. " +
     "The machine runs when this tool returns, and the load continues.",
   inputSchema: z
     .object({

package/src/mcp/tools/memory.ts

@@ -12,6 +12,8 @@ import { AddressInput, AddressOutput, Byte, defineTool, HexData, HexDataInput, M
 /** With out, a read or a disassembly can be larger than one answer of the session: it is read in parts (D39). */
 const MAX_MEMORY_READ_OUT = 0x10000;
 const MAX_DISASSEMBLE_OUT = 32768;
+/** A memory byte in a result: two lowercase hex digits, as memory data is. */
+const HexByte = z.string().regex(/^[0-9a-f]{2}$/);
 
 export const c64MemoryRead = defineTool({
   name: "c64_memory_read",
@@ -182,6 +184,7 @@ export const c64MemoryCompare = defineTool({
   description:
     `Compare two memory ranges of size bytes (1 to ${MAX_COMPARE_SIZE}). Each range has its own address, space and view. ` +
     `The result tells if they are equal, how many bytes differ, and the first ${MAX_COMPARE_DIFFERENCES} differences with their offset. ` +
+    "The bytes of a difference are lowercase hex. " +
     "This does not change the run state of the machine.",
   inputSchema: z
     .object({ left: Location, right: Location, size: z.number().int().min(1).max(MAX_COMPARE_SIZE) })
@@ -189,11 +192,13 @@ export const c64MemoryCompare = defineTool({
   outputSchema: z.object({
     equal: z.boolean(),
     differentBytes: z.number().int().min(0),
-    firstDifferences: z.array(z.object({ offset: z.number().int().min(0), left: Byte, right: Byte })),
+    firstDifferences: z.array(z.object({ offset: z.number().int().min(0), left: HexByte, right: HexByte })),
   }),
   readOnly: true,
   async run(input, session) {
-    return session.memoryCompare(input);
+    const result = await session.memoryCompare(input);
+    const hex = (byte: number) => byte.toString(16).padStart(2, "0");
+    return { ...result, firstDifferences: result.firstDifferences.map((difference) => ({ ...difference, left: hex(difference.left), right: hex(difference.right) })) };
   },
 });
 

package/src/mcp/tools/video.ts

@@ -3,7 +3,7 @@
 
 import { z } from "zod";
 
-import { formatC64Address } from "../../c64.ts";
+import { formatC64Address, formatSprite, formatVicii } from "../../c64.ts";
 import { WireFailure } from "../../protocol/messages.ts";
 import { CIA_SELECTIONS, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_OBSERVE_BYTES, MAX_OBSERVE_RANGES, SPACES, VICII_MODES, type ObserveParams } from "../../protocol/vice.ts";
 import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
@@ -31,8 +31,7 @@ export const c64Vicii = defineTool({
   }),
   readOnly: true,
   async run(_input, session) {
-    const state = await session.vicii();
-    return { ...state, screenAddress: formatC64Address(state.screenAddress), graphicsAddress: formatC64Address(state.graphicsAddress) };
+    return formatVicii(await session.vicii());
   },
 });
 
@@ -62,7 +61,7 @@ export const c64Sprite = defineTool({
   readOnly: true,
   async run(input, session) {
     const result = await session.sprites(input.sprites ?? []);
-    return { sprites: result.sprites.map((sprite) => ({ ...sprite, dataAddress: formatC64Address(sprite.dataAddress) })) };
+    return { sprites: result.sprites.map(formatSprite) };
   },
 });
 

package/src/native/ghidra/language/c64rt_6510.slaspec

@@ -263,13 +263,16 @@ REL: target      is rel [ target = inst_next + rel; ] { export *:2 target; }
 }
 
 # BRK skips its padding byte: the return address is two bytes on.
+# The vector at $FFFE is in ROM unless the program banks the KERNAL out, and
+# the analysis cannot know the banking. Thus BRK ends the flow, and Ghidra
+# does not follow the RAM bytes at $FFFE of a flat image (R2-07).
 :BRK is op=0x00 {
 	*:2 (SP - 1) = inst_next + 1;
 	SP = SP - 2;
 	pushP(1);
 	I = 1;
 	local vector:2 = 0xfffe;
-	goto [*:2 vector];
+	return [*:2 vector];
 }
 
 :CLC is op=0x18 { C = 0; }

package/src/protocol/vice.ts

@@ -337,8 +337,16 @@ export interface MachineStatus {
   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;
@@ -406,6 +414,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. */
@@ -425,6 +437,8 @@ export interface RunUntilResult {
   /** 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 {
@@ -469,7 +483,8 @@ export interface ViceOperations {
   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" };
     /** `next`: more ranges follow from this address; read again from there. */
@@ -646,9 +661,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"]);
@@ -1011,7 +1028,9 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         typeof value.warp === "boolean" &&
         typeof value.window === "boolean" &&
         (value.pc === undefined || isInteger(value.pc, 0, 0xffff)) &&
-        typeof value.cartridge === "boolean";
+        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;
     }
@@ -1080,7 +1099,8 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         isOneOf(STOP_REASONS, value.stopReason) &&
         isOneOf(RUN_STATES, value.state) &&
         isInteger(value.pc, 0, 0xffff) &&
-        isOneOf(SPACES, value.space);
+        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;
     }
@@ -1089,7 +1109,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;
     }
@@ -1198,6 +1220,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(