@fugloy/emu 0.2.0 → 0.3.0

package/src/devices/interrupt-latch.js

@@ -0,0 +1,76 @@
+/**
+ * The Model I Expansion Interface's interrupt latch at $37E0: one object, owned by the Model I's
+ * I/O decode (`IOSystem.latch`, null on the Model III and on a Model I built with
+ * `expansion: false`), that every interrupting device of the Expansion Interface raises its bit in.
+ *
+ * - Bit 7 is the real-time clock: the Expansion Interface's 40 Hz pulse (a "25-millisecond pulse
+ *   on the interrupt line", "this 40-times-per-second pulse": Kitsz, The Custom TRS-80 and Other
+ *   Mysteries, p. 136; MAME's trs80 driver, `IRQ_M1_RTC` 0x80 and its 40 Hz periodic interrupt).
+ *   TRS80System raises it on schedule (`raise(TIMER_BIT)`).
+ * - Bit 6 is the disk controller's INTRQ (MAME, `IRQ_M1_FDC` 0x40). The WD1771 (emu phase 6,
+ *   Task 3) drives it with `raise(DISK_BIT)` and `clear(DISK_BIT)` as its INTRQ rises and falls;
+ *   reading the controller's status at $37EC is what drops it.
+ *
+ * Any bit set holds the CPU's INT line low; the Z80 takes it in IM 1 (or IM 0 with $FF on the bus)
+ * at $0038 whenever its interrupts are enabled. There is no mask: every source interrupts.
+ *
+ * Reading $37E0 (and its mirrors $37E1-$37E3, as MAME maps them; the mirrors are unverified) returns
+ * the latch and clears the clock bit: "reading 37EC (disk controller status) followed by reading
+ * 37E0 (real-time clock) resets a flip-flop used to signal input from disk controller and real-time
+ * clock, respectively. This must be done each time or the interrupt will continue to be 'on'"
+ * (Kitsz, p. 137). The disk bit is left for the status read to clear. Bits 0-5 read 0
+ * (unverified; MAME and xtrs return only the sources).
+ *
+ * The Level II ROM never reads it: its interrupt vector at $4012 is `EI / RET`
+ * (MDL1LEV2.Z80, INITR at $06D2), and Level II BASIC runs with interrupts disabled (DI at $0000 and
+ * no EI outside that vector), so the clock bit simply stays set until a DOS or a program enables
+ * interrupts with a handler that reads $37E0.
+ */
+
+/** The real-time clock's bit. */
+export const TIMER_BIT = 0x80;
+/** The disk controller's INTRQ bit. */
+export const DISK_BIT = 0x40;
+
+export class InterruptLatch {
+  /** @type {number} The pending sources (TIMER_BIT, DISK_BIT). */
+  bits = 0;
+
+  /**
+   * Set source bits: the INT line goes (or stays) low.
+   * @param {number} mask
+   */
+  raise(mask) {
+    this.bits |= mask & 0xff;
+  }
+
+  /**
+   * Clear source bits.
+   * @param {number} mask
+   */
+  clear(mask) {
+    this.bits &= ~mask & 0xff;
+  }
+
+  /** True while any source holds the INT line. */
+  get pending() {
+    return this.bits !== 0;
+  }
+
+  /** A CPU read of $37E0: the latch, after which the clock bit is cleared. */
+  read() {
+    const value = this.bits;
+    this.bits &= ~TIMER_BIT;
+    return value;
+  }
+
+  /** The latch as a read would return it, clearing nothing (for the debugger and `m.mem.read`). */
+  peek() {
+    return this.bits;
+  }
+
+  /** Power-on: nothing pending. */
+  reset() {
+    this.bits = 0;
+  }
+}

package/src/devices/key-queue.js

@@ -74,9 +74,18 @@ const KDCB = 0x4015;
  * `code` in A, verified against the ROM listing (spec §6, "Keyboard-scan hook"): DE = $4015 (the
  * KDCB), BC, HL, IX, IY and the alternate set unchanged, F as the routine's last flag-setting
  * instruction leaves it (`CP 01H` at $3100 for $002B, `OR A` at $004C for $0049), and the return
