@henols/c64-re-tools 1.1.0 → 2.0.0-rc.10

package/src/host/vice/binary-monitor.ts

@@ -0,0 +1,389 @@
+// VICE binary remote monitor client (VICE manual, chapter "Binary monitor",
+// API version 2). Owns framing, request/response correlation and body
+// decoding. Nothing outside src/host/vice sees these bytes.
+
+import type { Socket } from "node:net";
+
+import { connectWithTimeout } from "./connect.ts";
+
+export const STX = 0x02;
+export const API_VERSION = 0x02;
+/** Request id VICE uses for responses it sends unprompted (events). */
+export const EVENT_REQUEST_ID = 0xffff_ffff;
+
+const COMMAND_HEADER_BYTES = 11;
+const RESPONSE_HEADER_BYTES = 12;
+
+/** Command type bytes. */
+export const Command = {
+  memoryGet: 0x01,
+  memorySet: 0x02,
+  checkpointGet: 0x11,
+  checkpointSet: 0x12,
+  checkpointDelete: 0x13,
+  checkpointList: 0x14,
+  checkpointToggle: 0x15,
+  conditionSet: 0x22,
+  registersGet: 0x31,
+  registersSet: 0x32,
+  dump: 0x41,
+  undump: 0x42,
+  resourceGet: 0x51,
+  resourceSet: 0x52,
+  advanceInstructions: 0x71,
+  keyboardFeed: 0x72,
+  executeUntilReturn: 0x73,
+  ping: 0x81,
+  banksAvailable: 0x82,
+  registersAvailable: 0x83,
+  displayGet: 0x84,
+  viceInfo: 0x85,
+  paletteGet: 0x91,
+  joyportSet: 0xa2,
+  userportSet: 0xb2,
+  exit: 0xaa,
+  quit: 0xbb,
+  reset: 0xcc,
+  autostart: 0xdd,
+} as const;
+
+/** Response types that are not simply the command byte. */
+const TERMINAL_RESPONSE: Partial<Record<number, number>> = {
+  [Command.checkpointGet]: 0x11,
+  [Command.checkpointSet]: 0x11,
+  [Command.registersSet]: 0x31,
+};
+
+/** Response types VICE sends as events (request id EVENT_REQUEST_ID). */
+export const ResponseType = {
+  invalid: 0x00,
+  checkpointInfo: 0x11,
+  registerInfo: 0x31,
+  jam: 0x61,
+  stopped: 0x62,
+  resumed: 0x63,
+} as const;
+
+/** The memspace byte. */
+export const Memspace = {
+  main: 0x00,
+  drive8: 0x01,
+} as const;
+
+export interface MonitorResponse {
+  type: number;
+  error: number;
+  requestId: number;
+  body: Buffer;
+}
+
+/** VICE answered a command with a non-zero error code. */
+export class MonitorError extends Error {
+  override name = "MonitorError";
+  readonly command: number;
+  readonly errorCode: number;
+
+  constructor(command: number, errorCode: number) {
+    super(`VICE refused monitor command 0x${command.toString(16)} with error 0x${errorCode.toString(16)}`);
+    this.command = command;
+    this.errorCode = errorCode;
+  }
+}
+
+/** The monitor connection broke, timed out or sent bytes that are not the protocol. */
+export class MonitorConnectionError extends Error {
+  override name = "MonitorConnectionError";
+}
+
+/**
+ * A command got no answer in time, but the connection is open. The command
+ * still waits in VICE and runs once VICE goes on (its own pause, a dialog).
+ */
+export class MonitorTimeoutError extends MonitorConnectionError {
+  override name = "MonitorTimeoutError";
+}
+
+export function encodeCommand(requestId: number, command: number, body: Uint8Array = new Uint8Array(0)): Buffer {
+  const frame = Buffer.alloc(COMMAND_HEADER_BYTES + body.length);
+  frame[0] = STX;
+  frame[1] = API_VERSION;
+  frame.writeUInt32LE(body.length, 2);
+  frame.writeUInt32LE(requestId, 6);
+  frame[10] = command;
+  frame.set(body, COMMAND_HEADER_BYTES);
+  return frame;
+}
+
+/** Splits the response stream into responses. Throws MonitorConnectionError on a bad header. */
+export class ResponseDecoder {
+  #pending: Buffer = Buffer.alloc(0);
+
+  push(chunk: Buffer): MonitorResponse[] {
+    this.#pending = this.#pending.length === 0 ? chunk : Buffer.concat([this.#pending, chunk]);
+    const responses: MonitorResponse[] = [];
+    while (this.#pending.length >= RESPONSE_HEADER_BYTES) {
+      if (this.#pending[0] !== STX) throw new MonitorConnectionError("response does not start with STX");
+      if (this.#pending[1] !== API_VERSION) {
+        throw new MonitorConnectionError(`response has API version ${this.#pending[1]}, expected ${API_VERSION}`);
+      }
+      const length = this.#pending.readUInt32LE(2);
+      if (this.#pending.length < RESPONSE_HEADER_BYTES + length) break;
+      responses.push({
+        type: this.#pending[6]!,
+        error: this.#pending[7]!,
+        requestId: this.#pending.readUInt32LE(8),
+        // Copy so a retained body never pins the whole receive buffer.
+        body: Buffer.from(this.#pending.subarray(RESPONSE_HEADER_BYTES, RESPONSE_HEADER_BYTES + length)),
+      });
+      this.#pending = this.#pending.subarray(RESPONSE_HEADER_BYTES + length);
+    }
+    return responses;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Body codecs
+
+export function memoryGetBody(options: { start: number; end: number; memspace: number; bank: number; sideEffects?: boolean }): Buffer {
+  const body = Buffer.alloc(8);
+  body[0] = options.sideEffects ? 1 : 0;
+  body.writeUInt16LE(options.start, 1);
+  body.writeUInt16LE(options.end, 3);
+  body[5] = options.memspace;
+  body.writeUInt16LE(options.bank, 6);
+  return body;
+}
+
+/** The bytes of a memory-get response. The length field is 0 for a full 64 KiB read, so trust the body. */
+export function decodeMemory(body: Buffer): Buffer {
+  if (body.length < 2) throw new MonitorConnectionError("memory response is too short");
+  return body.subarray(2);
+}
+
+export interface RegisterValue {
+  id: number;
+  value: number;
+}
+
+export function decodeRegisters(body: Buffer): RegisterValue[] {
+  const count = body.readUInt16LE(0);
+  const registers: RegisterValue[] = [];
+  let offset = 2;
+  for (let index = 0; index < count; index++) {
+    const size = body[offset]!;
+    registers.push({ id: body[offset + 1]!, value: body.readUInt16LE(offset + 2) });
+    offset += size + 1;
+  }
+  return registers;
+}
+
+export interface RegisterInfo {
+  id: number;
+  bits: number;
+  name: string;
+}
+
+export function decodeRegistersAvailable(body: Buffer): RegisterInfo[] {
+  const count = body.readUInt16LE(0);
+  const registers: RegisterInfo[] = [];
+  let offset = 2;
+  for (let index = 0; index < count; index++) {
+    const size = body[offset]!;
+    const nameLength = body[offset + 3]!;
+    registers.push({
+      id: body[offset + 1]!,
+      bits: body[offset + 2]!,
+      name: body.toString("latin1", offset + 4, offset + 4 + nameLength),
+    });
+    offset += size + 1;
+  }
+  return registers;
+}
+
+export interface BankInfo {
+  id: number;
+  name: string;
+}
+
+export function decodeBanks(body: Buffer): BankInfo[] {
+  const count = body.readUInt16LE(0);
+  const banks: BankInfo[] = [];
+  let offset = 2;
+  for (let index = 0; index < count; index++) {
+    const size = body[offset]!;
+    const nameLength = body[offset + 3]!;
+    banks.push({ id: body.readUInt16LE(offset + 1), name: body.toString("latin1", offset + 4, offset + 4 + nameLength) });
+    offset += size + 1;
+  }
+  return banks;
+}
+
+/** The program counter carried by stopped, resumed and JAM events. */
+export function decodeProgramCounter(body: Buffer): number {
+  return body.readUInt16LE(0);
+}
+
+// ---------------------------------------------------------------------------
+// Connection
+
+interface Pending {
+  command: number;
+  terminalType: number;
+  extras: MonitorResponse[];
+  resolve: (response: MonitorResponse & { extras: MonitorResponse[] }) => void;
+  reject: (error: Error) => void;
+  timer: NodeJS.Timeout | undefined;
+}
+
+export const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * While an earlier command is overdue, later ones are still sent (VICE runs
+ * them in order once it goes on, so cleanup lands) but waited for only this long.
+ */
+export const OVERDUE_REQUEST_TIMEOUT_MS = 1_000;
+
+/** One binary-monitor connection with request correlation and an event stream. */
+export class BinaryMonitor {
+  /** Settles once the connection is gone, with the reason when it was not closed by us. */
+  readonly closed: Promise<Error | undefined>;
+  readonly #socket: Socket;
+  readonly #decoder = new ResponseDecoder();
+  readonly #pending = new Map<number, Pending>();
+  readonly #eventListeners = new Set<(event: MonitorResponse) => void>();
+  #nextId = 1;
+  #failure: Error | undefined;
+  #closedByUs = false;
+  /** The time limit of a request that names none. */
+  defaultTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS;
+  /** The time limit of a request while an earlier one is overdue (see OVERDUE_REQUEST_TIMEOUT_MS). */
+  overdueTimeoutMs = OVERDUE_REQUEST_TIMEOUT_MS;
+  /** Requests that timed out and whose late answer has not come yet. */
+  readonly #overdue = new Set<number>();
+
+  private constructor(socket: Socket) {
+    this.#socket = socket;
+    socket.setNoDelay(true);
+    this.closed = new Promise((resolve) => {
+      socket.on("close", () => {
+        const reason = this.#closedByUs ? undefined : (this.#failure ?? new MonitorConnectionError("VICE closed the monitor connection"));
+        this.#rejectAll(reason ?? new MonitorConnectionError("monitor connection closed"));
+        resolve(reason);
+      });
+    });
+    socket.on("error", (error) => {
+      this.#failure ??= new MonitorConnectionError(`monitor connection failed: ${error.message}`);
+    });
+    socket.on("data", (chunk) => this.#receive(chunk));
+  }
+
+  /** Opens a connection. Rejects with MonitorConnectionError when nothing listens. */
+  static connect(port: number, host = "127.0.0.1", timeoutMs = 2_000): Promise<BinaryMonitor> {
+    return connectWithTimeout({
+      port,
+      host,
+      timeoutMs,
+      wrap: (socket) => new BinaryMonitor(socket),
+      failure: (message) => new MonitorConnectionError(`monitor ${message}`),
+    });
+  }
+
+  /** Subscribes to events (responses with request id EVENT_REQUEST_ID). Returns an unsubscribe function. */
+  onEvent(listener: (event: MonitorResponse) => void): () => void {
+    this.#eventListeners.add(listener);
+    return () => this.#eventListeners.delete(listener);
+  }
+
+  /**
+   * Sends one command and resolves with its terminal response. Responses
+   * carrying the same request id before the terminal one (checkpoint list)
+   * are returned in `extras`. Rejects with MonitorError on a VICE error code,
+   * and with MonitorTimeoutError after `timeoutMs` (Infinity: no limit).
+   */
+  request(
+    command: number,
+    body: Uint8Array = new Uint8Array(0),
+    timeoutMs = this.defaultTimeoutMs,
+  ): Promise<MonitorResponse & { extras: MonitorResponse[] }> {
+    if (this.#socket.destroyed) return Promise.reject(new MonitorConnectionError("monitor connection is closed"));
+    const requestId = this.#nextId;
+    this.#nextId = this.#nextId >= EVENT_REQUEST_ID - 1 ? 1 : this.#nextId + 1;
+    const limit = this.#overdue.size > 0 && timeoutMs !== Infinity ? Math.min(timeoutMs, this.overdueTimeoutMs) : timeoutMs;
+    return new Promise((resolve, reject) => {
+      const timer =
+        limit === Infinity
+          ? undefined
+          : setTimeout(() => {
+              this.#pending.delete(requestId);
+              this.#overdue.add(requestId);
+              reject(new MonitorTimeoutError(`monitor command 0x${command.toString(16)} got no response in ${limit} ms`));
+            }, limit);
+      this.#pending.set(requestId, {
+        command,
+        terminalType: TERMINAL_RESPONSE[command] ?? command,
+        extras: [],
+        resolve,
+        reject,
+        timer,
+      });
+      this.#socket.write(encodeCommand(requestId, command, body));
+    });
+  }
+
+  /** Closes the connection. Pending requests reject. */
+  close(): Promise<void> {
+    this.#closedByUs = true;
+    this.#socket.destroy();
+    return this.closed.then(() => {});
+  }
+
+  #receive(chunk: Buffer): void {
+    let responses: MonitorResponse[];
+    try {
+      responses = this.#decoder.push(chunk);
+    } catch (error) {
+      this.#failure = error as Error;
+      this.#socket.destroy();
+      return;
+    }
+    for (const response of responses) {
+      if (response.requestId === EVENT_REQUEST_ID) {
+        for (const listener of this.#eventListeners) listener(response);
+        continue;
+      }
+      const pending = this.#pending.get(response.requestId);
+      if (pending === undefined) {
+        // A late answer to a timed-out request: VICE went on.
+        this.#overdue.delete(response.requestId);
+        continue;
+      }
+      if (response.error !== 0) {
+        this.#settle(response.requestId, pending);
+        pending.reject(new MonitorError(pending.command, response.error));
+      } else if (response.type === pending.terminalType) {
+        this.#settle(response.requestId, pending);
+        pending.resolve({ ...response, extras: pending.extras });
+      } else if (pending.command === Command.checkpointList && response.type === ResponseType.checkpointInfo) {
+        pending.extras.push(response);
+      } else {
+        this.#settle(response.requestId, pending);
+        pending.reject(
+          new MonitorConnectionError(
+            `monitor command 0x${pending.command.toString(16)} got a response of type 0x${response.type.toString(16)} instead of 0x${pending.terminalType.toString(16)}`,
+          ),
+        );
+      }
+    }
+  }
+
+  #settle(requestId: number, pending: Pending): void {
+    clearTimeout(pending.timer);
+    this.#pending.delete(requestId);
+  }
+
+  #rejectAll(error: Error): void {
+    for (const [requestId, pending] of this.#pending) {
+      this.#settle(requestId, pending);
+      pending.reject(error);
+    }
+  }
+}

package/src/host/vice/chips.ts

@@ -0,0 +1,118 @@
+// Decodes C64 chip registers (VIC-II, CIA, SID) into the protocol's chip state shapes.
+// Input bytes are register values as VICE's monitor reads them from the I/O
+// bank without side effects; the SID's write-only registers read back as
+// last written.
+
+import { d018Offsets, vicBankBase } from "../../c64.ts";
+import type { CiaState, SidState, SpriteState, ViciiMode, ViciiState } from "../../protocol/vice.ts";
+
+export function viciiMode(d011: number, d016: number): ViciiMode {
+  const ecm = (d011 & 0x40) !== 0;
+  const bmm = (d011 & 0x20) !== 0;
+  const mcm = (d016 & 0x10) !== 0;
+  if (!ecm && !bmm) return mcm ? "multicolor-text" : "text";
+  if (!ecm && bmm) return mcm ? "multicolor-bitmap" : "bitmap";
+  if (ecm && !bmm && !mcm) return "extended-color-text";
+  return "invalid";
+}
+
+/** `vic` holds $d000-$d02e; `cia2` holds $dd00-$dd0f. */
+export function decodeVicii(vic: Uint8Array, cia2: Uint8Array): ViciiState {
+  const d011 = vic[0x11]!;
+  const d016 = vic[0x16]!;
+  const offsets = d018Offsets(vic[0x18]!);
+  const mode = viciiMode(d011, d016);
+  const base = vicBankBase(cia2[0x00]!, cia2[0x02]!);
+  const bitmap = mode === "bitmap" || mode === "multicolor-bitmap";
+  return {
+    rasterLine: ((d011 & 0x80) << 1) | vic[0x12]!,
+    mode,
+    screenAddress: base + offsets.screen,
+    graphicsAddress: base + (bitmap ? offsets.bitmap : offsets.characters),
+    scrollX: d016 & 0x07,
+    scrollY: d011 & 0x07,
+    borderColor: vic[0x20]! & 0x0f,
+    backgroundColors: [vic[0x21]! & 0x0f, vic[0x22]! & 0x0f, vic[0x23]! & 0x0f, vic[0x24]! & 0x0f],
+  };
+}
+
+/** `pointers` holds the eight sprite pointer bytes at screen + $3f8. */
+export function decodeSprite(index: number, vic: Uint8Array, cia2: Uint8Array, pointers: Uint8Array): SpriteState {
+  const bit = (register: number) => (vic[register]! & (1 << index)) !== 0;
+  return {
+    index,
+    x: vic[index * 2]! + (bit(0x10) ? 256 : 0),
+    y: vic[index * 2 + 1]!,
+    enabled: bit(0x15),
+    color: vic[0x27 + index]! & 0x0f,
+    multicolor: bit(0x1c),
+    expandX: bit(0x1d),
+    expandY: bit(0x17),
+    behindBackground: bit(0x1b),
+    dataAddress: vicBankBase(cia2[0x00]!, cia2[0x02]!) + pointers[index]! * 64,
+  };
+}
+
+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, hidden: CiaHidden): CiaState {
+  const word = (low: number) => registers[low]! | (registers[low + 1]! << 8);
+  const hourRegister = registers[0x0b]!;
+  const pm = (hourRegister & 0x80) !== 0;
+  return {
+    id,
+    portA: registers[0x00]!,
+    portB: registers[0x01]!,
+    ddrA: registers[0x02]!,
+    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),
+      seconds: bcd(registers[0x09]! & 0x7f),
+      tenths: registers[0x08]! & 0x0f,
+    },
+  };
+}
+
+/** `registers` holds $d400-$d418. */
+export function decodeSid(registers: Uint8Array): SidState {
+  const voices = [0, 1, 2].map((voice) => {
+    const at = voice * 7;
+    return {
+      index: voice + 1,
+      frequency: registers[at]! | (registers[at + 1]! << 8),
+      pulseWidth: registers[at + 2]! | ((registers[at + 3]! & 0x0f) << 8),
+      control: registers[at + 4]!,
+      attackDecay: registers[at + 5]!,
+      sustainRelease: registers[at + 6]!,
+    };
+  });
+  return {
+    voices,
+    filter: {
+      cutoff: (registers[0x15]! & 0x07) | (registers[0x16]! << 3),
+      resonance: registers[0x17]! >> 4,
+      routing: registers[0x17]! & 0x0f,
+      mode: registers[0x18]! >> 4,
+    },
+    volume: registers[0x18]! & 0x0f,
+  };
+}

package/src/host/vice/connect.ts

@@ -0,0 +1,34 @@
+// The TCP connect that both VICE monitor clients share.
+
+import { connect, type Socket } from "node:net";
+
+/**
+ * Connects to a VICE monitor port and wraps the socket with `wrap` at once.
+ * Rejects with the error that `failure` makes from a message when the
+ * connection fails or takes longer than `timeoutMs`.
+ */
+export function connectWithTimeout<T>(options: {
+  port: number;
+  host: string;
+  timeoutMs: number;
+  wrap: (socket: Socket) => T;
+  failure: (message: string) => Error;
+}): Promise<T> {
+  const { port, host, timeoutMs, wrap, failure } = options;
+  return new Promise((resolve, reject) => {
+    const socket = connect({ host, port });
+    const timer = setTimeout(() => {
+      socket.destroy();
+      reject(failure(`connect to port ${port} timed out`));
+    }, timeoutMs);
+    socket.once("connect", () => {
+      clearTimeout(timer);
+      socket.removeAllListeners("error");
+      resolve(wrap(socket));
+    });
+    socket.once("error", (error) => {
+      clearTimeout(timer);
+      reject(failure(`connect to port ${port} failed: ${error.message}`));
+    });
+  });
+}