@fugloy/emu 0.2.0 → 0.3.0

package/src/machine/io.js

@@ -7,20 +7,43 @@
  *   0xEC-0xEF  read: acknowledge/clear the RTC interrupt
  *              write: mode register (bit 1 = cassette motor,
  *                     bit 2 = 32-column mode, bit 3 = alt charset)
- *   0xF0-0xF3  floppy controller — absent; reads float to 0xFF
- *   0xF4       drive select — absent
+ *   0xE4-0xE7  read: NMI status, active-low (bit 7 = FDC INTRQ)
+ *              write: NMI mask (bit 7 = FDC INTRQ raises NMI)
+ *   0xF0-0xF3  WD1793 floppy controller; with no disk mounted anywhere it
+ *              is absent and reads float to 0xFF
+ *   0xF4       drive select (write): bits 0-3 drive, bit 4 side, bit 6
+ *              WAIT, bit 7 MFM
  *   0xF8-0xFB  line printer (read: status, write: data byte)
  *   0xFF       cassette port (write bits 0-1 = output level,
- *              read bit 7 = tape input)
+ *              read: bit 7 = 500-baud pulse latch, bit 0 = 1500-baud
+ *              level, bits 5-1 = port 0xEC's latch, bit 6 high)
  *
  * The RTC heartbeat interrupt fires at 30 Hz; its latch bit is RTC_IRQ_BIT.
  * The keyboard is memory-mapped at 0x3800-0x3BFF (see MemorySystem), not
  * an I/O port.
+ *
+ * The Model I has only port 0xFF (cassette, sound, and the video mode; its
+ * own handler, initializeModel1CassettePort): its other devices are
+ * memory-mapped by the Expansion Interface at 0x37E0-0x37EF
+ * (src/machine/models.js), which MemorySystem hands to `readExpansion`,
+ * `peekExpansion`, and `writeExpansion` here, so every other port floats to
+ * 0xFF. With the Expansion Interface (`expansion`, the default) the Model I
+ * has the interrupt latch at 0x37E0 (`latch`, devices/interrupt-latch.js),
+ * the drive select at 0x37E1, the printer at 0x37E8, and the WD1771 at
+ * 0x37EC-0x37EF (devices/fdc-wd1771.js, its INTRQ on the latch's bit 6);
+ * without it `latch` is null and nothing interrupts. The controller object
+ * exists on both models, clocked at the model's CPU clock (a WD1793 on the
+ * Model III, a WD1771 on the Model I); the Model I does not reach it through
+ * ports, and without the Expansion Interface not at all.
  */
 
 import { CassetteSystem } from "../devices/cassette.js";
 import { FDC1793 } from "../devices/fdc-wd1793.js";
+import { FDC1771 } from "../devices/fdc-wd1771.js";
 import { Printer } from "../devices/printer.js";
+import { InterruptLatch } from "../devices/interrupt-latch.js";
+import { MODEL_III } from "./models.js";
+import { decodeModel1Select, decodeModel3Select } from "./drive-select.js";
 
 export const RTC_IRQ_BIT = 0x04;
 // Cassette-edge interrupt sources (from the ROM's ISR at 0x35C2: E0
@@ -37,10 +60,32 @@ export const NMI_INTRQ_BIT = 0x80;
 // Mode register (port 0xEC write) bits
 export const MODE_32COL_BIT = 0x04; // 32-character display mode
 
