@fugloy/emu 0.0.0-stage → 0.2.0

package/src/machine/memory.js

@@ -0,0 +1,207 @@
+/**
+ * TRS-80 Model III Memory Management System
+ *
+ * Real Model III address map (non-disk machine):
+ *   0x0000-0x37FF  14K ROM (write-protected)
+ *   0x3800-0x3BFF  keyboard matrix (memory-mapped, read-only;
+ *                  low 8 address bits select rows, A8/A9 undecoded)
+ *   0x3C00-0x3FFF  1K video RAM (64 cols x 16 rows)
+ *   0x4000-0xFFFF  48K RAM
+ */
+
+const ROM_LIMIT = 0x3800;
+const KEYBOARD_LIMIT = 0x3c00;
+const RAM_BASE = 0x4000;
+
+export class MemorySystem {
+  constructor() {
+    // ROM storage is 16K so padded 16K images can be loaded verbatim,
+    // but only 0x0000-0x37FF is ever mapped as ROM.
+    this.rom = new Uint8Array(0x4000);
+
+    // 48K RAM (0x4000 - 0xFFFF)
+    this.ram = new Uint8Array(0xc000);
+
+    // 1K video RAM (0x3C00 - 0x3FFF)
+    this.videoRam = new Uint8Array(0x400);
+
+    // Set on every video RAM write so the renderer can skip idle frames
+    this.videoDirty = false;
+
+    // Keyboard matrix peripheral: { read(addrLow8) -> row bits } or null
+    this.keyboard = null;
+
+    this.romLoaded = false;
+
+    // Kept for API compatibility with existing callers
+    this.VIDEO_RAM_START = 0x3c00;
+    this.VIDEO_RAM_END = 0x3fff;
+  }
+
+  /**
+   * Get memory statistics
+   */
+  getStats() {
+    return {
+      romSize: this.rom.length,
+      ramSize: this.ram.length,
+      totalSize: this.rom.length + this.ram.length,
+      romLoaded: this.romLoaded,
+    };
+  }
+
+  /**
+   * Load a ROM image: the real 14K (0x3800) Model III ROM, or a 16K
+   * (0x4000) padded image of it. Anything else is a wrong file — reject
+   * it rather than guessing.
+   */
+  loadROM(romData) {
+    if (!romData || romData.length === 0) {
+      throw new Error("ROM data is required");
+    }
+
+    if (romData.length !== 0x3800 && romData.length !== 0x4000) {
+      throw new Error(
+        `Invalid ROM size: ${romData.length} bytes. Expected 14KB (0x3800) or a 16KB (0x4000) padded image`
+      );
+    }
+
+    this.rom.fill(0);
+    this.rom.set(romData, 0);
+
+    this.romLoaded = true;
+    return true;
+  }
+
+  /**
+   * Read a byte from memory
+   * Addresses are masked to 16 bits (0x0000 - 0xFFFF)
+   */
+  readByte(address) {
+    address = address & 0xffff;
+
+    if (address < ROM_LIMIT) {
+      return this.rom[address];
+    }
+    if (address < KEYBOARD_LIMIT) {
+      // Keyboard matrix: reading with no keys down yields 0x00
+      return this.keyboard ? this.keyboard.read(address & 0xff) : 0x00;
+    }
+    if (address < RAM_BASE) {
+      return this.videoRam[address - KEYBOARD_LIMIT];
+    }
+    return this.ram[address - RAM_BASE];
+  }
+
+  /**
+   * Write a byte to memory
+   * ROM and the keyboard region ignore writes; video RAM and RAM accept them.
+   */
+  writeByte(address, value) {
+    address = address & 0xffff;
+    value = value & 0xff;
+
+    if (address < KEYBOARD_LIMIT) {
+      return; // ROM / keyboard matrix: not writable
+    }
+    if (address < RAM_BASE) {
+      this.videoRam[address - KEYBOARD_LIMIT] = value;
+      this.videoDirty = true;
+      return;
+    }
+    this.ram[address - RAM_BASE] = value;
+  }
+
+  /**
+   * Read a 16-bit word (little-endian)
+   */
+  readWord(address) {
+    address = address & 0xffff;
+    const low = this.readByte(address);
+    const high = this.readByte((address + 1) & 0xffff);
+    return (high << 8) | low;
+  }
+
+  /**
+   * Write a 16-bit word (little-endian)
+   */
+  writeWord(address, value) {
+    address = address & 0xffff;
+    value = value & 0xffff;
+    const low = value & 0xff;
+    const high = (value >> 8) & 0xff;
+    this.writeByte(address, low);
+    this.writeByte((address + 1) & 0xffff, high);
+  }
+
+  /**
+   * Load a program into RAM
+   * @param {Uint8Array|Array} program - Program data
+   * @param {number} address - Load address (default: 0x4200)
+   * @returns {number} The address where the program was loaded
+   */
+  loadProgram(program, address = 0x4200) {
+    if (!program || program.length === 0) {
+      return address;
+    }
+
+    // Convert to Uint8Array if needed
+    let programData;
+    if (program instanceof Uint8Array) {
+      programData = program;
+    } else if (Array.isArray(program)) {
+      programData = new Uint8Array(program);
+    } else {
+      throw new Error("Program must be Uint8Array or Array");
+    }
+
+    address = address & 0xffff;
+
+    // Check if program fits in memory
+    if (address < RAM_BASE) {
+      throw new Error("Cannot load program into ROM area");
+    }
+
+    const endAddress = (address + programData.length - 1) & 0xffff;
+    if (endAddress < address) {
+      // Wrapped around - program too large
+      throw new Error("Program exceeds available memory");
+    }
+
+    // Load program into RAM
+    for (let i = 0; i < programData.length; i++) {
+      const addr = (address + i) & 0xffff;
+      this.writeByte(addr, programData[i]);
+    }
+
+    return address;
+  }
+
+  /**
+   * Clear all RAM (set to 0x00)
+   */
+  clearRAM() {
+    this.ram.fill(0);
+  }
+
+  /**
+   * Clear video RAM to spaces (what the ROM's CLS leaves behind)
+   */
+  clearVideoRAM() {
+    this.videoRam.fill(0x20);
+    this.videoDirty = true;
+  }
+
+  /**
+   * Get a view of the entire memory space (for debugging)
+   * Returns a Uint8Array representing the full 64K address space
+   */
+  getMemoryView() {
+    const view = new Uint8Array(0x10000);
+    view.set(this.rom.subarray(0, ROM_LIMIT), 0);
+    // Keyboard region reads as idle (0x00) in the debug view
+    view.set(this.videoRam, KEYBOARD_LIMIT);
+    view.set(this.ram, RAM_BASE);
+    return view;
+  }
+}

