jsbeeb 1.11.0 → 1.13.0

package/README.md

@@ -4,8 +4,9 @@
 
 [![jsbeeb](public/images/jsbeeb-example.png)](https://bbc.xania.org/)
 
-A BBC Micro emulator written in JavaScript and running in modern browsers. Emulates a 32K BBC B (with sideways RAM)
-and a 128K BBC Master, along with a number of different peripherals.
+A BBC Micro and other 8-bit Acorn emulator written in JavaScript and running in modern browsers. Emulates a 32K BBC B
+(with sideways RAM), a 128K BBC Master, and an Acorn Atom (with AtoMMC2 SD card interface), along with a number of
+different peripherals.
 
 ## Table of Contents
 
@@ -177,7 +178,15 @@ sudo rpm -i out/dist/jsbeeb-1.0.1.x86_64.rpm
   Doesn't support the sth: pseudo URL unlike `disc` and `tape`, but if given a ZIP file will attempt to use the `.rom`
   file assumed to be within.
 - (mostly internal use) `logFdcCommands`, `logFdcStateChanges` - turn on logging in the disc controller.
-- `audioDebug=true` turns on some audio debug graphs.
+- `audioDebug` - show audio queue stats chart.
+
+### Atom-specific parameters
+
+- `model=Atom` - select the Acorn Atom (MMC) model. Other Atom variants: `Atom-Tape`, `Atom-Tape-FP`, `Atom-DOS`.
+- `mmc=XXX` - load an MMC/SD card image (ZIP) for the Atom.
+
+Atom models can also be selected automatically by hostname: any hostname starting with `atom` (e.g. `atom.xania.org`)
+defaults to the Atom model.
 
 ## Patches
 
@@ -258,6 +267,11 @@ Cheers to [Ed Spittles](https://github.com/BigEd) for testing various interrupt
 
 Thanks to Chris Jordan for his thorough testing, bug reports, ideas and help.
 
+Huge thanks to [Andrew Hague](https://github.com/CommanderCoder) (CommanderCoder) for the Acorn Atom emulation
+support. Andrew developed the original Atom implementation including the MC6847 video chip, 8255 PPIA, AtoMMC2 SD card
+interface, Atom keyboard mapping, tape support, and speaker output. His work in [PR #505](https://github.com/mattgodbolt/jsbeeb/pull/505)
+was incrementally merged and refined into the codebase.
+
 A lot of the early development used the amazing [Visual 6502](http://visual6502.org/) as reference for intra-instruction
 timings. Amazing stuff.
 

package/package.json

@@ -7,7 +7,7 @@
   "name": "jsbeeb",
   "description": "Emulate a BBC Micro",
   "repository": "git@github.com:mattgodbolt/jsbeeb.git",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "//": "If you change the version of Node, it must also be updated at the top of the Dockerfile.",
   "engines": {
     "node": ">=22.12.0"
@@ -30,28 +30,27 @@
     "argparse": "^2.0.1",
     "bootstrap": "^5.3.8",
     "bootswatch": "^5.3.8",
-    "event-emitter-es6": "^1.1.5",
     "sharp": "^0.34.5",
     "smoothie": "^1.36.1"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^10.0.0",
+    "eslint": "^10.2.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
-    "globals": "^17.3.0",
+    "globals": "^17.5.0",
     "husky": "^9.1.7",
-    "jsdom": "^29.0.0",
-    "lint-staged": "^16.2.7",
+    "jsdom": "^29.0.2",
+    "lint-staged": "^16.4.0",
     "npm-run-all2": "^8.0.4",
     "pixelmatch": "^7.1.0",
-    "prettier": "^3.8.1",
-    "vite": "^8.0.3",
+    "prettier": "^3.8.2",
+    "vite": "^8.0.8",
     "vitest": "^4.0.10"
   },
   "optionalDependencies": {
-    "electron": "^41.1.1",
+    "electron": "^41.2.0",
     "electron-builder": "^26.8.1",
     "electron-store": "^11.0.2"
   },

package/src/6502.js

@@ -10,6 +10,8 @@ import { TouchScreen } from "./touchscreen.js";
 import { TeletextAdaptor } from "./teletext_adaptor.js";
 import { Filestore } from "./filestore.js";
 import { FakeRelayNoise } from "./relaynoise.js";
+import { AtomPPIA } from "./ppia.js";
+import { AtomMMC2 } from "./mmc.js";
 
 const signExtend = utils.signExtend;
 
@@ -1208,6 +1210,13 @@ export class Cpu6502 extends Base6502 {
         if (state.roms) {
             this.ramRomOs.set(state.roms.slice(0, 16 * 16384), this.romOffset);
         }
+        // Selectively overwrite individual sideways RAM banks (e.g. from BeebEm UEF import)
+        // without touching ROM banks that jsbeeb has already loaded.
+        if (state.swRamBanks) {
+            for (const [bank, data] of Object.entries(state.swRamBanks)) {
+                this.ramRomOs.set(data.slice(0, 16384), this.romOffset + Number(bank) * 16384);
+            }
+        }
         this.videoDisplayPage = state.videoDisplayPage;
         this.music5000PageSel = state.music5000PageSel;
 
@@ -1238,53 +1247,69 @@ export class Cpu6502 extends Base6502 {
 
     reset(hard) {
         if (hard) {
-            // On the Master, opcodes executing from 0xc000 - 0xdfff can optionally have their memory accesses
-            // redirected to shadow RAM.
-            this.memStatOffsetByIFetchBank = this.model.isMaster ? (1 << 0xc) | (1 << 0xd) : 0x0000;
-            if (!this.model.isTest) {
-                for (let i = 0; i < 128; ++i) this.memStat[i] = this.memStat[256 + i] = 1;
-                for (let i = 128; i < 256; ++i) this.memStat[i] = this.memStat[256 + i] = 2;
-                for (let i = 0; i < 128; ++i) this.memLook[i] = this.memLook[256 + i] = 0;
-                for (let i = 128; i < 192; ++i) this.memLook[i] = this.memLook[256 + i] = this.romOffset - 0x8000;
-                for (let i = 192; i < 256; ++i) this.memLook[i] = this.memLook[256 + i] = this.osOffset - 0xc000;
-
-                for (let i = 0xfc; i < 0xff; ++i) this.memStat[i] = this.memStat[256 + i] = 0;
-            } else {
-                // Test sets everything as RAM.
-                for (let i = 0; i < 256; ++i) {
-                    this.memStat[i] = this.memStat[256 + i] = 1;
-                    this.memLook[i] = this.memLook[256 + i] = 0;
-                }
-            }
-            // DRAM content is not guaranteed to contain any particular
-            // value on start up, so we choose values that help avoid
-            // bugs in various games.
-            for (let i = 0; i < this.romOffset; ++i) {
-                if (i < 0x100) {
-                    // For Clogger.
-                    this.ramRomOs[i] = 0x00;
-                } else {
-                    // For Eagle Empire.
-                    this.ramRomOs[i] = 0xff;
-                }
-            }
-            this.videoDisplayPage = 0;
-            if (this.config.printerPort) this.uservia.ca2changecallback = this.config.printerPort.outputStrobe;
-
-            this.sysvia.reset();
-            this.uservia.reset();
-            this.acia.reset();
-            this.serial.reset();
-            this.ddNoise.spinDown();
-            this.fdc.powerOnReset();
-            this.adconverter.reset();
-
-            this.touchScreen = new TouchScreen(this.scheduler);
-            if (this.model.hasTeletextAdaptor) this.teletextAdaptor = new TeletextAdaptor(this);
-            if (this.econet) this.filestore = new Filestore(this, this.econet);
+            this.setupMemoryMap();
+            this.resetPeripherals(hard);
         } else {
             this.fdc.reset();
         }
+        this.resetCpuState(hard);
+    }
+
+    // Override in subclasses for different memory maps.
+    setupMemoryMap() {
+        // On the Master, opcodes executing from 0xc000 - 0xdfff can optionally have their memory accesses
+        // redirected to shadow RAM.
+        this.memStatOffsetByIFetchBank = this.model.isMaster ? (1 << 0xc) | (1 << 0xd) : 0x0000;
+        if (!this.model.isTest) {
+            for (let i = 0; i < 128; ++i) this.memStat[i] = this.memStat[256 + i] = 1;
+            for (let i = 128; i < 256; ++i) this.memStat[i] = this.memStat[256 + i] = 2;
+            for (let i = 0; i < 128; ++i) this.memLook[i] = this.memLook[256 + i] = 0;
+            for (let i = 128; i < 192; ++i) this.memLook[i] = this.memLook[256 + i] = this.romOffset - 0x8000;
+            for (let i = 192; i < 256; ++i) this.memLook[i] = this.memLook[256 + i] = this.osOffset - 0xc000;
+
+            for (let i = 0xfc; i < 0xff; ++i) this.memStat[i] = this.memStat[256 + i] = 0;
+        } else {
+            // Test sets everything as RAM.
+            for (let i = 0; i < 256; ++i) {
+                this.memStat[i] = this.memStat[256 + i] = 1;
+                this.memLook[i] = this.memLook[256 + i] = 0;
+            }
+        }
+        // DRAM content is not guaranteed to contain any particular
+        // value on start up, so we choose values that help avoid
+        // bugs in various games.
+        for (let i = 0; i < this.romOffset; ++i) {
+            if (i < 0x100) {
+                // For Clogger.
+                this.ramRomOs[i] = 0x00;
+            } else {
+                // For Eagle Empire.
+                this.ramRomOs[i] = 0xff;
+            }
+        }
+        this.videoDisplayPage = 0;
+    }
+
+    // Override in subclasses for different peripheral sets.
+    // Only called on hard reset.
+    resetPeripherals() {
+        if (this.config.printerPort) this.uservia.ca2changecallback = this.config.printerPort.outputStrobe;
+
+        this.sysvia.reset();
+        this.uservia.reset();
+        this.acia.reset();
+        this.serial.reset();
+        this.ddNoise.spinDown();
+        this.fdc.powerOnReset();
+        this.adconverter.reset();
+
+        this.touchScreen = new TouchScreen(this.scheduler);
+        if (this.model.hasTeletextAdaptor) this.teletextAdaptor = new TeletextAdaptor(this);
+        if (this.econet) this.filestore = new Filestore(this, this.econet);
+    }
+
+    // Universal CPU state reset. Shared by all machine types.
+    resetCpuState(hard) {
         this.tube.reset(hard);
         if (hard) {
             this.targetCycles = 0;
@@ -1488,3 +1513,285 @@ export class Cpu6502 extends Base6502 {
         this.debugger.setCpu(this);
     }
 }
+
+// Acorn Atom memory map:
+//   0x0000-0x7FFF  RAM (32KB, or 40KB with extensions up to 0x9FFF)
+//   0x0A00-0x0AFF  FDC (8271) -- hole in RAM region
+//   0x8000-0x9FFF  Video RAM (shared with MC6847 VDG)
+//   0xA000-0xAFFF  Banked ROM/RAM (Branquart, 16 x 4KB banks via latch at 0xBFFF)
+//   0xB000-0xB003  PPIA (8255)
+//   0xB400-0xB40F  AtomMMC
+//   0xB800-0xB80F  VIA (6522)
+//   0xBFFF         Bank select latch (write-only)
+//   0xC000-0xEFFF  ROM (BASIC, FP, DOS in 4KB blocks)
+//   0xF000-0xFFFF  OS kernel ROM (4KB)
+//
+// Branquart banking: bits 0-3 of the latch at 0xBFFF select which 4KB
+// bank is visible at 0xA000-0xAFFF. Banks can contain ROM or RAM.
+// The latch is write-only; bit 6 is a lock bit.
+
+// Storage for Branquart banks starts after the BBC ROM area.
+const BranquartOffset = 128 * 1024 + 17 * 16 * 16384;
+const BranquartBankSize = 0x1000; // 4KB per bank
+const NumBranquartBanks = 16;
+const AtomRomBlockSize = 0x1000; // 4KB
+
+export class AtomCpu6502 extends Cpu6502 {
+    constructor(model, options) {
+        super(model, options);
+
+        // Atom peripherals
+        this.atomppia = new AtomPPIA(this, this.config.keyLayout, this.scheduler);
+        this.atommc = new AtomMMC2(this);
+
+        // Branquart bank selection
+        this.branquartLatch = 0;
+        // Track which banks are ROM (false) vs RAM (true) for write protection.
+        this.branquartRam = new Array(NumBranquartBanks).fill(true);
+
+        // Expand ramRomOs to include Branquart bank storage.
+        const expandedSize = BranquartOffset + NumBranquartBanks * BranquartBankSize;
+        if (this.ramRomOs.length < expandedSize) {
+            const expanded = new Uint8Array(expandedSize);
+            expanded.set(this.ramRomOs);
+            this.ramRomOs = expanded;
+        }
+
+        // Atom runs at 1 MHz
+        this.peripheralCyclesPerSecond = 1 * 1000 * 1000;
+        // reset() and debugger.setCpu() are called by initialise() after loadOs().
+    }
+
+    // Select which Branquart bank is visible at 0xA000-0xAFFF by
+    // updating the memLook table. This keeps reads on the fast path.
+    selectBranquartBank(bank) {
+        bank &= 0x0f;
+        const offset = BranquartOffset + bank * BranquartBankSize - 0xa000;
+        for (let i = 0xa0; i < 0xb0; ++i) {
+            this.memLook[i] = this.memLook[256 + i] = offset;
+        }
+        // ROM banks are read-only, RAM banks are writable
+        const stat = this.branquartRam[bank] ? 1 : 2;
+        for (let i = 0xa0; i < 0xb0; ++i) {
+            this.memStat[i] = this.memStat[256 + i] = stat;
+        }
+    }
+
+    setupMemoryMap() {
+        this.memStatOffsetByIFetchBank = 0; // no shadow RAM on Atom
+
+        // 0x0000-0x9FFF: RAM (including video RAM at 0x8000)
+        for (let i = 0; i < 0xa0; ++i) {
+            this.memStat[i] = this.memStat[256 + i] = 1;
+            this.memLook[i] = this.memLook[256 + i] = 0;
+        }
+
+        // 0xA000-0xAFFF: Branquart banked region (set up via selectBranquartBank)
+        this.branquartLatch = 0;
+        this.selectBranquartBank(0);
+
+        // 0xB000-0xBFFF: Device I/O (PPIA, MMC, VIA, bank latch)
+        for (let i = 0xb0; i < 0xc0; ++i) {
+            this.memStat[i] = this.memStat[256 + i] = 0;
+        }
+
+        // 0xC000-0xEFFF: ROM (4KB blocks loaded into romOffset area)
+        for (let i = 0xc0; i < 0xf0; ++i) {
+            this.memStat[i] = this.memStat[256 + i] = 2;
+            this.memLook[i] = this.memLook[256 + i] = this.romOffset - 0xa000;
+        }
+
+        // 0xF000-0xFFFF: OS kernel ROM
+        for (let i = 0xf0; i < 0x100; ++i) {
+            this.memStat[i] = this.memStat[256 + i] = 2;
+            this.memLook[i] = this.memLook[256 + i] = this.osOffset - 0xf000;
+        }
+
+        // FDC at 0x0A00 (device hole in RAM, if model uses FDC)
+        if (this.model.Fdc) {
+            this.memStat[0x0a] = this.memStat[256 + 0x0a] = 0;
+        }
+
+        // Randomise video RAM and seed bytes
+        for (let i = 8; i < 13; ++i) this.ramRomOs[i] = (256 * Math.random()) | 0;
+        for (let i = 0x8000; i < 0x9000; ++i) this.ramRomOs[i] = (256 * Math.random()) | 0;
+
+        this.videoDisplayPage = 0;
+    }
+
+    resetPeripherals() {
+        super.resetPeripherals();
+        this.atomppia.reset();
+        this.atommc.reset(true);
+    }
+
+    readDevice(addr) {
+        addr &= 0xffff;
+        switch (addr & ~0x0003) {
+            case 0x0a00:
+            case 0x0a04:
+                return this.fdc.read(addr);
+            case 0xb000:
+            case 0xb004:
+                return this.atomppia.read(addr);
+            case 0xb008:
+            case 0xb00c:
+                return 0x00;
+            case 0xb400:
+            case 0xb404:
+            case 0xb408:
+            case 0xb40c:
+                return this.atommc.read(addr);
+            case 0xb800:
+            case 0xb804:
+            case 0xb808:
+            case 0xb80c:
+                return this.uservia.read(addr);
+        }
+        return addr >>> 8; // open bus
+    }
+
+    writeDevice(addr, b) {
+        addr &= 0xffff;
+        b |= 0;
+        switch (addr & ~0x0003) {
+            case 0x0a00:
+            case 0x0a04:
+                return this.fdc.write(addr, b);
+            case 0xb000:
+            case 0xb004:
+            case 0xb008:
+            case 0xb00c:
+                return this.atomppia.write(addr, b);
+            case 0xb400:
+            case 0xb404:
+            case 0xb408:
+            case 0xb40c:
+                return this.atommc.write(addr, b);
+            case 0xb800:
+            case 0xb804:
+            case 0xb808:
+            case 0xb80c:
+                return this.uservia.write(addr, b);
+            case 0xbffc:
+                if (addr === 0xbfff) {
+                    this.branquartLatch = b & 0xff;
+                    this.selectBranquartBank(b & 0x0f);
+                }
+                return;
+        }
+    }
+
+    writemem(addr, b) {
+        addr &= 0xffff;
+        b |= 0;
+        if (this._debugWrite) this._debugWrite(addr, b);
+        const statOffset = this.memStatOffset + (addr >>> 8);
+        const stat = this.memStat[statOffset];
+        if (stat === 1) {
+            // Notify VDG of CPU address bus activity for snow effect
+            if (this.video.video6847) {
+                this.video.video6847.cpuAddrAccess(addr);
+            }
+            const offset = this.memLook[statOffset];
+            this.ramRomOs[offset + addr] = b;
+            return;
+        }
+        if (stat === 2) return; // ROM: write ignored
+        // Device page
+        this.writeDevice(addr, b);
+    }
+
+    // Atom ROMs are 4KB, not 16KB like BBC.
+    // OS layout: osOffset holds 4KB kernel at 0xF000.
+    // Extra ROMs (BASIC, FP, DOS) are 4KB blocks at romOffset+0..romOffset+0x5000
+    // mapped at 0xC000, 0xD000, 0xE000 etc.
+    async loadOs(os) {
+        const extraRoms = Array.prototype.slice.call(arguments, 1).concat(this.config.extraRoms);
+        const bankRoms = this.model.banks || [];
+        os = "roms/" + os;
+        console.log(`Loading Atom OS from ${os}`);
+        const data = await utils.loadData(os);
+        const len = data.length;
+
+        if (len < AtomRomBlockSize || len % AtomRomBlockSize !== 0) {
+            throw new Error(`Broken Atom ROM file (length=${len})`);
+        }
+
+        // Clear the OS area and load the kernel at osOffset (mapped to 0xF000)
+        this.ramRomOs.fill(0x00, this.osOffset, this.osOffset + 0x4000);
+        this.ramRomOs.set(data.subarray(0, AtomRomBlockSize), this.osOffset);
+
+        // Load extra ROMs (BASIC, FP, DOS) into 4KB blocks.
+        // romIndex counts down from 5: slot 4 maps to 0xE000 (romOffset+0x4000),
+        // slot 3 to 0xD000 (romOffset+0x3000), slot 2 to 0xC000 (romOffset+0x2000).
+        let romIndex = 5;
+        const awaiting = [];
+        for (const rom of extraRoms) {
+            romIndex--;
+            if (romIndex < 2)
+                throw new Error("Too many extra ROMs for Atom (max 3 addressable slots at 0xC000-0xEFFF)");
+            if (rom !== "") {
+                awaiting.push(this.loadRom(rom, this.romOffset + romIndex * AtomRomBlockSize));
+            }
+        }
+
+        // Load Branquart bank ROMs (max 16 banks)
+        const numBanks = Math.min(bankRoms.length, NumBranquartBanks);
+        for (let bankIndex = 0; bankIndex < numBanks; bankIndex++) {
+            if (bankRoms[bankIndex] !== "") {
+                awaiting.push(this.loadRom(bankRoms[bankIndex], BranquartOffset + bankIndex * BranquartBankSize));
+                this.branquartRam[bankIndex] = false; // mark as ROM
+            }
+        }
+
+        return await Promise.all(awaiting);
+    }
+
+    // Override loadRom to accept 4KB ROMs
+    async loadRom(name, offset) {
+        const data = await utils.loadData("roms/" + name);
+        const len = data.length;
+        if (len !== 16384 && len !== 8192 && len !== 4096) {
+            throw new Error(`Broken ROM file ${name} (length=${len})`);
+        }
+        this.ramRomOs.set(data, offset);
+    }
+
+    // Atom key layout goes through PPIA, not SysVia
+    updateKeyLayout() {
+        this.atomppia.setKeyLayout(this.config.keyLayout);
+    }
+
+    snapshotState(options) {
+        const state = super.snapshotState(options);
+        // Atom-specific state
+        state.branquartLatch = this.branquartLatch;
+        state.branquartRam = [...this.branquartRam];
+        // Save Branquart bank contents
+        state.branquartBanks = this.ramRomOs.slice(
+            BranquartOffset,
+            BranquartOffset + NumBranquartBanks * BranquartBankSize,
+        );
+        state.atomppia = this.atomppia.snapshotState();
+        return state;
+    }
+
+    // No-op: the Atom doesn't have BBC sideways ROM banking.
+    // This prevents super.restoreState() from corrupting the Atom memory map.
+    romSelect() {}
+
+    restoreState(state) {
+        super.restoreState(state);
+
+        // Restore Atom-specific state after the parent has handled
+        // CPU registers, memory, cycle tracking, and sub-components.
+        if (state.branquartRam) this.branquartRam = [...state.branquartRam];
+        if (state.branquartBanks) {
+            this.ramRomOs.set(state.branquartBanks, BranquartOffset);
+        }
+        this.branquartLatch = state.branquartLatch || 0;
+        this.selectBranquartBank(this.branquartLatch & 0x0f);
+        if (state.atomppia) this.atomppia.restoreState(state.atomppia);
+    }
+}