- * address popped. It also does what the CPU does at the end of any instruction: clears `afterPrefix`
- * and counts a pending EI down. It costs what a RET costs, 10 T-states and one refresh-counter step; the
- * routine's RAM side effects (its key-rollover buffer at $4036, the repeat counters) are not made.
+ * address popped.
+ *
+ * The Model I Level II ROM keeps the same contract (MDL1LEV2.Z80, kiwisincebirth/TRS-80-ROMS at
+ * 736bcba): `_KBD` at $002B loads DE with the KDCB ($4015) and goes through `_GET` ($0013) and
+ * `CIO` ($03C2), which saves BC, HL, IX, and that DE and restores them at `CIORTN` ($03DD), to the
+ * keyboard driver `KBDDRV` ($03E3, the KDCB's driver address at $4016), whose path for a key ends
+ * with `CP $01` at $0453 (the BREAK test) and `RET NZ`, or for BREAK `RST 28H` (a RET under
+ * Level II, $400C) and `RET`; `_KEY` at $0049 is `CALL _KBD / OR A / RET NZ / JR _KEY`. So the
+ * stand-in is the same on both models (phase 6 plan, Ruling 6). It also does what the CPU does at
+ * the end of any instruction: clears `afterPrefix` and counts a pending EI down. It costs what a
+ * RET costs, 10 T-states and one refresh-counter step; the routine's RAM side effects (its
+ * key-rollover buffer at $4036, the repeat counters) are not made.
  * @param {import('../cpu/z80cpu.js').Z80CPU} cpu
  * @param {number} pc
  * @param {number} code
