@henols/c64-re-tools 2.0.0-rc.7 → 2.0.0-rc.8

package/skills/c64-unpacker/SKILL.md

@@ -36,7 +36,7 @@ node <skill>/scripts/unpack.ts loads original/game.d64 --steps parts.json --out
 | `--timeout-frames 3000` | How many frames the program can run before the capture stops (default 3000). |
 | `--frames 3000` | `trace` only: how many frames the program runs (default 3000). |
 | `--entry '$c000'` | `trace`, `stages` and `capture`: start the program at this address. Without it, the script types RUN. A file that is not a BASIC program at `$0801` needs it. |
-| `--steps input.json` | Input for the program, right after it starts: a JSON list of steps. Use it when an intro waits for a key or a menu waits for a choice. |
+| `--steps input.json` | Input for the program, right after it starts: a JSON list of steps. Use it when an intro waits for a key or a menu waits for a choice. The scripts start the program as a c64-testing scenario does. Thus the same steps in a scenario get the program to the entry at the same time. |
 | `--drive` | `loads` only: each capture also writes the 2 KiB RAM of the 1541 drive as `drive8.prg`. |
 | `--min-block 64` | `loads` only: the smallest block of changed memory that becomes a segment (default 64). The result counts smaller changes as `smallChanges`. |
 | `--min-stage 64` | `stages` and `capture`: the smallest block of written memory that starts a new stage when the CPU executes it (default 64). |
@@ -76,7 +76,7 @@ A `type` step puts keys in the keyboard queue of the KERNAL. A program that read
    - `image.bin`: all 64 KiB of RAM at the entry.
    - `image.json`: the entry, the segments, the vectors and the stages. A segment is a block that a stage wrote. A block is not a segment when it holds the entry of a later stage before the program, and no stage wrote over that entry. The block with the capture entry is always a segment. Segments do not overlap. `writtenBy` tells the last stage that wrote into the segment.
    - One PRG for each segment.
-   - `entry_state.json`: the registers, `$00` and `$01`, pages 0 to 3, the VIC, SID and CIA registers, and the vectors. `differsFromReset` lists the bytes that are not as a clean C64 has them at READY. A rebuild must make these bytes the same, because the program can read them.
+   - `entry_state.json`: the registers, `$00` and `$01`, pages 0 to 3, the VIC, SID and CIA registers, and the vectors. `cia` gives the CIA timer latches and interrupt masks. `differsFromReset` lists the bytes that are not as a clean C64 has them at READY. A rebuild must make these bytes the same, because the program can read them.
 5. Make sure that the result is the application: the code at the entry must not be the unpacker again. A segment can be data that a loader left, for example intro graphics. Keep it until other evidence shows that the program does not use it.
 6. Give `image.bin` to the c64-static-analysis skill with its `--flat64k` option, or give it the segment PRGs.
 7. Use `--range` only when you know the area of the program. Then the capture writes that one segment.

package/skills/c64-unpacker/scripts/loads.ts

@@ -4,8 +4,8 @@
 // image with its entry state, and with --drive the drive RAM as a PRG for
 // knowledge space drive8. No tool guesses where a load ends: the steps decide.
 
-import { COVERAGE, formatC64Address, parseC64Address, textToPetscii } from "#src/c64.ts";
-import { autostartLoaded, LOAD_LIMIT_FRAMES } from "#src/host-client/autostart.ts";
+import { COVERAGE, formatC64Address, parseC64Address } from "#src/c64.ts";
+import { autostartLoaded, LOAD_LIMIT_FRAMES, RUN_LIMIT_FRAMES, typeRun } from "#src/host-client/autostart.ts";
 import { readCoverage } from "#src/host-client/coverage.ts";
 import { ACTION_STEP_KEYS, ACTION_STEP_KINDS, checkActionStep, isObject, runActionStep, type ActionStep } from "#src/host-client/steps.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