package/src/machine/rom-hashes.js

@@ -0,0 +1,14 @@
+/**
+ * Known Model III ROM images by SHA-256 (lowercase hex), so the Machine can report which ROM it
+ * was given (spec §5: the core validates by length and a known-hash table). Hashes are facts
+ * about the images; the images themselves are never committed or bundled.
+ *
+ * Source for both: github.com/kiwisincebirth/TRS-80-ROMS, folder test-roms/, hashed locally
+ * 2026-10-17. `Model3-RevC-2EF8.bin` is the stock Model III Rev C ROM (14,336 bytes) and the
+ * image the repository's fugloy.mcp.json names as roms.model3; `Model3-RevC-FreHD.bin` is the
+ * same ROM patched to boot a FreHD hard-disk emulator.
+ */
+export const ROM_HASHES = Object.freeze({
+  beeb3741175a8b8706cc384d5b2534ebf32e383662864054e5a0ce4d861a43bb: 'model3-rev-c-2ef8',
+  ad6de30c6aece2d6a2243ee90a2959295d5c46b82650b27f46f1ecf8b34b2361: 'model3-rev-c-frehd',
+});

package/src/machine/sha256.js

@@ -0,0 +1,74 @@
+/**
+ * SHA-256 (FIPS 180-4) in plain JavaScript, because the core may use neither Node's crypto nor
+ * the browser's asynchronous Web Crypto. A copy of @fugloy/disasm's `src/hash.ts` (emu must not
+ * depend on disasm); identifies ROM images against ROM_HASHES.
+ */
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+const H0 = [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19];
+
+const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {Uint8Array} the 32-byte digest
+ */
+export function sha256(bytes) {
+  const len = bytes.length;
+  const padded = new Uint8Array(((len + 9 + 63) >> 6) << 6);
+  padded.set(bytes);
+  padded[len] = 0x80;
+  const view = new DataView(padded.buffer);
+  const bits = len * 8;
+  view.setUint32(padded.length - 8, Math.floor(bits / 0x100000000));
+  view.setUint32(padded.length - 4, bits >>> 0);
+
+  const h = Uint32Array.from(H0);
+  const w = new Uint32Array(64);
+  for (let off = 0; off < padded.length; off += 64) {
+    for (let i = 0; i < 16; i++) w[i] = view.getUint32(off + i * 4);
+    for (let i = 16; i < 64; i++) {
+      const w15 = w[i - 15];
+      const w2 = w[i - 2];
+      const s0 = rotr(w15, 7) ^ rotr(w15, 18) ^ (w15 >>> 3);
+      const s1 = rotr(w2, 17) ^ rotr(w2, 19) ^ (w2 >>> 10);
+      w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+    }
+    let a = h[0], b = h[1], c = h[2], d = h[3], e = h[4], f = h[5], g = h[6], hh = h[7];
+    for (let i = 0; i < 64; i++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (hh + S1 + ch + K[i] + w[i]) >>> 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (S0 + maj) >>> 0;
+      hh = g; g = f; f = e;
+      e = (d + t1) >>> 0;
+      d = c; c = b; b = a;
+      a = (t1 + t2) >>> 0;
+    }
+    h[0] = (h[0] + a) >>> 0; h[1] = (h[1] + b) >>> 0; h[2] = (h[2] + c) >>> 0; h[3] = (h[3] + d) >>> 0;
+    h[4] = (h[4] + e) >>> 0; h[5] = (h[5] + f) >>> 0; h[6] = (h[6] + g) >>> 0; h[7] = (h[7] + hh) >>> 0;
+  }
+  const out = new Uint8Array(32);
+  const outView = new DataView(out.buffer);
+  for (let i = 0; i < 8; i++) outView.setUint32(i * 4, h[i]);
+  return out;
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {string} the digest as 64 lowercase hex digits
+ */
+export function sha256Hex(bytes) {
+  return Array.from(sha256(bytes), (b) => b.toString(16).padStart(2, '0')).join('');
+}

package/src/machine/trs80-system.js

@@ -0,0 +1,232 @@
+/**
+ * TRS-80 Model III System
+ *
+ * Owns and wires the machine: Z80 CPU, memory map, I/O ports, and the
+ * keyboard matrix. Runs the CPU in T-state-budgeted slices at the real
+ * 2.02752 MHz clock and raises the 30 Hz RTC heartbeat interrupt the
+ * ROM's clock/cursor services depend on.
+ *
+ * Rendering is the caller's concern: read `memory.videoRam` (or
+ * `screenText()`) and consult `memory.videoDirty`. Keyboard input goes
+ * through `system.keyboard` (press and release keys directly).
+ */
+
+import { Z80CPU } from "../cpu/z80cpu.js";
+import { MemorySystem } from "./memory.js";
+import { IOSystem, MODE_32COL_BIT } from "./io.js";
+import { KeyboardMatrix } from "../devices/keyboard.js";
+
+export const CPU_CLOCK_HZ = 2027520;
+export const RTC_HZ = 30;
+export const RTC_INTERVAL_TSTATES = CPU_CLOCK_HZ / RTC_HZ; // 67,584
+
+export class TRS80System {
+  constructor({ romData, log }) {
+    this.memory = new MemorySystem();
+    this.io = new IOSystem();
+    this.keyboard = new KeyboardMatrix();
+    this.cpu = new Z80CPU();
+    if (log !== undefined) {
+      this.cpu.log = log;
+      this.io.cassette.log = log;
+    }
+
+    this.memory.keyboard = this.keyboard;
+
+    this.cpu.readMemory = (addr) => this.memory.readByte(addr);
+    this.cpu.writeMemory = (addr, value) => this.memory.writeByte(addr, value);
+    this.cpu.readPort = (port) => this.io.readPort(port);
+    this.cpu.writePort = (port, value) => this.io.writePort(port, value);
+
+    // A mode-register change (e.g. the ROM handling CHR$(23)) redraws
+    // the same video RAM in a different layout — force a repaint.
+    this.io.onModeWrite = () => {
+      this.memory.videoDirty = true;
+    };
+
+    // Cassette-out sound transitions are stamped in CPU T-states
+    this.io.getCycles = () => this.cpu.cycles;
+
+    this.memory.loadROM(romData);
+
+    this.nextRtcAt = RTC_INTERVAL_TSTATES;
+    this.reset();
+  }
+
+  /**
+   * Hardware reset (the orange button): CPU restarts at 0x0000, interrupt
+   * latches clear, screen blanks. RAM contents survive, as on the real
+   * machine.
+   */
+  reset() {
+    this.cpu.reset();
+    this.io.reset();
+    this.keyboard.reset();
+    this.memory.clearVideoRAM();
+    this.nextRtcAt = this.cpu.cycles + RTC_INTERVAL_TSTATES;
+    this._nmiWasPending = false;
+  }
+
+  /**
+   * Execute instructions until `budget` T-states have elapsed, raising
+   * the RTC heartbeat on schedule and delivering pending interrupts
+   * between instructions. Returns the T-states actually consumed (the
+   * final instruction may overshoot slightly).
+   */
+  runTStates(budget) {
+    const start = this.cpu.cycles;
+    const target = start + budget;
+
+    while (this.cpu.cycles < target) {
+      this.stepInstruction();
+    }
+
+    return this.cpu.cycles - start;
+  }
+
+  /**
+   * One instruction boundary, the only place the machine advances: raise
+   * the RTC heartbeat when its T-state is due, deliver a pending
+   * interrupt or NMI edge, then call `beforeExecute` (if given) and
+   * execute one instruction, ticking the disk controller by its cost.
+   * `runTStates` and the Machine facade both step through here, so the
+   * RTC keeps one schedule however the machine is driven. Returns the
+   * T-states consumed, an interrupt response included.
+   * @param {() => boolean | 'stop' | void} [beforeExecute] called after interrupt delivery, with PC at the instruction about to run; returning true means it stood in for that instruction, which then does not execute; returning 'stop' means no instruction executes at all (a debugger break)
+   * @returns {number}
+   */
+  stepInstruction(beforeExecute) {
+    const start = this.cpu.cycles;
+    if (this.cpu.cycles >= this.nextRtcAt) {
+      this.io.raiseRTC();
+      this.nextRtcAt += RTC_INTERVAL_TSTATES;
+    }
+    if (this.io.pendingInterrupt()) {
+      this.cpu.interrupt();
+    }
+    // FDC INTRQ -> NMI, edge-triggered so one assertion fires one NMI
+    const nmiNow = this.io.nmiPending();
+    if (nmiNow && !this._nmiWasPending) {
+      this.cpu.nmi();
+    }
+    this._nmiWasPending = nmiNow;
+
+    // beforeExecute returning true has executed the boundary's instruction itself (the
+    // Machine's ROM keyboard-scan hook stands in for a RET), so the CPU does not run one.
+    // Returning 'stop' runs nothing and the disk controller does not tick: like the normal path,
+    // it never ticks for an interrupt response's T-states. The return value is those T-states.
+    const before = this.cpu.cycles;
+    if (beforeExecute !== undefined) {
+      const r = beforeExecute();
+      if (r === 'stop') {
+        return before - start;
+      }
+      if (r !== true) this.cpu.executeInstruction();
+    } else {
+      this.cpu.executeInstruction();
+    }
+    this.io.fdc.tick(this.cpu.cycles - before);
+    return this.cpu.cycles - start;
+  }
+
+  /**
+   * True when the machine is in 32-character mode (mode register bit 2,
+   * set by the ROM for CHR$(23), cleared by CLS). The ROM lays 32-column
+   * text at even video addresses; hardware shows them double-wide.
+   */
+  get columns32() {
+    return (this.io.modeRegister & MODE_32COL_BIT) !== 0;
+  }
+
+  /** Mount a .dsk image (DiskImage) in drive 0-3. */
+  mountDisk(driveNumber, image) {
+    this.io.fdc.attachDrive(driveNumber, image);
+  }
+
+  /**
+   * Eject every drive and reboot into cassette BASIC, answering the
+   * ROM's Cass? and Memory Size? prompts. Cassette-world loaders (the
+   * library, .cas tapes, paste-BASIC) need the machine at READY — under
+   * a booted DOS their typed RUN goes to the DOS prompt instead. Runs
+   * ~3.5 emulated seconds inline, a blink of wall clock.
+   * @returns {boolean} true when the READY prompt was reached
+   */
+  bootToCassetteBasic() {
+    for (let drive = 0; drive < 4; drive++) {
+      this.ejectDisk(drive);
+    }
+    this.reset();
+    const pressEnter = () => {
+      this.keyboard.keyDown("Enter", "bootdance");
+      this.runTStates(200000);
+      this.keyboard.keyUp("bootdance");
+      this.runTStates(100000);
+    };
+    this.runSeconds(1);
+    pressEnter();
+    this.runSeconds(0.5);
+    pressEnter();
+    this.runSeconds(2);
+    return this.screenText().join("\n").includes("READY");
+  }
+
+  ejectDisk(driveNumber) {
+    this.io.fdc.ejectDrive(driveNumber);
+  }
+
+  /** Convenience for tests: run N emulated seconds. */
+  runSeconds(seconds) {
+    return this.runTStates(Math.round(seconds * CPU_CLOCK_HZ));
+  }
+
+  /**
+   * Type text through the keyboard matrix at emulated speed ("turbo
+   * paste"): each key is held long enough for the ROM's scan/debounce,
+   * but the wall-clock cost is only the emulation time (~3 ms/char).
+   * '\n' presses ENTER. Returns the number of characters that had no
+   * matrix mapping and were skipped.
+   *
+   * After ENTER the ROM tokenizes and stores the line (cost grows with
+   * program size) before it scans the keyboard again — give it room or
+   * the first character of the next line gets eaten. The default suits
+   * the small built-in classics; pass a larger `enterTStates` for
+   * multi-KB listings (a 5.7 KB program needs ~1M).
+   */
+  typeText(text, { enterTStates = 400000 } = {}) {
+    let skipped = 0;
+    let seq = 0;
+    for (const ch of text) {
+      const key = ch === "\n" ? "Enter" : ch;
+      const code = `typeText:${seq++}`;
+      if (!this.keyboard.keyDown(key, code)) {
+        skipped++;
+        continue;
+      }
+      this.runTStates(70000); // held across several scans + debounce
+      this.keyboard.keyUp(code);
+      this.runTStates(ch === "\n" ? enterTStates : 50000);
+    }
+    return skipped;
+  }
+
+  /**
+   * The 64x16 screen as strings, for tests and status displays.
+   * Control bytes 0x00-0x1F display as their 0x40-0x5F fold (Model III
+   * character generator); block-graphics bytes render as '.'.
+   */
+  screenText() {
+    const rows = [];
+    for (let row = 0; row < 16; row++) {
+      let line = "";
+      for (let col = 0; col < 64; col++) {
+        let byte = this.memory.videoRam[row * 64 + col];
+        if (byte < 0x20) {
+          byte += 0x40;
+        }
+        line += byte >= 0x20 && byte < 0x80 ? String.fromCharCode(byte) : ".";
+      }
+      rows.push(line);
+    }
+    return rows;
+  }
+}