jsbeeb 1.14.0 → 1.16.0

package/src/tapes.js

@@ -1,9 +1,6 @@
 "use strict";
 import * as utils from "./utils.js";
 
-const BbcCpuSpeed = 2 * 1000 * 1000;
-const AtomCpuSpeed = 1 * 1000 * 1000;
-
 function secsToClocks(secs, cpuSpeed) {
     return (cpuSpeed * secs) | 0;
 }
@@ -25,11 +22,11 @@ function parityOf(curByte) {
 const ParityN = "N".charCodeAt(0);
 
 class UefTape {
-    constructor(stream, isAtom = false) {
+    constructor(stream, model) {
         this.stream = stream;
         this.baseFrequency = 1200;
-        this.isAtom = isAtom;
-        this.cpuSpeed = isAtom ? AtomCpuSpeed : BbcCpuSpeed;
+        this.isAtom = model.isAtom;
+        this.cpuSpeed = model.cyclesPerSecond;
         this.rewind();
 
         this.curChunk = this.readChunk();
@@ -265,9 +262,10 @@ class UefTape {
 const dividerTable = [1, 16, 64, -1];
 
 class TapefileTape {
-    constructor(stream) {
+    constructor(stream, model) {
         this.count = 0;
         this.stream = stream;
+        this.cpuSpeed = model.cyclesPerSecond;
     }
 
     rate(acia) {
@@ -278,7 +276,7 @@ class TapefileTape {
         const divider = dividerTable[acia.cr & 0x03];
         // http://beebwiki.mdfs.net/index.php/Serial_ULA says the serial rate is ignored
         // for cassette mode.
-        const cpp = (2 * 1000 * 1000) / (19200 / divider);
+        const cpp = this.cpuSpeed / (19200 / divider);
         return Math.floor(bitsPerByte * cpp);
     }
 
@@ -297,7 +295,7 @@ class TapefileTape {
             } else if (byte === 0x04) {
                 acia.setTapeCarrier(true);
                 // Simulate 5 seconds of carrier.
-                return 5 * 2 * 1000 * 1000;
+                return secsToClocks(5, this.cpuSpeed);
             } else if (byte !== 0xff) {
                 throw "Got a weird byte in the tape";
             }
@@ -307,15 +305,15 @@ class TapefileTape {
     }
 }
 
-export async function loadTapeFromData(name, data, isAtom = false) {
+export async function loadTapeFromData(name, data, model) {
     const stream = await utils.DataStream.create(name, data);
     if (stream.readByte(0) === 0xff && stream.readByte(1) === 0x04) {
         console.log("Detected a 'tapefile' tape");
-        return new TapefileTape(stream);
+        return new TapefileTape(stream, model);
     }
     if (stream.readNulString(0) === "UEF File!") {
         console.log("Detected a UEF tape");
-        return new UefTape(stream, isAtom);
+        return new UefTape(stream, model);
     }
     console.log("Unknown tape format");
     return null;

package/src/teletext_adaptor.js

@@ -34,9 +34,20 @@ Status register:
 
 */
 
-export class TeletextAdaptor {
+/**
+ * Emulates the Acorn teletext adaptor. Dispatches a `showError` CustomEvent, carrying
+ * `context` and `error` in its detail, when a channel's stream cannot be loaded.
+ */
+export class TeletextAdaptor extends EventTarget {
     constructor(cpu) {
+        super();
         this.cpu = cpu;
+        // Not cleared by a reset, so a fetch still in flight across one is recognised as stale.
+        this.streamRequest = 0;
+        this.clearState();
+    }
+
+    clearState() {
         this.teletextStatus = 0x0f; /* low nibble comes from LK4-7 and mystery links which are left floating */
         this.teletextInts = false;
         this.teletextEnable = false;
@@ -45,26 +56,40 @@ export class TeletextAdaptor {
         this.totalFrames = 0;
         this.rowPtr = 0x00;
         this.colPtr = 0x00;
-        this.frameBuffer = new Array(16).fill(0).map(() => new Array(64).fill(0));
         this.streamData = null;
         this.pollCount = 0;
+        this.frameBuffer = new Array(16).fill(0).map(() => new Array(64).fill(0));
+        // Only a register access clears our IRQ, so an interrupt latched before the reset would hang the machine.
+        this.cpu.interrupt &= ~(1 << TELETEXT_IRQ);
     }
 
     reset(hard) {
-        if (hard) {
-            console.log("Teletext adaptor: initialisation");
-            this.loadChannelStream(this.channel);
-        }
+        if (!hard) return;
+        this.clearState();
+        this.loadChannelStream(this.channel);
     }
 
-    loadChannelStream(channel) {
+    async loadChannelStream(channel) {
         console.log("Teletext adaptor: switching to channel " + channel);
-        const teletextRef = this;
-        utils.loadData("teletext/txt" + channel + ".dat").then(function (data) {
-            teletextRef.streamData = data;
-            teletextRef.totalFrames = data.length / TELETEXT_FRAME_SIZE;
-            teletextRef.currentFrame = 0;
-        });
+        const request = ++this.streamRequest;
+        let data;
+        try {
+            data = await utils.loadData(`teletext/txt${channel}.dat`);
+        } catch (error) {
+            if (request !== this.streamRequest) return;
+            console.error(`Teletext adaptor: failed to load channel ${channel}`, error);
+            this.dispatchEvent(
+                new CustomEvent("showError", {
+                    detail: { context: `loading teletext channel ${channel}`, error },
+                }),
+            );
+            return;
+        }
+        // Fetches can resolve out of order; only the newest request may apply its data.
+        if (request !== this.streamRequest) return;
+        this.streamData = data;
+        this.totalFrames = Math.floor(data.length / TELETEXT_FRAME_SIZE);
+        this.currentFrame = 0;
     }
 
     read(addr) {

package/src/touchscreen.js

@@ -3,7 +3,6 @@
 import * as utils from "./utils.js";
 
 const PollHz = 8; // Made up
-const PollCycles = (2 * 1000 * 1000) / PollHz;
 
 function doScale(val, scale, margin) {
     val = (val - margin) / (1 - 2 * margin);
@@ -11,13 +10,14 @@ function doScale(val, scale, margin) {
 }
 
 export class TouchScreen {
-    constructor(scheduler) {
+    constructor(scheduler, cyclesPerSecond) {
         this.scheduler = scheduler;
-        this.mouse = [];
+        this.pollCycles = cyclesPerSecond / PollHz;
+        this.mouse = { x: 0, y: 0, button: 0 };
         this.outBuffer = new utils.Fifo(16);
         this.delay = 0;
         this.mode = 0;
-        this.pollTask = this.scheduler.newTask(this.poll);
+        this.pollTask = this.scheduler.newTask(() => this.poll());
     }
 
     tryReceive(rts) {
@@ -47,7 +47,7 @@ export class TouchScreen {
 
     poll() {
         this.doRead();
-        this.pollTask.reschedule(PollCycles);
+        this.pollTask.reschedule(this.pollCycles);
     }
 
     store(byte) {
@@ -81,6 +81,6 @@ export class TouchScreen {
                 if (this.mode === 1) this.doRead();
                 break;
         }
-        this.pollTask.ensureScheduled(this.mode === 129 || this.mode === 130, PollCycles);
+        this.pollTask.ensureScheduled(this.mode === 129 || this.mode === 130, this.pollCycles);
     }
 }

package/src/tube.js

@@ -36,6 +36,11 @@ const TUBE_ULA_FLAG_STATUS_PARASITE_RESET_ACTIVE_LOW = TUBE_ULA_FLAG_STATUS_P;
 const TUBE_ULA_FLAG_STATUS_CLEAR_ALL_TUBE_REGISTERS = TUBE_ULA_FLAG_STATUS_T;
 const TUBE_ULA_FLAG_STATUS_SET_CONTROL_FLAGS = TUBE_ULA_FLAG_STATUS_S;
 const TUBE_ULA_R1_PARASITE_BYTE_COUNT = 24;
+//  the control flags live in the bottom six bits of the register 1 status registers, which both
+//  sides see merged with their own flow control bits
+const TUBE_ULA_CONTROL_FLAG_MASK = 0x3f;
+//  every status register except register 1's reads its unused bits as ones
+const TUBE_ULA_STATUS_UNUSED_BITS = 0x3f;
 
 export class Tube {
     constructor(hostCpu, parasiteCpu) {
@@ -54,6 +59,7 @@ export class Tube {
         this.parasiteToHostFifoByteCount1 = 0;
         this.parasiteToHostFifoByteCount3 = 0;
         this.hostToParasiteFifoByteCount3 = 0;
+        this.parasiteNmi = false;
         this.debug = false;
     }
     reset(updateInternalStatusRegister = true) {
@@ -61,8 +67,10 @@ export class Tube {
             this.internalStatusRegister = 0;
         }
         for (let i = 0; i < 4; i++) {
-            this.hostStatus[i] = TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL;
-            this.parasiteStatus[i] = TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL;
+            //  register 1's spare bits carry the control flags instead, merged in when either side reads it
+            const unused = i === TUBE_ULA_R1 ? 0 : TUBE_ULA_STATUS_UNUSED_BITS;
+            this.hostStatus[i] = TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL | unused;
+            this.parasiteStatus[i] = TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL | unused;
             if (i === TUBE_ULA_R3) {
                 //  register 3 has one valid but insignificant byte in the parasite to host FIFO (this is to prevent an immediate PNMI state after PRST)
                 this.hostStatus[i] |= TUBE_ULA_FLAG_DATA_AVAILABLE;
@@ -73,8 +81,39 @@ export class Tube {
         //  see info in the loop above from Tube Application Note about R3
         this.parasiteToHostFifoByteCount3 = 1;
         this.hostToParasiteFifoByteCount3 = 0;
+        this.parasiteNmi = false;
         this.updateInterrupts();
     }
+
+    /**
+     * The register 3 condition the ULA raises an NMI from, before the M flag gates it: the host has
+     * queued a whole transfer for the parasite, or the parasite has nothing queued back to the host.
+     *
+     * @returns {boolean} whether the condition currently holds
+     */
+    r3NmiCondition() {
+        const bytesPerTransfer = this.internalStatusRegister & TUBE_ULA_FLAG_STATUS_ENABLE_2_BYTE_R3_DATA ? 2 : 1;
+        return this.hostToParasiteFifoByteCount3 >= bytesPerTransfer || this.parasiteToHostFifoByteCount3 === 0;
+    }
+
+    /** @returns {boolean} whether that condition is currently allowed to reach the parasite's NMI pin. */
+    parasiteNmiEnabled() {
+        return !!(this.internalStatusRegister & TUBE_ULA_FLAG_STATUS_ENABLE_PARASITE_NMI_FROM_R3_DATA);
+    }
+
+    /** Drops the NMI request once the parasite has vectored through it. */
+    acknowledgeNmi() {
+        this.parasiteNmi = false;
+        this.updateInterrupts();
+    }
+
+    /**
+     * Withdraws a pending NMI whose register 3 condition has since gone away. Only the parasite's own
+     * accesses can do this: a transfer it has satisfied no longer needs servicing.
+     */
+    clearNmiIfSatisfied() {
+        if (!this.r3NmiCondition()) this.parasiteNmi = false;
+    }
     updateInterrupts() {
         //  host IRQ
         if (
@@ -97,21 +136,11 @@ export class Tube {
             this.parasiteCpu.interrupt = false;
         }
         //  parasite NMI
-        //  (from Tube Application Note)
-        //  either: M = 1, V = 0, 1 or 2 bytes in host to parasite register 3 FIFO or 0 bytes in parasite
-        //  to host register 3 FIFO (this allows single byte transfers across
-        //  register 3)
-        //  or: M = 1, V = 1, 2 bytes in host to parasite register 3 FIFO or 0 bytes in parasite to host
-        //  register 3 FIFO. (this allows two byte transfers across register 3)
-        const r3Size = this.internalStatusRegister & TUBE_ULA_FLAG_STATUS_ENABLE_2_BYTE_R3_DATA ? 2 : 1;
-        if (
-            this.internalStatusRegister & TUBE_ULA_FLAG_STATUS_ENABLE_PARASITE_NMI_FROM_R3_DATA &&
-            (this.hostToParasiteFifoByteCount3 >= r3Size || this.parasiteToHostFifoByteCount3 === 0)
-        ) {
-            this.parasiteCpu.NMI(true);
-        } else {
-            this.parasiteCpu.NMI(false);
-        }
+        //  The ULA latches its NMI request rather than presenting the register 3 condition as a level:
+        //  each host access to register 3 that gives the parasite something to do raises a request, and
+        //  only the parasite can retire one, by servicing the transfer or by taking the NMI. Recomputing
+        //  the condition here instead would lose every request raised while an earlier one still stood.
+        this.parasiteCpu.NMI(this.parasiteNmi && this.parasiteNmiEnabled());
         //  parasite CPU RESET held low - not implemented in the CPU - the CPU should be frozen until this signal is released
         this.parasiteCpu.resetHeldLow = this.internalStatusRegister & TUBE_ULA_FLAG_STATUS_PARASITE_RESET_ACTIVE_LOW;
     }
@@ -122,8 +151,7 @@ export class Tube {
                 result =
                     (this.hostStatus[TUBE_ULA_R1] &
                         (TUBE_ULA_FLAG_DATA_AVAILABLE | TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL)) |
-                    (this.internalStatusRegister &
-                        ~(TUBE_ULA_FLAG_DATA_AVAILABLE | TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL));
+                    (this.internalStatusRegister & TUBE_ULA_CONTROL_FLAG_MASK);
                 break;
             case TUBE_ULA_R1_DATA_ADDRESS:
                 result = this.parasiteToHostData[TUBE_ULA_R1][0];
@@ -143,8 +171,10 @@ export class Tube {
                 break;
             case TUBE_ULA_R2_DATA_ADDRESS:
                 result = this.parasiteToHostData[TUBE_ULA_R2][0];
-                this.parasiteStatus[TUBE_ULA_R2] |= TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL;
-                this.hostStatus[TUBE_ULA_R2] &= ~TUBE_ULA_FLAG_DATA_AVAILABLE;
+                if (this.hostStatus[TUBE_ULA_R2] & TUBE_ULA_FLAG_DATA_AVAILABLE) {
+                    this.parasiteStatus[TUBE_ULA_R2] |= TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL;
+                    this.hostStatus[TUBE_ULA_R2] &= ~TUBE_ULA_FLAG_DATA_AVAILABLE;
+                }
                 break;
             case TUBE_ULA_R3_STATUS_ADDRESS:
                 result = this.hostStatus[TUBE_ULA_R3];
@@ -157,6 +187,8 @@ export class Tube {
                     this.parasiteToHostFifoByteCount3--;
                     if (this.parasiteToHostFifoByteCount3 === 0) {
                         this.hostStatus[TUBE_ULA_R3] &= ~TUBE_ULA_FLAG_DATA_AVAILABLE;
+                        //  the parasite owes the host a byte, so ask it for one
+                        this.parasiteNmi = true;
                     }
                 }
                 break;
@@ -165,8 +197,10 @@ export class Tube {
                 break;
             case TUBE_ULA_R4_DATA_ADDRESS:
                 result = this.parasiteToHostData[TUBE_ULA_R4][0];
-                this.parasiteStatus[TUBE_ULA_R4] |= TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL;
-                this.hostStatus[TUBE_ULA_R4] &= ~TUBE_ULA_FLAG_DATA_AVAILABLE;
+                if (this.hostStatus[TUBE_ULA_R4] & TUBE_ULA_FLAG_DATA_AVAILABLE) {
+                    this.parasiteStatus[TUBE_ULA_R4] |= TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL;
+                    this.hostStatus[TUBE_ULA_R4] &= ~TUBE_ULA_FLAG_DATA_AVAILABLE;
+                }
                 break;
         }
         this.updateInterrupts();
@@ -180,14 +214,13 @@ export class Tube {
             console.log("TUBE ULA: host write " + utils.hexword(address) + " = " + utils.hexbyte(value));
         }
         switch (address & 7) {
-            case TUBE_ULA_R1_STATUS_ADDRESS:
+            case TUBE_ULA_R1_STATUS_ADDRESS: {
+                //  M and V both feed the NMI, so a write here can raise or drop the request on its own
+                const nmiBefore = this.parasiteNmiEnabled() && this.r3NmiCondition();
                 if (value & TUBE_ULA_FLAG_STATUS_SET_CONTROL_FLAGS) {
-                    this.internalStatusRegister |=
-                        value & ~(TUBE_ULA_FLAG_DATA_AVAILABLE | TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL);
+                    this.internalStatusRegister |= value & TUBE_ULA_CONTROL_FLAG_MASK;
                 } else {
-                    this.internalStatusRegister &= ~(
-                        value & ~(TUBE_ULA_FLAG_DATA_AVAILABLE | TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL)
-                    );
+                    this.internalStatusRegister &= ~(value & TUBE_ULA_CONTROL_FLAG_MASK);
                 }
                 if (value & TUBE_ULA_FLAG_STATUS_CLEAR_ALL_TUBE_REGISTERS) {
                     this.reset(false);
@@ -200,7 +233,11 @@ export class Tube {
                         this.parasiteCpu.reset(true); //  this in turn calls our this.reset(true)
                     }
                 }
+                const nmiAfter = this.parasiteNmiEnabled() && this.r3NmiCondition();
+                if (!nmiBefore && nmiAfter) this.parasiteNmi = true;
+                if (!nmiAfter) this.parasiteNmi = false;
                 break;
+            }
             case TUBE_ULA_R1_DATA_ADDRESS:
                 if (this.hostStatus[TUBE_ULA_R1] & TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL) {
                     this.hostToParasiteData[TUBE_ULA_R1][0] = value;
@@ -224,12 +261,15 @@ export class Tube {
                         if (this.hostToParasiteFifoByteCount3 === 2) {
                             this.parasiteStatus[TUBE_ULA_R3] |= TUBE_ULA_FLAG_DATA_AVAILABLE;
                             this.hostStatus[TUBE_ULA_R3] &= ~TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL;
+                            //  a whole transfer is waiting, so ask the parasite to take it
+                            this.parasiteNmi = true;
                         }
                     } else {
                         this.hostToParasiteData[TUBE_ULA_R3][0] = value;
                         this.hostToParasiteFifoByteCount3 = 1;
                         this.parasiteStatus[TUBE_ULA_R3] |= TUBE_ULA_FLAG_DATA_AVAILABLE;
                         this.hostStatus[TUBE_ULA_R3] &= ~TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL;
+                        this.parasiteNmi = true;
                     }
                 }
                 break;
@@ -250,20 +290,24 @@ export class Tube {
         let result = 0;
         switch (address & 7) {
             case TUBE_ULA_R1_STATUS_ADDRESS:
-                result = this.parasiteStatus[TUBE_ULA_R1];
+                result = this.parasiteStatus[TUBE_ULA_R1] | (this.internalStatusRegister & TUBE_ULA_CONTROL_FLAG_MASK);
                 break;
             case TUBE_ULA_R1_DATA_ADDRESS:
                 result = this.hostToParasiteData[TUBE_ULA_R1][0];
-                this.hostStatus[TUBE_ULA_R1] |= TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL;
-                this.parasiteStatus[TUBE_ULA_R1] &= ~TUBE_ULA_FLAG_DATA_AVAILABLE;
+                if (this.parasiteStatus[TUBE_ULA_R1] & TUBE_ULA_FLAG_DATA_AVAILABLE) {
+                    this.hostStatus[TUBE_ULA_R1] |= TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL;
+                    this.parasiteStatus[TUBE_ULA_R1] &= ~TUBE_ULA_FLAG_DATA_AVAILABLE;
+                }
                 break;
             case TUBE_ULA_R2_STATUS_ADDRESS:
                 result = this.parasiteStatus[TUBE_ULA_R2];
                 break;
             case TUBE_ULA_R2_DATA_ADDRESS:
                 result = this.hostToParasiteData[TUBE_ULA_R2][0];
-                this.hostStatus[TUBE_ULA_R2] |= TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL;
-                this.parasiteStatus[TUBE_ULA_R2] &= ~TUBE_ULA_FLAG_DATA_AVAILABLE;
+                if (this.parasiteStatus[TUBE_ULA_R2] & TUBE_ULA_FLAG_DATA_AVAILABLE) {
+                    this.hostStatus[TUBE_ULA_R2] |= TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL;
+                    this.parasiteStatus[TUBE_ULA_R2] &= ~TUBE_ULA_FLAG_DATA_AVAILABLE;
+                }
                 break;
             case TUBE_ULA_R3_STATUS_ADDRESS:
                 result = this.parasiteStatus[TUBE_ULA_R3];
@@ -277,6 +321,7 @@ export class Tube {
                         this.hostStatus[TUBE_ULA_R3] |= TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL;
                         this.parasiteStatus[TUBE_ULA_R3] &= ~TUBE_ULA_FLAG_DATA_AVAILABLE;
                     }
+                    this.clearNmiIfSatisfied();
                 }
                 break;
             case TUBE_ULA_R4_STATUS_ADDRESS:
@@ -284,8 +329,10 @@ export class Tube {
                 break;
             case TUBE_ULA_R4_DATA_ADDRESS:
                 result = this.hostToParasiteData[TUBE_ULA_R4][0];
-                this.hostStatus[TUBE_ULA_R4] |= TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL;
-                this.parasiteStatus[TUBE_ULA_R4] &= ~TUBE_ULA_FLAG_DATA_AVAILABLE;
+                if (this.parasiteStatus[TUBE_ULA_R4] & TUBE_ULA_FLAG_DATA_AVAILABLE) {
+                    this.hostStatus[TUBE_ULA_R4] |= TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL;
+                    this.parasiteStatus[TUBE_ULA_R4] &= ~TUBE_ULA_FLAG_DATA_AVAILABLE;
+                }
                 break;
         }
         this.updateInterrupts();
@@ -304,13 +351,15 @@ export class Tube {
             parasiteToHostFifoByteCount1: this.parasiteToHostFifoByteCount1,
             parasiteToHostFifoByteCount3: this.parasiteToHostFifoByteCount3,
             hostToParasiteFifoByteCount3: this.hostToParasiteFifoByteCount3,
+            parasiteNmi: this.parasiteNmi,
         };
     }
 
     /**
      * The interrupt and reset lines are not saved: they are derived from the status registers
      * and FIFO counts, in the same way the host's `interrupt` is rebuilt by the VIA and ACIA
-     * restores.
+     * restores. The latched NMI request is saved, as nothing else records whether the parasite
+     * still owes the host a transfer.
      */
     restoreState(state) {
         this.internalStatusRegister = state.internalStatusRegister;
@@ -323,6 +372,8 @@ export class Tube {
         this.parasiteToHostFifoByteCount1 = state.parasiteToHostFifoByteCount1;
         this.parasiteToHostFifoByteCount3 = state.parasiteToHostFifoByteCount3;
         this.hostToParasiteFifoByteCount3 = state.hostToParasiteFifoByteCount3;
+        //  snapshots taken before the ULA latched its NMI have to fall back on the condition itself
+        this.parasiteNmi = state.parasiteNmi ?? this.r3NmiCondition();
         this.updateInterrupts();
     }
 
@@ -366,6 +417,7 @@ export class Tube {
                         this.hostStatus[TUBE_ULA_R3] |= TUBE_ULA_FLAG_DATA_AVAILABLE;
                         this.parasiteStatus[TUBE_ULA_R3] &= ~TUBE_ULA_FLAG_DATA_REGISTER_NOT_FULL;
                     }
+                    this.clearNmiIfSatisfied();
                 }
                 break;
             case TUBE_ULA_R4_DATA_ADDRESS:

package/src/url-params.js

@@ -161,52 +161,56 @@ export function buildUrlFromParams(baseUrl, parsedQuery, paramTypes = {}) {
 }
 
 /**
- * Process keyboard mapping parameters from query string
+ * Process keyboard and gamepad mapping parameters from query string
  * @param {Object} parsedQuery - The parsed query parameters
- * @param {Object} BBC - BBC key constants
+ * @param {Object} machineKeys - Emulated machine's key constants (`BBC`, or `ATOM` for the Atom)
  * @param {Object} keyCodes - Key code constants
  * @param {Array} userKeymap - Array to store user key mappings
  * @param {Object} gamepad - Gamepad object for handling mapping
- * @returns {Object} Updated query parameters
+ * @returns {string[]} descriptions of any mappings that were skipped, for showing to the user
  */
-export function processKeyboardParams(parsedQuery, BBC, keyCodes, userKeymap, gamepad) {
+export function processInputParams(parsedQuery, machineKeys, keyCodes, userKeymap, gamepad) {
+    const warnings = [];
+
     Object.entries(parsedQuery).forEach(([key, val]) => {
         if (!val) return;
 
-        // eg KEY.CAPSLOCK=CTRL
+        // `KEY.<host key>=<machine key>`, eg `KEY.CAPSLOCK=CTRL`. Host names come from
+        // `keyCodes`, so the BBC's RETURN is ENTER here; both lists are in the README.
         if (key.toUpperCase().indexOf("KEY.") === 0) {
-            const bbcKey = val.toUpperCase();
+            const machineKey = val.toUpperCase();
+            const nativeKey = key.substring(4).toUpperCase(); // remove KEY.
 
-            if (BBC[bbcKey]) {
-                const nativeKey = key.substring(4).toUpperCase(); // remove KEY.
-                if (keyCodes[nativeKey]) {
-                    console.log("mapping " + nativeKey + " to " + bbcKey);
-                    userKeymap.push({ native: nativeKey, bbc: bbcKey });
-                } else {
-                    console.log("unknown key: " + nativeKey);
-                }
+            if (!machineKeys[machineKey]) {
+                warnings.push(`${key}=${val}: "${machineKey}" is not a key on the emulated machine.`);
+            } else if (!keyCodes[nativeKey]) {
+                warnings.push(`${key}=${val}: "${nativeKey}" is not a key on your keyboard.`);
             } else {
-                console.log("unknown BBC key: " + val);
+                console.log("mapping " + nativeKey + " to " + machineKey);
+                userKeymap.push({ native: nativeKey, key: machineKey });
             }
         } else if (key.indexOf("GP.") === 0) {
             // gamepad mapping
             // eg ?GP.FIRE2=RETURN
             const gamepadKey = key.substring(3).toUpperCase(); // remove GP. prefix
-            gamepad.remap(gamepadKey, val.toUpperCase());
+            const problem = gamepad.remap(gamepadKey, val.toUpperCase());
+            if (problem) warnings.push(`${key}=${val}: ${problem}`);
         } else {
             switch (key) {
                 case "LEFT":
                 case "RIGHT":
                 case "UP":
                 case "DOWN":
-                case "FIRE":
-                    gamepad.remap(key, val.toUpperCase());
+                case "FIRE": {
+                    const problem = gamepad.remap(key, val.toUpperCase());
+                    if (problem) warnings.push(`${key}=${val}: ${problem}`);
                     break;
+                }
             }
         }
     });
 
-    return parsedQuery;
+    return warnings;
 }
 
 /**

package/src/utils.js

@@ -657,6 +657,12 @@ export function getKeyMap(keyLayout) {
         keys2[shiftDown][s] = colRow;
     }
 
+    // Overriding a default is the point here, so unlike `map` this doesn't warn about the clash.
+    function remap(s, colRow) {
+        keys2[true][s] = colRow;
+        keys2[false][s] = colRow;
+    }
+
     // shiftDown undefined -> map both
     function map(s, colRow, shiftDown) {
         if ((!s && s !== 0) || !colRow) {
@@ -935,11 +941,10 @@ export function getKeyMap(keyLayout) {
     // eg Master Dunjunz needs # Del 3 , * Enter
     // https://web.archive.org/web/20080305042238/http://bbc.nvg.org/doc/games/Dunjunz-docs.txt
 
-    // user keymapping
-    // do last (to override defaults)
-    while (userKeymap.length > 0) {
-        const mapping = userKeymap.pop();
-        map(keyCodes[mapping.native], BBC[mapping.bbc]);
+    // `KEY.` URL parameters, applied last so they win. Not consumed: this map is rebuilt on
+    // layout and model changes, and the user's mapping has to survive that.
+    for (const mapping of userKeymap) {
+        remap(keyCodes[mapping.native], BBC[mapping.key]);
     }
 
     return keys2;

package/src/utils_atom.js

@@ -249,6 +249,12 @@ export function getKeyMapAtom(keyLayout) {
         keys2[shiftDown][s] = colRow;
     }
 
+    // Overriding a default is the point here, so unlike `map` this doesn't warn about the clash.
+    function remap(s, colRow) {
+        keys2[true][s] = colRow;
+        keys2[false][s] = colRow;
+    }
+
     // shiftDown undefined -> map both
     function map(s, colRow, shiftDown) {
         if ((!s && s !== 0) || !colRow) {
@@ -477,11 +483,9 @@ export function getKeyMapAtom(keyLayout) {
         // Z - M normal
     }
 
-    // user keymapping
-    // do last (to override defaults)
-    while (userKeymap.length > 0) {
-        const mapping = userKeymap.pop();
-        map(keyCodes[mapping.native], ATOM[mapping.atom]);
+    // `KEY.` URL parameters, applied last so they win. See the equivalent in `getKeyMap`.
+    for (const mapping of userKeymap) {
+        remap(keyCodes[mapping.native], ATOM[mapping.key]);
     }
 
     return keys2;