@fugloy/emu 0.0.0-stage → 0.3.0

package/src/index.js

@@ -0,0 +1,23 @@
+/**
+ * @fugloy/emu — headless, deterministic TRS-80 Model III and Model I emulator core.
+ * Extracted in emu phase 0 from cschweda/trs80-emulator at 11612849 (v1.6.0); see NOTICE.md.
+ */
+export { Machine } from './machine/machine.js';
+export { Debugger, COVERAGE } from './debug/debugger.js';
+export { LABEL_FILE_VERSION, COVERAGE_FIELDS, encodeRle, decodeRle, parseLabelFile, mergeLabelFiles } from './debug/label-file.js';
+export { ROM_HASHES } from './machine/rom-hashes.js';
+export { clockHz } from './machine/models.js';
+export { TRS80System, CPU_CLOCK_HZ, RTC_HZ, RTC_INTERVAL_TSTATES } from './machine/trs80-system.js';
+export { Z80CPU } from './cpu/z80cpu.js';
+export { MemorySystem } from './machine/memory.js';
+export { IOSystem, RTC_IRQ_BIT, CASSETTE_RISE_IRQ_BIT, CASSETTE_FALL_IRQ_BIT, NMI_INTRQ_BIT, MODE_32COL_BIT } from './machine/io.js';
+export { KeyboardMatrix } from './devices/keyboard.js';
+export { CassetteSystem } from './devices/cassette.js';
+export { casToPulses, pulsesToBytes, ensureLeader } from './devices/cassette-tape.js';
+export { FDC1793, parseWriteTrackStream } from './devices/fdc-wd1793.js';
+export { DiskImage, JV1_MODEL1_SD_TRACKS } from './devices/disk-image.js';
+export { Printer } from './devices/printer.js';
+export { parseCas, fastLoadBasic, fastLoadSystem } from './loaders/cas-format.js';
+export { parseBas } from './loaders/bas.js';
+export { parseCmd, fastLoadCmd } from './loaders/cmd-format.js';
+export { STATE_VERSION, STATE_MACHINE, toBase64, fromBase64, serializeState, restoreState } from './debug/state.js';

package/src/loaders/bas.js

