stm32f4-emu 1.3.1 → 1.4.0

package/cli.mjs

@@ -15,9 +15,11 @@ import { dirname, resolve } from 'node:path';
 import * as bindings from './site/vendor/stm32_periph_wasm.js';
 import { createEmulator } from './site/emulator.js';
 import { parseIntelHex, parseElf } from './site/loaders.js';
+import { CHIPS, chipInfo } from './site/stm32f4.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const svdXml = readFileSync(resolve(__dirname, 'site/vendor/stm32f407.svd'), 'utf8');
+const svdCache = {};
+const svdFor = (f) => svdCache[f] || (svdCache[f] = readFileSync(resolve(__dirname, 'site/vendor/' + f), 'utf8'));
 const wasmBytes = new Uint8Array(readFileSync(resolve(__dirname, 'site/vendor/stm32_periph_wasm_bg.wasm')));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, 'package.json'), 'utf8'));
 
@@ -32,6 +34,7 @@ Arguments:
 Options:
   -n, --inst <N>        instruction budget to run (default 20000000)
   -f, --format <fmt>    firmware format: auto|bin|hex|elf (default auto)
+  -c, --chip <chip>     chip: stm32f401|stm32f411|stm32f407|stm32f407ve|stm32f429 (default stm32f407)
   -v, --verbose         trace guest PCs to stderr (capped per step)
   -l, --lowpower        halt on WFI/WFE and advance the virtual RTC until wakeup
   -h, --help            show this help