@@ -113,6 +122,8 @@ export class KeyQueue {
   #matrix;
   /** @type {() => number} */
   #now;
+  /** @type {number} */
+  #clockHz;
   /** @type {KeyEvent[]} Matrix events in time order. */
   #events = [];
   /** @type {number} Index of the next undelivered matrix event. */
@@ -130,9 +141,15 @@ export class KeyQueue {
    * @param {import('./keyboard.js').KeyboardMatrix} matrix
    * @param {() => number} now the current T-state
    */
-  constructor(matrix, now) {
+  /**
+   * @param {import('./keyboard.js').KeyboardMatrix} matrix
+   * @param {() => number} now the CPU's T-state count
+   * @param {number} [clockHz] the CPU clock `type`'s cps counts in (the Model III's by default)
+   */
+  constructor(matrix, now, clockHz = CPU_CLOCK_HZ) {
     this.#matrix = matrix;
     this.#now = now;
+    this.#clockHz = clockHz;
   }
 
   /**
@@ -173,7 +190,7 @@ export class KeyQueue {
     if (mode === 'hook') return this.feed(str);
     if (mode !== 'matrix') throw new Error(`type: mode must be 'matrix' or 'hook', not ${String(mode)}`);
     if (!(cps > 0) || !Number.isFinite(cps)) throw new Error(`type: cps must be a positive number, not ${String(cps)}`);
-    const period = Math.round(CPU_CLOCK_HZ / cps);
+    const period = Math.round(this.#clockHz / cps);
     const hold = Math.round(period / 2);
     const keys = Array.from(str, (ch) => this.#mapped(ch, 'type'));
     this.#compact();

package/src/devices/video.js

@@ -1,7 +1,10 @@
 /**
- * The Model III video as a text readout: 16 lines over video RAM at $3C00-$3FFF, 64 columns, or
- * 32 in 32-column mode (port $EC bit 2), where the hardware shows the even-address bytes
- * double-wide. It reads the live video RAM; it draws nothing.
+ * The video as a text readout: 16 lines over video RAM at $3C00-$3FFF, 64 columns, or 32 in
+ * 32-column mode (on the Model III, port $EC bit 2; on the Model I, port $FF bit 3, MODESEL), where
+ * the hardware shows the even-address bytes double-wide. It reads the live video RAM; it draws
+ * nothing. The Model I's video RAM sits at the same addresses (models.js); the stock machine has no
+ * bit 6 there, so a byte reads back, and shows, with bit 6 made from bits 5 and 7 (memory.js, which
+ * cites the Technical Reference Handbook), unless the lowercase modification is fitted.
  */
 
 import { fromBase64 } from '../debug/state.js';

package/src/index.js

@@ -1,11 +1,12 @@
 /**
- * @fugloy/emu — headless, deterministic TRS-80 Model III emulator core.
+ * @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';
@@ -14,7 +15,7 @@ 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 } from './devices/disk-image.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';

package/src/loaders/load.js

@@ -10,6 +10,8 @@
 import { parseCmd, fastLoadCmd } from './cmd-format.js';
 import { parseCas, fastLoadBasic, fastLoadSystem } from './cas-format.js';
 import { casToPulses } from '../devices/cassette-tape.js';
+import { CPU_CLOCK_HZ } from '../machine/trs80-system.js';
+import { DiskImage, JV1_MODEL1_SD_TRACKS } from '../devices/disk-image.js';
 
 /**
  * @typedef {{ addr: number, len: number, why: string, predicted?: true }} ManifestBlock
@@ -17,14 +19,43 @@ import { casToPulses } from '../devices/cassette-tape.js';
  * @typedef {{ format: 'cmd', name: string, entry: number, blocks: ManifestBlock[] }} CmdManifest
  * @typedef {{ format: 'cas', kind: 'basic' | 'system', name: string, entry?: number, blocks: ManifestBlock[],
  *   baud: 500 | 1500 | null, via: 'rom' | 'fast' }} CasManifest
+ * @typedef {{ drive: number, container: 'jv1' | 'jv3' | 'dmk', tracks: number, sides: number,
+ *   sectorsPerTrack?: number, writeProtected: boolean }} DriveInfo
+ *   `sectorsPerTrack` is present only when every track side holds the same number of sectors
+ * @typedef {{ format: 'dsk', container: 'jv1' | 'jv3' | 'dmk', drive: number, boot: boolean, blocks: ManifestBlock[] }} DskManifest
+ *   `blocks` is empty: mounting writes nothing to memory (what the ROM or a DOS reads lands later)
  */
 
 const TXTTAB_PTR = 0x40a4;
 
-function checkBaud(baud) {
+/**
+ * @param {unknown} baud
+ * @param {import('../machine/machine.js').Machine} machine
+ */
+function checkBaud(baud, machine) {
+  if (machine.model === 1) {
+    // The Level II ROM reads only 500 baud (MDL1LEV2.Z80, CTBIT at $0241: one clock pulse and an
+    // optional data pulse a bit cell); 1500 baud is the Model III's.
+    if (baud !== 500) throw new Error(`The Model I reads cassettes at 500 baud only (1500 is the Model III's rate), not ${String(baud)}.`);
+    return;
+  }
   if (baud !== 500 && baud !== 1500) throw new Error(`cassette baud must be 500 or 1500 (the Model III's L and H rates), not ${String(baud)}`);
 }
 
+/**
+ * The pulse tape for `bytes` at `baud`, in T-states of this machine's clock. casToPulses times the
+ * tape in Model III T-states; a tape plays in real time, so on the Model I (a slower clock) every
+ * time is scaled by the clocks' ratio, which keeps the 500-baud bit cell at its 2 ms.
+ * @param {import('../machine/machine.js').Machine} machine
+ * @param {Uint8Array} bytes
+ * @param {500 | 1500} baud
+ */
+function pulsesFor(machine, bytes, baud) {
+  const times = casToPulses(tapeForBaud(bytes, baud), baud);
+  const scale = machine.system.clockHz / CPU_CLOCK_HZ;
+  return scale === 1 ? times : times.map((t) => Math.round(t * scale));
+}
+
 /**
  * The tape as the deck plays it at `baud`: the file's own leader and sync (00s or 55s, then A5
  * or 7F, any of which may be missing) replaced by 255 leader bytes and the sync byte of that
@@ -56,8 +87,8 @@ export function cassetteDeck(machine) {
      * @param {{ baud?: 500 | 1500 }} [opts]
      */
     insert(bytes, { baud = 500 } = {}) {
-      checkBaud(baud);
-      deck.insertPulseTape(casToPulses(tapeForBaud(bytes, baud), baud));
+      checkBaud(baud, machine);
+      deck.insertPulseTape(pulsesFor(machine, bytes, baud));
     },
     /** Back to the start of the tape. */
     rewind() {
@@ -103,7 +134,7 @@ export function loadCmd(machine, bytes) {
  */
 export function loadCas(machine, bytes, { baud = 500, via = 'rom' } = {}) {
   if (via !== 'rom' && via !== 'fast') throw new Error(`load.cas: via must be 'rom' or 'fast', not ${String(via)}`);
-  if (via === 'rom') checkBaud(baud);
+  if (via === 'rom') checkBaud(baud, machine);
   const parsed = parseCas(bytes);
   const system = machine.system;
 
@@ -121,7 +152,7 @@ export function loadCas(machine, bytes, { baud = 500, via = 'rom' } = {}) {
   if (via === 'rom') blocks = blocks.map((b) => ({ ...b, predicted: /** @type {true} */ (true) }));
 
   if (via === 'rom') {
-    system.io.cassette.insertPulseTape(casToPulses(tapeForBaud(bytes, baud), baud));
+    system.io.cassette.insertPulseTape(pulsesFor(machine, bytes, baud));
   } else if (parsed.kind === 'system') {
     fastLoadSystem(system, parsed);
   } else {
@@ -133,3 +164,136 @@ export function loadCas(machine, bytes, { baud = 500, via = 'rom' } = {}) {
   const tail = { blocks, baud: via === 'rom' ? baud : null, via };
   return parsed.kind === 'system' ? { ...head, entry: parsed.entry, ...tail } : { ...head, ...tail };
 }
+
+/**
+ * What a mounted disk looks like from outside: its container and geometry, as `DiskImage` parsed
+ * them, and whether writes are refused.
+ * @param {number} drive
+ * @param {DiskImage} disk
+ * @returns {DriveInfo}
+ */
+function driveInfo(drive, disk) {
+  const container = /** @type {'jv1' | 'jv3' | 'dmk'} */ (disk.format);
+  const tracks = disk.trackCount();
+  const sides = disk.sideCount();
+  /** @type {Set<number>} */
+  const counts = new Set();
+  if (container === 'jv1') counts.add(disk.sectorsPerTrack);
+  else {
+    for (let t = 0; t < tracks; t++) for (let side = 0; side < sides; side++) counts.add(disk.sectorsOn(t, side).length);
+  }
+  const info = { drive, container, tracks, sides };
+  const [spt] = counts;
+  return counts.size === 1 && spt > 0 ? { ...info, sectorsPerTrack: spt, writeProtected: disk.writeProtected } : { ...info, writeProtected: disk.writeProtected };
+}
+
+function checkDrive(op, drive) {
+  if (!Number.isInteger(drive) || drive < 0 || drive > 3) throw new Error(`${op}: drive must be 0, 1, 2, or 3, not ${String(drive)}`);
+}
+
+/**
+ * The four floppy drives of the Model III's WD1793 controller, or of the Model I Expansion
+ * Interface's WD1771 (spec §3, §6), over `TRS80System.mountDisk` and `ejectDisk`. With no disk in
+ * any drive the controller's ports (on the Model I its addresses $37EC-$37EF) float (read $FF),
+ * which is what sends the ROM to cassette BASIC (Level II BASIC on the Model I) at reset, so a
+ * machine with nothing mounted boots as it did before disks existed. A Model I built without the
+ * Expansion Interface has no disk controller, and refuses a mount. On a Model I a 10-sector JV1
+ * may have 35 to 42, 77, or 80 tracks (disk-image.js, JV1_MODEL1_SD_TRACKS).
+ * @param {import('../machine/machine.js').Machine} machine
+ */
+export function diskDrives(machine) {
+  const system = machine.system;
+  const model1 = system.model.id === 1;
+  return {
+    /**
+     * Put a disk in a drive, replacing what was there. Bytes are copied into a new `DiskImage`
+     * (the container is detected from the content: DMK, then JV3, then JV1 by size); a
+     * `DiskImage` is mounted as it is, so writes the machine makes show in it.
+     * @param {number} drive 0..3
+     * @param {Uint8Array | DiskImage} image
+     * @param {{ writeProtect?: boolean }} [opts] `writeProtect` overrides the image's own flag (the DMK or JV3 header's); a passed `DiskImage` has its `writeProtected` set
+     * @returns {DriveInfo}
+     */
+    mount(drive, image, { writeProtect } = {}) {
+      checkDrive('fdc.mount', drive);
+      if (writeProtect !== undefined && typeof writeProtect !== 'boolean') throw new Error(`fdc.mount: writeProtect must be true or false, not ${String(writeProtect)}`);
+      if (model1 && system.io.latch === null) {
+        throw new Error('fdc.mount: this Model I has no Expansion Interface, so no disk controller; construct the Machine with expansion: true (the default) to mount a disk');
+      }
+      let disk;
+      if (image instanceof DiskImage) disk = image;
+      else if (ArrayBuffer.isView(image) && image.BYTES_PER_ELEMENT === 1) {
+        try {
+          disk = new DiskImage(/** @type {Uint8Array} */ (image), `drive ${drive}`, model1 ? { jv1SdTracks: JV1_MODEL1_SD_TRACKS } : {});
+        } catch (e) {
+          throw new Error(`fdc.mount: ${/** @type {Error} */ (e).message}`);
+        }
+      } else throw new Error('fdc.mount: the image must be a Uint8Array of a JV1, JV3, or DMK file, or a DiskImage');
+      if (writeProtect !== undefined) disk.writeProtected = writeProtect;
+      system.mountDisk(drive, disk);
+      return driveInfo(drive, disk);
+    },
+    /**
+     * Take the disk out of a drive.
+     * @param {number} drive 0..3
+     * @returns {boolean} true when there was a disk to take out
+     */
+    unmount(drive) {
+      checkDrive('fdc.unmount', drive);
+      const had = system.io.fdc.drives[drive] !== null;
+      system.ejectDisk(drive);
+      return had;
+    },
+    /**
+     * The four drives, in order: each one's mount info, or null when empty. Read from the
+     * controller each time, so it follows a snapshot restore.
+     * @returns {(DriveInfo | null)[]}
+     */
+    get drives() {
+      return system.io.fdc.drives.map((/** @type {DiskImage | null} */ d, i) => (d === null ? null : driveInfo(i, d)));
+    },
+    /**
+     * The disk in a drive as DMK bytes (spec §6: read JV1, JV3, and DMK; write DMK only), with
+     * every write the machine has made to it: a DMK as it now stands, a JV1 or JV3 laid out as
+     * raw tracks with each sector's ID, density, data mark, and CRCs (`DiskImage.toDMK`). The
+     * bytes mount back with the same sectors.
+     * @param {number} drive 0..3
+     * @returns {Uint8Array}
+     */
+    export(drive) {
+      checkDrive('fdc.export', drive);
+      const disk = system.io.fdc.drives[drive];
+      if (disk === null) throw new Error(`fdc.export: drive ${drive} is empty`);
+      return disk.toDMK();
+    },
+  };
+}
+
+/**
+ * Load a disk image: mount it, and with `boot` reset the machine so the ROM boots from drive 0
+ * (the Model III ROM reads track 0, sector 1 to $4300 and jumps there, ROM $34D9-$3516; the Model I
+ * Level II ROM reads track 0, sector 0 to $4200 and jumps there, MDL1LEV2.Z80 BOOT at $069F-$06C9,
+ * after its PAUSE at $06AF, 65,536 passes of 26 T-states, about a second). Nothing is in memory
+ * when this returns, so the manifest's `blocks` is empty. Booting needs a disk in drive 0, this one
+ * or one mounted before. A reset clears the keyboard queue; without `boot` it is left alone.
+ * @param {import('../machine/machine.js').Machine} machine
+ * @param {Uint8Array} bytes
+ * @param {{ drive?: number, boot?: boolean }} [opts]
+ * @returns {DskManifest}
+ */
+export function loadDsk(machine, bytes, { drive = 0, boot = true } = {}) {
+  checkDrive('load.dsk', drive);
+  if (typeof boot !== 'boolean') throw new Error(`load.dsk: boot must be true or false, not ${String(boot)}`);
+  if (!(ArrayBuffer.isView(bytes) && bytes.BYTES_PER_ELEMENT === 1)) throw new Error('load.dsk: bytes must be a Uint8Array of a JV1, JV3, or DMK file');
+  if (boot && drive !== 0 && machine.system.io.fdc.drives[0] === null) {
+    throw new Error(`load.dsk: the ROM boots from drive 0, which is empty; mount a disk there first, or load into drive 0, or pass boot: false`);
+  }
+  let info;
+  try {
+    info = machine.fdc.mount(drive, bytes);
+  } catch (e) {
+    throw new Error(/** @type {Error} */ (e).message.replace(/^fdc\.mount/, 'load.dsk'));
+  }
+  if (boot) machine.reset();
+  return { format: 'dsk', container: info.container, drive, boot, blocks: [] };
+}

package/src/machine/drive-select.js

@@ -0,0 +1,42 @@
+/**
+ * Each model's drive-select latch, decoded into the controller's neutral `select(drive, side,
+ * mfm)` (devices/fdc-wd1793.js). A module of its own so the controllers and the I/O decode
+ * (machine/io.js, which re-exports these) can import it without an import cycle.
+ */
+
+/**
+ * Decode a Model III port F4 write: bits 0-3 select drive 0-3 (the lowest set bit wins; none set
+ * selects no drive, -1), bit 4 the side, bit 6 WAIT, bit 7 MFM (1) or FM (0); bit 5, write
+ * precompensation, does nothing here. Bits from MAME's trs80m3 driver and the ROM's use, not yet
+ * checked against the Model III Technical Reference Manual (spec §5).
+ * @param {number} value
+ * @returns {{ drive: number, side: number, mfm: boolean, wait: boolean }}
+ */
+export function decodeModel3Select(value) {
+  let drive = -1;
+  if (value & 0x01) drive = 0;
+  else if (value & 0x02) drive = 1;
+  else if (value & 0x04) drive = 2;
+  else if (value & 0x08) drive = 3;
+  return { drive, side: value & 0x10 ? 1 : 0, mfm: (value & 0x80) !== 0, wait: (value & 0x40) !== 0 };
+}
+
+/**
+ * Decode a write to the Model I Expansion Interface's drive-select latch at $37E1: "a 4-bit drive
+ * select indicator sent to the drive" (Kitsz, The Custom TRS-80 and Other Mysteries, ch. 9,
+ * pp. 205-206), bits 0-3 for drives 0-3; the Level II ROM selects drive 0 by writing 1
+ * (MDL1LEV2.Z80, BOOT at $069F). The lowest set bit wins, as on the Model III (the hardware would
+ * select every drive whose bit is set); none set selects no drive, -1. The stock interface is
+ * single-sided and single-density, so bits 4-7 do nothing here (double-density and side-select
+ * modifications used them; not modelled).
+ * @param {number} value
+ * @returns {{ drive: number }}
+ */
+export function decodeModel1Select(value) {
+  let drive = -1;
+  if (value & 0x01) drive = 0;
+  else if (value & 0x02) drive = 1;
+  else if (value & 0x04) drive = 2;
+  else if (value & 0x08) drive = 3;
+  return { drive };
+}