@@ -0,0 +1,107 @@
+/**
+ * .BAS loader. A first byte of $FF means a tokenized program: per line a 2-byte next pointer, a
+ * 2-byte line number, the body, and 00, with two zero bytes ending the program. Otherwise the
+ * file is ASCII source, which the Machine feeds through the ROM keyboard hook.
+ *
+ * The pointers in a tokenized file are absolute from the machine that saved it, so they are
+ * rebuilt for the load address. A line body may hold 00 (machine code in a REM), so the chain is
+ * followed by pointer when it is self-consistent and by 00-scan when it is not.
+ */
+import { writeTokenizedProgram } from './cas-format.js';
+
+const hex = (n) => `$${n.toString(16).toUpperCase()}`;
+
+/** Follows the pointer chain with line 1 assumed at `base`; null when it does not hold together. */
+function walk(bytes, start, base) {
+  const n = bytes.length;
+  const lines = [];
+  let off = start;
+  let addr = base;
+  for (;;) {
+    if (off + 2 > n) return null;
+    const ptr = bytes[off] | (bytes[off + 1] << 8);
+    if (ptr === 0) return lines;
+    const len = ptr - addr;
+    if (len < 5 || off + len > n || bytes[off + len - 1] !== 0) return null;
+    lines.push({ lineNo: bytes[off + 2] | (bytes[off + 3] << 8), tokens: bytes.slice(off + 4, off + len - 1) });
+    addr = ptr;
+    off += len;
+  }
+}
+
+/** Splits at each 00, ignoring the pointers; throws when the program runs off the end of the file. */
+function scan(bytes, start) {
+  const n = bytes.length;
+  const lines = [];
+  let off = start;
+  for (;;) {
+    if (off + 2 > n) throw new Error(`truncated .BAS: no 00 00 program terminator after ${lines.length} lines`);
+    if (bytes[off] === 0 && bytes[off + 1] === 0) return lines;
+    if (off + 4 > n) throw new Error(`truncated .BAS: line header cut off at offset ${off}`);
+    const end = bytes.indexOf(0, off + 4);
+    if (end < 0) throw new Error(`truncated .BAS: line at offset ${off} has no 00 terminator`);
+    lines.push({ lineNo: bytes[off + 2] | (bytes[off + 3] << 8), tokens: bytes.slice(off + 4, end) });
+    off = end + 1;
+  }
+}
+
+function parseTokenized(bytes) {
+  const start = 1;
+  if (bytes.length - start < 2) throw new Error('truncated .BAS: no program after the $FF header');
+  const ptr1 = bytes[start] | (bytes[start + 1] << 8);
+  if (ptr1 === 0) return { kind: 'tokenized', lines: [] };
+  // Line 1's base is unknown: try the stock TXTTAB, then each 00 in line 1 as its end.
+  const bases = [0x42e9];
+  for (let j = start + 4; j < bytes.length; j++) {
+    if (bytes[j] === 0) {
+      bases.push(ptr1 - (j + 1 - start));
+      if (bases.length > 64) break;
+    }
+  }
+  for (const base of bases) {
+    const lines = walk(bytes, start, base);
+    if (lines) return { kind: 'tokenized', lines };
+  }
+  // No pointer chain holds together (a bad next pointer, say): fall back to splitting at each 00,
+  // which throws "truncated" only when the program runs off the end of the file.
+  return { kind: 'tokenized', lines: scan(bytes, start) };
+}
+
+/**
+ * Parse a .BAS file.
+ * @param {Uint8Array} bytes
+ * @returns {{ kind: 'tokenized', lines: { lineNo: number, tokens: Uint8Array }[] } | { kind: 'ascii', text: string }}
+ */
+export function parseBas(bytes) {
+  if (!bytes || bytes.length === 0) throw new Error('not a .BAS file: empty');
+  if (bytes[0] === 0xff) return parseTokenized(bytes);
+  let text = '';
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i];
+    if (b === 0) throw new Error(`not a .BAS file: NUL at offset ${i} (looks like tokenized BASIC without the $FF header; add a leading $FF byte to load it)`);
+    if (!((b >= 0x20 && b <= 0x7e) || b === 0x0d || b === 0x0a || b === 0x09)) {
+      throw new Error(`not a .BAS file: byte ${hex(b)} at offset ${i} is neither tokenized ($FF first) nor ASCII text`);
+    }
+    text += String.fromCharCode(b);
+  }
+  text = text.replace(/\r\n?/g, '\n');
+  if (!text.endsWith('\n')) text += '\n';
+  return { kind: 'ascii', text };
+}
+
+/**
+ * Load a .BAS file into a Machine. Tokenized: write at TXTTAB and fix the pointers. ASCII: feed
+ * the text through the keyboard hook, which BASIC reads as the machine runs.
+ * @param {import('../machine/machine.js').Machine} machine
+ * @param {Uint8Array} bytes
+ * @returns {{ format: 'bas', kind: 'tokenized' | 'ascii', start: number, end: number | null, blocks: { addr: number, len: number, why: string }[] }}
+ */
+export function loadBas(machine, bytes) {
+  const parsed = parseBas(bytes);
+  if (parsed.kind === 'ascii') {
+    machine.keyboard.feed(parsed.text);
+    return { format: 'bas', kind: 'ascii', start: machine.system.memory.readWord(0x40a4), end: null, blocks: [] };
+  }
+  const { start, end } = writeTokenizedProgram(machine.system, parsed.lines);
+  return { format: 'bas', kind: 'tokenized', start, end, blocks: [{ addr: start, len: end - start, why: 'BASIC program' }] };
+}

package/src/loaders/cas-format.js

