stm32f4-emu 1.1.1 → 1.2.1

package/README.md

@@ -6,6 +6,14 @@
 [![CI](https://github.com/danish9661/stm32F4-emulator/actions/workflows/ci.yml/badge.svg)](https://github.com/danish9661/stm32F4-emulator/actions/workflows/ci.yml)
 [![Pages](https://github.com/danish9661/stm32F4-emulator/actions/workflows/pages.yml/badge.svg)](https://github.com/danish9661/stm32F4-emulator/actions/workflows/pages.yml)
 
+> **Status: emulation complete.** All 41 peripheral modules are Detailed
+> (0 Partial), all five board maps verify green (37/37/72/73/59 presets),
+> and the Ethernet descriptor layer (EDFE, TCH/TER + RCH/RER walks, RDES4,
+> backoff probe) plus the Wireshark-validated pcap capture (`a1b2c3d4`,
+> tcpdump-verified DHCP→TCP→HTTP) are in. What remains is product work,
+> not emulation: npm publish, https gateway endpoint, VS Code packaging
+> (see [docs/progress-and-future.md](docs/progress-and-future.md)).
+
 An STM32F407 microcontroller emulator that runs real Cortex-M4 firmware. It
 combines a **Rust CPU core** (a WASM-native Thumb-2 interpreter with exact
 Cortex-M exception entry/return, including the VFPv4-SP FPU) with a
@@ -15,7 +23,12 @@ browser tab**, with no SDL, no native deps, no hardware.
 
 It ships three real networking firmwares (`eth_http`, `eth_dhcp`, `eth_test`)
 that do DHCP + TCP + HTTP against a simulated (or a real gVisor-backed)
-network, a browser demo, and a publishable npm package.
+network, a 66-marker Ethernet feature matrix (`eth_feat_test`: PHY/MDIO,
+checksum offload, hash/perfect/SA/DA filtering, VLAN, PTP, WOL, wire
+pacing, deferral/collisions, pause frames, MMC, RBUS — see
+[NETWORKING.md](NETWORKING.md)) plus real LwIP 2.2.1 (`lwip_demo`) and
+MII/RMII pin mirrors (`eth_pins_test`), a browser demo, and a publishable
+npm package.
 
 ## Live demo
 
@@ -24,7 +37,7 @@ The browser demo deploys to GitHub Pages:
 **https://danish9661.github.io/stm32F4-emulator/**
 
 A single console page that starts **idle** — nothing runs until you pick a
-firmware: a preset dropdown with 31 bundled binaries (network demos, a
+firmware: a preset dropdown with 223 bundled binaries (network demos, a
 bare-metal LED blinker, peripheral/crypto/UART/SPI test binaries), custom
 firmware upload (`.bin`, Intel `.hex`, `.elf` — with loadable RAM segments
 and symbols — plus `.map` for a symbol table), Run/Stop/Reset, a **gateway
@@ -35,7 +48,7 @@ characters excluded per HTML spec, see AGENTS.md §11), GPIO pin readout
 for banks A–E, and key peripheral registers. Interrupt-driven firmware
 (`rx_interrupt_test`, `rx_crypto_test`) gets inline guest-IRQ delivery;
 polling firmware (the ETH demos) never uses it. For automation, a
-preset can auto-boot via the URL: `?fw=eth_http`, `?fw=blinky`, `?fw=crypto_test`, …
+preset can auto-boot via the URL: `console.html?fw=eth_http`, `console.html?fw=blinky`, `console.html?fw=crypto_test`, …
 
 ## DOOM (in the browser)
 
@@ -60,7 +73,7 @@ reloads.
 - Controls: move W/S/A/D + arrows · strafe Shift · fire Ctrl · use
   Space · menu Enter/Esc · save F2/F6 · load F3/F9 · F1/F10/F11/F12.
 - Boot → menu → gameplay verified end-to-end by
-  `node site/test_doom.mjs` (boot markers, menu navigation to E1M1,
+  `node site/test_doom_wasm.mjs` (boot markers, menu navigation to E1M1,
   palette + framebuffer, W-move + turn, audio, **save → `SAVE ok slot=0`
   → load handshake**).
 - `site/doom1.wad` is the 4.2 MB shareware WAD; the firmware never reads
@@ -78,7 +91,7 @@ npm test                       # == node site/test_flow.mjs
 
 # websocket bridge: headless Node serves the emulator, browser is a thin UI
 npm run bridge -- blinky/blinky.bin --port 8234
-# then open http://127.0.0.1:8123?bridge=ws://127.0.0.1:8234
+# then open http://127.0.0.1:8123/console.html?bridge=ws://127.0.0.1:8234
 
 # gateway-backed run: firmware talks to a REAL network stack (gVisor)
 cd stm32-periph-wasm/pkg
@@ -145,14 +158,14 @@ is a thin UI. Zero impact on the existing local WASM path:
 node site/ws-bridge.mjs eth_http/eth_http.bin --port 8234
 
 # 2. Open the browser console with the bridge URL param
-open "http://127.0.0.1:8123/?bridge=ws://127.0.0.1:8234"
+open "http://127.0.0.1:8123/console.html?bridge=ws://127.0.0.1:8234"
 ```
 
 The `RemoteEmu` adapter (`site/remote-emu.js`) is a drop-in replacement
 for the local `emu` object — same `step()`/`drainUart()`/`read32()` API,
 all proxied over binary WebSocket. Device stubs (OLED/TFT/etc.) run in
 Node and are not visible to browser JS. Without `?fw=`, the page boots
-whatever firmware the bridge was started with; with `?fw=blinky&bridge=ws://…`,
+whatever firmware the bridge was started with; with `console.html?fw=blinky&bridge=ws://…`,
 the browser sends the firmware image over the bridge.
 
 See AGENTS.md §20 for the full binary protocol reference.
@@ -164,8 +177,11 @@ See AGENTS.md §20 for the full binary protocol reference.
 | `eth_http/` | DHCP + TCP client + HTTP GET + prints the response | `TCP connected`, `=== HTTP <len>b ===` |
 | `eth_dhcp/` | Loops DHCP Discover/Offer/Request/Ack | `DHCP SUCCESS` |
 | `eth_test/` | Raw ETH TX/RX self-test | `ETH Test: done` |
+| `eth_feat_test/` | 66-marker Ethernet feature matrix (netsim, F407 + F429) | `FEAT Test: done` (all 66 markers, `FAIL`/`TIMEOUT` anti-markers) |
+| `lwip_demo/` | Real LwIP 2.2.1 (DHCP→DNS→TCP echo→TCP server→UDP echo) | `LWIP DEMO DONE` |
+| `eth_pins_test/` | MII/RMII pin-level mirrors (TX_EN/CRS_DV/RXD/COL/MDIO/MDC) | `PINS ALL PASS` |
 | `blinky/` | **No ethernet** — LED blinker on GPIOA PA5 + UART tick counter | `tick N LED=ON/OFF` |
-| `doom/` | **DOOM 1 shareware** (doomgeneric F407 port, browser page `site/doom.html`) | `node site/test_doom.mjs` (boot + menu + gameplay + save/load) |
+| `doom/` | **DOOM 1 shareware** (doomgeneric F407 port, browser page `site/doom.html`) | `node site/test_doom_wasm.mjs` (boot + menu + gameplay + save/load) |
 
 Plus 17 more test binaries (`crypto_test`, `hal_test`, `timer_test`,
 `periph_test`, `echo_test`, `blink_serial`, `rx_interrupt_test`,
@@ -199,9 +215,12 @@ firmware .bin ──► Rust WASM CPU (Thumb-2 + NVIC/exceptions)
   exception stacking — no native deps, no JIT, no hooks.
 - **Peripherals**: a `wasm-bindgen` crate (`stm32-periph-wasm/`); registers
   and bit fields come from the vendor SVD (`monox/stm32f407.svd`).
-- **Ethernet**: TX is captured from the DMA descriptors; RX frames are
-  injected into the RX ring and the firmware's `eth_irq_flag` (SRAM) drives
-  polling — no interrupts required. Optionally, a Go gateway
+- **Ethernet**: TX is captured from the DMA descriptors (OWN/FS/LS poll
+  demand); RX frames are delivered head-only with FS+LS status, IPHCE/PCE
+  checksum status, and PTP snapshots for event messages. The full MAC
+  register map is cross-checked against CMSIS `stm32f407xx.h` (DMASR/
+  DMAIER/MACFFR/MACPMTCTL positions — see [NETWORKING.md](NETWORKING.md)
+  §6 for the audit). Optionally, a Go gateway
   (`openhw-local-gateway/`) with a gVisor network stack makes the firmware
   talk to a real network: `node cli.mjs <fw.bin> <inst> --gateway`.
 - **Browser build** (`site/`): same modules as ESM; `site/emulator.js` is an
@@ -259,7 +278,10 @@ rebuild — delete it so the vendor assets stay tracked/committed.
 
 ## Testing
 
-- `npm test` — flow test (`site/test_flow.mjs`) + blinky test
+- `npm test` — flow test (`site/test_flow.mjs`) + Ethernet mock harnesses
+  (`site/test_eth_mock_model.mjs`: 18 checks, fake bindings + real driver;
+  `site/test_eth_mock_consumer.mjs`: 44 checks, fake firmware + real model)
+  + blinky test
   (`site/test_blinky.mjs`) + interrupt-UART test (`site/test_rx_interrupt.mjs`)
   + component-API tests (`site/test_component_{led,button,pwm,i2cregfile}.mjs`,
   each against real firmware — LED/blinky, Button/exti_test, Pwm/buzzer_test,
@@ -269,7 +291,7 @@ rebuild — delete it so the vendor assets stay tracked/committed.
   process (see docs/components.md). The same suite runs in CI on
   `ubuntu-latest`/`windows-latest`/`macos-latest`
   ([.github/workflows/ci.yml](.github/workflows/ci.yml)) on every push.
-- `node site/test_doom.mjs` — DOOM boot → menu → E1M1 gameplay + save/load
+- `node site/test_doom_wasm.mjs` — DOOM boot → menu → E1M1 gameplay + save/load
   (see the DOOM section above).
 - `scripts/verify_ethernet.sh [max_inst]` — runs all three firmwares through
   the gateway, asserts the success markers and 0 `TCP fail`.
@@ -281,7 +303,7 @@ rebuild — delete it so the vendor assets stay tracked/committed.
 - [site/about.html](site/about.html) — in-repo About page: what it is, architecture, featured firmwares, and how to use it (CLI / browser / Node API / MCP).
 - [docs/architecture.md](docs/architecture.md) — how the emulator is put
   together (CPU, peripheral model, drivers, ETH flow, interrupts).
-- [docs/peripherals.md](docs/peripherals.md) — all 33 peripherals and the
+- [docs/peripherals.md](docs/peripherals.md) — all 41 peripherals and the
   level each is implemented to, plus external devices and known gaps.
 - [docs/usage.md](docs/usage.md) — CLI, browser, and npm-library usage,
   config files, env vars, building.

package/index.d.ts

@@ -46,3 +46,10 @@ export class Potentiometer {
 export class I2cRegisterDevice {
   constructor(emu: any, peripheral: string, opts?: any);
 }
+
+// Board LED map + host reset/boot control (see site/boards.js,
+// site/emulator.js, site/stm32f4.js).
+export interface BoardLed { bank: number; pin: number; label: string; }
+export declare const BOARD_LED: Record<string, BoardLed>;
+export declare const BOARD_LED_ALIASES: Record<string, BoardLed>;
+export declare function boardLed(fwName: string, boardKey: string): BoardLed;

package/index.mjs

@@ -40,3 +40,4 @@ export async function createSTM32F407(opts = {}) {
 }
 
 export { createEmulator, createNetSim, FIRMWARES, bindings, svdXml, LED, Button, Pwm, I2cRegisterDevice, Potentiometer, STM32F4, GPIOPin, USART, DMAStream };
+export { boardLed, BOARD_LED, BOARD_LED_ALIASES } from './site/boards.js';

package/mcp/server.mjs

@@ -252,4 +252,27 @@ server.registerTool('reset', {
     return text(`closed session (${was})`);
 });
 
+server.registerTool('reset_cpu', {
+    description: 'Host reset button: CPU back to the vector-table SP/PC, peripherals keep state (like a real NRST pulse without the hold). Prefer over load_firmware when re-running the same image.',
+    inputSchema: {},
+}, async () => {
+    const { emu } = requireSession();
+    if (typeof emu.resetCpu === 'function') emu.resetCpu();
+    else emu.reset();
+    return text('cpu reset to vector table');
+});
+
+server.registerTool('set_nrst', {
+    description: 'Hold (assert=true) or release the NRST line. While held, step() only advances the model clock — the CPU executes nothing, like real hardware in reset. Query with level omitted.',
+    inputSchema: { level: z.boolean().optional().describe('true = assert (hold in reset), false = release; omit to query') },
+}, async ({ level }) => {
+    const { emu } = requireSession();
+    if (level === undefined) {
+        const s = typeof emu.isNrstAsserted === 'function' ? emu.isNrstAsserted() : false;
+        return text({ asserted: !!s });
+    }
+    const s = typeof emu.setNrst === 'function' ? emu.setNrst(level) : false;
+    return text({ asserted: !!s });
+});
+
 await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stm32f4-emu",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "STM32F407 emulator: Rust CPU + peripheral model (WASM). Runs real Cortex-M4 firmware in Node or the browser.",
   "type": "module",
   "main": "index.mjs",
@@ -31,6 +31,7 @@
     "site/emulator.js",
     "site/emulator.d.ts",
     "site/stm32f4.js",
+    "site/boards.js",
     "site/components.js",
     "site/netsim.js",
     "site/firmware.js",
@@ -39,6 +40,7 @@
     "site/ws-bridge.mjs",
     "site/app.js",
     "site/index.html",
+    "site/console.html",
     "site/vendor/",
     "mcp/server.mjs",
     "tools/make_firmware.mjs"
@@ -66,8 +68,8 @@
     "node": ">=20"
   },
   "scripts": {
-    "test": "node site/test_stm32f4_api.mjs && node site/test_stm32f4_periph.mjs && node site/test_ws_bridge.mjs && node site/test_flow.mjs && node site/test_blinky.mjs && node site/test_rx_interrupt.mjs && 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_multi_instance.mjs && node site/test_fsmc_dcmi.mjs && node site/test_fsmc.mjs && node site/test_dcmi.mjs && node site/probe_freertos.mjs   && node site/test_candemo.mjs && node site/test_lowpower.mjs   && node site/test_edge_cases.mjs && node site/test_can_inject.mjs   && node site/test_watchdog.mjs   && node site/test_wwdg.mjs   && node site/test_wwdg_window.mjs && node site/test_tim_capture.mjs && node site/test_qspi.mjs && node site/test_fpu.mjs && node site/test_fpu_irq.mjs && node site/test_mpu.mjs && node site/test_usb.mjs && node site/test_qspi_cdp.mjs && node site/test_browser.mjs",
-    "test:unit": "node site/test_stm32f4_api.mjs && node site/test_stm32f4_periph.mjs && node site/test_ws_bridge.mjs && node site/test_flow.mjs && node site/test_blinky.mjs && node site/test_rx_interrupt.mjs && 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_multi_instance.mjs && node site/test_fsmc_dcmi.mjs && node site/test_fsmc.mjs && node site/test_dcmi.mjs && node site/probe_freertos.mjs   && node site/test_candemo.mjs && node site/test_lowpower.mjs   && node site/test_edge_cases.mjs && node site/test_can_inject.mjs   && node site/test_watchdog.mjs   && node site/test_wwdg.mjs   && node site/test_wwdg_window.mjs && node site/test_tim_capture.mjs && node site/test_qspi.mjs",
+    "test": "node site/test_stm32f4_api.mjs && node site/test_stm32f4_periph.mjs && node site/test_ws_bridge.mjs && node site/test_flow.mjs && node site/test_eth_mock_model.mjs && node site/test_eth_mock_consumer.mjs && node site/test_periph_mock_consumer.mjs && node site/test_blinky.mjs && node site/test_blinky_f401.mjs && node site/test_blinky_f411.mjs && node site/test_blinky_f407g.mjs && node site/test_blinky_nucleo_f401.mjs && node site/test_blinky_nucleo_f411.mjs && node site/test_blinky_f429.mjs && node site/test_blinky_f407ve.mjs && node site/test_rx_interrupt.mjs && 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_multi_instance.mjs && node site/test_fsmc_dcmi.mjs && node site/test_fsmc.mjs && node site/test_dcmi.mjs && node site/probe_freertos.mjs   && node site/test_candemo.mjs && node site/test_lowpower.mjs   && node site/test_edge_cases.mjs && node site/test_can_inject.mjs   && node site/test_watchdog.mjs   && node site/test_wwdg.mjs   && node site/test_wwdg_window.mjs && node site/test_tim_capture.mjs && node site/test_qspi.mjs && node site/test_fpu.mjs && node site/test_fpu_irq.mjs && node site/test_mpu.mjs && node site/test_usb.mjs && node site/test_arduino_boards.mjs && node site/test_exti.mjs && node site/test_flash.mjs && node site/test_spi_flash.mjs && node site/test_board_matrix.mjs && node site/test_qspi_cdp.mjs && node site/test_browser.mjs",
+    "test:unit": "node site/test_stm32f4_api.mjs && node site/test_stm32f4_periph.mjs && node site/test_ws_bridge.mjs && node site/test_flow.mjs && node site/test_blinky.mjs && node site/test_blinky_f401.mjs && node site/test_blinky_f411.mjs && node site/test_blinky_f407g.mjs && node site/test_blinky_nucleo_f401.mjs && node site/test_blinky_nucleo_f411.mjs && node site/test_blinky_f429.mjs && node site/test_blinky_f407ve.mjs && node site/test_rx_interrupt.mjs && 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_multi_instance.mjs && node site/test_fsmc_dcmi.mjs && node site/test_fsmc.mjs && node site/test_dcmi.mjs && node site/probe_freertos.mjs   && node site/test_candemo.mjs && node site/test_lowpower.mjs   && node site/test_edge_cases.mjs && node site/test_can_inject.mjs   && node site/test_watchdog.mjs   && node site/test_wwdg.mjs   && node site/test_wwdg_window.mjs && node site/test_tim_capture.mjs && node site/test_qspi.mjs",
     "test:bridge": "node site/test_ws_bridge.mjs",
     "test:bridge:browser": "node site/test_bridge_cdp.mjs",
     "test:flow": "node site/test_flow.mjs",
@@ -81,7 +83,9 @@
     "test:wwdgwin": "node site/test_wwdg_window.mjs",
     "test:timcap": "node site/test_tim_capture.mjs",
     "test:lowpower": "node site/test_lowpower.mjs",
+    "test:standby": "node site/test_standby.mjs",
     "test:qspi": "node site/test_qspi.mjs",
+    "test:eth:mock": "node site/test_eth_mock_model.mjs && node site/test_eth_mock_consumer.mjs && node site/test_periph_mock_consumer.mjs",
     "test:fpu": "node site/test_fpu.mjs",
     "test:fpuirq": "node site/test_fpu_irq.mjs",
     "test:mpu": "node site/test_mpu.mjs",