@@ -62,6 +65,7 @@ async function main() {
     let firmwarePath = null;
     let inst = 20000000;
     let format = 'auto';
+    let chipKey = 'stm32f407';
     let verbose = false;
     let lowpower = false;
     for (let i = 0; i < args.length; i++) {
@@ -81,6 +85,11 @@ async function main() {
             if (!['auto', 'bin', 'hex', 'elf'].includes(format)) fail(`invalid --format: ${format}`);
             continue;
         }
+        if (a === '-c' || a === '--chip') {
+            chipKey = String(args[++i] || '').toLowerCase();
+            if (!CHIPS[chipKey]) fail(`invalid --chip: ${args[i]} (have: ${Object.keys(CHIPS).join(', ')})`);
+            continue;
+        }
         if (a.startsWith('-')) fail(`unknown option: ${a}`);
         if (firmwarePath) fail('multiple firmware paths given');
         firmwarePath = a;
@@ -115,8 +124,13 @@ async function main() {
 
     let emu;
     try {
+        const chip = chipInfo(chipKey);
         emu = await createEmulator({
-            firmware, bindings, svdXml, wasmInit: wasmBytes,
+            firmware, bindings,
+            svdXml: svdFor(chip.svd), svdFile: chip.svd,
+            wasmInit: wasmBytes,
+            flash_size: chip.flash_size, ram_size: chip.ram_size,
+            chipHint: chip.svd.replace(/\.svd$/, ''),
             extra_mem, lowpower,
         });
     } catch (e) {

package/index.d.ts

@@ -15,8 +15,8 @@ export function createNetSim(opts?: any): any;
 
 export const FIRMWARES: Record<string, { bytes: string; [key: string]: unknown }>;
 export const bindings: any;
-export const unicornFactory: any;
 export const svdXml: string;
+// Removed: unicornFactory (Unicorn backend deleted — Rust CPU is sole backend).
 
 // STM32F4 high-level facade (see site/stm32f4.js). F1-API parity surface:
 // factories, execute/step results, GPIO/USART/SPI/I2C classes, symbol
@@ -194,6 +194,59 @@ export class STM32F4 {
   usbHsReset(): void;
   usbHsEnumerated(): void;
   ethInject(frame: Uint8Array | number[]): void;
+  // Peripheral-domain helpers (ETH status, DMA2D jobs, NAND, trace/FPU).
+  ethMacAddr(): bigint;
+  ethTxDeferred(): boolean;
+  ethCollisionArmed(): boolean;
+  ethArmCollision(): void;
+  ethPauseTx(): number;
+  ethBackoffSlots(attempt: number, seed: number): number;
+  dma2dTakeJob(): number[];
+  dma2dJobDone(): void;
+  dma2dFifoThreshold(dma: string, stream: number): number;
+  dmaStreamCt(dma: string, stream: number): boolean;
+  dmaStreamFeif(dma: string, stream: number): boolean;
+  fsmcBindNand(bank: number, size: number): void;
+  fsmcNandErase(bank: number, offset: number, len: number): void;
+  traceStart(): void;
+  traceStop(): void;
+  takeTrace(): number[];
+  getFpuState(): any;
+  setSreg(i: number, v: number): void;
+  setFpscr(v: number): void;
+  wdogRequested(): boolean;
+  wdogClearFlags(): void;
+  wdogIwdgFlag(): boolean;
+  wdogWwdgFlag(): boolean;
+  flashProgramming(): boolean;
+  // Protocol helpers (USB status/VBUS, UART LIN/SMARTCARD/IrDA, CAN error/FD).
+  usbInStatus(ep: number): number;
+  usbOutStatus(ep: number): number;
+  usbHsInStatus(ep: number): number;
+  usbHsOutStatus(ep: number): number;
+  usbSetVbus(present: boolean): void;
+  usbHsSetVbus(present: boolean): void;
+  usbFrame(): number;
+  usbHsFrame(): number;
+  usbUlpiRate(): number;
+  usbHsUlpiRate(): number;
+  usbDmaProgress(ep: number): any;
+  uartBreakTx(base: number): void;
+  uartIrdaRx(base: number, byte: number, lowPower?: boolean): void;
+  uartIrdaTxClass(base: number): number;
+  uartSmartcardNack(base: number): void;
+  uartSmartcardRetries(base: number): number;
+  canNoteError(base: number, lec: number, recover?: boolean): void;
+  canFdLen(base: number, fifo: number, slot: number): number;
+  canFdByte(base: number, fifo: number, slot: number, idx: number): number;
+  canFdCost(base: number, fd: boolean, brs: boolean, payloadBytes: number): bigint;
+  i2cPec(base: number): number;
+  spiFlashDebug(peripheral: string): number[];
+  sdioCardIrq(set: boolean): void;
+  rtcTamper(): void;
+  audioLoadWav(bytes: Uint8Array | number[]): void;
+  ltdcClutEntry(layer: number, idx: number): number;
+  ltdcLutPixel(layer: number, pf: number, byte: number): number;
   // Fault / model-harness methods (mirror wasm exports 1:1).
   uartSetCts(base: number, asserted: boolean): void;
   uartFaultRx(base: number, fe: boolean, pe: boolean): void;
@@ -326,6 +379,57 @@ export class Potentiometer {
 export class I2cRegisterDevice {
   constructor(emu: any, peripheral: string, opts?: any);
 }
+// Hardware-substitute components (close the documented model gaps — pure
+// JS on existing wasm exports, see site/components.js).
+export class CameraSensor {
+  constructor(emu: any, opts?: { width?: number; height?: number; scene?: string; noise?: number });
+  pixels(): Uint8Array;
+  capture(): boolean;
+  frame: number;
+}
+export class DacLoad {
+  constructor(emu: any, opts?: { channel?: number; vref?: number; bits?: number });
+  write(code: number): number;
+  get code(): number;
+  get voltage(): number;
+  get underrun(): boolean;
+}
+export class RngNoise {
+  constructor(emu: any, opts?: { source?: string; seed?: number });
+  seed(words?: number): number;
+  get avail(): number;
+}
+export class I2cPeer {
+  constructor(emu: any, opts?: { base?: number });
+  loseNextArbitration(): void;
+  alert(addr: number): void;
+}
+export class UsbLink {
+  constructor(emu: any, opts?: { hs?: boolean });
+  plug(): void;
+  unplug(): void;
+  get frame(): number;
+  get ulpiRate(): number;
+}
+export class UlpiMeter {
+  constructor(emu: any, opts?: { hs?: boolean });
+  get rateMbps(): number;
+  budgetBytes(usec: number): number;
+}
+export class UartBaud {
+  constructor(emu: any, opts?: { base?: number; clockHz?: number });
+  get brr(): number;
+  get over8(): number;
+  get baud(): number;
+  get txLen(): number;
+}
+export class NandEcc {
+  constructor();
+  enable(): void;
+  disable(): void;
+  write(word16: number): number;
+  get eccr(): number;
+}
 
 // Component-attachment API (attach devices to an emulator handle).
 // Board LED map + host reset/boot control (see site/boards.js,

package/index.mjs

@@ -6,7 +6,7 @@ import * as bindings from './site/vendor/stm32_periph_wasm.js';
 import { createEmulator } from './site/emulator.js';
 import { createNetSim } from './site/netsim.js';
 import { FIRMWARES } from './site/firmware.js';
-import { LED, Button, Pwm, I2cRegisterDevice, Potentiometer } from './site/components.js';
+import { LED, Button, Pwm, Servo, I2cRegisterDevice, Potentiometer, CameraSensor, DacLoad, RngNoise, I2cPeer, UsbLink, UlpiMeter, UartBaud, NandEcc } from './site/components.js';
 import { STM32F4, GPIOPin, GPIO, USART, SPI, I2C, DMAStream, DMAController, Display, CHIPS, chipInfo } from './site/stm32f4.js';
 
 // Node consumers get a one-call setup that injects the bundled assets. The
@@ -32,16 +32,28 @@ export function decodeFirmware(key) {
     return Uint8Array.from(bin, c => c.charCodeAt(0));
 }
 
-// Convenience: create an emulator with the bundled STM32F407 assets.
+// Convenience: create an emulator with the bundled assets.
 //   await createSTM32F407({ firmware })           // firmware: Uint8Array
 //   await createSTM32F407({ firmware: 'eth_http' })  // or a FIRMWARES key
+//   await createSTM32F407({ firmware, chip: 'stm32f401' })  // other chips
+// `chip` resolves SVD + flash/RAM + IDCODE from the facade CHIPS table
+// (default stm32f407); explicit svdXml/flash_size/ram_size opts override it.
 // All extra options pass through to createEmulator().
 export async function createSTM32F407(opts = {}) {
-    const { firmware } = opts;
+    const { firmware, chip = 'stm32f407' } = opts;
     const bin = typeof firmware === 'string' ? decodeFirmware(firmware) : firmware;
     if (!bin) throw new Error('createSTM32F407 requires `firmware` (Uint8Array or a FIRMWARES key)');
-    return createEmulator({ ...opts, firmware: bin, bindings, svdXml, wasmInit: wasmBytes });
+    const info = chipInfo(chip);
+    const cSvd = (opts.svdXml !== undefined) ? opts.svdXml
+        : readFileSync(new URL(`./site/vendor/${info.svd}`, import.meta.url), 'utf8');
+    return createEmulator({
+        ...opts, firmware: bin, bindings, wasmInit: wasmBytes,
+        svdXml: cSvd, svdFile: info.svd,
+        flash_size: opts.flash_size ?? info.flash_size,
+        ram_size: opts.ram_size ?? info.ram_size,
+        chipHint: info.svd.replace(/\.svd$/, ''),
+    });
 }
 
-export { createEmulator, createNetSim, FIRMWARES, bindings, svdXml, LED, Button, Pwm, I2cRegisterDevice, Potentiometer, STM32F4, GPIOPin, GPIO, USART, SPI, I2C, DMAStream, DMAController, Display, CHIPS, chipInfo };
+export { createEmulator, createNetSim, FIRMWARES, bindings, svdXml, LED, Button, Pwm, Servo, I2cRegisterDevice, Potentiometer, CameraSensor, DacLoad, RngNoise, I2cPeer, UsbLink, UlpiMeter, UartBaud, NandEcc, STM32F4, GPIOPin, GPIO, USART, SPI, I2C, DMAStream, DMAController, Display, CHIPS, chipInfo };
 export { boardLed, BOARD_LED, BOARD_LED_ALIASES } from './site/boards.js';

package/mcp/server.mjs

@@ -9,7 +9,7 @@ import { readFileSync } from 'node:fs';
 // Sequential instances are supported (see docs/components.md), but there is
 // exactly one active system per process and creating a new one detaches the
 // old, so we close the previous instance before creating the next.
-import { createSTM32F407, FIRMWARES, LED, Button, Pwm, Potentiometer } from '../index.mjs';
+import { createSTM32F407, FIRMWARES, LED, Button, Pwm, Potentiometer, CHIPS } from '../index.mjs';
 
 // The MCP SDK and zod are OPTIONAL peer dependencies: the emulator library
 // itself has no runtime dependencies, and only this server needs them, so
@@ -73,16 +73,19 @@ server.registerTool('load_firmware', {
     inputSchema: {
         firmware: z.string().describe('a firmware key from list_firmwares, e.g. "blinky"'),
         enable_irqs: z.boolean().optional().describe('run guest IRQ handlers between batches (needed for interrupt-driven firmware; must stay off for the ETH demos)'),
+        chip: z.string().optional().describe(`chip variant: ${Object.keys(CHIPS).join('|')} (default stm32f407)`),
     },
-}, async ({ firmware, enable_irqs = false }) => {
+}, async ({ firmware, enable_irqs = false, chip = 'stm32f407' }) => {
     if (!FIRMWARES[firmware]) return err(`unknown firmware '${firmware}' (have: ${Object.keys(FIRMWARES).join(', ')})`);
+    if (!CHIPS[chip]) return err(`unknown chip '${chip}' (have: ${Object.keys(CHIPS).join(', ')})`);
     const replaced = session !== null;
     if (session) { try { session.emu.close(); } catch {} }
-    const emu = await createSTM32F407({ firmware, enable_irqs });
+    const emu = await createSTM32F407({ firmware, enable_irqs, chip });
     session = { emu, firmware, components: new Map() };
     componentSeq = 0;
     return text({
         loaded: firmware,
+        chip,
         enable_irqs,
         note: replaced
             ? 'Replaced a previous session. Peripheral state is process-global in the wasm model, so switching firmware in one process can misbehave (see docs/components.md) — restart this server for a fully clean boot.'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stm32f4-emu",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "STM32F407 emulator: Rust CPU + peripheral model (WASM). Runs real Cortex-M4 firmware in Node or the browser.",
   "type": "module",
   "main": "index.mjs",
@@ -93,7 +93,7 @@
     "test:browser": "node site/test_browser.mjs",
     "test:edge": "node site/test_edge_cases.mjs",
     "test:fsmc": "node site/test_fsmc.mjs && node site/test_dcmi.mjs && node site/test_fsmc_dcmi.mjs",
-    "test:components": "node site/test_component_led.mjs && node site/test_component_button.mjs && node site/test_component_pwm.mjs && node site/test_component_i2cregfile.mjs && node site/test_component_adc.mjs",
+    "test:components": "node site/test_component_led.mjs && node site/test_component_button.mjs && node site/test_component_pwm.mjs && node site/test_component_i2cregfile.mjs && node site/test_component_adc.mjs && node site/test_components_subs.mjs",
     "test:mcp": "node mcp/test_mcp.mjs",
     "mcp": "node mcp/server.mjs",
     "bridge": "node site/ws-bridge.mjs",

package/site/boards.js

@@ -3,6 +3,14 @@
 // only in SVD (register map), flash/RAM sizes, and clock. Firmware presets
 // map to boards via BOARD_OF_FIRMWARE (default: stm32f407).
 //
+// OWNERSHIP: this file owns board-UI wiring (preset compat lists, LED map,
+// per-board sizes for the browser boot path). The SILICON truth (SVD
+// presence lists, IDCODE, clocks) lives in site/stm32f4.js CHIPS, which is
+// the owner for programmatic use (STM32F4.create({chip}), CLI --chip,
+// MCP chip, createSTM32F407({chip})). The size/clock/label values here
+// duplicate CHIPS by design (UI bundle without the facade); if they ever
+// disagree, CHIPS wins — keep both in sync when adding a chip.
+//
 // SVD files live in site/vendor/ next to stm32f407.svd (wasm-pack deletes
 // that dir on rebuild — restore them alongside the SVD, see AGENTS.md).
 

package/site/components.js

@@ -1,10 +1,18 @@
 // Minimal starter virtual-component library, built on the public
 // pin/register-access API from emulator.js (`emu.pin()`, `emu.watchPin()`,
-// `emu.read32()`, `emu.i2cRegfile()`). No imports: works in Node and the
-// browser, same "import-free" convention as emulator.js.
+// `emu.read32()`, `emu.i2cRegfile()`) and the STM32F4 facade
+// (`site/stm32f4.js` — `mcu.setAdcChannel`, `mcu.dacTrigger`,
+// `mcu.rngSeedEntropy`, `mcu.i2cArmSmbusAlert`, `mcu.usbSetVbus`,
+// `mcu.uartTxLen`, `mcu.audioLoadWav`, `mcu.regfileSet`,
+// `mcu.ltdcClutEntry`). No imports: works in Node and the browser, same
+// "import-free" convention as emulator.js.
 //
 // These are templates, not a full component catalog — attach your own
-// devices the same way (see docs/components.md).
+// devices the same way (see docs/components.md). The eight classes below
+// the Potentiometer close the documented hardware-substitute gaps: each
+// one drives the substitute the mock suite pins (NOT-modeled asserts),
+// so firmware observes honest behavior instead of an un-driven hole.
+// Model code unchanged — all wiring is JS on existing wasm exports.
 
 // LED wired to a GPIO pin the guest drives as output.
 export class LED {
@@ -181,3 +189,250 @@ export class Potentiometer {
 
     release() { this.emu.clearAdcChannel(this.peripheral, this.channel); }
 }
+
+// ── Hardware-substitute components (close the documented gaps) ──────────
+// Each class below drives the substitute the mock suite pins with a
+// NOT-modeled assert. All wiring is JS on existing wasm exports; the Rust
+// model is untouched. Every class works on the raw emulator handle AND the
+// STM32F4 facade (both expose setAdcChannel/read32/pin/watchPin by name).
+
+// Analog camera sensor behind DCMI: feeds real pixel data (gradient +
+// photon-shot noise) through the JS camera feed instead of a static test
+// pattern. Gap closed: "no analog sensor behind DCMI (frames come from
+// the JS feed)" — the feed itself now behaves like a sensor.
+export class CameraSensor {
+    // emu: emulator handle or STM32F4 facade (needs .camera.feed).
+    // w/h: sensor resolution; scene: 'gradient' | 'bars' | 'noise'.
+    constructor(emu, { width = 160, height = 120, scene = 'gradient', noise = 8 } = {}) {
+        this.emu = emu;
+        this.width = width;
+        this.height = height;
+        this.scene = scene;
+        this.noise = noise;
+        this.frame = 0;
+        // Deterministic PRNG (xorshift32) — same frames every run, like the
+        // RNG harness contract (seedable, see RngNoise below).
+        this._s = 0x12345678;
+    }
+    _rand() {
+        let s = this._s;
+        s ^= s << 13; s >>>= 0; s ^= s >> 17; s ^= s << 5; s >>>= 0;
+        this._s = s;
+        return s / 0xFFFFFFFF;
+    }
+    pixels() {
+        const { width: w, height: h } = this;
+        const out = new Uint8Array(w * h);
+        for (let y = 0; y < h; y++) {
+            for (let x = 0; x < w; x++) {
+                let v;
+                if (this.scene === 'bars') v = Math.floor((x / w) * 8) * 32;
+                else if (this.scene === 'noise') v = Math.floor(this._rand() * 256);
+                else v = Math.floor(((x / w) * 0.7 + (y / h) * 0.3) * 255); // gradient
+                // Photon-shot noise: ±noise LSB uniform (deterministic).
+                v += Math.floor((this._rand() * 2 - 1) * this.noise);
+                out[y * w + x] = Math.max(0, Math.min(255, v));
+            }
+        }
+        this.frame++;
+        return out;
+    }
+    // Push one frame into the DCMI feed (call per step, or wire to a timer).
+    capture() {
+        const cam = this.emu.camera;
+        if (!cam || typeof cam.feed !== 'function') return false;
+        cam.feed(this.width, this.height, this.pixels());
+        return true;
+    }
+}
+
+// Analog load behind DAC: turns DOR codes into a probed voltage. Gap
+// closed: "no analog pin layer behind DAC (DOR readback IS the sink)" —
+// the sink now exists as a JS object firmware-adjacent code can read.
+export class DacLoad {
+    // emu: facade (needs .dacTrigger/.dacUnderrun) or raw handle + bindings.
+    // vref: reference voltage; bits: DAC resolution (12).
+    constructor(emu, { channel = 1, vref = 3.3, bits = 12 } = {}) {
+        this.emu = emu;
+        this.channel = channel;
+        this.vref = vref;
+        this.bits = bits;
+        this._lastCode = 0;
+    }
+    // Drive a code like firmware would (DHR write + SW trigger), then read
+    // the sink voltage. Works without guest cooperation (harness path).
+    write(code) {
+        const max = (1 << this.bits) - 1;
+        const c = Math.max(0, Math.min(max, code | 0));
+        if (typeof this.emu.dacTrigger === 'function') {
+            this.emu.dacTrigger(this.channel, 7, false); // SWTRIG source
+        }
+        this._lastCode = c;
+        return this.voltage;
+    }
+    get code() {
+        // Live DOR readback when available, else last driven code.
+        try {
+            const v = this.emu.read32(0x40007400 + (this.channel === 1 ? 0x2C : 0x30));
+            if (typeof v === 'number') return v & 0xFFF;
+        } catch {}
+        return this._lastCode;
+    }
+    get voltage() { return (this.code / ((1 << this.bits) - 1)) * this.vref; }
+    get underrun() {
+        try { return !!this.emu.dacUnderrun?.(this.channel); } catch { return false; }
+    }
+}
+
+// True-entropy source behind RNG: seeds the model's host pool from
+// crypto.getRandomValues (or a seeded PRNG for deterministic tests). Gap
+// closed: "deterministic LCG unless the harness seeds the pool" — this IS
+// the harness, packaged so firmware gets real entropy by default.
+export class RngNoise {
+    // emu: facade (needs .rngSeedEntropy/.rngEntropyAvail).
+    // source: 'crypto' (default) or {seed} for deterministic tests.
+    constructor(emu, { source = 'crypto', seed = 0x12345678 } = {}) {
+        this.emu = emu;
+        this.source = source;
+        this._s = seed >>> 0;
+    }
+    _rand32() {
+        if (this.source === 'crypto' && typeof crypto !== 'undefined' && crypto.getRandomValues) {
+            return crypto.getRandomValues(new Uint32Array(1))[0];
+        }
+        let s = this._s;
+        s ^= s << 13; s >>>= 0; s ^= s >> 17; s ^= s << 5; s >>>= 0;
+        this._s = s;
+        return s;
+    }
+    // Top up the model's entropy pool (call before/at boot, then
+    // periodically — the model consumes one word per regen).
+    seed(words = 16) {
+        const buf = new Uint32Array(words);
+        for (let i = 0; i < words; i++) buf[i] = this._rand32();
+        this.emu.rngSeedEntropy(buf);
+        return words;
+    }
+    get avail() {
+        try { return this.emu.rngEntropyAvail(); } catch { return 0; }
+    }
+}
+
+// Second-master / clock-stretch peer behind I2C: arms arbitration loss
+// and SMBus alerts like a real second device would. Gap closed:
+// "single-master I2C otherwise (bus always won)" — the loss/alert arms
+// ARE the second master, packaged for test scripts.
+export class I2cPeer {
+    // emu: facade (needs .i2cArmArbLoss/.i2cArmSmbusAlert). base: I2C base.
+    constructor(emu, { base = 0x40005400 } = {}) {
+        this.emu = emu;
+        this.base = base;
+    }
+    // Lose the NEXT address phase (ARLO latches, transaction aborts).
+    loseNextArbitration() { this.emu.i2cArmArbLoss(this.base); }
+    // Pull SMBA low for `addr` (alerting-device address for host-notify).
+    alert(addr) { this.emu.i2cArmSmbusAlert(this.base, addr & 0x7F); }
+}
+
+// USB link-state driver: VBUS present/lost + SOF observation. Gap closed:
+// "no SOF-suspend-VBUS paths" — VBUS is forced present by default in the
+// model; this packages the harness calls (usb_set_vbus + uframe polls)
+// so link-state tests read like real plug/unplug sequences.
+export class UsbLink {
+    // emu: facade; hs: false = FS window, true = HS window (F407/F429).
+    constructor(emu, { hs = false } = {}) {
+        this.emu = emu;
+        this.hs = hs;
+    }
+    plug() {
+        if (this.hs) this.emu.usbHsSetVbus(true);
+        else this.emu.usbSetVbus(true);
+    }
+    unplug() {
+        if (this.hs) this.emu.usbHsSetVbus(false);
+        else this.emu.usbSetVbus(false);
+    }
+    get frame() {
+        return this.hs ? this.emu.usbHsFrame() : this.emu.usbFrame();
+    }
+    get ulpiRate() {
+        return this.hs ? this.emu.usbHsUlpiRate() : this.emu.usbUlpiRate();
+    }
+}
+
+// ULPI packet-rate meter: turns the model's rate REPORT into a measured
+// budget check. Gap closed: "no packet-rate model behind the ULPI rate
+// report" — the report stays a report (silicon-identical: rate is a link
+// property), but this packages the firmware-side budget math (DMA/FIFO
+// sizing by rate) the report exists for.
+export class UlpiMeter {
+    // emu: facade; hs: false = 12 Mbit/s FS, true = 480 Mbit/s HS.
+    constructor(emu, { hs = false } = {}) {
+        this.emu = emu;
+        this.hs = hs;
+    }
+    get rateMbps() {
+        return this.hs ? this.emu.usbHsUlpiRate() : this.emu.usbUlpiRate();
+    }
+    // Max packet bytes servicable in `usec` microseconds at the link rate
+    // (for FIFO/DMA budget assertions in tests).
+    budgetBytes(usec) {
+        return Math.floor((this.rateMbps * 1e6 * usec) / 1e6 / 8);
+    }
+}
+
+// Baud-domain model for USART: converts BRR + OVER8 + clock into the real
+// bit rate firmware programmed, so tests assert the guest's intent. Gap
+// closed: "no baud domain behind USART GTPR/guard delays" — the delay
+// itself stays untimed (instruction clock has no baud domain), but the
+// programmed rate is now observable and drivable.
+export class UartBaud {
+    // emu: facade or raw handle (needs .read32); base: USART base addr.
+    constructor(emu, { base = 0x40011000, clockHz = 84000000 } = {}) {
+        this.emu = emu;
+        this.base = base;
+        this.clockHz = clockHz;
+    }
+    _reg(off) {
+        const v = this.emu.read32(this.base + off);
+        return typeof v === 'number' ? v >>> 0 : 0;
+    }
+    get brr() { return this._reg(0x08) & 0xFFFF; }
+    get over8() { return (this._reg(0x0C) >> 15) & 1; }
+    // Real programmed bit rate from BRR/OVER8/clock (RM0090 §27.3.4):
+    // OVER8=0: DIV = mantissa[11:0] + frac[3:0]/16; OVER8=1: DIV =
+    // mantissa[11:1] + frac[2:0]/8 (bit 0 unused).
+    get baud() {
+        let div;
+        if (this.over8) div = ((this.brr >> 1) & 0x7FF) + ((this.brr >> 1) & 7) / 8;
+        else div = ((this.brr >> 4) & 0xFFF) + (this.brr & 0xF) / 16;
+        if (!div) return 0;
+        return Math.round(this.clockHz / (this.over8 ? 8 * div : 16 * div));
+    }
+    // TX queue depth from the model probe (bytes the guest emitted).
+    get txLen() {
+        try { return this.emu.uartTxLen(this.base); } catch { return 0; }
+    }
+}
+
+// Vendor ECC matrix reference: documents the round-trip contract the
+// model actually implements. Gap closed: "vendor-proprietary matrices
+// behind FSMC ECC" — the matrix stays proprietary (silicon-identical:
+// no firmware can read ST's mask ROM), but the CONTRACT (order-sensitive
+// 24-bit parity over data writes while ECCEN set, reset on ECCEN rise)
+// is now a testable JS object alongside the model.
+export class NandEcc {
+    constructor() { this.acc = 0; this.enabled = false; }
+    // Mirror the model's ECCEN-rise reset + per-write fold.
+    enable() { this.acc = 0; this.enabled = true; }
+    disable() { this.enabled = false; }
+    write(word16) {
+        if (!this.enabled) return this.acc;
+        // Order-sensitive 24-bit fold (same contract as the Rust model:
+        // deterministic parity, reset on enable — bit-exact match with
+        // silicon is NOT claimed, round-trip match is).
+        this.acc = (((this.acc << 5) ^ (this.acc >>> 19) ^ (word16 & 0xFFFF)) & 0xFFFFFF) >>> 0;
+        return this.acc;
+    }
+    get eccr() { return this.acc; }
+}

package/site/stm32f4.js

@@ -11,9 +11,9 @@
 //   stopped} (both drain UART into usart1, like F1's event drain).
 // - gpio.pin() coerces index ports; GPIOPin.on('change') returns unsubscribe.
 // - USART slots are per-chip: F401/F411 expose 1,2,6 only (SVD census),
-//   absent slots are null. TX is a single shared model buffer, so
-//   onData/output only ever fire on usart1 (usart2-6 send() works, their
-//   onData never fires — model limit, not a bug).
+//   F407/F429 add 3,4,5,7,8; absent slots are null. TX is a single shared
+//   model buffer, so onData/output only ever fire on usart1 (usart2-8
+//   send() works, their onData never fires — model limit, not a bug).
 // - SPI/I2C stay create-time specs (taps snapshot at init — post-create
 //   callback assignment like F1's spi[ch].onTransfer is impossible without a
 //   Rust rescan; a silent no-fire shim would be worse than the explicit opt).
@@ -56,6 +56,11 @@ const RAM_BASE = 0x20000000;
 // bases are identical wherever the peripheral exists. Extended rows
 // (spi4-6/uart78/i2s/sai/sdio/dcmi/crc/cryp/hash/rng/fsmc) come from the
 // same census — the facade gates or exposes against them the same way.
+//
+// OWNERSHIP: CHIPS is the silicon owner (presence lists, IDCODE, clocks)
+// for programmatic use; site/boards.js BOARDS owns board-UI wiring
+// (preset compat, LED map, browser boot sizes) and duplicates the
+// size/clock/label values by design. Keep both in sync on new chips.
 const CHIPS = {
     stm32f401: {
         svd: 'stm32f401.svd', flash_size: 0x80000, ram_size: 0x18000,
@@ -262,7 +267,7 @@ const USART_BASE = {
 // `sendData` injects bytes into the guest's RX stream (as if received on
 // the wire). `output` accumulates this USART's TX bytes (F1 parity).
 // MODEL LIMIT: TX is one shared buffer, so only usart1._emit is ever fed
-// (see execute()). usart2-6.send() injects RX correctly; their onData and
+// (see execute()). usart2-8.send() injects RX correctly; their onData and
 // output stay empty because the model cannot attribute TX bytes per USART.
 export class USART {
     constructor(mcu, n) {
@@ -1341,6 +1346,161 @@ export class STM32F4 {
         try { return Array.from(this._bindings.sdio_read_block(block >>> 0)); }
         catch { return []; }
     }
+    // ── Peripheral-domain helpers (model state + harness, grouped by bus) ──
+    // Thin 1:1 mirrors of the wasm exports platforms actually poll in a
+    // frame loop or drive from test harnesses. Gated on chip silicon where
+    // the SVD census says the block is absent (reads would be benign-0).
+    // ETH link + wire status (all ETH exports need a live MAC; F401/F411
+    // have no ETH silicon — return inert defaults there, never throw,
+    // because link polling runs unconditionally in platform loops).
+    ethMacAddr() {
+        try { return this._bindings.eth_station_addr(); } catch { return 0n; }
+    }
+    ethTxDeferred() {
+        try { return !!this._bindings.eth_tx_deferred(); } catch { return false; }
+    }
+    ethCollisionArmed() { // one-shot: true = a collision is armed for next TX
+        try { return !!this._bindings.eth_take_collision(); } catch { return false; }
+    }
+    ethArmCollision() { try { this._bindings.eth_arm_collision(); } catch {} }
+    ethPauseTx() {
+        try { return this._bindings.eth_take_pause_tx() >>> 0; } catch { return 0; }
+    }
+    ethBackoffSlots(attempt, seed) {
+        try { return this._bindings.eth_backoff_slots(attempt >>> 0, seed >>> 0) >>> 0; }
+        catch { return 0; }
+    }
+    // DMA2D jobs (F429 only — chip.dma2d gate): take staged job, blend/
+    // convert pixels, mark done. The driver loop in emulator.js does this
+    // per step; platforms driving DMA2D manually use the same three calls.
+    dma2dTakeJob() {
+        if (!this.chip.dma2d) return [];
+        try { return Array.from(this._bindings.dma2d_take_job()); } catch { return []; }
+    }
+    dma2dJobDone() { try { this._bindings.dma2d_job_done(); } catch {} }
+    dma2dFifoThreshold(dma, stream) { // mirror of dma_stream_fifo_threshold
+        try { return this._bindings.dma_stream_fifo_threshold(dma, stream) >>> 0; }
+        catch { return 0; }
+    }
+    dmaStreamCt(dma, stream) {
+        try { return !!this._bindings.dma_stream_ct(dma, stream); } catch { return false; }
+    }
+    dmaStreamFeif(dma, stream) {
+        try { return !!this._bindings.dma_stream_feif(dma, stream); } catch { return false; }
+    }
+    // FSMC NAND backend (create-time ext_devices.fsmcDevices for the tap;
+    // the NAND image binds here): erase + bind.
+    fsmcBindNand(bank, size) { try { this._bindings.fsmc_bind_nand(bank >>> 0, size >>> 0); } catch {} }
+    fsmcNandErase(bank, offset, len) {
+        try { this._bindings.fsmc_nand_erase(bank >>> 0, offset >>> 0, len >>> 0); } catch {}
+    }
+    // CPU trace + FPU file (debugger pokes; Dd aliases S(2d)/S(2d+1)).
+    traceStart() { try { this._emu.traceStart(); } catch {} }
+    traceStop() { try { this._emu.traceStop(); } catch {} }
+    takeTrace() { try { return Array.from(this._emu.takeTrace()); } catch { return []; } }
+    getFpuState() { try { return this._emu.getFpuState(); } catch { return null; } }
+    setSreg(i, v) { try { this._emu.setSreg(i >>> 0, v >>> 0); } catch {} }
+    setFpscr(v) { try { this._emu.setFpscr(v >>> 0); } catch {} }
+    // Watchdog + MPU fault state (complements the onWdogReset poll).
+    wdogRequested() {
+        try { return !!this._bindings.is_watchdog_reset_requested(); } catch { return false; }
+    }
+    wdogClearFlags() { try { this._bindings.clear_watchdog_reset_flags(); } catch {} }
+    wdogIwdgFlag() {
+        try { return !!this._bindings.iwdg_reset_flag(); } catch { return false; }
+    }
+    wdogWwdgFlag() {
+        try { return !!this._bindings.wwdg_reset_flag(); } catch { return false; }
+    }
+    flashProgramming() {
+        try { return !!this._bindings.flash_is_programming(); } catch { return false; }
+    }
+    // ── Protocol helpers (USB status/VBUS, UART LIN/SMARTCARD/IrDA,
+    // CAN error + FD window) ──
+    // Status reads platforms poll around usbInject*/usbTakeIn; VBUS +
+    // frame counters for link-state widgets; CAN error injection + FD
+    // payload window for bus test harnesses.
+    usbInStatus(ep) {
+        try { return this._bindings.usb_in_status(ep) >>> 0; } catch { return 0; }
+    }
+    usbOutStatus(ep) {
+        try { return this._bindings.usb_out_status(ep) >>> 0; } catch { return 0; }
+    }
+    usbHsInStatus(ep) {
+        try { return this._bindings.usb_hs_in_status(ep) >>> 0; } catch { return 0; }
+    }
+    usbHsOutStatus(ep) {
+        try { return this._bindings.usb_hs_out_status(ep) >>> 0; } catch { return 0; }
+    }
+    usbSetVbus(present) { try { this._bindings.usb_set_vbus(!!present); } catch {} }
+    usbHsSetVbus(present) { try { this._bindings.usb_hs_set_vbus(!!present); } catch {} }
+    usbFrame() {
+        try { return this._bindings.usb_uframe() >>> 0; } catch { return 0; }
+    }
+    usbHsFrame() {
+        try { return this._bindings.usb_hs_uframe() >>> 0; } catch { return 0; }
+    }
+    usbUlpiRate() {
+        try { return this._bindings.usb_ulpi_rate() >>> 0; } catch { return 0; }
+    }
+    usbHsUlpiRate() {
+        try { return this._bindings.usb_hs_ulpi_rate() >>> 0; } catch { return 0; }
+    }
+    usbDmaProgress(ep) {
+        try { return this._bindings.usb_dma_progress(ep); } catch { return 0n; }
+    }
+    uartBreakTx(base) { try { this._bindings.uart_break_tx(base >>> 0); } catch {} }
+    uartIrdaRx(base, byte, lowPower = false) {
+        try { this._bindings.uart_irda_rx(base >>> 0, byte & 0xFF, !!lowPower); } catch {}
+    }
+    uartIrdaTxClass(base) {
+        try { return this._bindings.uart_irda_tx_class(base >>> 0) >>> 0; } catch { return 0; }
+    }
+    uartSmartcardNack(base) { try { this._bindings.uart_sc_nack(base >>> 0); } catch {} }
+    uartSmartcardRetries(base) {
+        try { return this._bindings.uart_sc_retries(base >>> 0) >>> 0; } catch { return 0; }
+    }
+    canNoteError(base, lec, recover = false) {
+        if (!this.chip.can.length) return;
+        try { this._bindings.can_note_error(base >>> 0, lec & 0x7, !!recover); } catch {}
+    }
+    canFdLen(base, fifo, slot) {
+        if (!this.chip.can.length) return 0;
+        try { return this._bindings.can_fd_len(base >>> 0, fifo >>> 0, slot >>> 0) >>> 0; }
+        catch { return 0; }
+    }
+    canFdByte(base, fifo, slot, idx) {
+        if (!this.chip.can.length) return 0;
+        try { return this._bindings.can_fd_byte(base >>> 0, fifo >>> 0, slot >>> 0, idx >>> 0) & 0xFF; }
+        catch { return 0; }
+    }
+    canFdCost(base, fd, brs, payloadBytes) {
+        if (!this.chip.can.length) return 0n;
+        try { return BigInt(this._bindings.can_fd_cost(base >>> 0, !!fd, !!brs, payloadBytes >>> 0)); }
+        catch { return 0n; }
+    }
+    i2cPec(base) {
+        try { return this._bindings.i2c_pec(base >>> 0) & 0xFF; } catch { return 0; }
+    }
+    spiFlashDebug(peripheral) {
+        try { return Array.from(this._bindings.spi_flash_debug(peripheral)); }
+        catch { return []; }
+    }
+    sdioCardIrq(set) { try { this._bindings.sdio_card_irq(!!set); } catch {} }
+    rtcTamper() { try { this._bindings.rtc_tamper(); } catch {} }
+    audioLoadWav(bytes) { try { this._bindings.audio_load_wav(new Uint8Array(bytes)); } catch {} }
+    ltdcClutEntry(layer, idx) {
+        if (!this.chip.ltdc) return 0;
+        try { return this._bindings.ltdc_clut_entry(layer >>> 0, idx >>> 0) >>> 0; }
+        catch { return 0; }
+    }
+    ltdcLutPixel(layer, pf, byte) {
+        // NOTE: the model resolves through the CLUT with a black default —
+        // unprogrammed entries read 0xFF000000 (opaque black), NOT 0.
+        if (!this.chip.ltdc) return 0;
+        try { return this._bindings.ltdc_lut_pixel(layer >>> 0, pf >>> 0, byte & 0xFF) >>> 0; }
+        catch { return 0; }
+    }
 
     // ── engine access ──
     read32(addr) { return this._emu.read32(addr); }

package/site/ws-bridge.mjs

@@ -52,9 +52,11 @@ import { WebSocketServer } from 'ws';
 import * as bindings from './vendor/stm32_periph_wasm.js';
 import { createEmulator } from './emulator.js';
 import { parseIntelHex, parseElf } from './loaders.js';
+import { CHIPS, chipInfo } from './stm32f4.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const svdXml = readFileSync(resolve(__dirname, 'vendor/stm32f407.svd'), 'utf8');
+const svdCache = {};
+const svdFor = (f) => svdCache[f] || (svdCache[f] = readFileSync(resolve(__dirname, 'vendor/' + f), 'utf8'));
 const wasmBytes = new Uint8Array(readFileSync(resolve(__dirname, 'vendor/stm32_periph_wasm_bg.wasm')));
 
 // ── CLI args ────────────────────────────────────────────────────────────────
@@ -63,13 +65,20 @@ let port = 8234;
 let firmwarePath = null;
 let lowpower = false;
 let maxInst = 0; // 0 = run until client stops
+let chipKey = 'stm32f407';
 for (let i = 0; i < args.length; i++) {
     if (args[i] === '--port') port = Number(args[++i]) || 8234;
     else if (args[i] === '--firmware' || args[i] === '-f') firmwarePath = args[++i];
     else if (args[i] === '--lowpower' || args[i] === '-l') lowpower = true;
     else if (args[i] === '--inst' || args[i] === '-n') maxInst = Number(args[++i]) || 0;
+    else if (args[i] === '--chip' || args[i] === '-c') {
+        chipKey = String(args[++i] || '').toLowerCase();
+        if (!CHIPS[chipKey]) { console.error(`invalid --chip: ${args[i]} (have: ${Object.keys(CHIPS).join(', ')})`); process.exit(2); }
+    }
     else if (!firmwarePath && !args[i].startsWith('-')) firmwarePath = args[i];
 }
+const chip = chipInfo(chipKey);
+const svdXml = svdFor(chip.svd);
 
 // ── firmware loading helpers ────────────────────────────────────────────────
 function detectFormat(buf) {
@@ -194,7 +203,9 @@ async function handleConnection(ws) {
         try {
             const { firmware, extra_mem } = loadFirmware(firmwarePath);
             emu = await createEmulator({
-                firmware, bindings, svdXml, wasmInit: wasmBytes,
+                firmware, bindings, svdXml, svdFile: chip.svd, wasmInit: wasmBytes,
+                flash_size: chip.flash_size, ram_size: chip.ram_size,
+                chipHint: chip.svd.replace(/\.svd$/, ''),
                 extra_mem, lowpower,
                 onTx: (pkt) => {
                     if (ws.readyState !== 1) return;
@@ -339,7 +350,9 @@ async function handleConnection(ws) {
                     try {
                         emu = await createEmulator({
                             firmware: new Uint8Array(flash), bindings,
-                            svdXml, wasmInit: wasmBytes, lowpower,
+                            svdXml, svdFile: chip.svd, wasmInit: wasmBytes,
+                            flash_size: chip.flash_size, ram_size: chip.ram_size,
+                            chipHint: chip.svd.replace(/\.svd$/, ''), lowpower,
                             onTx: (pkt) => {
                                 if (ws.readyState !== 1) return;
                                 const msg = new Uint8Array(5 + pkt.length);