@@ -0,0 +1,213 @@
+/**
+ * TRS-80 .cas cassette image handling
+ *
+ * A .cas file is the decoded byte stream of a tape. Two layouts matter:
+ *
+ *   BASIC (CSAVE):  [leader 0x00/0x55 ...] 0xA5  0xD3 0xD3 0xD3  name(1)
+ *                   then the tokenized program image: per line
+ *                   [link u16][line# u16][tokens...][0x00], ending with a
+ *                   0x0000 link. Link pointers are absolute addresses from
+ *                   the saving machine — they are recomputed on load.
+ *
+ *   SYSTEM:         [leader] 0xA5  0x55  name(6) then blocks:
+ *                   0x3C len(0=256) addr(u16) data[len] checksum
+ *                   terminated by 0x78 entry(u16).
+ *
+ * Fast-loading bypasses the cassette port entirely: BASIC programs are
+ * written at TXTTAB with fresh links and the variable pointers fixed up
+ * (what CLOAD leaves behind); SYSTEM blocks are written to their target
+ * addresses and execution jumps to the entry point (what SYSTEM's "/"
+ * does).
+ */
+
+import { startProgram } from "./handoff.js";
+
+// Model III cassette BASIC work area
+const TXTTAB_PTR = 0x40a4; // -> start of BASIC program (0x42E9 stock)
+const VARTAB_PTR = 0x40f9; // simple variables (= end of program)
+const ARYTAB_PTR = 0x40fb; // arrays
+const FRETOP_PTR = 0x40fd; // free space
+
+/**
+ * Parse a .cas byte stream.
+ * @returns {{kind:"basic",name:string,lines:{lineNo:number,tokens:number[]}[]}
+ *        | {kind:"system",name:string,blocks:{addr:number,data:Uint8Array}[],entry:number,checksumErrors:number}}
+ */
+export function parseCas(bytes) {
+  if (!bytes || bytes.length < 4) {
+    throw new Error("Not a .cas image: too short");
+  }
+
+  // Skip the leader (0x00 or 0x55 bytes) up to the sync byte — 0xA5 on
+  // 500-baud tapes, 0x7F on Model III 1500-baud ones. Some images omit
+  // the leader or even the sync.
+  let i = 0;
+  while (i < bytes.length && (bytes[i] === 0x00 || bytes[i] === 0x55)) i++;
+  if (bytes[i] === 0xa5 || bytes[i] === 0x7f) {
+    i++;
+  } else {
+    i = 0; // no leader/sync: start over at the raw content
+  }
+
+  if (bytes[i] === 0xd3 && bytes[i + 1] === 0xd3 && bytes[i + 2] === 0xd3) {
+    return parseBasic(bytes, i + 3);
+  }
+  if (bytes[i] === 0x55) {
+    return parseSystem(bytes, i + 1);
+  }
+  // A few BASIC images begin at the D3s without sync handled above
+  throw new Error(
+    "Unrecognized .cas layout (expected BASIC 0xD3 0xD3 0xD3 or SYSTEM 0x55 header)"
+  );
+}
+
+// Stock cassette BASIC program base (Model I and III alike): the link
+// addresses a real CSAVE writes are absolute from here.
+const TXTTAB_STOCK = 0x42e9;
+
+function parseBasic(bytes, offset) {
+  const name = String.fromCharCode(bytes[offset]);
+  let i = offset + 1;
+  const lines = [];
+
+  // Real CLOAD walks the link-pointer chain, which is what lets a line
+  // contain 0x00 bytes (machine code embedded in a REM — the
+  // Christopherson games). Trust each link while it stays
+  // self-consistent; fall back to 0x00-scanning for that record when it
+  // doesn't (some tools write garbage links). After a fallback the next
+  // record re-syncs on the link value, so lengths derive from link
+  // deltas and the saving machine's base stops mattering.
+  let addr = TXTTAB_STOCK;
+  while (i + 1 < bytes.length) {
+    const link = bytes[i] | (bytes[i + 1] << 8);
+    if (link === 0x0000) {
+      break; // program terminator
+    }
+    const lineNo = bytes[i + 2] | (bytes[i + 3] << 8);
+    const recLen = link - addr; // [link u16][line# u16][tokens...][0x00]
+    if (
+      recLen >= 5 &&
+      recLen <= 1000 &&
+      i + recLen < bytes.length &&
+      bytes[i + recLen - 1] === 0x00
+    ) {
+      lines.push({
+        lineNo,
+        tokens: Array.from(bytes.slice(i + 4, i + recLen - 1)),
+      });
+      i += recLen;
+    } else {
+      const tokens = [];
+      let j = i + 4;
+      while (j < bytes.length && bytes[j] !== 0x00) {
+        tokens.push(bytes[j]);
+        j++;
+      }
+      j++; // consume the end-of-line 0x00
+      lines.push({ lineNo, tokens });
+      i = j;
+    }
+    addr = link; // re-sync even after a fallback record
+  }
+
+  return { kind: "basic", name, lines };
+}
+
+function parseSystem(bytes, offset) {
+  const name = String.fromCharCode(...bytes.slice(offset, offset + 6))
+    .replace(/\0/g, " ")
+    .trimEnd();
+  let i = offset + 6;
+  const blocks = [];
+  let entry = null;
+  let checksumErrors = 0;
+
+  while (i < bytes.length) {
+    const marker = bytes[i++];
+    if (marker === 0x3c) {
+      let len = bytes[i++];
+      if (len === 0) len = 256;
+      const addr = bytes[i] | (bytes[i + 1] << 8);
+      i += 2;
+      const data = bytes.slice(i, i + len);
+      i += len;
+      const checksum = bytes[i++];
+      let sum = (addr & 0xff) + ((addr >> 8) & 0xff);
+      for (const b of data) sum += b;
+      if ((sum & 0xff) !== checksum) checksumErrors++;
+      blocks.push({ addr, data: new Uint8Array(data) });
+    } else if (marker === 0x78) {
+      entry = bytes[i] | (bytes[i + 1] << 8);
+      break;
+    } else if (marker === 0x00 || marker === 0x55) {
+      // stray leader/padding between blocks on some tapes
+      continue;
+    } else {
+      throw new Error(
+        `Unexpected SYSTEM block marker 0x${marker.toString(16)} at ${i - 1}`
+      );
+    }
+  }
+
+  if (entry === null) {
+    throw new Error("SYSTEM tape has no entry-point (0x78) block");
+  }
+  return { kind: "system", name, blocks, entry, checksumErrors };
+}
+
+/**
+ * Write tokenized BASIC lines at TXTTAB with freshly computed next-line pointers, end the program
+ * with 00 00, and set the variable-area pointers ($40F9, $40FB, $40FD) as CLOAD leaves them.
+ * Shared by fastLoadBasic and the .BAS loader.
+ * @param {{ memory: any }} system
+ * @param {{ lineNo: number, tokens: ArrayLike<number> }[]} lines
+ * @returns {{ start: number, end: number }} TXTTAB, and the address one past the terminator
+ */
+export function writeTokenizedProgram(system, lines) {
+  const memory = system.memory;
+  const start = memory.readWord(TXTTAB_PTR);
+  let addr = start;
+
+  for (const line of lines) {
+    const next = addr + 2 + 2 + line.tokens.length + 1;
+    memory.writeWord(addr, next);
+    memory.writeWord(addr + 2, line.lineNo);
+    for (let i = 0; i < line.tokens.length; i++) {
+      memory.writeByte(addr + 4 + i, line.tokens[i]);
+    }
+    memory.writeByte(next - 1, 0x00);
+    addr = next;
+  }
+
+  memory.writeWord(addr, 0x0000); // program terminator
+  addr += 2;
+
+  memory.writeWord(VARTAB_PTR, addr);
+  memory.writeWord(ARYTAB_PTR, addr);
+  memory.writeWord(FRETOP_PTR, addr);
+  return { start, end: addr };
+}
+
+/**
+ * Fast-load a parsed BASIC program: write it at TXTTAB with recomputed
+ * line links and set the variable-area pointers, exactly the state CLOAD
+ * leaves. The machine should be sitting at READY. Caller typically
+ * follows with system.typeText("RUN\n").
+ * @returns {number} address one past the program terminator
+ */
+export function fastLoadBasic(system, parsed) {
+  return writeTokenizedProgram(system, parsed.lines).end;
+}
+
+/**
+ * Fast-load a parsed SYSTEM (machine-code) tape: write every block and
+ * jump to the entry point — the same transfer SYSTEM's "/" performs.
+ */
+export function fastLoadSystem(system, parsed) {
+  for (const block of parsed.blocks) {
+    for (let i = 0; i < block.data.length; i++) {
+      system.memory.writeByte((block.addr + i) & 0xffff, block.data[i]);
+    }
+  }
+  return startProgram(system, parsed.entry);
+}

