# ngspice-split — the eeschema simulator as a lazy worker service

> Status: implemented (2026-07-17). The SPICE analog of the [occ split](../occ-split/):
> ngspice's sharedspice engine runs in a dedicated Web Worker module
> (`ngspice_service.wasm`, ~5.4 MB, `-O2`), the editor binds a statically linked
> RPC client, and Inspect → Simulator works with **full native parity** —
> XSPICE (all seven bundled code models), CIDER, the complete BSIM4/B3SOI/
> B4SOI/HSIM parameter tables, and real background-run semantics (`bg_halt`
> interrupts a running simulation).

## Why a worker service

- **No dlopen in wasm.** Native KiCad dlopens libngspice and resolves ~10
  symbols (`eeschema/sim/ngspice.cpp init_dll`). A static emscripten build has
  no dynamic linking, and the occ-split analysis rates MAIN_MODULE dynamic
  linking RED for the editor (wasm-EH + pthreads + asyncify).
- **Crash isolation.** KiCad's native crash recovery installs SIGSEGV/SIGABRT/
  SIGFPE handlers around the simulation thread — emscripten stubs these
  (emscripten#8567, wontfix). In-process, a hard ngspice fault kills the tab;
  in a worker, the provider fails in-flight requests, KiCad's `m_error` →
  `NGSPICE::validate()` path re-inits, and a **fresh worker** boots.
- **The editor stays lean.** kicad_editor.wasm carries zero ngspice; the 5.4 MB
  service is fetched on the first simulator open (lazy boundary asserted in
  e2e).
- **KiCad's usage is RPC-friendly.** It passes nullptr for the streaming
  SendData/SendInitData callbacks and pulls vectors after (or during) the run
  via `ngGet_Vec_Info`; only console/status text and run-state transitions
  stream mid-run.

## Architecture

```
kicad_editor (eeschema, ASYNCIFY=1)                ngspice_service (ASYNCIFY=0, pthreads)
┌────────────────────────────────────┐             ┌──────────────────────────────────┐
│ NGSPICE (upstream; ONE ifdef in    │ postMessage │ ngspice_service_main.cpp (embind)│
│  init_dll binds pcbjam_ngSpice_*)  │◄───────────►│ libngspice.a: sharedspice static,│
│ wasm/stubs/sharedspice_client.cpp: │             │  XSPICE static registry, CIDER   │
│  EM_ASYNC_JS request suspend,      │  {evt}      │ callbacks → MAIN_THREAD_ASYNC_   │
│  event dispatch (fresh entries),   │◄────────────│  EM_ASM → Module.ngspiceEmit     │
│  vec arena, .include shipper,      │             │ bg_run = real ngspice pthread;   │
│  atomic running mirror             │             │ main thread free → bg_halt works │
└────────────────────────────────────┘             └──────────────────────────────────┘
  provider: web/standalone/src/wasm/ngspice-service.ts (lazy blob worker)
  worker wrapper (shared app/tests): web/standalone/src/wasm/ngspice-worker.js
```

### Pieces

| Piece | Where |
|---|---|
| dep build (sharedspice static + code models) | `scripts/deps/build-ngspice.sh` (ngspice 46) |
| static code-model registry sources | `scripts/deps/ngspice-wasm/{ngcm_registry.c,ngcm_dlmain_static.c}` |
| Gate-1 node smoke (rc/xspice/cider/halt) | `scripts/deps/ngspice-wasm/smoke/` |
| service module | `wasm/ngspice-service/{CMakeLists.txt,ngspice_service_main.cpp}` |
| service build (standalone emcmake, NOT the kicad tree) | `scripts/kicad/build-ngspice_service.sh` |
| editor client stub | `wasm/stubs/sharedspice_client.cpp` + decls in `wasm/stubs/ngspice/sharedspice.h` |
| the single kicad-fork edit | `eeschema/sim/ngspice.cpp` `init_dll()` `#ifdef __EMSCRIPTEN__` block |
| model-data tables restored at `-O2` | `eeschema/CMakeLists.txt` EMSCRIPTEN block |
| app provider / bundle | `web/standalone/src/wasm/{ngspice-service.ts,ngspice-worker.js}`, `constants.ts`, `boot.ts` |
| e2e | `tests/kicad/{ngspice-probe,eeschema-sim}.spec.ts`, harness stub `tests/kicad/utils/ngspice-service.ts` |

## The ngspice dep build (`build-ngspice.sh`)

`--with-ngshared --disable-shared --enable-static` builds `libngspice.a` with
the sharedspice API and no CLI (upstream gates `bin_PROGRAMS` on
`!SHARED_MODULE`). Idempotent (marker-guarded) edits to the extracted tarball,
each load-bearing:

1. **libtool static-mode override.** ngspice hardwires libtool's `-shared`
   mode for the ngshared build (`STATIC=-shared` consumed as AM_CFLAGS
   everywhere, plus literal `-shared` in `libngspice_la_{CFLAGS,LDFLAGS}`);
   libtool hard-errors on `-shared` without shared-lib support. Fixed with
   `make STATIC=-static` (command line beats makefile) + a sed on the two
   generated `src/Makefile` lines.
2. **XSPICE code models without dlopen.** Natively each `.cm` is dlopen'd via
   `load_opus()` (`src/spicelib/devices/dev.c`). Statically: the icm build is
   redirected (env `NGCM_STATIC`/`NGCM_DLMAIN`) to compile per-cm renamed
   tables (`ngcm_<cm>_cmDEVices…`, `ngcm_dlmain_static.c`) and `emar` each
   model into a `.cm` archive; a registry appended to dev.c resolves the seven
   bundled basenames straight into `add_device`/`add_udn`, falling through to
   dlopen (→ ngspice's normal error) for unknown paths. dlmain.c's coreitf
   wrapper section is deliberately dropped (it would shadow real core symbols
   with calls through a never-initialized coreitf); its utility tail
   (`fopen_with_path`, `cm_message_printf`, `cm_is_inertial`) is extracted at
   build time into `ngcm_common.a`, with `cm_getvar` bound directly to the
   core's `cp_getvar` (the dllitf mapping, `cmexport.c`).
3. **cmpp runs on the build host** — automatic in ngspice 46 when
   `cross_compiling=yes` (`src/xspice/cmpp/build/`), BUT the icm makefile's
   `$(shell cmpp -p …)` model-list calls hardcode the CROSS-compiled cmpp:
   patched to `$(CMPP)`. Symptom of the unpatched bug: `.cm` archives quietly
   containing only `dlmain.o` ("Permission denied" from the wasm binary).
4. **verilog/vhdl subdirs skipped** (generated `src/xspice/Makefile` sed):
   ivlng/ivlngvpi VPI co-simulation shims are inherently shared objects
   plugging into an external Icarus/GHDL process — impossible in wasm; the
   d_cosim model fails at runtime exactly like a native install without a
   cosimulator.
5. **Upstream 32-bit bug fixed (TODO: upstream).** CIDER card parsing frees
   through `dataType & IF_REALVEC` — a composite mask (0x8004) that also
   matches scalar `IF_SET|IF_REAL` (0x2004) parameters and then frees the
   vec-pointer union member overlaying the parsed scalar double. On 64-bit
   the misread lands in zero padding (free(NULL)); on wasm32 the pointer
   member overlays the HIGH half of the double → heap fault on e.g.
   `.model … numd … defa=1p`. Patched to exact `IF_VARTYPES` tests.
6. `/proc/meminfo` header check forced off (`ac_cv_header__proc_meminfo=no`):
   configure runs on a Linux build host, the browser has no procfs, and
   ngspice treats "0 bytes available" as OOM.
7. `-pthread` everywhere: without `HAVE_LIBPTHREAD`, `bg_run` silently
   degrades to a synchronous blocking call (sharedspice.c `runc()`).
8. spinit installs to the sysroot and is `--embed-file`'d into the service at
   `/ngspice/scripts/spinit`; `main()` sets `SPICE_LIB_DIR=/ngspice` so
   ngspice's env-first search finds it regardless of the baked build prefix.
   Its `codemodel <prefix>/<cm>.cm` lines resolve by basename in the registry.

Gate 1 (`scripts/deps/ngspice-wasm/smoke/run-smoke.sh`, node): static link,
RC transient numerics, XSPICE gain block through the registry, CIDER numd DC
sweep, and bg_run → mid-run bg_halt → BGThreadRunning(finished). **The
emscripten default 64 KB stack overflows in ngspice's parser** — the smoke
and the service both run `-sSTACK_SIZE=4MB -sDEFAULT_PTHREAD_STACK_SIZE=2MB`
(the unchecked overflow corrupts the heap and detonates later as free()
faults; found via `-sSAFE_HEAP=1`).

## The service module

Pure libngspice + a ~350-line embind shim — **no KiCad/wx code**, so it
builds standalone with emcmake (`build-ngspice_service.sh`, seconds, no
docker) rather than through the kicad CMake tree like occ_service; the
artifact lands in the standard `build-wasm/kicad-ngspice_service/ngspice_service/`
layout so docker copy / test staging / publish treat it like any app.

- RPC surface mirrors sharedspice 1:1: `init/circ/command/getVecInfo/curPlot/
  allPlots/allVecs/running/cmInputPath`.
- **Events**: callbacks fire on ngspice's bg pthread → `strdup` +
  `MAIN_THREAD_ASYNC_EM_ASM` → `Module.ngspiceEmit` (per-target FIFO keeps
  order; the service main thread is idle during a run so it drains promptly);
  the worker wrapper batches char/stat lines per microtask into one `{evt}`
  postMessage (flood guard) and flushes the batch before bg/exit events.
- **bg_halt works mid-run** because the simulation occupies its own pthread —
  the module main thread stays free to service the halt RPC. Never shrink the
  pthread pool (occ lesson: a blocked browser thread cannot spawn workers).
- **Vector reads are copied under `ngSpice_LockRealloc`** inside the service —
  this replaces KiCad's client-side RAII lock (a no-op across RPC; the ifdef
  leaves `m_ngSpice_LockRealloc` null) and makes the UI's mid-run plot
  refresh safe against the growing tran vectors.
- getVecInfo returns heap views; the worker wrapper copies them into fresh
  arrays before postMessage (**a SAB-backed view cannot be transferred**).

## The editor side

- `NGSPICE::init_dll()` gets one `#ifdef __EMSCRIPTEN__` block binding the
  `m_ngSpice_*` pointers to `pcbjam_ngSpice_*` (prefix required: the class-
  scope typedef names would shadow same-named globals inside the member),
  plus a second `#ifndef __EMSCRIPTEN__` guard skipping the client-side
  spinit/codemodel staging. That staging is NOT harmless in wasm: its
  `wxSetWorkingDirectory( exe dir )` always fails in MEMFS (error 44), the
  queued wxLogError then flushes as a MODAL dialog over the freshly opened
  simulator frame, and the modal event pump dies with an asyncify-corruption
  signature ("index out of bounds" / "indirect call to null" — the known
  nested-modal-inside-doRewind limitation documented in
  wxwidgets/src/wasm/dialog.cpp; the pump's cancel-recovery keeps the app
  alive, but the corruption gate in eeschema-sim.spec.ts rightly fails). The
  service embeds its own spinit + code models, so the staging has nothing to
  do here anyway. Still the ONLY kicad-fork source file touched.
- `wasm/stubs/sharedspice_client.cpp`: EM_ASYNC_JS request bridge (suspends
  the editor; `__asyncjs__*` is pre-covered by asyncify-imports.txt — do NOT
  add any of this path to the removelist), a dedicated get_vec bridge that
  mallocs vector doubles straight into the editor heap, a per-call
  `vector_info` arena (every NGSPICE consumer copies within the same call),
  an atomic `ngSpice_running` mirror (the UI polls on a timer; zero RPC per
  poll), and the **`.include`/`.lib` shipper**: `NETLIST_EXPORTER_SPICE`
  emits absolute `.include` paths (Sim.Library models, the IBIS cache) that
  ngspice must open in ITS filesystem — the stub scans the deck recursively
  (depth ≤ 4), reads the files from editor MEMFS and ships `{path,text}`
  pairs for the service to stage at identical paths.
- **Events into a suspended editor**: the provider hands `{evt}` frames to
  `globalThis.__ngspiceOnEvent` (installed by the stub at first init), which
  calls the exported `pcbjam_ngspice_event` — a fresh wasm entry from JS,
  the same mechanism every wx-dom DOM event uses while the main loop is
  asyncify-suspended. KiCad's callbacks only take a mutex + `wxQueueEvent`,
  so nothing on the path can suspend.
- The four giant model-data files (bsim4/b3soi/b4soi/hsim) are restored with
  per-source `-O2` (the "too many locals" limit was an -O0 artifact; same
  workaround as the msys block in eeschema/CMakeLists.txt) — full parameter
  tables in the model dialogs.

## Traps (learned the hard way)

- **`MIF*/` inside a C block comment terminates it** — the registry's early
  drafts broke the build with prose. (clangd flagged it; the diagnostics were
  right.)
- The dev.c registry hook must be inserted BEFORE the registry body is
  appended, and its idempotency guard must match the CALL (`ngcm_static_load(name)`),
  not the name — the appended definition otherwise masks the hook forever.
- ngspice's `BGThreadRunning` callback argument is *"not running"* (true =
  finished) — KiCad treats it as `aFinished`; keep the polarity.
- The `running` mirror flips true at `bg_run` ACCEPTANCE (not at the bg
  'started' event) so an immediate `IsRunning()` poll already sees it.
- Emscripten's `HEAPF64.set` after `_malloc` inside EM_ASYNC_JS is safe under
  memory growth (the views are refreshed), but always re-read the global
  after allocating.
- sharedspice error recovery longjmps (`errbufm`/`errbufc`) — fine under the
  tree-wide wasm-SjLj model and an ASYNCIFY=0 module; never let it meet an
  asyncify-instrumented stack.

## Known limitations (parity-consistent)

- User-compiled `.cm` code models and `.osdi` (OpenVAF) binaries cannot load —
  wasm can't dlopen user binaries. ngspice reports them with its native error
  text. (Native parity minus the ability to install binary plugins.)
- Verilog/GHDL co-simulation (`d_cosim`) needs an external simulator process —
  same failure text as a native install without Icarus.
- OpenMP is off (unsupported in emscripten) — BSIM model evaluation runs
  single-threaded per timestep; the simulation itself still runs on its own
  background thread.