jsbeeb 1.22.4 → 1.24.0

package/src/printer.js

@@ -1,21 +1,14 @@
-"use strict";
-
 /**
  * Centronics printer attached to the user VIA: acknowledges each character and keeps the most
- * recent output so it can be shown whenever a printer window is opened.
+ * recent output so it can be shown whenever a printer window is opened. Dispatches "output" with
+ * each character as its detail, and "first-output" once, when the machine first prints.
  */
 
 export const MaxBufferedChars = 64 * 1024;
 
-export class Printer {
-    /**
-     * @param {object} [handlers]
-     * @param {function(string): void} [handlers.onOutput] called with each character as it is printed
-     * @param {function(): void} [handlers.onFirstOutput] called once, when the machine first prints
-     */
-    constructor({ onOutput = () => {}, onFirstOutput = () => {} } = {}) {
-        this._onOutput = onOutput;
-        this._onFirstOutput = onFirstOutput;
+export class Printer extends EventTarget {
+    constructor() {
+        super();
         this._uservia = null;
         this._olderText = "";
         this._newerText = "";
@@ -52,8 +45,8 @@ export class Printer {
         }
         if (!this._hasPrinted) {
             this._hasPrinted = true;
-            this._onFirstOutput();
+            this.dispatchEvent(new Event("first-output"));
         }
-        this._onOutput(char);
+        this.dispatchEvent(new CustomEvent("output", { detail: char }));
     }
 }

package/src/relaynoise.js

@@ -1,4 +1,3 @@
-"use strict";
 // Cassette motor relay click sound (issue #296).
 // Audio samples recorded from a real BBC Master cassette motor relay.
 import { SamplePlayer } from "./sample-player.js";

package/src/rewind.js

@@ -1,5 +1,3 @@
-"use strict";
-
 /**
  * Circular buffer of emulator state snapshots for rewind functionality.
  * Snapshots are stored directly without deep-copying, since

package/src/sample-player.js

@@ -1,5 +1,4 @@
-"use strict";
-import * as utils from "./utils.js";
+import { loadData } from "./loader.js";
 
 /**
  * Base class for audio components that load and play back sample buffers
@@ -27,7 +26,7 @@ export class SamplePlayer {
         const entries = Object.entries(pathMap);
         const decoded = await Promise.all(
             entries.map(async ([, path]) => {
-                const data = await utils.loadData(path);
+                const data = await loadData(path);
                 // Safari doesn't support the promise form of decodeAudioData.
                 return new Promise((resolve, reject) => {
                     this.context.decodeAudioData(

package/src/serial.js

@@ -1,5 +1,3 @@
-"use strict";
-
 const table = [19200, 9600, 4800, 2400, 1200, 300, 150, 75];
 
 export class Serial {

package/src/snapshot-helpers.js

@@ -1,5 +1,3 @@
-"use strict";
-
 // Shared helpers for snapshot importers (bem-snapshot.js, uef-snapshot.js).
 // Contains volume table, default peripheral state, video state builder,
 // and the common snapshot envelope that wraps per-format parsed state.

package/src/snapshot.js

@@ -1,5 +1,3 @@
-"use strict";
-
 import { typedArrayToBase64, base64ToTypedArray } from "./state-utils.js";
 import { findModel } from "./models.js";
 

package/src/soundchip.js

@@ -347,7 +347,7 @@ export class SoundChip {
     updateSlowDataBus(slowDataBus, active) {
         this.slowDataBus = slowDataBus;
         this.active = active;
-        // TODO: this probably isn't modeled correctly. Currently the sound chip "notices" a new data bus value some
+        // TODO(#835) this probably isn't modeled correctly. Currently the sound chip "notices" a new data bus value some
         // fixed number of cycles after WE (write enable) is triggered. In reality, the sound chip likely pulls data off
         // the bus at a fixed point in its cycle, iff WE is active.
         if (active) {

package/src/state-utils.js

@@ -1,5 +1,3 @@
-"use strict";
-
 /**
  * Convert a TypedArray to a base64 string for JSON serialization.
  * @param {ArrayBufferView} typedArray

package/src/sth.js

@@ -1,6 +1,4 @@
-"use strict";
-
-import * as utils from "./utils.js";
+import { unzipDiscImage } from "./archive.js";
 
 // Always https, whatever the page was loaded over: the mirror redirects plain
 // http, so following the page's protocol would cost a redirect on every request
@@ -55,7 +53,7 @@ export class StairwayToHell {
         const response = await fetch(url);
         if (!response.ok) throw new Error(`Unable to load ${url}, http code ${response.status}`);
         try {
-            return await utils.unzipDiscImage(new Uint8Array(await response.arrayBuffer()));
+            return await unzipDiscImage(new Uint8Array(await response.arrayBuffer()));
         } catch (error) {
             console.error("Failed to fetch file:", error);
             throw error;

package/src/tapes.js

@@ -1,5 +1,6 @@
-"use strict";
-import * as utils from "./utils.js";
+import { DataStream, stringToUint8Array } from "./binary.js";
+import { ungzip } from "./archive.js";
+import { hexword } from "./hex.js";
 
 function secsToClocks(secs, cpuSpeed) {
     return (cpuSpeed * secs) | 0;
@@ -240,7 +241,7 @@ class UefTape {
                 acia.tone(0);
                 return secsToClocks(gap, this.cpuSpeed);
             default:
-                console.log("Skipping unknown chunk " + utils.hexword(this.curChunk.id));
+                console.log("Skipping unknown chunk " + hexword(this.curChunk.id));
                 this.curChunk = this.readChunk();
                 break;
         }
@@ -306,7 +307,12 @@ class TapefileTape {
 }
 
 export async function loadTapeFromData(name, data, model) {
-    const stream = await utils.DataStream.create(name, data);
+    const raw = stringToUint8Array(data);
+    if (raw && raw.length > 4 && raw[0] === 0x1f && raw[1] === 0x8b) {
+        console.log("Ungzipping " + name);
+        data = await ungzip(raw);
+    }
+    const stream = new DataStream(name, data);
     if (stream.readByte(0) === 0xff && stream.readByte(1) === 0x04) {
         console.log("Detected a 'tapefile' tape");
         return new TapefileTape(stream, model);

package/src/teletext.js

@@ -1,7 +1,6 @@
-"use strict";
 import { makeChars } from "./teletext_data.js";
-import { makeFast32 } from "./utils.js";
 import { BbcDefaultPalette as BbcDefaultCollook } from "./bbc-palette.js";
+import { makeFast32 } from "./binary.js";
 
 export class Teletext {
     constructor() {
@@ -341,7 +340,7 @@ export class Teletext {
 
     // Flashing text starts off in sync with a slow cursor, extinguished together. Multiple MODE
     // changes gradually desynchronise the frame counters.
-    // TODO: setDEW is reached a MOS-dependent number of times before Video.frameCount rises, so
+    // TODO(#1057) setDEW is reached a MOS-dependent number of times before Video.frameCount rises, so
     // the initial sync here holds under MOS 1.20 only.
     get hideFlashing() {
         return this.flashTime < 16;

package/src/teletext_adaptor.js

@@ -1,6 +1,4 @@
-"use strict";
-
-import * as utils from "./utils.js";
+import { loadData } from "./loader.js";
 
 // Code ported from Beebem (C to .js) by Jason Robson
 const TELETEXT_IRQ = 5;
@@ -74,7 +72,7 @@ export class TeletextAdaptor extends EventTarget {
         const request = ++this.streamRequest;
         let data;
         try {
-            data = await utils.loadData(`teletext/txt${channel}.dat`);
+            data = await loadData(`teletext/txt${channel}.dat`);
         } catch (error) {
             if (request !== this.streamRequest) return;
             console.error(`Teletext adaptor: failed to load channel ${channel}`, error);

package/src/teletext_data.js

@@ -1,5 +1,3 @@
-"use strict";
-
 // Extremely heavily based on b-em.
 export function makeChars() {
     // prettier-ignore

package/src/test-machine.js

@@ -0,0 +1,307 @@
+import { installBasic } from "./basic-loader.js";
+import * as fdc from "./fdc.js";
+import { fake6502 } from "./fake6502.js";
+import { findModel } from "./models.js";
+import assert from "assert";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as Tokeniser from "./basic-tokenise.js";
+import { VduTextCapture } from "./vdu-capture.js";
+import { setNodeBasePath } from "./loader.js";
+import { Typist } from "./typist.js";
+
+const MaxCyclesPerIter = 100 * 1000;
+const RepoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+export class TestMachine {
+    constructor(model, opts) {
+        model = model || "B-DFS1.2";
+        this.model = findModel(model);
+        if (!this.model) throw new Error(`Unknown model "${model}"`);
+        this.processor = fake6502(this.model, opts || {});
+        this.typist = new Typist(this.processor);
+        this._capturedChars = [];
+        this._captureHookInstalled = false;
+    }
+
+    /** The keyboard interface for this machine (SysVia for BBC, PPIA for Atom). */
+    get _keyInterface() {
+        return this.processor.keyboardInterface;
+    }
+
+    async initialise() {
+        setNodeBasePath(RepoRoot);
+        await this.processor.initialise();
+        if (this.model.isAtom) this._startAtomVSync();
+    }
+
+    /**
+     * The Atom ROM's main loop waits for VSync (bit 7 of Port C) to
+     * toggle before scanning the keyboard.  The MC6847 video chip drives
+     * this in the real emulator, but fake6502 doesn't create one, so we
+     * simulate it with a scheduler task at ~60 Hz (NTSC).
+     */
+    _startAtomVSync() {
+        const ppia = this.processor.atomppia;
+        const VsyncPeriod = 16667; // 1 MHz / 60 Hz (NTSC 262-line frame)
+        const VsyncPulse = 800;
+        let inVsync = false;
+        const task = this.processor.scheduler.newTask(() => {
+            if (!inVsync) {
+                ppia.setVBlankInt(1);
+                inVsync = true;
+                task.reschedule(VsyncPulse);
+            } else {
+                ppia.setVBlankInt(0);
+                inVsync = false;
+                task.reschedule(VsyncPeriod - VsyncPulse);
+            }
+        });
+        task.schedule(VsyncPeriod);
+    }
+
+    /**
+     * Calls `listener` with each character the machine sends to the VDU, by
+     * watching the write-character vector (WRCHV, $020E on the BBC and $0208 on
+     * the Atom) as the OS or a program leaves it. Returns a function that stops
+     * listening.
+     */
+    onVduChar(listener) {
+        if (!this._vduListeners) {
+            this._vduListeners = [];
+            const cpu = this.processor;
+            const ram = cpu.ramRomOs;
+            const wrchvAddr = this.model.wrchvAddress;
+            cpu.debugInstruction.add((addr) => {
+                if (addr === (ram[wrchvAddr] | (ram[wrchvAddr + 1] << 8))) {
+                    for (const listen of this._vduListeners) listen(cpu.a);
+                }
+                return false;
+            });
+        }
+        this._vduListeners.push(listener);
+        return () => {
+            this._vduListeners = this._vduListeners.filter((other) => other !== listener);
+        };
+    }
+
+    /** Accumulates every character sent to the VDU for drainText(); safe to call more than once. */
+    startCapture() {
+        if (this._captureHookInstalled) return;
+        this._captureHookInstalled = true;
+        this.onVduChar((c) => this._capturedChars.push(c));
+    }
+
+    /**
+     * Return all captured characters since the last drain (or since
+     * startCapture was called), then clear the buffer.
+     * @returns {number[]} array of character codes
+     */
+    drainCapturedChars() {
+        const chars = this._capturedChars;
+        this._capturedChars = [];
+        return chars;
+    }
+
+    /**
+     * Return captured text as a string (printable chars only, with
+     * optional newline preservation), then clear the buffer.
+     * @param {Object} [opts]
+     * @param {boolean} [opts.raw=false] - if true, preserve newlines
+     */
+    drainText({ raw = false } = {}) {
+        const chars = this.drainCapturedChars();
+        return chars
+            .map((c) => {
+                if (raw && c === 10) return "\n";
+                if (c === 13) return "";
+                if (c >= 0x20 && c < 0x7f) return String.fromCharCode(c);
+                return "";
+            })
+            .join("");
+    }
+
+    runFor(cycles) {
+        let left = cycles;
+        let stopped = false;
+        return new Promise((resolve) => {
+            const runAnIter = () => {
+                const todo = Math.max(0, Math.min(left, MaxCyclesPerIter));
+                if (todo) {
+                    stopped = !this.processor.execute(todo);
+                    left -= todo;
+                }
+                // Not truthiness: a negative or NaN request clamps todo to zero,
+                // so left would never move and the loop never end.
+                if (left > 0 && !stopped) {
+                    setTimeout(runAnIter, 0);
+                } else {
+                    resolve(stopped);
+                }
+            };
+            runAnIter();
+        });
+    }
+
+    /** Emulated cycles since power-on, undoing the per-second rebasing execute() applies. */
+    get elapsedCycles() {
+        const cpu = this.processor;
+        return cpu.cycleSeconds * this.model.cyclesPerSecond + cpu.currentCycles;
+    }
+
+    async runUntilVblank() {
+        let hit = false;
+        if (this.processor.isMaster) throw new Error("Not yet implemented");
+        const hook = this.processor.debugInstruction.add((addr) => {
+            if (addr === 0xdd15) {
+                hit = true;
+                return true;
+            }
+        });
+        await this.runFor(10 * 1000 * 1000);
+        hook.remove();
+        assert(hit, "did not hit appropriate breakpoint in time");
+    }
+
+    async runUntilInput(secs) {
+        if (!secs) secs = 120;
+        console.log("Running until keyboard input requested");
+        const idleAddr = this.model.idleAddress;
+        let hit = false;
+        const hook = this.processor.debugInstruction.add((addr) => {
+            if (addr === idleAddr) {
+                hit = true;
+                return true;
+            }
+        });
+        await this.runFor(secs * this.model.cyclesPerSecond);
+        hook.remove();
+        assert(hit, "did not hit appropriate breakpoint in time");
+        return this.runFor(10 * 1000);
+    }
+
+    async runUntilAddress(targetAddr, secs) {
+        if (!secs) secs = 120;
+        let hit = false;
+        const hook = this.processor.debugInstruction.add((addr) => {
+            if (addr === targetAddr) {
+                hit = true;
+                return true;
+            }
+        });
+        await this.runFor(secs * this.model.cyclesPerSecond);
+        hook.remove();
+        assert(hit, "did not hit appropriate breakpoint in time");
+    }
+
+    async loadDisc(image) {
+        const data = await fdc.load(image);
+        this.processor.fdc.loadDisc(0, fdc.discFor(image, data));
+    }
+
+    /**
+     * Load a disc image from raw data (Uint8Array or Buffer).
+     * @param {Uint8Array|Buffer} data - raw disc image bytes
+     */
+    loadDiscData(data) {
+        this.processor.fdc.loadDisc(0, fdc.discFor("", data));
+    }
+
+    /**
+     * Reset the machine.
+     * @param {boolean} hard - true for power-on reset, false for soft reset
+     */
+    reset(hard) {
+        this.processor.reset(hard);
+    }
+
+    /**
+     * Take a snapshot of the entire machine state (CPU, RAM, SWRAM,
+     * VIAs, video, FDC, etc). Returns an opaque state object that
+     * can be passed to restore().
+     */
+    snapshot({ includeRoms = true } = {}) {
+        return this.processor.snapshotState({ includeRoms });
+    }
+
+    /**
+     * Restore a previously saved snapshot. The machine will be in
+     * exactly the state it was when snapshot() was called.
+     */
+    restore(state) {
+        this.processor.restoreState(state);
+    }
+
+    async loadBasic(source) {
+        const tokeniser = await Tokeniser.create();
+        const tokenised = tokeniser.tokenise(source);
+        installBasic(tokenised, {
+            readByte: (addr) => this.readbyte(addr),
+            writeByte: (addr, value) => this.writebyte(addr, value),
+        });
+    }
+
+    /**
+     * Types the text and a RETURN at the machine, running the CPU until the
+     * last key is up. The keys arrive from the scheduler, so a breakpoint that
+     * stops the CPU part way leaves the rest to be typed when it runs again.
+     */
+    async type(text) {
+        const lines = text.replace(/\r\n?/g, "\n");
+        this.typist.type(this.model.stringToKeys(lines + "\n"), true);
+        while (this.typist.isTyping) {
+            const stopped = await this.runFor(MaxCyclesPerIter);
+            if (stopped) break;
+        }
+    }
+
+    /**
+     * Press a key on the keyboard.
+     * @param {number} code - key code (BBC keyCode or Atom raw key)
+     */
+    keyDown(code) {
+        this._keyInterface.keyDown(code);
+    }
+
+    /**
+     * Release a key on the keyboard.
+     * @param {number} code - key code
+     */
+    keyUp(code) {
+        this._keyInterface.keyUp(code);
+    }
+
+    /**
+     * Load a ROM image directly into a sideways RAM slot.
+     * @param {number} slot - slot number (0-15, typically 4-7 for SWRAM)
+     * @param {Uint8Array|Buffer} data - ROM data (up to 16384 bytes)
+     */
+    loadSidewaysRam(slot, data) {
+        const offset = this.processor.romOffset + slot * 16384;
+        for (let i = 0; i < data.length && i < 16384; i++) {
+            this.processor.ramRomOs[offset + i] = data[i];
+        }
+    }
+
+    writebyte(addr, val) {
+        this.processor.writemem(addr, val);
+    }
+
+    readbyte(addr) {
+        return this.processor.readmem(addr);
+    }
+
+    readword(addr) {
+        return this.readbyte(addr) | (this.readbyte(addr + 1) << 8);
+    }
+
+    /**
+     * Decodes the machine's VDU output into text elements for `onElement`
+     * until the returned capture's `stop()` is called; see VduTextCapture.
+     */
+    captureText(onElement) {
+        const capture = new VduTextCapture(onElement, { isAtom: this.model.isAtom });
+        capture.stop = this.onVduChar((c) => capture.onChar(c));
+        return capture;
+    }
+}

package/src/touchscreen.js

@@ -1,6 +1,4 @@
-"use strict";
-
-import * as utils from "./utils.js";
+import { Fifo } from "./binary.js";
 
 const PollHz = 8; // Made up
 
@@ -13,7 +11,7 @@ export class TouchScreen {
     constructor(scheduler, cyclesPerSecond) {
         this.scheduler = scheduler;
         this.pollCycles = cyclesPerSecond / PollHz;
-        this.outBuffer = new utils.Fifo(16);
+        this.outBuffer = new Fifo(16);
         this.pollTask = this.scheduler.newTask(() => this.poll());
         this.reset();
     }

package/src/tube.js

@@ -1,5 +1,4 @@
-"use strict";
-import * as utils from "./utils.js";
+import { hexbyte, hexword } from "./hex.js";
 
 //  this one should be declared more globally
 const HOST_CPU_FLAG_IRQ_TUBE_ULA = 8;
@@ -205,13 +204,13 @@ export class Tube {
         }
         this.updateInterrupts();
         if (this.debug) {
-            console.log("TUBE ULA: host read " + utils.hexword(address) + " = " + utils.hexbyte(result));
+            console.log("TUBE ULA: host read " + hexword(address) + " = " + hexbyte(result));
         }
         return result;
     }
     hostWrite(address, value) {
         if (this.debug) {
-            console.log("TUBE ULA: host write " + utils.hexword(address) + " = " + utils.hexbyte(value));
+            console.log("TUBE ULA: host write " + hexword(address) + " = " + hexbyte(value));
         }
         switch (address & 7) {
             case TUBE_ULA_R1_STATUS_ADDRESS: {
@@ -337,7 +336,7 @@ export class Tube {
         }
         this.updateInterrupts();
         if (this.debug) {
-            console.log("TUBE ULA: parasite read " + utils.hexword(address) + " = " + utils.hexbyte(result));
+            console.log("TUBE ULA: parasite read " + hexword(address) + " = " + hexbyte(result));
         }
         return result;
     }
@@ -382,7 +381,7 @@ export class Tube {
         //  Boot mode is terminated by the software when it selects any one of the Tube addresses.
         //  This deselects the ROM
         if (this.debug) {
-            console.log("TUBE ULA: parasite write " + utils.hexword(address) + " = " + utils.hexbyte(value));
+            console.log("TUBE ULA: parasite write " + hexword(address) + " = " + hexbyte(value));
         }
         switch (address & 7) {
             case TUBE_ULA_R1_DATA_ADDRESS:

package/src/typist.js

@@ -0,0 +1,103 @@
+import { BBC } from "./keymap.js";
+
+const RepeatedKeyGapMs = 30;
+
+/**
+ * Types a key sequence into the keyboard matrix from the processor's
+ * scheduler, one key per tick, so the CPU stays on its fast path while the
+ * text arrives. An entry is one of the model's raw keys, or a number of
+ * milliseconds to wait. SHIFT toggles and stays held; any other key is pressed
+ * on one tick and released on the next.
+ */
+export class Typist {
+    constructor(processor) {
+        this.processor = processor;
+        this.keyInterface = processor.keyboardInterface;
+        this._shiftKey = processor.model.keys.SHIFT;
+        this._keys = [];
+        this._lastKey = undefined;
+        this._clocksPerMs = 0;
+        this._task = processor.scheduler.newTask(() => this._deliver());
+    }
+
+    /**
+     * @param {Array} keys raw keys and millisecond delays, consumed as they are sent
+     * @param {boolean} checkCapsAndShiftLocks bracket the keys with a lock toggle when
+     *   the machine's lock lights say the letters would come out in the wrong case
+     */
+    type(keys, checkCapsAndShiftLocks) {
+        if (this.isTyping) this.cancel();
+        this.keyInterface.disableKeyboard();
+        // The task lives on the processor's scheduler, which is polled with peripheral
+        // cycles, so the delays stay in real time whatever the CPU multiplier is.
+        this._clocksPerMs = this.processor.peripheralCyclesPerSecond / 1000;
+
+        if (checkCapsAndShiftLocks) {
+            let toggleKey = null;
+            if (!this.keyInterface.capsLockLight) toggleKey = BBC.CAPSLOCK;
+            else if (this.keyInterface.shiftLockLight) toggleKey = BBC.SHIFTLOCK;
+            if (toggleKey) {
+                keys.unshift(toggleKey);
+                keys.push(toggleKey);
+            }
+        }
+
+        this._keys = keys;
+        this._lastKey = undefined;
+        this._task.schedule(0);
+    }
+
+    cancel() {
+        if (!this.isTyping) return;
+        this._task.cancel();
+        this._releaseLastKey();
+        this._lastKey = undefined;
+        this._keys = [];
+        this.keyInterface.enableKeyboard();
+    }
+
+    get isTyping() {
+        return this._keys.length > 0 || this._task.scheduled();
+    }
+
+    _releaseLastKey() {
+        if (this._lastKey && this._lastKey !== this._shiftKey) this.keyInterface.keyToggleRaw(this._lastKey);
+    }
+
+    _deliver() {
+        this._releaseLastKey();
+
+        if (this._keys.length === 0) {
+            this._lastKey = undefined;
+            this.keyInterface.enableKeyboard();
+            return;
+        }
+
+        const releaseGapMs = this.processor.model.pasteReleaseGapMs;
+        if (this._lastKey && this._lastKey !== this._shiftKey && releaseGapMs) {
+            this._lastKey = undefined;
+            this._task.schedule(releaseGapMs * this._clocksPerMs);
+            return;
+        }
+
+        const key = this._keys[0];
+        const repeated = this._lastKey === key;
+        this._lastKey = key;
+        if (repeated) {
+            this._lastKey = undefined;
+            this._task.schedule(RepeatedKeyGapMs * this._clocksPerMs);
+            return;
+        }
+
+        let delayMs = this.processor.model.pasteKeyDelayMs;
+        if (typeof key === "number") {
+            delayMs = key;
+            this._lastKey = undefined;
+        } else {
+            this.keyInterface.keyToggleRaw(key);
+        }
+
+        this._keys.shift();
+        this._task.schedule(delayMs * this._clocksPerMs);
+    }
+}

package/src/uef-snapshot.js

@@ -1,5 +1,3 @@
-"use strict";
-
 // BeebEm UEF save state parser.
 // Converts a BeebEm UEF save state file into a jsbeeb snapshot object, in the same way
 // that bem-snapshot.js converts B-em snapshots.