package/src/loaders/cmd-format.js

@@ -0,0 +1,88 @@
+/**
+ * TRS-80 DOS /CMD executable handling
+ *
+ * A /CMD file is a stream of records: [type][length][payload…]. The
+ * types honored here:
+ *
+ *   0x01  object-code block   payload: addr.lo addr.hi data…
+ *                             For this type the length byte counts the
+ *                             address AND data bytes, with the quirk
+ *                             that 0, 1 and 2 mean 256, 257 and 258
+ *                             (a block always carries the 2 address
+ *                             bytes plus at least one data byte).
+ *   0x02  transfer address    payload: entry.lo entry.hi — ends the load
+ *   0x05  module name         payload: ASCII name
+ *   other                     skipped by their length byte (comments,
+ *                             patch and directory records)
+ *
+ * Record 07 is a patch name header: its payload is the patch's name in
+ * ASCII, and the patch's code follows it as ordinary 01 blocks, which
+ * load like any other; a patch that has been YANKed has those blocks
+ * retyped 10, which the loader ignores (LDOS 5.1 manual, Tech Info:
+ * File Formats p. 1, item c; Soltoff, The Programmer's Guide to
+ * LDOS/TRSDOS Version 6, p. A-149, figure A-1). So skipping 07 and 10
+ * by their length is the whole of their handling.
+ *
+ * Fast-loading writes the blocks straight into RAM and jumps to the
+ * entry point — the same hand-off TRSDOS performs — so tape/disk-era
+ * machine-language games run with no DOS resident.
+ */
+
+import { startProgram } from "./handoff.js";
+
+/**
+ * Parse a /CMD byte stream.
+ * @returns {{name:string, blocks:{addr:number,data:Uint8Array}[], entry:number}}
+ */
+export function parseCmd(bytes) {
+  if (!bytes || bytes.length < 4) {
+    throw new Error("Not a /CMD image: too short");
+  }
+  const blocks = [];
+  let entry = null;
+  let name = "";
+  let i = 0;
+
+  while (i + 1 < bytes.length) {
+    const type = bytes[i++];
+    let len = bytes[i++];
+    if (type === 0x01) {
+      if (len < 3) len += 256; // 0,1,2 mean 256,257,258
+      if (i + len > bytes.length) {
+        throw new Error("Truncated /CMD load block");
+      }
+      const addr = bytes[i] | (bytes[i + 1] << 8);
+      blocks.push({ addr, data: new Uint8Array(bytes.slice(i + 2, i + len)) });
+      i += len;
+    } else if (type === 0x02) {
+      entry = bytes[i] | (bytes[i + 1] << 8);
+      break; // transfer address ends the load; trailing bytes are ignored
+    } else if (type === 0x05) {
+      name = String.fromCharCode(...bytes.slice(i, i + len)).trimEnd();
+      i += len;
+    } else {
+      i += len; // unknown record: skip its payload
+    }
+  }
+
+  if (entry === null) {
+    throw new Error("/CMD image has no transfer-address (0x02) record");
+  }
+  if (blocks.length === 0) {
+    throw new Error("/CMD image has no load blocks");
+  }
+  return { name, blocks, entry };
+}
+
+/**
+ * Fast-load a parsed /CMD: write every block and jump to the entry point.
+ */
+export function fastLoadCmd(system, parsed) {
+  for (const block of parsed.blocks) {
+    for (let i = 0; i < block.data.length; i++) {
+      system.memory.writeByte((block.addr + i) & 0xffff, block.data[i]);
+    }
+  }
+  return startProgram(system, parsed.entry);
+}
+

