125 lines
6.9 KiB
Markdown
125 lines
6.9 KiB
Markdown
# test_intel — Retro Intel + Z80 emulation via velxio custom chips
|
||
|
||
Goal: emulate the Intel 4004, 4040, 8080, 8086 and Zilog Z80 as **velxio
|
||
custom chips** (C compiled to WASM, loaded by the existing
|
||
`ChipRuntime`). Each CPU becomes a single drag-and-drop chip whose pins
|
||
match the real silicon, so users can wire them to ROM, RAM, UART, etc.,
|
||
on the velxio canvas.
|
||
|
||
## Folder layout
|
||
|
||
```
|
||
test_intel/
|
||
├── 00_README.md ← this file (plan + viability matrix)
|
||
├── package.json ← vitest harness
|
||
├── vitest.config.js
|
||
├── autosearch/ ← all research notes (specs, refs, strategy)
|
||
├── scripts/ ← compile-chip.sh + compile-all.sh
|
||
├── src/ ← BoardHarness, helpers, ISA opcode tables
|
||
├── fixtures/ ← compiled .wasm output (gitignored)
|
||
├── test_buses/ ← reusable ROM / RAM chips
|
||
│ ├── README.md
|
||
│ ├── rom-32k.test.js
|
||
│ └── ram-64k.test.js
|
||
├── test_4004/ ← per-chip work (README → tests → .c → sketch)
|
||
├── test_4040/
|
||
├── test_8080/
|
||
├── test_8086/
|
||
└── test_z80/
|
||
```
|
||
|
||
The structure mirrors the existing `test/test_custom_chips/` and
|
||
`test/autosearch/` conventions already used in the repo.
|
||
|
||
## How to run the tests
|
||
|
||
```bash
|
||
cd test/test_intel
|
||
npm install # one-time: vitest only
|
||
npm test # all tests skip until chips are compiled
|
||
npm run compile:all # builds any .c found under test_*/ (needs WASI-SDK)
|
||
npm test # tests for compiled chips now actually run
|
||
```
|
||
|
||
The `it.skipIf(!chipWasmExists(...))` pattern means TDD lives the
|
||
expected lifecycle: **red** = tests skip with the chip absent;
|
||
**green** = tests pass once the chip is implemented and compiled.
|
||
|
||
## Decisions locked in (for posterity)
|
||
|
||
These are the architectural calls already made — see `autosearch/`
|
||
for the reasoning trail.
|
||
|
||
| Decision | Choice | Rationale |
|
||
| --- | --- | --- |
|
||
| Implementation source | **Clean-room from datasheets** | ISA is not copyrightable; implementation is. Avoids GPL contamination, no third-party drift. |
|
||
| Validation | Public-domain test ROMs (CPUDIAG, ZEXDOC) when CPU works | Same standard as MAME, zexall, etc. |
|
||
| Vendoring | **None** | We are not pulling any third-party emulator code into the repo. |
|
||
| Bus-device strategy | Separate `rom-32k` and `ram-64k` C chips | Faithful to real PCBs; reusable across all 5 CPUs. |
|
||
| Unit-test memory | `BoardHarness.installFakeRom()` / `installFakeRam()` (JS) | No per-test recompile; tests stay fast and flexible. |
|
||
| ROM-image loading | Baked into C source per ROM variant | SDK has no blob attribute today; one variant per demo. |
|
||
| Power simplification | Collapse multi-rail packages to `VCC`/`GND` | Velxio is digital; multi-rail is not modelled. |
|
||
| Implementation order | 8080 → Z80 → 4004 → 4040 → 8086 | 8080 = cleanest bus; 8086 = most complex. |
|
||
|
||
## Viability summary (TL;DR)
|
||
|
||
The custom-chip runtime in `frontend/src/simulation/customChips/` and the
|
||
SDK in `backend/sdk/velxio-chip.h` give us:
|
||
|
||
- C source compiled to WASM (clang + WASI-SDK).
|
||
- Up to **1 MB linear memory per chip instance** (16 × 64 KB pages).
|
||
- Arbitrary number of named GPIO pins via `vx_pin_register`.
|
||
- Pin watches with edge detection, plus `vx_timer_*` for cycle/clock
|
||
pacing in nanoseconds.
|
||
- I²C / SPI / UART helpers (not used here — CPUs use raw bus pins).
|
||
|
||
That is enough to host an instruction-level emulator for every chip on
|
||
the list. The hard part is **bus modelling**, not CPU semantics.
|
||
|
||
| Chip | Pins | Bus model | Internal RAM/regs needed | Verdict |
|
||
| ----- | ---- | -------------------------------- | ------------------------ | ------- |
|
||
| 4004 | 16 | 4-bit data muxed with 12-bit addr| ~64 B | ✅ Viable, easiest |
|
||
| 4040 | 24 | Superset of 4004 + interrupts | ~96 B | ✅ Viable |
|
||
| 8080 | 40 | Separate A0-A15 + D0-D7 | ~32 B regs + flags | ✅ Viable, cleanest model |
|
||
| Z80 | 40 | 8080-compatible + M1/MREQ/IORQ/RFSH | ~64 B regs (incl. shadow set, IX/IY) | ✅ Viable, well-documented MIT emulators exist |
|
||
| 8086 | 40 | 16-bit data muxed with 20-bit addr (min/max modes) | ~80 B regs + segment regs | ⚠️ Viable but most complex (multiplexed AD bus, prefetch queue, segment math) |
|
||
|
||
No CPU on this list needs more than ~100 B of register state, so even
|
||
emulating a few hundred instructions worth of internal cache fits
|
||
comfortably in the default 128 KB initial WASM memory.
|
||
|
||
**Bus reality:** the runtime does not expose an "address-bus connector"
|
||
abstraction — chips talk only via pin events. That is exactly how the
|
||
real silicon works (the 8080 / Z80 / 8086 drive raw address and data
|
||
pins). It is **not** a blocker; it is the correct model. External RAM
|
||
and ROM are emulated as separate velxio chips wired to the CPU's
|
||
address and data pins, just like in a real PCB.
|
||
|
||
## What's not solved here yet
|
||
|
||
- Whether a velxio "external bus device" (RAM/ROM addressed by 16 pins
|
||
+ 8 data pins + control) already exists, or whether we need to write
|
||
one as part of this work. Tracked in `autosearch/05_open_questions.md`.
|
||
- Per-chip implementation (`<chip>.c`, `<chip>.chip.json`, demo sketch).
|
||
The per-chip READMEs lay out the pinout and bus contract; actual
|
||
emulator code is the next phase.
|
||
|
||
## Implementation status
|
||
|
||
| Folder | Tests | Code | Notes |
|
||
| ------------ | ----- | ----- | ----- |
|
||
| autosearch/ | n/a | n/a | ✅ Intel 4004/4040/8080 + Zilog Z80 manuals + EPROM/SRAM datasheets cited; PDFs under `pdfs/` |
|
||
| harness | ✅ | ✅ | `BoardHarness`, `helpers`, scripts/ — all working |
|
||
| **test_buses/**| ✅ 13 | ✅ | **🎯 13/13 passing**. `rom-32k.c` (~80 LOC) + `ram-64k.c` (~110 LOC, malloc'd to fit 128 KB initial WASM mem). |
|
||
| **test_4004/**| ✅ 11 | ✅ | **🎯 4 passing + 7 todo. ~150 LOC clean-room from Intel MCS-4 manual (Feb 1973).** Deferred: 46-instruction ISA, SRC/CMRAM strobing, I/O instructions. |
|
||
| **test_4040/**| ✅ 5 | ✅ | **🎯 2 passing + 3 todo. ~250 LOC clean-room from Intel MCS-40 manual (Nov 1974).** Deferred: full INT vectoring, BBS, 14 new opcodes' semantics. |
|
||
| **test_8080/**| ✅ 20 | ✅ | **🎯 18 passing + 2 todo (CPUDIAG integration). ~470 LOC clean-room from Intel 1975/1981 manuals.** |
|
||
| test_8086/ | ✅ 13 | 📋 | Reset to 0xFFFF0, ALE protocol, basic instructions todo |
|
||
| **test_z80/**| ✅ 13 | ✅ | **🎯 6 passing + 7 todo. ~550 LOC clean-room from Zilog UM008003 + Sean Young's "Undocumented Z80 Documented" v0.91.** Deferred: undocumented X/Y flags, MEMPTR, IM 2 vector, NMI exact, ZEXDOC integration. |
|
||
|
||
Total: **75 tests authored, 43 passing** (8080: 18, rom-32k: 6,
|
||
ram-64k: 7, z80: 6, 4004: 4, 4040: 2), 3 skipping (8086 chip not
|
||
compiled yet), 29 todo (deferred integration / extended-spec tests).
|
||
Zero failures. No velxio core source has been modified. Run `npm test`
|
||
from `test/test_intel/` to confirm.
|