@@ -113,7 +113,8 @@ export async function loads(program: string, options: { out: string; steps: Load
       previous.fill(0, load, Math.min(0x10000, load + bytes.length - 2));
       loadedProgram = bytes;
       await client.memmap({ action: "clear" });
-      await client.keyboard(textToPetscii("RUN\n"));
+      // RUN as c64-testing types it: the steps start at the same time as a scenario's (D62).
+      if (!(await typeRun(client))) return { output: { loaded: false, reason: `After RUN, BASIC ran no program line in ${RUN_LIMIT_FRAMES} frames.` }, failed: true };
     } else {
       // A disk, tape or cartridge: VICE loads and starts it. The RAM test of the KERNAL puts back what it writes.
       previous = await readRam(client, 0x0000, 0x10000);

package/skills/c64-unpacker/scripts/machine.ts

@@ -14,10 +14,19 @@ export const IO_AREAS = { vic: [0xd000, 0x2f], sid: [0xd400, 0x1d], cia1: [0xdc0
 /** Frames from a hard reset to the READY prompt, with margin. */
 export const READY_FRAMES = 200;
 
+/** What no register read of a CIA gives (D63). */
+export interface CiaHidden {
+  latchA: number;
+  latchB: number;
+  interruptMask: number;
+}
+
 export interface MachineState {
   port: Buffer;
   pages: Buffer;
   io: Record<keyof typeof IO_AREAS, Buffer>;
+  /** The timer latches and the interrupt mask of each CIA. */
+  cia: { cia1: CiaHidden; cia2: CiaHidden };
   romVectors: Buffer;
 }
 
@@ -36,8 +45,9 @@ export async function machineState(client: ViceSessionClient): Promise<MachineSt
   const pages = await readRam(client, 0x0000, 0x400);
   const io = {} as Record<keyof typeof IO_AREAS, Buffer>;
   for (const [name, [address, size]] of Object.entries(IO_AREAS)) io[name as keyof typeof IO_AREAS] = Buffer.from((await client.ioRead(address, size)).data, "hex");
+  const [cia1, cia2] = (await client.cia("both")).chips.map(({ latchA, latchB, interruptMask }) => ({ latchA, latchB, interruptMask }));
   const romVectors = Buffer.from((await client.memoryRead({ address: 0xfffa, size: 6, space: "c64", view: "cpu" })).data, "hex");
-  return { port, pages, io, romVectors };
+  return { port, pages, io, cia: { cia1: cia1!, cia2: cia2! }, romVectors };
 }
 
 const word = (bytes: Buffer, offset: number) => formatC64Address(bytes[offset]! | (bytes[offset + 1]! << 8));
@@ -60,6 +70,8 @@ export function entryState(registers: Registers, state: MachineState, vectors: R
     cpuPort: { $00: state.port[0], $01: state.port[1] },
     pages: Object.fromEntries([0, 1, 2, 3].map((page) => [formatC64Address(page << 8), state.pages.subarray(page << 8, (page + 1) << 8).toString("hex")])),
     io: Object.fromEntries(Object.entries(IO_AREAS).map(([name, [address]]) => [name, { from: formatC64Address(address), bytes: state.io[name as keyof typeof IO_AREAS].toString("hex") }])),
+    // The CIA latches and interrupt masks: write-only on the chip, so the I/O bytes do not hold them (D63).
+    cia: state.cia,
     vectors,
     ...(differsFromReset === undefined ? {} : { differsFromReset }),
   };

package/skills/c64-unpacker/scripts/unpack.ts

@@ -8,8 +8,8 @@
 
 import { parseArgs } from "node:util";
 
-import { COVERAGE, EXECUTE, formatC64Address, parseC64Address, READ, textToPetscii, WRITE } from "#src/c64.ts";
-import { autostartLoaded, LOAD_LIMIT_FRAMES } from "#src/host-client/autostart.ts";
+import { COVERAGE, EXECUTE, formatC64Address, parseC64Address, READ, WRITE } from "#src/c64.ts";
+import { autostartLoaded, LOAD_LIMIT_FRAMES, RUN_LIMIT_FRAMES, typeRun } from "#src/host-client/autostart.ts";
 import { readCoverage, writtenBlocks } from "#src/host-client/coverage.ts";
 import { checkActionSteps, runActionStep, type ActionStep } from "#src/host-client/steps.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
@@ -107,10 +107,8 @@ async function trace(program: string, options: { frames: number; entry?: number;
   const client = await ViceSessionClient.open({ videoStandard: "pal" });
   try {
     // Loaded but not started, so the memory map can start empty: the KERNAL start-up writes all of RAM.
-    if (!(await autostartLoaded(client, program, bytes))) return { output: { traced: false, reason: `The program was not in memory at ${formatC64Address(load)} after ${LOAD_LIMIT_FRAMES} frames.` }, failed: true };
-    await client.memmap({ action: "clear" });
-    if (options.entry !== undefined) await client.registersSet("c64", { pc: options.entry });
-    else await client.keyboard(textToPetscii("RUN\n"));
+    const notStarted = await startLoaded(client, program, bytes, options.entry);
+    if (notStarted !== undefined) return { output: { traced: false, reason: notStarted }, failed: true };
     const stepFailed = await runSteps(client, options.steps);
     if (stepFailed !== undefined) return { output: { traced: false, reason: stepFailed }, failed: true };
     let ran = 0;
@@ -191,6 +189,26 @@ const SYS_FRAMES = 50;
  * The first PC in the program after its BASIC text, for a SYS whose address
  * BASIC computes: an exec breakpoint over that part of the program stops there.
  */
+/**
+ * Starts the program as a c64-testing scenario does (D62): hard reset, load,
+ * an empty memory map, then RUN up to the first BASIC line, or the pc at
+ * `entry`. Gives why it did not start.
+ */
+async function startLoaded(client: ViceSessionClient, program: string, bytes: Uint8Array, entry: number | undefined): Promise<string | undefined> {
+  await client.reset({ mode: "hard", run: false });
+  if (!(await autostartLoaded(client, program, bytes))) return `The program was not in memory at ${formatC64Address(bytes[0]! | (bytes[1]! << 8))} after ${LOAD_LIMIT_FRAMES} frames.`;
+  await client.memmap({ action: "clear" });
+  if (entry !== undefined) await client.registersSet("c64", { pc: entry });
+  else if (!(await typeRun(client))) return `After RUN, BASIC ran no program line in ${RUN_LIMIT_FRAMES} frames.`;
+  return undefined;
+}
+
+/** The raster position now: where a step's frames end (D62). */
+async function rasterAt(client: ViceSessionClient): Promise<{ line: number; cycle: number }> {
+  const { timing } = await client.observe({ timing: true });
+  return { line: timing!.rasterLine, cycle: timing!.rasterCycle };
+}
+
 async function firstPcAfterBasic(client: ViceSessionClient, from: number, to: number): Promise<number | undefined> {
   return from > to ? undefined : firstPcIn(client, [{ start: from, end: to }]);
 }
@@ -246,10 +264,11 @@ async function follow(
   const load = bytes[0]! | (bytes[1]! << 8);
   const basic = basicStart(bytes);
   if (options.entry === undefined && basic === undefined) throw new UsageError(NO_BASIC);
-  if (!(await autostartLoaded(client, program, bytes))) return { stages: [], frames: 0, reached: false, failed: `The program was not in memory at ${formatC64Address(load)} after ${LOAD_LIMIT_FRAMES} frames.` };
-  await client.memmap({ action: "clear" });
-  if (options.entry !== undefined) await client.registersSet("c64", { pc: options.entry });
-  else await client.keyboard(textToPetscii("RUN\n"));
+  const notStarted = await startLoaded(client, program, bytes, options.entry);
+  if (notStarted !== undefined) return { stages: [], frames: 0, reached: false, failed: notStarted };
+  // The frames of each step end where a scenario's do: the first step counts from RUN, a later one from where it starts (D62).
+  let anchor: { line: number; cycle: number } | undefined = await rasterAt(client);
+  const framed = () => (anchor === undefined ? {} : { anchor });
   const found: Stage[] = [];
   const start = options.entry ?? basic!.sys?.address ?? (await firstPcAfterBasic(client, basic!.basicEnd, load + bytes.length - 3));
   if (start === undefined) return { stages: [], frames: 0, reached: false, failed: `After RUN, the CPU did not execute the program after its BASIC text (${formatC64Address(basic!.basicEnd)} on) in ${SYS_FRAMES} frames. Give --entry <address>.` };
@@ -311,7 +330,7 @@ async function follow(
       await client.snapshot({ action: "save", name: CALL_SNAPSHOT });
       const point = await client.breakpoint({ action: "add", address: back, space: "c64" });
       try {
-        const run = await client.execution({ action: "advance-frames", count: frames, space: "c64" });
+        const run = await client.execution({ action: "advance-frames", count: frames, space: "c64", ...framed() });
         if ((run.pc ?? (await client.registersGet("c64")).pc) === back) return run.advancedFrames ?? 0;
         await client.snapshot({ action: "restore", name: CALL_SNAPSHOT });
         return undefined;
@@ -330,7 +349,7 @@ async function follow(
         }
         const written = (address: number) => ((stage.map[address]! | map[address]!) & COVERAGE.ramWrite) !== 0;
         await arm(stagePoints(candidates, stage.own, written, stage.called));
-        const run = await client.execution({ action: "advance-frames", count: left, space: "c64" });
+        const run = await client.execution({ action: "advance-frames", count: left, space: "c64", ...framed() });
         const advanced = run.advancedFrames ?? 0;
         used += advanced;
         left -= advanced;
@@ -365,13 +384,21 @@ async function follow(
 
   /** Tracks the stages for some frames; true when the CPU got to stopAt. */
   const track = async (frames: number): Promise<boolean> => {
+    anchor ??= await rasterAt(client);
+    try {
+      return await trackFrom(frames);
+    } finally {
+      anchor = undefined;
+    }
+  };
+  const trackFrom = async (frames: number): Promise<boolean> => {
     let left = frames;
     let stopped = false;
     while (left > 0 && !ended && !stopped && found.length < MAX_STAGES) {
       await client.snapshot({ action: "save", name: STAGE_SNAPSHOT });
       await client.memmap({ action: "clear" });
       const chunk = Math.min(STAGE_CHUNK_FRAMES, left);
-      const first = await client.execution({ action: "advance-frames", count: chunk, space: "c64" });
+      const first = await client.execution({ action: "advance-frames", count: chunk, space: "c64", ...framed() });
       const firstPc = first.pc ?? (await client.registersGet("c64")).pc;
       const map = await readCoverage(client);
       const candidates = stageCandidates(stage.map, map, stage.own, options.minStage, stage.called);

package/src/c64.ts

@@ -163,7 +163,9 @@ const MIN_BASIC_LOAD = 0x0400;
  * zero, the "marker" is the first machine code after the BASIC text (SYS
  * lines that jump right behind themselves). The stored links are not read:
  * BASIC relinks a loaded program, and a crack can store odd links to hide
- * lines from LIST. A load address below $0400 is a memory dump (F-12).
+ * lines from LIST. A load address below $0400 is a memory dump (F-12), and so
+ * is a file whose bytes run past $ffff: a 64 KiB dump from $0000 always does
+ * (b2/01, R3-02).
  */
 export function parseTokenized(program: Uint8Array): TokenizedProgram {
   if (program.length < 4) return { reason: "The file is too short for a BASIC program." };
@@ -171,6 +173,9 @@ export function parseTokenized(program: Uint8Array): TokenizedProgram {
   if (loadAddress < MIN_BASIC_LOAD) {
     return { reason: `The load address ${formatC64Address(loadAddress)} is below $0400, in the zero page, the stack or the system pages. The file is a memory dump or machine code, not a BASIC program.` };
   }
+  if (loadAddress + program.length - 2 > 0x10000) {
+    return { reason: `The file holds ${program.length - 2} bytes from ${formatC64Address(loadAddress)}, which runs past $ffff. The file is a memory dump, not a BASIC program.` };
+  }
   const lines: TokenizedLine[] = [];
   let at = 2;
   const ended = (basicEnd: number): TokenizedProgram => ({ loadAddress, basicEnd, textBytes: at, lines });

package/src/host/vice/adapter.ts

@@ -6,6 +6,7 @@ import { type Comparison, type Condition, type BacktraceFrame, type HistoryEntry
 import { COVERAGE, formatC64Address, formatC64Byte } from "../../c64.ts";
 import { decodeDisplay, decodePalette, visibleFrame, type IndexedFrame } from "./screen.ts";
 import type { TextMonitor } from "./text-monitor.ts";
+import type { CiaHidden } from "./chips.ts";
 import {
   BinaryMonitor,
   Command,
@@ -431,6 +432,19 @@ export class ViceAdapter {
     return bytes.toString("hex");
   }
 
+  /**
+   * The timer latches and the interrupt mask of the CIA at `base`, from VICE's
+   * text-monitor dump: no register read gives them (D63).
+   */
+  async ciaHidden(base: 0xdc00 | 0xdd00): Promise<CiaHidden> {
+    const answer = await this.#computerText(`io ${hex4(base)}`);
+    const mask = /\(mask: ([0-9a-f]{2})\)/i.exec(answer);
+    const latchA = /Timer A: [0-9a-f]{4} \(latched ([0-9a-f]{4})\)/i.exec(answer);
+    const latchB = /Timer B: [0-9a-f]{4} \(latched ([0-9a-f]{4})\)/i.exec(answer);
+    if (mask === null || latchA === null || latchB === null) throw unknownForm("CIA dump", answer.split("\n"));
+    return { latchA: Number.parseInt(latchA[1]!, 16), latchB: Number.parseInt(latchB[1]!, 16), interruptMask: Number.parseInt(mask[1]!, 16) & 0x1f };
+  }
+
   /** Reads C64 I/O registers through the I/O bank, whatever the CPU has banked in, without side effects. */
   async readIo(start: number, size: number): Promise<Uint8Array> {
     const response = await this.#monitor.request(

package/src/host/vice/chips.ts

@@ -57,8 +57,15 @@ function bcd(value: number): number {
   return (value >> 4) * 10 + (value & 0x0f);
 }
 
+/** The parts of a CIA that no register read gives: the timer latches and the interrupt mask. */
+export interface CiaHidden {
+  latchA: number;
+  latchB: number;
+  interruptMask: number;
+}
+
 /** `registers` holds $dc00-$dc0f or $dd00-$dd0f. TOD hours become 0-23. */
-export function decodeCia(id: 1 | 2, registers: Uint8Array): CiaState {
+export function decodeCia(id: 1 | 2, registers: Uint8Array, hidden: CiaHidden): CiaState {
   const word = (low: number) => registers[low]! | (registers[low + 1]! << 8);
   const hourRegister = registers[0x0b]!;
   const pm = (hourRegister & 0x80) !== 0;
@@ -70,9 +77,12 @@ export function decodeCia(id: 1 | 2, registers: Uint8Array): CiaState {
     ddrB: registers[0x03]!,
     timerA: word(0x04),
     timerB: word(0x06),
+    latchA: hidden.latchA,
+    latchB: hidden.latchB,
     controlA: registers[0x0e]!,
     controlB: registers[0x0f]!,
     interruptStatus: registers[0x0d]!,
+    interruptMask: hidden.interruptMask,
     tod: {
       hours: (bcd(hourRegister & 0x1f) % 12) + (pm ? 12 : 0),
       minutes: bcd(registers[0x0a]! & 0x7f),

package/src/host/vice/screen.ts

@@ -4,6 +4,7 @@
 import { crc32, deflateSync } from "node:zlib";
 
 import type { VideoStandard } from "../../protocol/messages.ts";
+import { FRAME_SIZE } from "../../protocol/vice.ts";
 
 export interface IndexedFrame {
   width: number;
@@ -44,8 +45,8 @@ export function decodeDisplay(body: Buffer): RawDisplay {
  * offsets: PAL 384×272, NTSC 384×247.
  */
 const VISIBLE: Record<VideoStandard, { dx: number; dy: number; width: number; height: number }> = {
-  pal: { dx: -32, dy: -36, width: 384, height: 272 },
-  ntsc: { dx: -32, dy: -23, width: 384, height: 247 },
+  pal: { dx: -32, dy: -36, ...FRAME_SIZE.pal },
+  ntsc: { dx: -32, dy: -23, ...FRAME_SIZE.ntsc },
 };
 
 /** Crops the visible bordered frame out of VICE's full raster buffer. */

package/src/host/vice/session.ts

@@ -381,12 +381,21 @@ export class ViceSession implements ViceSessionHandle {
           this.#cartridge = false;
           this.#replaceStaged("cartridge", undefined);
         }
+        // Port 1 shares the keyboard lines: a held direction types keys into the RUN that the autostart types (R3-05).
+        const centred: Array<1 | 2> = [];
+        for (const [port, joystick] of this.#joysticks) {
+          if (joystick.direction === "center" && !joystick.fire) continue;
+          const centre: JoystickState = { port, direction: "center", fire: false };
+          await this.#observe(() => this.#machine.setJoystick(centre));
+          this.#joysticks.set(port, centre);
+          centred.push(port);
+        }
         await this.#runningCommand(() => this.#machine.autostart(file, index, run));
         if (type === "crt") this.#cartridge = true;
         this.#replaceStaged(stagedKind(type), file);
         // A reset sets the CPU clock back, so the stopwatch starts again.
         this.#timingStart = 0n;
-        return { state: "running", ...(type === "tap" && this.#inputFlaw !== undefined ? { emulatorFlaw: this.#inputFlaw } : {}) };
+        return { state: "running", ...(type === "tap" && this.#inputFlaw !== undefined ? { emulatorFlaw: this.#inputFlaw } : {}), ...(centred.length === 0 ? {} : { joysticksCentred: centred }) };
       }
       case "diskAttach": {
         const { type } = params as ViceOperations["diskAttach"]["params"];
@@ -498,8 +507,7 @@ export class ViceSession implements ViceSessionHandle {
   async #status(): Promise<MachineStatus> {
     const warp = await this.#observe(() => this.#machine.warp());
     // Read after #observe: it resumes a running machine, unless a breakpoint or a JAM stopped it meanwhile.
-    const status: MachineStatus = { state: this.#state, videoStandard: this.#videoStandard, warp, window: this.#mode === "window" };
-    if (this.#cartridge) status.cartridge = true;
+    const status: MachineStatus = { state: this.#state, videoStandard: this.#videoStandard, warp, window: this.#mode === "window", cartridge: this.#cartridge };
     if (status.state === "stopped") status.pc = await this.#pc();
     return status;
   }
@@ -526,7 +534,11 @@ export class ViceSession implements ViceSessionHandle {
     }
     if (params.action === "advance-frames") {
       if (params.count === undefined) throw new WireFailure("invalid-input", "advance-frames needs count, the number of frames");
-      const outcome = await this.#runFrames(params.count);
+      const raster = RASTER[this.#videoStandard];
+      if (params.anchor !== undefined && (params.anchor.line >= raster.lines || params.anchor.cycle >= raster.cycles)) {
+        throw new WireFailure("invalid-input", `The anchor is outside the frame: a ${this.#videoStandard} frame has lines 0-${raster.lines - 1} and cycles 0-${raster.cycles - 1}.`);
+      }
+      const outcome = await this.#runFrames(params.count, undefined, params.anchor);
       return { state: "stopped", pc: outcome.pc, advancedFrames: outcome.frames };
     }
     await this.#stop();
@@ -588,10 +600,11 @@ export class ViceSession implements ViceSessionHandle {
    * checkpoint, a user breakpoint or watchpoint, or a JAM ends the run early.
    * The machine is stopped afterwards.
    */
-  async #runFrames(limit: number, target?: { checkpoint: number; deferred: boolean }): Promise<{ end: RunEnd; frames: number; pc: number; space: "c64" | "drive8" }> {
+  async #runFrames(limit: number, target?: { checkpoint: number; deferred: boolean }, anchor?: { line: number; cycle: number }): Promise<{ end: RunEnd; frames: number; pc: number; space: "c64" | "drive8" }> {
     await this.#stop();
     const lines = RASTER[this.#videoStandard].lines;
-    const start = await this.#machine.rasterPosition();
+    // A frame ends where the raster passes the anchor; without one, where this run starts.
+    const start = anchor ?? (await this.#machine.rasterPosition());
     const arming = rasterLinesExpression((start.line + Math.floor(lines / 2)) % lines, lines);
     const ending = rasterWindowExpression(start.line, start.cycle, lines);
     const clock = await this.#machine.addCheckpoint({ start: 0x0000, end: 0xffff, operation: 0x04, space: "c64" });
@@ -920,7 +933,10 @@ export class ViceSession implements ViceSessionHandle {
   async #cias(which: CiaSelection): Promise<CiaState[]> {
     const ids: Array<1 | 2> = which === "both" ? [1, 2] : [Number(which) as 1 | 2];
     const chips = [];
-    for (const id of ids) chips.push(decodeCia(id, await this.#machine.readIo(id === 1 ? 0xdc00 : 0xdd00, 0x10)));
+    for (const id of ids) {
+      const base = id === 1 ? 0xdc00 : 0xdd00;
+      chips.push(decodeCia(id, await this.#machine.readIo(base, 0x10), await this.#machine.ciaHidden(base)));
+    }
     return chips;
   }
 

package/src/host-client/autostart.ts

@@ -36,10 +36,20 @@ export const RUN_LIMIT_FRAMES = 300;
  */
 export async function runProgram(client: ViceSessionClient, path: string, prg: Uint8Array): Promise<"not-loaded" | "not-started" | undefined> {
   if (!(await autostartLoaded(client, path, prg))) return "not-loaded";
+  return (await typeRun(client)) ? undefined : "not-started";
+}
+
+/**
+ * Types RUN at the READY prompt and stops where BASIC starts the first line,
+ * before its SYS. Every tool that starts a loaded program this way reaches
+ * its entry at the same raster line and timer values (D62). False when BASIC
+ * runs no line within RUN_LIMIT_FRAMES.
+ */
+export async function typeRun(client: ViceSessionClient): Promise<boolean> {
   await client.keyboard(textToPetscii("RUN\n"));
   const started = await client.runUntil({
     target: { kind: "memory", address: CURLIN_HIGH, operator: "ne", value: 0xff, space: "c64", view: "ram" },
     timeoutFrames: RUN_LIMIT_FRAMES,
   });
-  return started.reached ? undefined : "not-started";
+  return started.reached;
 }

package/src/host-client/tools.ts

@@ -86,4 +86,4 @@ export async function hostTools(options: ToolCallOptions = {}): Promise<{ host:
 /** Skill scripts see failures and wire limits through the host-client, never the private protocol module. */
 export { WireFailure } from "../protocol/messages.ts";
 export { DISK_ACTIONS } from "../protocol/tools.ts";
-export { JOYSTICK_DIRECTIONS, MAX_BASELINES, MAX_EXECUTION_COUNT, MAX_KEYBOARD_BYTES, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_MEMORY_WRITE, MAX_TIMEOUT_FRAMES } from "../protocol/vice.ts";
+export { JOYSTICK_DIRECTIONS, MAX_BASELINES, MAX_EXECUTION_COUNT, MAX_KEYBOARD_BYTES, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_MEMORY_WRITE, MAX_TIMEOUT_FRAMES, maskCoversFrame } from "../protocol/vice.ts";

package/src/mcp/tools/debug.ts

@@ -41,7 +41,8 @@ export const c64Breakpoint = defineTool({
   description:
     "Manage breakpoints. A breakpoint stops the CPU when it is about to execute the instruction at an address. " +
     "Action add sets one at address in space c64 or drive8. With a condition, it stops only when the condition is true. " +
-    "add returns the new id. Actions remove, enable and disable take that id. remove returns removed true and the id. Action list gives all breakpoints. Each breakpoint shows its condition, when it has one. " +
+    "add returns the new id. Breakpoints and watchpoints take their ids from one counter, so the ids of one kind can have gaps. " +
+    "Actions remove, enable and disable take that id. remove returns removed true and the id. Action list gives all breakpoints. Each breakpoint shows its condition, when it has one. " +
     "Breakpoints stay through a reset.",
   inputSchema: z
     .object({
@@ -84,7 +85,8 @@ export const c64Watchpoint = defineTool({
     "Manage watchpoints. A watchpoint stops the CPU when an instruction reads or writes memory in a range. " +
     `Action add sets one at address for size bytes (1 to ${MAX_WATCH_SIZE}, default 1), with access read, write or read-write. ` +
     "With a condition, it stops only when the condition is true. For a write, a memory condition sees the memory after the write. " +
-    "add returns the new id. Actions remove, enable and disable take that id. remove returns removed true and the id. Action list gives all watchpoints. Each watchpoint shows its condition, when it has one.",
+    "add returns the new id. Breakpoints and watchpoints take their ids from one counter, so the ids of one kind can have gaps. " +
+    "Actions remove, enable and disable take that id. remove returns removed true and the id. Action list gives all watchpoints. Each watchpoint shows its condition, when it has one.",
   inputSchema: z
     .object({
       action: z.enum(CHECKPOINT_ACTIONS),
@@ -205,7 +207,8 @@ export const c64Profile = defineTool({
   name: "c64_profile",
   title: "Cycle profile",
   description:
-    "Get the routines where the C64 CPU spent the most cycles since the session started. " +
+    "Get the routines where the C64 CPU spent the most cycles since the session started or since the last c64_window. " +
+    "After c64_window or a snapshot restore, the emulator can give the cycles to a routine that ran before the restore, for example $fd50. Do not trust the routine addresses then. " +
     `limit is the maximum number of routines (1 to ${MAX_PROFILE}, default 20). ` +
     "Each entry gives the routine address, its total cycles with the routines it calls, and its own cycles. " +
     "percent is the part of all cycles that the routine used itself. " +

package/src/mcp/tools/machine.ts

@@ -22,7 +22,7 @@ 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"),
-    cartridge: z.literal(true).optional().describe("true while a cartridge is attached. Absent when none is"),
+    cartridge: z.boolean().describe("true while a cartridge from c64_autostart is attached"),
   }),
   readOnly: true,
   async run(_input, session) {
@@ -32,8 +32,8 @@ export const c64Status = defineTool({
       videoStandard: status.videoStandard,
       warp: status.warp,
       window: status.window,
+      cartridge: status.cartridge,
       ...(status.pc === undefined ? {} : { pc: formatC64Address(status.pc) }),
-      ...(status.cartridge === undefined ? {} : { cartridge: status.cartridge }),
     };
   },
 });

package/src/mcp/tools/media.ts

@@ -21,6 +21,7 @@ export const c64Autostart = defineTool({
     `Start a program, or a disk, tape or cartridge image, from the project (${list(AUTOSTART_TYPES)}). ` +
     "The C64 resets and loads the file. With run true (the default), it also runs the file. A disk image stays in drive 8. " +
     "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 machine runs when this tool returns, and the load continues.",
   inputSchema: z
@@ -33,6 +34,7 @@ export const c64Autostart = defineTool({
   outputSchema: z.object({
     state: z.enum(RUN_STATES),
     emulatorFlaw: z.string().optional().describe("for a tape image: a known flaw of this VICE version that stops a tape load"),
+    joysticksCentred: z.array(z.union([z.literal(1), z.literal(2)])).optional().describe("the joystick ports that held a direction or fire and were centred before the reset"),
   }),
   readOnly: false,
   async run(input, session) {

package/src/mcp/tools/video.ts

@@ -74,9 +74,12 @@ const CiaOutput = z.object({
   ddrB: Byte,
   timerA: z.number().int().min(0).max(0xffff),
   timerB: z.number().int().min(0).max(0xffff),
+  latchA: z.number().int().min(0).max(0xffff).describe("the value that timer A loads when it underflows"),
+  latchB: z.number().int().min(0).max(0xffff).describe("the value that timer B loads when it underflows"),
   controlA: Byte,
   controlB: Byte,
   interruptStatus: Byte,
+  interruptMask: z.number().int().min(0).max(0x1f).describe("the interrupt sources that are on, as bits 0-4 of the interrupt control register"),
   tod: z.object({ hours: z.number().int(), minutes: z.number().int(), seconds: z.number().int(), tenths: z.number().int() }),
 });
 
@@ -84,8 +87,8 @@ export const c64Cia = defineTool({
   name: "c64_cia",
   title: "CIA state",
   description:
-    "Get the state of CIA 1, CIA 2 or both. The state has the ports, the data direction registers and the current timer values. " +
-    `It also has the control registers, the interrupt flags and the time of day (hours 0 to 23). ${NO_CHANGE}`,
+    "Get the state of CIA 1, CIA 2 or both. The state has the ports, the data direction registers, the current timer values and the timer latches. " +
+    `It also has the control registers, the interrupt flags, the interrupt mask and the time of day (hours 0 to 23). ${NO_CHANGE}`,
   inputSchema: z.object({ cia: z.enum(CIA_SELECTIONS).default("both") }).strict(),
   outputSchema: z.object({ chips: z.array(CiaOutput) }),
   readOnly: true,

package/src/protocol/vice.ts

@@ -168,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 };
 }
 
@@ -256,6 +261,24 @@ 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;
@@ -312,8 +335,8 @@ export interface MachineStatus {
   window: boolean;
   /** Present only while the C64 CPU is stopped. */
   pc?: number;
-  /** Present, true, while a cartridge from an autostart is attached. */
-  cartridge?: true;
+  /** True while a cartridge from an autostart is attached (D64). */
+  cartridge: boolean;
 }
 
 export interface MemoryReadParams {
@@ -370,6 +393,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 {
@@ -421,8 +450,11 @@ export interface ViceOperations {
   /** 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. `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). */
-  autostart: { params: { type: string; index: number; run: boolean }; result: { state: RunState; emulatorFlaw?: string } };
+  /**
+   * `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. */
@@ -748,7 +780,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";
@@ -760,6 +792,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": {
@@ -972,7 +1011,7 @@ 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)) &&
-        (value.cartridge === undefined || value.cartridge === true);
+        typeof value.cartridge === "boolean";
       if (!ok) throw new ProtocolError("status result is malformed");
       break;
     }
@@ -1059,6 +1098,9 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
       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": {
@@ -1235,8 +1277,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) &&