package/src/loaders/handoff.js

@@ -0,0 +1,29 @@
+/**
+ * The loaders' hand-off to a loaded program, shared by fastLoadCmd (cmd-format.js) and
+ * fastLoadSystem (cas-format.js).
+ */
+
+/**
+ * Jump to `entry` with nothing of the interrupted code left half-done. The CPU leaves HALT. An EI
+ * still in flight (it enables interrupts only after the next instruction) takes effect now, so
+ * IFF1 and IFF2 are set as they would be one instruction later; a DD/FD prefix still pending is
+ * dropped. Any interrupt request latched before the load is cleared, so no request from before
+ * the load interrupts the program; the next request is the next one the hardware raises.
+ * Otherwise IFF1, IFF2, and the interrupt mode are left as they were.
+ * @param {any} system a TRS80System (a bare { cpu } works too)
+ * @param {number} entry
+ * @returns {number} the entry
+ */
+export function startProgram(system, entry) {
+  const cpu = system.cpu;
+  cpu.halted = false;
+  if (cpu.pendingEI > 0) {
+    cpu.IFF1 = true;
+    cpu.IFF2 = true;
+  }
+  cpu.pendingEI = 0;
+  cpu.afterPrefix = false;
+  if (system.io) system.io.intLatch = 0;
+  cpu.registers.PC = entry;
+  return entry;
+}