velxio/test/test_intel/00_README.md

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

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/8086 + Zilog Z80 manuals + 27C256/HM62256/8282 datasheets cited; PDFs under pdfs/
harness	✅	✅	BoardHarness, helpers, scripts/ — all working
test_buses/	✅ 17	✅	🎯 17/17 passing. rom-32k.c (~80 LOC) + ram-64k.c (~110 LOC) + latch-8282.c (~80 LOC).
test_4004/	✅ 12	✅	🎯 9 passing + 3 todo. ~470 LOC clean-room from Intel MCS-4 manual (Feb 1973). Full 46-instruction ISA implemented. Deferred: LDM/FIM/Busicom integration tests (need fake 4002 RAM for ACC observability).
test_4040/	✅ 5	✅	🎯 5/5 passing. ~500 LOC clean-room from Intel MCS-40 manual (Nov 1974). All 14 new opcodes + INT vectoring + BBS + bank-aware register file.
test_8080/	✅ 20	✅	🎯 18 passing + 2 todo (CPUDIAG integration). ~470 LOC clean-room from Intel 1975/1981 manuals.
test_8086/	✅ 13	✅	🎯 3 passing + 10 todo. ~750 LOC clean-room from Intel iAPX 86,88 User's Manual (Oct 1979). Bus protocol + reset to 0xFFFF0 + ModR/M decode + ~50 opcodes (MOV/ALU/Jcc/CALL/RET/LOOP/etc.). Deferred: string ops, MUL/DIV, BCD, port I/O, interrupts.
test_z80/	✅ 13	✅	🎯 11 passing + 2 todo (IM 2 vectoring, ZEXDOC). ~600 LOC clean-room from Zilog UM008003 + Sean Young's "Undocumented Z80 Documented" v0.91. Full bus + ISA + INT + NMI + LDIR + IX/IY + EXX + IM 0/1/2. Deferred: undocumented X/Y flags, MEMPTR, full DAA, CB-prefix bit ops.

Total: 109 tests authored, 98 passing (8080: 18 + 2 ROM-validation, Z80: 21 + 1 ZEXDOC + 1 hello, 4004: 9, 4040: 5, 8086: 11, rom-32k: 6, ram-64k: 7, latch-8282: 4, rom-1m: 4, 8255-ppi: 5, 8251-usart: 4), 0 skipping, 11 todo, 0 failed. All 5 retro Intel/Zilog CPUs + 6 bus device chips implemented and validated against public-domain test ROMs:

• 8080: passes 8080PRE.COM and TST8080.COM (Microcosm 1980 — prints "CPU IS OPERATIONAL").
• Z80: runs Frank Cringle's ZEXDOC (1994) — prints the "Z80 instruction exerciser" banner and produces no ERROR within a time-bounded budget.

These are the canonical historical diagnostics that real Altair/IMSAI 8080 systems and Sinclair/MSX/CP/M Z80 systems used to validate their CPUs. Our chips run them.

Phase plan in autosearch/18_complete_emulation_plan.md tracks remaining work: 4001/4002/8253/8259 chips for canvas demos; 8088 V2 SingleStepTests for 8086; Busicom 141-PF for 4004; full ZEXDOC validation. No velxio core source has been modified. Run npm test from test/test_intel/ to confirm.