jsbeeb 1.5.0 → 1.7.0

package/README.md

@@ -10,6 +10,8 @@ and a 128K BBC Master, along with a number of different peripherals.
 ## Table of Contents
 
 - [Keyboard Mappings](#keyboard-mappings)
+- [Emulator Shortcuts](#emulator-shortcuts)
+- [Save State and Rewind](#save-state-and-rewind)
 - [Getting Set Up to Run Locally](#getting-set-up-to-run-locally)
 - [Running as a Desktop Application](#running-as-a-desktop-application)
 - [URL Parameters](#url-parameters)
@@ -33,6 +35,26 @@ The BBC had a somewhat different-looking keyboard to a modern PC, and so it's us
 To play right now, visit [https://bbc.xania.org/](https://bbc.xania.org/). To load the default disc image (Elite in this
 case), press shift-F12 (which is shift-Break on the BBC).
 
+### Emulator Shortcuts
+
+| Shortcut       | Action                          |
+| -------------- | ------------------------------- |
+| `Ctrl+Home`    | Stop and enter debugger         |
+| `Ctrl+Insert`  | Toggle turbo (fast-as-possible) |
+| `Ctrl+End`     | Pause emulation                 |
+| `Alt+PageDown` | Open rewind scrubber            |
+
+### Save State and Rewind
+
+Save and load full emulator state snapshots from the **State** menu (or `Ctrl+S` / `Ctrl+O` in the Electron app).
+
+The emulator continuously captures snapshots into a 30-slot rewind buffer (~1 per second). Open the rewind scrubber from **State > Rewind** or press **Alt+PageDown** to browse recent states as a visual filmstrip:
+
+- **Left/Right arrows** — navigate between snapshots (the main screen updates live)
+- **Click** a thumbnail to jump to that point
+- **Enter** — commit selection and close the panel
+- **Escape** — cancel and restore the original state
+
 ### Joystick Support
 
 jsbeeb supports both USB/Bluetooth gamepads and mouse-based analogue joystick emulation. Note that BBC Micro joysticks use inverted axes:
@@ -184,8 +206,6 @@ If you're looking to help:
   - Play lots of games and report issues either on [GitHub](https://github.com/mattgodbolt/jsbeeb/issues) or by email (
     matt@godbolt.org).
 - Core
-  - Save state ability
-    - Once we have this I'd love to get some "reverse step" debugging support
   - Get the "boo" of the boot "boo-beep" working (disabled currently as the JavaScript startup makes the sound
     dreadfully choppy on Chrome at least).
 - Save disc support

package/package.json

@@ -7,7 +7,7 @@
   "name": "jsbeeb",
   "description": "Emulate a BBC Micro",
   "repository": "git@github.com:mattgodbolt/jsbeeb.git",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "//": "If you change the version of Node, it must also be updated at the top of the Dockerfile.",
   "engines": {
     "node": "22"
@@ -34,8 +34,8 @@
     "fflate": "^0.8.2",
     "jquery": "^4.0.0",
     "pako": "^2.1.0",
-    "smoothie": "^1.36.1",
     "sharp": "^0.34.5",
+    "smoothie": "^1.36.1",
     "underscore": "^1.13.7"
   },
   "devDependencies": {
@@ -46,6 +46,7 @@
     "eslint-plugin-prettier": "^5.5.5",
     "globals": "^17.3.0",
     "husky": "^9.1.7",
+    "jsdom": "^29.0.0",
     "lint-staged": "^16.2.7",
     "npm-run-all2": "^8.0.4",
     "pixelmatch": "^7.1.0",

package/src/6502.js

@@ -616,6 +616,7 @@ export class Cpu6502 extends Base6502 {
         this.videoCycles = 0;
 
         this.polltime = this.buildPolltime();
+        this.is1MHzAccess = this.buildIs1MHzAccess();
 
         this._debugRead = this._debugWrite = this._debugInstruction = null;
         this.debugInstruction = new DebugHook(this, "_debugInstruction");
@@ -1130,6 +1131,96 @@ export class Cpu6502 extends Base6502 {
         this.resetLine = !resetOn;
     }
 
+    snapshotState() {
+        return {
+            // CPU registers
+            a: this.a,
+            x: this.x,
+            y: this.y,
+            s: this.s,
+            pc: this.pc,
+            p: this.p.asByte(),
+            nmiLevel: this._nmiLevel,
+            nmiEdge: this._nmiEdge,
+            halted: this.halted,
+            takeInt: this.takeInt,
+            // Memory control
+            romsel: this.romsel,
+            acccon: this.acccon,
+            videoDisplayPage: this.videoDisplayPage,
+            // Cycle tracking
+            currentCycles: this.currentCycles,
+            targetCycles: this.targetCycles,
+            cycleSeconds: this.cycleSeconds,
+            peripheralCycles: this.peripheralCycles,
+            videoCycles: this.videoCycles,
+            music5000PageSel: this.music5000PageSel,
+            // RAM only (ROMs don't change at runtime)
+            ram: this.ramRomOs.slice(0, this.romOffset),
+            // Sub-component state
+            scheduler: this.scheduler.snapshotState(),
+            sysvia: this.sysvia.snapshotState(),
+            uservia: this.uservia.snapshotState(),
+            video: this.video.snapshotState(),
+            soundChip: this.soundChip.snapshotState(),
+            acia: this.acia.snapshotState(),
+            adc: this.adconverter.snapshotState(),
+            fdc: this.fdc.snapshotState(),
+        };
+    }
+
+    restoreState(state) {
+        // 1. Scheduler epoch first (so task offsets resolve correctly)
+        this.scheduler.restoreState(state.scheduler);
+
+        // 2. CPU registers
+        this.a = state.a;
+        this.x = state.x;
+        this.y = state.y;
+        this.s = state.s;
+        this.pc = state.pc;
+        this.p.setFromByte(state.p);
+        // interrupt is rebuilt by sub-component restores (VIA updateIFR, ACIA updateIrq)
+        this.interrupt = 0;
+        this._nmiLevel = state.nmiLevel;
+        this._nmiEdge = state.nmiEdge;
+        this.halted = state.halted;
+        this.takeInt = state.takeInt;
+
+        // 3. Memory
+        this.ramRomOs.set(state.ram);
+        // Load ROMs if present (e.g. from BEM snapshot import)
+        if (state.roms) {
+            this.ramRomOs.set(state.roms.slice(0, 16 * 16384), this.romOffset);
+        }
+        this.videoDisplayPage = state.videoDisplayPage;
+        this.music5000PageSel = state.music5000PageSel;
+
+        // 4. Rebuild memStat/memLook from romsel/acccon
+        this.romSelect(state.romsel);
+        if (this.model.isMaster) this.writeAcccon(state.acccon);
+
+        // 5. Cycle tracking
+        this.currentCycles = state.currentCycles;
+        this.targetCycles = state.targetCycles;
+        this.cycleSeconds = state.cycleSeconds;
+        this.peripheralCycles = state.peripheralCycles;
+        this.videoCycles = state.videoCycles;
+
+        // 6. Sub-components (these re-register scheduler tasks)
+        this.sysvia.restoreState(state.sysvia);
+        this.uservia.restoreState(state.uservia);
+        this.video.restoreState(state.video);
+        this.soundChip.restoreState(state.soundChip);
+        this.acia.restoreState(state.acia);
+        this.adconverter.restoreState(state.adc);
+
+        // FDC state (v2+). If absent (v1 snapshot), FDC keeps its current state.
+        if (state.fdc) {
+            this.fdc.restoreState(state.fdc);
+        }
+    }
+
     reset(hard) {
         if (hard) {
             // On the Master, opcodes executing from 0xc000 - 0xdfff can optionally have their memory accesses
@@ -1191,6 +1282,7 @@ export class Cpu6502 extends Base6502 {
         this._nmiEdge = false;
         this._nmiLevel = false;
         this.halted = false;
+        this.breakpointResume = false;
         this.music5000PageSel = 0;
         this.video.reset(this, this.sysvia, hard);
         this.soundChip.reset(hard);
@@ -1206,15 +1298,30 @@ export class Cpu6502 extends Base6502 {
         this.sysvia.setKeyLayout(this.config.keyLayout);
     }
 
-    polltimeAddr(cycles, addr) {
+    polltimeAddr(cycles, addr, isWrite) {
         cycles = cycles | 0;
-        if (is1MHzAccess(addr)) {
+        if (this.is1MHzAccess(addr, isWrite)) {
             cycles += 1 + ((cycles ^ this.currentCycles) & 1);
         }
         this.polltime(cycles);
     }
 
-    // Builds commong code between polltimeSlow and polltimeFast
+    // Bake in the 1MHz bus check at construction time. On the Master, ACCCON
+    // TST (bit 6) remaps FRED, JIM, and SHEILA reads (&FC00-&FEFF) to the
+    // internal 2MHz bus, but writes still go through the external 1MHz bus.
+    // Non-Master machines just use the static address check with no ACCCON
+    // awareness.
+    buildIs1MHzAccess() {
+        if (this.model.isMaster) {
+            return (addr, isWrite) => {
+                if (!isWrite && this.acccon & 0x40 && addr >= 0xfc00 && addr < 0xff00) return false;
+                return is1MHzAccess(addr);
+            };
+        }
+        return is1MHzAccess;
+    }
+
+    // Builds common code between polltimeSlow and polltimeFast
     buildPolltime() {
         const nop = (_cycles) => {};
         const tubeStuff = (cycles) => (this.model.tube ? this.tube.execute(cycles) : nop);
@@ -1289,16 +1396,22 @@ export class Cpu6502 extends Base6502 {
     }
 
     executeInternal() {
-        let first = true;
+        // Skip the debug-instruction check on the very first instruction only
+        // when resuming from a previous breakpoint stop (so we don't immediately
+        // re-trigger the same breakpoint).  Previously this skipped the first
+        // instruction of every execute() chunk, which could miss breakpoints.
+        let skipNext = this.breakpointResume;
+        this.breakpointResume = false;
         while (!this.halted && this.currentCycles < this.targetCycles) {
             this.oldPcIndex = (this.oldPcIndex + 1) & 0xff;
             this.oldPcArray[this.oldPcIndex] = this.pc;
             this.memStatOffset = this.memStatOffsetByIFetchBank & (1 << (this.pc >>> 12)) ? 256 : 0;
             const opcode = this.readmem(this.pc);
-            if (this._debugInstruction && !first && this._debugInstruction(this.pc, opcode)) {
+            if (this._debugInstruction && !skipNext && this._debugInstruction(this.pc, opcode)) {
+                this.breakpointResume = true;
                 return false;
             }
-            first = false;
+            skipNext = false;
             this.incpc();
             this.runner.run(opcode);
             this.oldAArray[this.oldPcIndex] = this.a;

package/src/6502.opcodes.js

@@ -88,6 +88,7 @@ class InstructionGen {
         let op = `cpu.writemem(${addr}, ${reg});`;
         if (spurious) op += " // spurious";
         this.append(this.cycle, op, true, addr);
+        this.ops[this.cycle].isWrite = true;
     }
 
     zpReadOp(addr, reg) {
@@ -129,7 +130,8 @@ class InstructionGen {
             }
             if (this.cycleAccurate && toSkip && this.ops[i].exact) {
                 if (this.ops[i].addr) {
-                    out.push(`cpu.polltimeAddr(${toSkip}, ${this.ops[i].addr});`);
+                    const isWrite = this.ops[i].isWrite ? "true" : "false";
+                    out.push(`cpu.polltimeAddr(${toSkip}, ${this.ops[i].addr}, ${isWrite});`);
                 } else {
                     out.push(`cpu.polltime(${toSkip});`);
                 }
@@ -140,7 +142,8 @@ class InstructionGen {
         }
         if (toSkip) {
             if (this.cycleAccurate && this.ops[this.cycle] && this.ops[this.cycle].addr) {
-                out.push(`cpu.polltimeAddr(${toSkip}, ${this.ops[this.cycle].addr});`);
+                const isWrite = this.ops[this.cycle].isWrite ? "true" : "false";
+                out.push(`cpu.polltimeAddr(${toSkip}, ${this.ops[this.cycle].addr}, ${isWrite});`);
             } else {
                 out.push(`cpu.polltime(${toSkip});`);
             }
@@ -1151,7 +1154,9 @@ function makeCpuFunctions(cpu, opcodes, is65c12, cycleAccurate = true) {
                         // so I read the non-carry here.
                         if (!op.rotate) ig.ifFalse.readOp("addrNonCarry", "REG");
                         ig.readOp("addrWithCarry", "REG");
-                        ig.writeOp("addrWithCarry", "REG");
+                        // 65c12 does "two reads and one write" for RMW (not the 6502's
+                        // "one read and two writes"). The spurious cycle is a read.
+                        ig.readOp("addrWithCarry", "", true);
                     } else {
                         // For RMW we always have a spurious read and then a spurious read or write
                         ig.readOp("addrNonCarry");
@@ -1236,11 +1241,19 @@ function makeCpuFunctions(cpu, opcodes, is65c12, cycleAccurate = true) {
                     ig.readOp("addrWithCarry", "REG");
                     ig.spuriousOp("addrWithCarry", "REG");
                 } else if (op.write) {
-                    // Pure stores still exhibit a read at the non-carried address.
-                    ig.readOp("addrNonCarry");
-                    if (op.zpQuirk) {
-                        // with this quirk on undocumented instructions, a page crossing writes to 00XX
-                        ig.append("if (addrWithCarry !== addrNonCarry) addrWithCarry &= 0xff;");
+                    if (is65c12) {
+                        // On the 65c12, the dead cycle reads the Previous Bus Address (PBA)
+                        // rather than the partially-formed or target address. Since PBA is
+                        // always a zero-page or instruction-fetch address (2MHz), it never
+                        // triggers 1MHz bus stretching. We model this as tick(1).
+                        ig.tick(1);
+                    } else {
+                        // Pure stores still exhibit a read at the non-carried address.
+                        ig.readOp("addrNonCarry");
+                        if (op.zpQuirk) {
+                            // with this quirk on undocumented instructions, a page crossing writes to 00XX
+                            ig.append("if (addrWithCarry !== addrNonCarry) addrWithCarry &= 0xff;");
+                        }
                     }
                 }
                 ig.append(op.op);

package/src/acia.js

@@ -197,6 +197,48 @@ export class Acia {
         this.updateIrq();
     }
 
+    snapshotState() {
+        const scheduler = this.txCompleteTask.scheduler;
+        return {
+            sr: this.sr,
+            cr: this.cr,
+            dr: this.dr,
+            rs423Selected: this.rs423Selected,
+            motorOn: this.motorOn,
+            tapeCarrierCount: this.tapeCarrierCount,
+            tapeDcdLineLevel: this.tapeDcdLineLevel,
+            hadDcdHigh: this.hadDcdHigh,
+            serialReceiveRate: this.serialReceiveRate,
+            serialReceiveCyclesPerByte: this.serialReceiveCyclesPerByte,
+            txCompleteTaskOffset: this.txCompleteTask.scheduled()
+                ? this.txCompleteTask.expireEpoch - scheduler.epoch
+                : null,
+            runTapeTaskOffset: this.runTapeTask.scheduled() ? this.runTapeTask.expireEpoch - scheduler.epoch : null,
+            runRs423TaskOffset: this.runRs423Task.scheduled() ? this.runRs423Task.expireEpoch - scheduler.epoch : null,
+        };
+    }
+
+    restoreState(state) {
+        this.sr = state.sr;
+        this.cr = state.cr;
+        this.dr = state.dr;
+        this.rs423Selected = state.rs423Selected;
+        this.motorOn = state.motorOn;
+        this.tapeCarrierCount = state.tapeCarrierCount;
+        this.tapeDcdLineLevel = state.tapeDcdLineLevel;
+        this.hadDcdHigh = state.hadDcdHigh;
+        this.serialReceiveRate = state.serialReceiveRate;
+        this.serialReceiveCyclesPerByte = state.serialReceiveCyclesPerByte;
+        this.updateIrq();
+
+        this.txCompleteTask.cancel();
+        this.runTapeTask.cancel();
+        this.runRs423Task.cancel();
+        if (state.txCompleteTaskOffset !== null) this.txCompleteTask.schedule(state.txCompleteTaskOffset);
+        if (state.runTapeTaskOffset !== null) this.runTapeTask.schedule(state.runTapeTaskOffset);
+        if (state.runRs423TaskOffset !== null) this.runRs423Task.schedule(state.runRs423TaskOffset);
+    }
+
     setTape(tape) {
         this.tape = tape;
     }

package/src/adc.js

@@ -99,6 +99,28 @@ export class Adc {
         }
     }
 
+    snapshotState() {
+        const scheduler = this.task.scheduler;
+        return {
+            status: this.status,
+            low: this.low,
+            high: this.high,
+            taskOffset: this.task.scheduled() ? this.task.expireEpoch - scheduler.epoch : null,
+        };
+    }
+
+    restoreState(state) {
+        this.status = state.status;
+        this.low = state.low;
+        this.high = state.high;
+        this.task.cancel();
+        if (state.taskOffset !== null) {
+            this.task.schedule(state.taskOffset);
+            // Conversion in progress: CB1 should be high (set by write(), cleared by onComplete())
+            this.sysvia.setcb1(true);
+        }
+    }
+
     /**
      * Read from the ADC registers
      * @param {number} addr - The address to read from

package/src/app/app.js

@@ -230,6 +230,35 @@ const template = [
                 click: showModal("configuration"),
             },
             { type: "separator" },
+            {
+                label: "Save State...",
+                accelerator: "CmdOrCtrl+S",
+                click: sendAction("save-state"),
+            },
+            {
+                label: "Load State...",
+                accelerator: "CmdOrCtrl+O",
+                click: async (_, browserWindow) => {
+                    const result = await dialog.showOpenDialog(browserWindow, {
+                        title: "Load emulator state",
+                        filters: [
+                            { name: "Snapshot files", extensions: ["gz", "json", "snp"] },
+                            { name: "All files", extensions: ["*"] },
+                        ],
+                        properties: ["openFile"],
+                    });
+                    if (!result.canceled) {
+                        const filePath = getFileParam(result.filePaths[0]);
+                        browserWindow.webContents.send("load-state", { path: filePath });
+                    }
+                },
+            },
+            { type: "separator" },
+            {
+                label: "Rewind...",
+                click: sendAction("rewind"),
+            },
+            { type: "separator" },
             {
                 label: "Soft Reset",
                 click: sendAction("soft-reset"),

package/src/app/electron.js

@@ -6,7 +6,7 @@
 export let initialise = function () {};
 
 function init(args) {
-    const { loadDiscImage, loadTapeImage, processor, modals, actions, config } = args;
+    const { loadDiscImage, loadTapeImage, loadStateFile, processor, modals, actions, config } = args;
     const api = window.electronAPI;
 
     api.onLoadDisc(async (message) => {
@@ -34,6 +34,15 @@ function init(args) {
         }
     });
 
+    api.onLoadState(async (message) => {
+        if (loadStateFile) {
+            const response = await fetch(message.path);
+            const blob = await response.blob();
+            const file = new File([blob], message.path.split("/").pop());
+            await loadStateFile(file);
+        }
+    });
+
     // Observe model name changes and update window title
     const modelElement = document.querySelector(".bbc-model");
     if (modelElement) {

package/src/app/preload.js

@@ -7,6 +7,7 @@ contextBridge.exposeInMainWorld("electronAPI", {
     onLoadTape: (callback) => ipcRenderer.on("load-tape", (event, message) => callback(message)),
     onShowModal: (callback) => ipcRenderer.on("show-modal", (event, message) => callback(message)),
     onAction: (callback) => ipcRenderer.on("action", (event, message) => callback(message)),
+    onLoadState: (callback) => ipcRenderer.on("load-state", (event, message) => callback(message)),
     setTitle: (title) => ipcRenderer.send("set-title", title),
     saveSettings: (settings) => ipcRenderer.send("save-settings", settings),
 });