+// The Model I's port 0xFF output latch (Z59), D0-D3: "D0 and D1 ... are used
+// to output data that is recorded on tape during a CSAVE function. D2 ...
+// controls the status of the Recorder's motor. D3 ... controls the status of
+// MODESEL*" (TRS-80 Micro Computer Technical Reference Handbook, 2nd ed.,
+// 1982, p. 45, "OUTSIG*"). On the Model I `modeRegister` holds this latch.
+export const M1_MOTOR_BIT = 0x04;
+export const M1_MODESEL_BIT = 0x08; // 32-character display mode
+
+export { decodeModel1Select, decodeModel3Select } from "./drive-select.js";
+
 export class IOSystem {
-  constructor() {
+  /**
+   * @param {{ model?: import('./models.js').Model, expansion?: boolean }} [opts] the model whose
+   *   ports to install (the Model III by default), and on the Model I whether the Expansion
+   *   Interface is fitted (by default it is)
+   */
+  constructor({ model = MODEL_III, expansion = true } = {}) {
+    this.model = model;
+    // The Expansion Interface's interrupt latch at 0x37E0: the one object the timer (bit 7) and
+    // the disk controller (bit 6, emu phase 6 Task 3) raise and clear their bits in.
+    /** @type {InterruptLatch | null} */
+    this.latch = model.id === 1 && expansion ? new InterruptLatch() : null;
     this.cassette = new CassetteSystem();
-    this.fdc = new FDC1793();
+    // A Model I recording decodes in Model III T-states (cassette.js)
+    if (model.id !== 3) this.cassette.timeScale = MODEL_III.clockHz / model.clockHz;
+    this.fdc = model.id === 3 ? new FDC1793({ cpuHz: model.clockHz }) : new FDC1771({ cpuHz: model.clockHz, latch: this.latch });
     this.printer = new Printer();
     this.keyboardBuffer = []; // legacy internal buffer (not a Model III port)
     this.portHandlers = new Map();
@@ -52,7 +97,8 @@ export class IOSystem {
     // NMI mask (port 0xE4 write): bit 7 = FDC INTRQ triggers NMI
     this.nmiMask = 0;
 
-    // Mode register (port 0xEC write)
+    // Mode register (port 0xEC write); on the Model I, the port 0xFF
+    // output latch, D0-D3 (M1_MOTOR_BIT, M1_MODESEL_BIT)
     this.modeRegister = 0;
 
     // Fired when a mode-register write changes the value (the display
@@ -74,8 +120,21 @@ export class IOSystem {
     this.onSoundWrite = null;
     // Called when the timeline restarts (state restore): the Machine clears its sound ring.
     this.onSoundReset = null;
+    // The Model III WAIT (port F4 bit 6): called with a function that runs the controller to
+    // its next DRQ or INTRQ and returns the T-states that took, for the CPU to wait them; wired
+    // by TRS80System. Unwired, port F4 does not wait.
+    this.onWait = null;
 
-    this.initializeModelIIIPorts();
+    if (model.id === 3) {
+      this.initializeModelIIIPorts();
+      this.initializeCassettePort();
+    } else {
+      this.initializeModel1CassettePort();
+      // The Model I interrupts through the Expansion Interface's latch alone, which has no mask
+      // (none without the interface); the Model III's pendingInterrupt below is left as it was.
+      const latch = this.latch;
+      this.pendingInterrupt = latch === null ? () => false : () => latch.bits !== 0;
+    }
   }
 
   initializeModelIIIPorts() {
@@ -114,6 +173,10 @@ export class IOSystem {
 
     // 0xE4-0xE7: disk NMI mask (write) / status (read, active-low).
     // With no controller "present" (no disk mounted) the port floats.
+    // Bit 7 is the FDC's INTRQ, read live. MAME's trs80m3 driver also
+    // names bit 6 (motor timeout, its own NMI enable) and bit 5 (the reset
+    // button); neither is modeled, and none of this is yet checked against
+    // the Model III Technical Reference Manual (spec §5).
     for (let port = 0xe4; port <= 0xe7; port++) {
       this.portHandlers.set(port, {
         read: () => {
@@ -157,11 +220,17 @@ export class IOSystem {
       },
     });
 
-    // 0xF4: drive select / side / density latch
+    // 0xF4: drive select / side / density latch. Bit 6 asserts WAIT
+    // until the controller raises DRQ or INTRQ (MAME's trs80m3: only when
+    // both are low); the ROM's boot read and the DOSes' INI loops rely on
+    // it to take each byte as it arrives.
     this.portHandlers.set(0xf4, {
       read: () => 0xff,
       write: (v) => {
-        if (fdcPresent()) this.fdc.selectDrive(v);
+        if (!fdcPresent()) return;
+        const sel = decodeModel3Select(v);
+        this.fdc.select(sel.drive, sel.side, sel.mfm);
+        if (sel.wait && this.onWait) this.onWait(() => this.fdc.waitForDrq());
       },
     });
 
@@ -174,7 +243,10 @@ export class IOSystem {
         write: (v) => this.printer.write(v),
       });
     }
+  }
 
+  /** Port 0xFF on the Model III. */
+  initializeCassettePort() {
     // 0xFF: cassette data port. Reads return the input latch in bit 7
     // (set by tape transitions while the motor runs); ANY write clears
     // the latch — that's the Model III's latch circuit, and it's how
@@ -190,11 +262,15 @@ export class IOSystem {
         //           does IN A,(0xFF) / AND 0x01 / CP E per edge);
         //   bit 7 — a rising-edge PULSE LATCH (the 500-baud reader
         //           polls it with RLA and resets it by OUT (0xFF),A).
+        // Bits 5-1 read port 0xEC's latch back (DISWAIT, ENEXTIO, ENALTSET,
+        // MODSEL, CASMOTORON), and bit 6 is undefined: Model III Technical
+        // Reference Manual p. 22 (CASIN*). Undriven, bit 6 floats high, as
+        // an absent port's bits do; trs80gp (and trsjs) read it as 1 too.
         // Reading also acks the edge interrupt sources: the ISR reads
         // 0xE0 then 0xFF and nothing else.
         this.intLatch &= ~(CASSETTE_RISE_IRQ_BIT | CASSETTE_FALL_IRQ_BIT);
         const level = this.cassette.tapeLevel(cycles);
-        return (this.cassette.pulseLatch ? 0x80 : 0x00) | (level ? 0x01 : 0x00);
+        return (this.cassette.pulseLatch ? 0x80 : 0x00) | 0x40 | (this.modeRegister & 0x3e) | (level ? 0x01 : 0x00);
       },
       write: (value) => {
         const cycles = this.getCycles ? this.getCycles() : 0;
@@ -212,6 +288,156 @@ export class IOSystem {
     });
   }
 
+  /**
+   * Port 0xFF on the Model I. The port is the Z59 output latch and one input
+   * flip-flop (Technical Reference Handbook, 2nd ed., p. 45, "OUTSIG*",
+   * and pp. 50-51, "INSIG*"):
+   *   write D0-D1  cassette output level (the only sound source; logged for
+   *                the sound driver and m.sound, and recorded while the
+   *                motor runs, as on the Model III)
+   *   write D2     the cassette motor relay
+   *   write D3     MODESEL: 32 characters a line when set
+   *   any write    resets the cassette flip-flop ("set by cassette data and
+   *                reset by OUTSIG*", p. 50)
+   *   read  D7     the cassette flip-flop: the Level II ROM's bit reader
+   *                (MDL1LEV2.Z80, CTBIT at $0241) polls it with RLA and resets
+   *                it through CTSTAT ($021E), an OUT of the shadow copy CAST
+   * The other read bits are MAME's (trs80 driver, port_ff_r: D6 is MODESEL
+   * inverted, D0-D5 read 1); the handbook says only that INSIG* enables the
+   * flip-flop's buffer, so they are unverified. The deck sets the flip-flop
+   * on a rising edge of the tape signal (cassette.js); MAME takes the
+   * falling edge, which for the 500-baud pulses moves nothing a reader sees.
+   */
+  initializeModel1CassettePort() {
+    this.portHandlers.set(0xff, {
+      read: () => {
+        const cycles = this.getCycles ? this.getCycles() : 0;
+        this.cassette.tapeLevel(cycles); // play the tape up to now
+        return (
+          (this.cassette.pulseLatch ? 0x80 : 0x00) |
+          (this.modeRegister & M1_MODESEL_BIT ? 0x00 : 0x40) |
+          0x3f
+        );
+      },
+      write: (value) => {
+        const cycles = this.getCycles ? this.getCycles() : 0;
+        if (this.onSoundWrite) this.onSoundWrite(cycles, value);
+        const motor = (value & M1_MOTOR_BIT) !== 0;
+        if (motor !== this.cassette.motorOn) {
+          this.cassette.control(motor ? 1 : 0, cycles);
+        }
+        const level = value & 0x03;
+        if (level !== this.cassetteOut) {
+          this.cassetteOut = level;
+          if (this.getCycles && this.soundLog.length < this.SOUND_LOG_LIMIT) {
+            this.soundLog.push({ t: cycles, level });
+          }
+          this.cassette.recordTransition(cycles, level);
+        }
+        const latch = value & 0x0f;
+        const changed = (latch ^ this.modeRegister) & M1_MODESEL_BIT;
+        this.modeRegister = latch;
+        if (changed && this.onModeWrite) this.onModeWrite(this.modeRegister);
+        this.cassette.clearPulseLatch(cycles);
+      },
+    });
+  }
+
+  /**
+   * A CPU read of the Model I's Expansion Interface addresses 0x37E0-0x37EF
+   * (MemorySystem calls it only on a Model I with the Expansion Interface):
+   *   0x37E0-0x37E3  the interrupt latch, clearing its clock bit
+   *                  (interrupt-latch.js; the mirrors are MAME's, unverified)
+   *   0x37E4-0x37E7  0xFF (the cassette select at 0x37E4 is write-only, and a
+   *                  second deck is not modelled)
+   *   0x37E8-0x37EB  the printer's status: the Level II ROM's PRTAVL at $05D1
+   *                  reads 0x37E8 and takes (status AND F0H) = 30H as ready
+   *                  (MDL1LEV2.Z80); the mirrors are MAME's (unverified)
+   *   0x37EC-0x37EF  the WD1771: status, track, sector, data (CONSTANTS.Z80,
+   *                  "Memory Mapped Hardware, Model 1"); a status read clears
+   *                  INTRQ and with it the latch's disk bit
+   * With no disk mounted in any drive the controller is taken as absent, as on
+   * the Model III, and 0x37EC-0x37EF read 0xFF: the ROM's test at $0696-$069C
+   * (status + 1 < 2, that is $FF or $00: no disk controller) then sends it to
+   * Level II BASIC instead of a boot that would wait for a disk forever.
+   * @param {number} address
+   */
+  readExpansion(address) {
+    if (address <= 0x37e3) return this.latch.read();
+    if (address >= 0x37ec) {
+      if (!this.fdc.anyDiskMounted()) return 0xff;
+      switch (address) {
+        case 0x37ec:
+          return this.fdc.readStatus();
+        case 0x37ed:
+          return this.fdc.readTrackReg();
+        case 0x37ee:
+          return this.fdc.readSectorReg();
+        default:
+          return this.fdc.readData();
+      }
+    }
+    if (address >= 0x37e8) return this.printer.status();
+    return 0xff;
+  }
+
+  /**
+   * What `readExpansion` would return, with no side effect (the latch keeps
+   * its clock bit, the controller its INTRQ and DRQ).
+   * @param {number} address
+   */
+  peekExpansion(address) {
+    if (address <= 0x37e3) return this.latch.peek();
+    if (address >= 0x37ec) {
+      if (!this.fdc.anyDiskMounted()) return 0xff;
+      if (address === 0x37ec) return this.fdc.peekStatus();
+      if (address === 0x37ed) return this.fdc.trackReg;
+      if (address === 0x37ee) return this.fdc.sectorReg;
+      return this.fdc.dataReg;
+    }
+    if (address >= 0x37e8) return this.printer.status();
+    return 0xff;
+  }
+
+  /**
+   * A CPU write to 0x37E0-0x37EF:
+   *   0x37E0-0x37E3  the drive select (decodeModel1Select; written at 0x37E1,
+   *                  the mirrors are MAME's, unverified). The latch is the
+   *                  Expansion Interface's, not the controller's, so it takes
+   *                  a write with no disk mounted too, and a disk mounted
+   *                  later finds the drive the program last selected
+   *   0x37E8-0x37EB  a byte to the printer (the ROM's `LD (37E8H),A` at $05BB)
+   *   0x37EC-0x37EF  the WD1771: command, track, sector, data
+   * The controller's registers ignore writes while no disk is mounted
+   * (absent, as above).
+   * @param {number} address
+   * @param {number} value
+   */
+  writeExpansion(address, value) {
+    if (address <= 0x37e3) {
+      this.fdc.select(decodeModel1Select(value).drive, 0, false);
+      return;
+    }
+    if (address >= 0x37ec) {
+      if (!this.fdc.anyDiskMounted()) return;
+      switch (address) {
+        case 0x37ec:
+          this.fdc.writeCommand(value);
+          return;
+        case 0x37ed:
+          this.fdc.writeTrackReg(value);
+          return;
+        case 0x37ee:
+          this.fdc.writeSectorReg(value);
+          return;
+        default:
+          this.fdc.writeData(value);
+      }
+      return;
+    }
+    if (address >= 0x37e8) this.printer.write(value);
+  }
+
   readPort(port) {
     port &= 0xff;
     const handler = this.portHandlers.get(port);
@@ -261,17 +487,14 @@ export class IOSystem {
 
   /** Clear interrupt state (system reset). Mounted disks stay mounted. */
   reset() {
+    this.latch?.reset();
     this.intLatch = 0;
     this.intMask = 0;
     this.nmiMask = 0;
     this.modeRegister = 0;
     this.cassetteOut = 0;
     this.soundLog = [];
-    this.fdc.intrq = false;
-    this.fdc.pending = null;
-    this.fdc.buffer = null;
-    this.fdc.status = 0;
-    this.fdc.commandType = 1;
+    this.fdc.reset();
   }
 
   readKeyboard() {

package/src/machine/machine.js

@@ -1,15 +1,17 @@
 /**
- * The spec §3 `Machine`: the public face of the emulator, over a TRS80System. Phase 2 builds
- * the Model III with 48K; execution, state access, and ROM identification live here, and the
- * device, loader, and debug surfaces arrive in later tasks.
+ * The spec §3 `Machine`: the public face of the emulator, over a TRS80System. It builds the
+ * Model III with 48K, or (emu phase 6) the Model I with 4, 16, 32, or 48K, as the model
+ * descriptions in models.js lay them out; execution, state access, ROM identification, the
+ * devices, the loaders, and the debugger live here.
  */
 import { TRS80System } from './trs80-system.js';
 import { ROM_HASHES } from './rom-hashes.js';
+import { modelOf, ramProblem, romModelProblem } from './models.js';
 import { sha256Hex } from './sha256.js';
 import { Video } from '../devices/video.js';
 import { Sound } from '../devices/sound.js';
 import { loadBas } from '../loaders/bas.js';
-import { cassetteDeck, loadCas, loadCmd } from '../loaders/load.js';
+import { cassetteDeck, diskDrives, loadCas, loadCmd, loadDsk } from '../loaders/load.js';
 import { Debugger } from '../debug/debugger.js';
 import { KeyQueue, romKeyReturn } from '../devices/key-queue.js';
 
@@ -41,12 +43,15 @@ export class Machine {
   keyboard;
   /**
    * @type {{ bas(bytes: Uint8Array): ReturnType<typeof loadBas>, cmd(bytes: Uint8Array): ReturnType<typeof loadCmd>,
-   *   cas(bytes: Uint8Array, opts?: { baud?: 500 | 1500, via?: 'rom' | 'fast' }): ReturnType<typeof loadCas> }}
+   *   cas(bytes: Uint8Array, opts?: { baud?: 500 | 1500, via?: 'rom' | 'fast' }): ReturnType<typeof loadCas>,
+   *   dsk(bytes: Uint8Array, opts?: { drive?: number, boot?: boolean }): ReturnType<typeof loadDsk> }}
    * Program loaders; each returns a manifest of where the bytes land and why.
    */
   load;
   /** @type {ReturnType<typeof cassetteDeck>} The cassette deck: insert a .CAS at a baud, rewind, read the motor relay. */
   cassette;
+  /** @type {ReturnType<typeof diskDrives>} The four floppy drives: mount a JV1, JV3, or DMK image, unmount, list what is in each, export one as DMK. */
+  fdc;
   /** @type {Debugger} Breakpoints, watchpoints, hooks, coverage, the instruction trace, snapshots, labels, and the label file (spec §7, §8). */
   debug;
 
@@ -62,18 +67,32 @@ export class Machine {
   #stopped = false;
 
   /**
-   * @param {{ model?: 3, ram?: 48, roms: { level2: Uint8Array }, log?: (level: string, text: string) => void }} opts
+   * @param {{ model?: 1 | 3, ram?: 4 | 16 | 32 | 48, roms: { level2: Uint8Array }, expansion?: boolean, lowercase?: boolean,
+   *   log?: (level: string, text: string) => void }} opts
+   *   `ram` defaults to 48 (the Model III takes only 48 for now); `expansion` (the Expansion Interface, default
+   *   true) and `lowercase` (the lowercase modification, default false) are Model I options
    */
-  constructor({ model = 3, ram = 48, roms, log } = /** @type {any} */ ({})) {
-    if (model !== 3 || ram !== 48) {
-      throw new Error(`phase 2 builds the Model III with 48K; got model ${model} with ${ram}K (the Model I, the Model 4, and other RAM sizes come in later phases)`);
+  constructor({ model = 3, ram, roms, expansion, lowercase, log } = /** @type {any} */ ({})) {
+    const desc = modelOf(model);
+    const kb = ram ?? desc.defaultRam;
+    const badRam = ramProblem(desc, kb);
+    if (badRam !== null) throw new Error(badRam);
+    for (const [name, value] of /** @type {const} */ ([['expansion', expansion], ['lowercase', lowercase]])) {
+      if (value === undefined) continue;
+      if (desc.id !== 1) throw new Error(`${name} is a Model I option; the ${desc.name} has no ${name === 'expansion' ? 'Expansion Interface' : 'lowercase modification (its lowercase is built in)'}.`);
+      if (typeof value !== 'boolean') throw new Error(`${name} must be true or false, not ${String(value)}.`);
     }
     const level2 = roms?.level2;
     if (!ArrayBuffer.isView(level2) || level2.BYTES_PER_ELEMENT !== 1) throw new Error('Machine needs roms.level2, the ROM image as a Uint8Array');
 
-    this.system = new TRS80System({ romData: level2, log });
+    // A ROM recognised as the other model's is refused by name before its size is checked, so the
+    // sentence says which model it needs rather than only that its length is wrong.
     const sha256 = sha256Hex(level2);
-    this.rom = { bytes: level2.length, sha256, recognized: ROM_HASHES[sha256] ?? null };
+    const recognized = ROM_HASHES[sha256] ?? null;
+    const problem = romModelProblem(recognized, desc.id);
+    if (problem !== null) throw new Error(problem);
+    this.system = new TRS80System({ romData: level2, log, model: desc, ram: kb, expansion: expansion ?? true, lowercase: lowercase ?? false });
+    this.rom = { bytes: level2.length, sha256, recognized };
 
     const sys = this.system;
     const cpu = sys.cpu;
@@ -95,7 +114,8 @@ export class Machine {
     this.mem = {
       read(addr, len) {
         const out = new Uint8Array(len);
-        for (let k = 0; k < len; k++) out[k] = sys.memory.readByte((addr + k) & 0xffff);
+        // Peeked: reading the Model I's interrupt latch here does not clear it, as a CPU read would.
+        for (let k = 0; k < len; k++) out[k] = sys.memory.peekByte((addr + k) & 0xffff);
         return out;
       },
       write(addr, bytes) {
@@ -109,7 +129,7 @@ export class Machine {
     this.sound = new Sound();
     sys.io.onSoundWrite = (cycle, value) => this.sound.record(cycle, value);
     sys.io.onSoundReset = () => this.sound.clear();
-    this.keyboard = new KeyQueue(sys.keyboard, () => sys.cpu.cycles);
+    this.keyboard = new KeyQueue(sys.keyboard, () => sys.cpu.cycles, sys.clockHz);
     this.debug = new Debugger(this);
     // Each load records its manifest and the bytes' hash for the label file (the last one wins).
     const record = (/** @type {any} */ manifest, /** @type {Uint8Array} */ bytes) => {
@@ -120,14 +140,30 @@ export class Machine {
       bas: (bytes) => record(loadBas(this, bytes), bytes),
       cmd: (bytes) => record(loadCmd(this, bytes), bytes),
       cas: (bytes, opts) => record(loadCas(this, bytes, opts), bytes),
+      dsk: (bytes, opts) => record(loadDsk(this, bytes, opts), bytes),
     };
     this.cassette = cassetteDeck(this);
+    this.fdc = diskDrives(this);
     this.io = {
       in: (port) => sys.io.readPort(port),
       out: (port, value) => sys.io.writePort(port, value),
     };
   }
 
+  /** @returns {1 | 3} The model built: 1 (the Model I) or 3 (the Model III). */
+  get model() {
+    return this.system.model.id;
+  }
+
+  /**
+   * The model's CPU clock in Hz: 2,027,520 on the Model III, 1,774,080 on the Model I (models.js).
+   * T-state counts (`cycles`, `run`'s budget, `m.sound` stamps) are in this clock's states.
+   * @returns {number}
+   */
+  get clockHz() {
+    return this.system.clockHz;
+  }
+
   /** Total T-states since the last reset. */
   get cycles() {
     return this.system.cpu.cycles;
@@ -157,8 +193,10 @@ export class Machine {
    * delivery, before the instruction executes) by both `step` and `run`: deliver the matrix key
    * events now due, then, with a fed character waiting and the PC at the ROM's keyboard scan
    * ($002B) or wait-for-key ($0049), return from that routine with the character as the ROM
-   * would (spec §6, "Keyboard-scan hook"). That return stands in for the boundary's instruction,
-   * as one RET (10 T-states); a halted CPU idles instead, as it does for any instruction, so the next boundary is at the caller's return address.
+   * would (spec §6, "Keyboard-scan hook"). The Model I Level II ROM has the same two entries with
+   * the same contract (romKeyReturn), so the hook serves both models. That return stands in for
+   * the boundary's instruction, as one RET (10 T-states); a halted CPU idles instead, as it does
+   * for any instruction, so the next boundary is at the caller's return address.
    * Between draining and the keyboard hook, a breakpoint hit (only while `debug.active`, and
    * never in `step`) stops the boundary: nothing executes. Last, with memory accesses watched or
    * hooked, the debugger is told an instruction starts at PC, so its fetches are not taken for