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

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) &&

package/src/trace.ts

@@ -1,7 +1,8 @@
 // An opt-in trace for the person who debugs a run. With C64RT_TRACE=<directory>
-// in the environment, each process appends its events as JSON lines to a file
-// of its own in that directory; unset, every call does nothing. The trace is
-// for people: nothing of it reaches the agent, and no result depends on it.
+// in the environment (the host: --log-dir), each process appends its events as
+// JSON lines to a file of its own in that directory. The host can also echo
+// each event to the console (--log-console). Off, every call does nothing. The
+// trace is for people: nothing of it reaches the agent, and no result depends on it.
 
 import { appendFileSync, copyFileSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -66,14 +67,16 @@ export class Trace {
   readonly kind: TraceKind;
   /** The directory of the trace, or undefined when the trace is off. */
   readonly dir: string | undefined;
-  /** The file this trace appends to, or undefined when the trace is off. */
+  /** The file this trace appends to, or undefined when the trace writes no file. */
   readonly file: string | undefined;
+  readonly #echo: ((line: string) => void) | undefined;
   #broken = false;
 
-  private constructor(kind: TraceKind, dir: string | undefined, file: string | undefined) {
+  private constructor(kind: TraceKind, dir: string | undefined, file: string | undefined, echo?: (line: string) => void) {
     this.kind = kind;
     this.dir = dir;
     this.file = file;
+    this.#echo = echo;
   }
 
   /** A trace that records nothing. */
@@ -81,31 +84,46 @@ export class Trace {
     return new Trace(kind, undefined, undefined);
   }
 
+  /** A trace that writes no file and gives each event to `echo` as one line. */
+  static echoing(kind: TraceKind, echo: (line: string) => void): Trace {
+    return new Trace(kind, undefined, undefined, echo);
+  }
+
   /**
    * A trace into `dir`, created when it is missing. The file is
    * `<kind>-<CET time>-<pid>.jsonl`, and its first event is `trace.start`.
    * Throws when the directory cannot be used.
    */
-  static open(kind: TraceKind, dir: string, now = new Date()): Trace {
+  static open(kind: TraceKind, dir: string, now = new Date(), echo?: (line: string) => void): Trace {
     mkdirSync(dir, { recursive: true });
-    const trace = new Trace(kind, dir, join(dir, `${kind}-${fileStampCet(now)}-${process.pid}.jsonl`));
+    const trace = new Trace(kind, dir, join(dir, `${kind}-${fileStampCet(now)}-${process.pid}.jsonl`), echo);
     trace.event("trace.start", { version: runningVersion(), pid: process.pid, argv: process.argv.slice(1), cwd: process.cwd(), node: process.version, platform: process.platform });
     return trace;
   }
 
   get on(): boolean {
+    return this.#writes || this.#echo !== undefined;
+  }
+
+  get #writes(): boolean {
     return this.file !== undefined && !this.#broken;
   }
 
-  /** Appends one event. A write that fails turns the trace off; nothing throws. */
+  /**
+   * Records one event: appends it to the file, and gives it to the echo as
+   * "<event> <fields as JSON>". The echo skips `log` events, which the program
+   * prints itself. A write that fails stops the file; nothing throws.
+   */
   event(name: string, fields: TraceFields = {}): void {
     if (!this.on) return;
-    const line: Record<string, unknown> = { t: isoCet(), kind: this.kind, event: name };
+    const summary: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(fields)) {
-      if (!RESERVED.has(key) && value !== undefined) line[key] = summarize(value);
+      if (!RESERVED.has(key) && value !== undefined) summary[key] = summarize(value);
     }
+    if (this.#echo !== undefined && name !== "log") this.#echo(`${name} ${JSON.stringify(summary)}`);
+    if (!this.#writes) return;
     try {
-      appendFileSync(this.file!, `${JSON.stringify(line)}\n`);
+      appendFileSync(this.file!, `${JSON.stringify({ t: isoCet(), kind: this.kind, event: name, ...summary })}\n`);
     } catch {
       this.#broken = true;
     }
@@ -121,7 +139,7 @@ export class Trace {
    * trace, as `<kind>-<pid>-<name>`. A copy that fails is recorded, not thrown.
    */
   keep(source: string, name: string): void {
-    if (!this.on) return;
+    if (!this.#writes) return;
     const target = join(this.dir!, `${this.kind}-${process.pid}-${name}`);
     try {
       copyFileSync(source, target);
@@ -135,23 +153,37 @@ export class Trace {
 // Off until a program calls startTrace; the kind is a placeholder until then.
 let current = Trace.off("script");
 
+/** Where the trace of a process goes: a directory for its file, and an echo for each event. */
+export interface TraceTarget {
+  /** The directory, and how the user gave it (`--log-dir <path>`, for example) for a warning. */
+  dir?: { path: string; given: string };
+  echo?: (line: string) => void;
+}
+
+/** The target that C64RT_TRACE in `env` gives: its directory, or nothing. */
+export function traceTargetFromEnv(env: NodeJS.ProcessEnv = process.env): TraceTarget {
+  const path = env[TRACE_VARIABLE];
+  return path === undefined || path === "" ? {} : { dir: { path, given: `${TRACE_VARIABLE}=${path}` } };
+}
+
 /**
- * Switches the trace of this process on when `env` (the environment by
- * default) has C64RT_TRACE, and off otherwise. A directory that cannot be used
- * leaves the trace off and reports that through `warn`. Called once, at the
- * start of a program.
+ * Switches the trace of this process on for `target` (by default what
+ * C64RT_TRACE in `env` gives), and off when the target is empty. A directory
+ * that cannot be used writes no file and reports that through `warn`; an echo
+ * stays on. Called once, at the start of a program.
  */
-export function startTrace(kind: TraceKind, options: { env?: NodeJS.ProcessEnv; warn?: (line: string) => void } = {}): Trace {
-  const dir = (options.env ?? process.env)[TRACE_VARIABLE];
-  if (dir === undefined || dir === "") {
-    current = Trace.off(kind);
+export function startTrace(kind: TraceKind, options: { env?: NodeJS.ProcessEnv; target?: TraceTarget; warn?: (line: string) => void } = {}): Trace {
+  const { dir, echo } = options.target ?? traceTargetFromEnv(options.env);
+  const noFile = () => (echo === undefined ? Trace.off(kind) : Trace.echoing(kind, echo));
+  if (dir === undefined) {
+    current = noFile();
     return current;
   }
   try {
-    current = Trace.open(kind, dir);
+    current = Trace.open(kind, dir.path, new Date(), echo);
   } catch (error) {
-    current = Trace.off(kind);
-    options.warn?.(`${TRACE_VARIABLE}=${dir} cannot be used (${error instanceof Error ? error.message : String(error)}); the trace is off.`);
+    current = noFile();
+    options.warn?.(`${dir.given} cannot be used (${error instanceof Error ? error.message : String(error)}); no trace file is written.`);
   }
   return current;
 }