jsbeeb 1.23.0 → 1.24.1

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,281 @@
+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();
+    }
+
+    /**
+     * 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.

package/src/url-params.js

@@ -295,17 +295,16 @@ export function guessModelFromHostname(hostname) {
 }
 
 /**
- * Parse disc or tape images from the query parameters
+ * Parse disc images from the query parameters
  * @param {Object} parsedQuery - The query parameters
- * @returns {Object} Object containing disc and tape information
+ * @returns {Object} Object containing disc information
  *   - discImage: disc image URL (?disc= or ?disc1=)
  *   - secondDiscImage: second disc URL (?disc2=)
- *   - tapeImage: tape image URL (?tape=)
  *   - mmcImage: MMC/SD card image URL (?mmc=, Atom only)
  */
 export function parseMediaParams(parsedQuery) {
-    const { disc, disc1, disc2, tape, mmc } = parsedQuery;
+    const { disc, disc1, disc2, mmc } = parsedQuery;
     const discImage = disc || disc1;
 
-    return { discImage, secondDiscImage: disc2, tapeImage: tape, mmcImage: mmc };
+    return { discImage, secondDiscImage: disc2, mmcImage: mmc };
 }

package/src/vdu-capture.js

@@ -0,0 +1,113 @@
+/**
+ * Turns the bytes a program sends to the VDU into text elements,
+ * `{ x, y, text, foreground, background, mode }`, following the cursor and
+ * colour codes and swallowing the parameters of the rest. Text-mode output
+ * only; anything visual wants a screenshot.
+ */
+// How many parameter bytes follow each BBC VDU code that takes any.
+const SequenceParamCounts = {
+    1: 1, // next character to the printer only
+    17: 1, // COLOUR n
+    18: 2, // GCOL
+    19: 5, // define logical colour
+    22: 1, // MODE n
+    25: 5, // PLOT
+    28: 4, // define text window
+    29: 4, // define graphics origin
+    31: 2, // TAB(x,y)
+};
+
+export class VduTextCapture {
+    constructor(onElement, { isAtom = false } = {}) {
+        this.onElement = onElement;
+        this.isAtom = isAtom;
+        this.attributes = { x: 0, y: 0, text: "", foreground: 7, background: 0, mode: 7 };
+        this.currentText = "";
+        this.params = [];
+        this.nextN = 0;
+        this.vduProc = null;
+        this.sequenceHandlers = {
+            17: (p) => {
+                if (p[0] & 0x80) this.attributes.background = p[0] & 0xf;
+                else this.attributes.foreground = p[0] & 0xf;
+            },
+            22: (p) => {
+                Object.assign(this.attributes, { mode: p[0], x: 0, y: 0, foreground: 7, background: 0 });
+            },
+            31: (p) => {
+                this.attributes.x = p[0];
+                this.attributes.y = p[1];
+            },
+        };
+    }
+
+    flush() {
+        if (this.currentText.length) {
+            this.onElement({ ...this.attributes, text: this.currentText });
+            this.attributes.x += this.currentText.length;
+        }
+        this.currentText = "";
+    }
+
+    onChar(c) {
+        const attributes = this.attributes;
+        if (this.nextN) {
+            this.params.push(c);
+            if (--this.nextN === 0) {
+                if (this.vduProc) this.vduProc(this.params);
+                this.params = [];
+                this.vduProc = null;
+            }
+            return;
+        }
+        switch (c) {
+            case 10:
+                this.flush();
+                attributes.y++;
+                return;
+            case 12:
+                this.flush();
+                attributes.x = 0;
+                attributes.y = 0;
+                return;
+            case 13:
+                this.flush();
+                attributes.x = 0;
+                return;
+        }
+        // The Atom has no multi-byte VDU sequences; treating its bytes as
+        // parameters would swallow printable characters.
+        const paramCount = this.isAtom ? undefined : SequenceParamCounts[c];
+        if (paramCount !== undefined) {
+            this.flush();
+            this.nextN = paramCount;
+            this.vduProc = this.sequenceHandlers[c] ?? null;
+            return;
+        }
+        if (c >= 32 && c < 0x7f) this.currentText += String.fromCharCode(c);
+        else this.flush();
+    }
+
+    /** The decoder's position in the byte stream, for a machine snapshot to carry. */
+    snapshot() {
+        return {
+            attributes: { ...this.attributes },
+            currentText: this.currentText,
+            params: [...this.params],
+            nextN: this.nextN,
+        };
+    }
+
+    /**
+     * Puts back a snapshot(). The handler for a half-read sequence is a
+     * closure and does not survive, so such a sequence is dropped rather
+     * than printed as text.
+     */
+    restore(state) {
+        Object.assign(this.attributes, state.attributes);
+        this.currentText = state.currentText;
+        this.params = [...state.params];
+        this.nextN = state.nextN;
+        this.vduProc = null;
+    }
+}