test_intel: historic ROM boots — Busicom + Tiny BASIC + Galaksija
Wire up three real, public-domain ROMs from the silicon era and prove
they boot end-to-end on the clean-room chip implementations. Each
test reads a separate well-known boot artifact:
* Busicom 141-PF firmware (4004, 1 KB, Intel PD 2009)
Wires real 4004 + real 4002 chips on the multiplexed nibble bus.
Toggles TEST every ~400 phases to mimic the printer-drum encoder
pulse the firmware polls. Asserts >2000 opcode fetches, >15 unique
PC addresses, and >100 CMROM strobes.
* Palo Alto Tiny BASIC v2 (8080, 1.9 KB, Wang 1976 PD)
CPUville port loaded from Intel HEX. Fake polled 8251 UART at port
0x02 (data) / 0x03 (status). Asserts the captured TX stream
contains the BASIC "OK" prompt — proving the interpreter reached
its REPL.
* Galaksija ROM A (Z80, 4 KB, Voja Antonić PD 1984)
ROM A+B at 0x0000..0x1FFF, system RAM at 0x2000..0x3FFF. Asserts
PC visits the JP target 0x03DA from reset and the ASCII "READY"
prompt appears in RAM after init.
ROMs are downloaded to roms/{4004,8080,z80}/ and gitignored — the
tests skip cleanly when the binaries are absent. License-clean: no
GPL ROMs, all PD by upstream provenance.
Total: 126 → 129 passing, 0 todo, 0 failed; 19 → 22 test files.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
David Montero
parent
f429e113ab
commit
afad6a1ed0
|
|
@ -1,3 +1,4 @@
|
|||
node_modules/
|
||||
fixtures/
|
||||
*.wasm
|
||||
roms/
|
||||
|
|
|
|||
|
|
@ -117,8 +117,13 @@ address and data pins, just like in a real PCB.
|
|||
| **test_8086/**| ✅ 16 | ✅ | **🎯 7 passing + 9 deferred (skipIf TODO areas). ~800 LOC clean-room from Intel iAPX 86,88 User's Manual (Oct 1979).** Bus + reset + ModR/M + full ISA (string/MUL/DIV/port I/O/BCD/interrupts) + ALE/AD-release pin tests + 1 MB segment-wrap + memory-mapped UART hello-world. |
|
||||
| **test_z80/**| ✅ 22 | ✅ | **🎯 22 passing. ~600 LOC clean-room from Zilog UM008003 + Sean Young's "Undocumented Z80 Documented" v0.91.** Full bus + ISA + INT (IM 0/1/2 incl. vector-table lookup) + NMI + LDIR + IX/IY + EXX. ZEXDOC end-to-end run lives in zexdoc.test.js. |
|
||||
|
||||
Total: **126 tests authored, 126 passing** across 19 test files,
|
||||
0 skipping, 0 todo, 0 failed.
|
||||
Total: **129 tests authored, 129 passing** across 22 test files,
|
||||
0 skipping, 0 todo, 0 failed. **Three historic public-domain ROMs
|
||||
boot end-to-end on our chips:** Busicom 141-PF (4004, 1 KB, Intel
|
||||
PD 2009), Palo Alto Tiny BASIC v2 (8080, 1.9 KB, Wang 1976 PD), and
|
||||
Galaksija ROM A (Z80, 4 KB, Voja Antonić PD 1984). Each test wires
|
||||
the real chip + RAM/UART/etc. and asserts on a real boot artifact
|
||||
(printer-drum scan loop, "OK" prompt via 8251 UART, "READY" in RAM).
|
||||
|
||||
| Chip | Type | Tests | LOC | Validation |
|
||||
| --- | --- | --- | --- | --- |
|
||||
|
|
|
|||
|
|
@ -782,6 +782,60 @@ only needs a sourceable ROM image plus 4 4001 chip-id variants.
|
|||
|
||||
---
|
||||
|
||||
## Phase F-extension — historic ROM boots (2026-05-01)
|
||||
|
||||
Three public-domain ROMs from the actual silicon era now boot end-
|
||||
to-end on our clean-room chip implementations:
|
||||
|
||||
### Galaksija ROM A (Z80, 4 KB) — `test_z80/galaksija.test.js`
|
||||
- **Source:** mejs/galaksija on GitHub, ROM_A_with_ROM_B_init_ver_29.bin
|
||||
- **License:** Voja Antonić explicitly placed the design + ROM in the
|
||||
public domain (Galaksija magazine #6, 1984).
|
||||
- **Setup:** ROM A+B image at 0x0000..0x1FFF, fake RAM at 0x2000..
|
||||
0x3FFF (system stack + video buffer + user RAM).
|
||||
- **Verifies:** PC visits the JP-from-reset target 0x03DA, runs
|
||||
>1000 M1 fetches, and the ASCII string "READY" appears in RAM
|
||||
after init — the canonical Galaksija prompt.
|
||||
|
||||
### Busicom 141-PF firmware (4004, 1 KB) — `test_4004/busicom.test.js`
|
||||
- **Source:** carlini/intel-4004-in-4004-bytes-of-c on GitHub
|
||||
(originally Tim McNerney's 4004.com restoration).
|
||||
- **License:** Intel released the firmware to public domain in 2009.
|
||||
- **Setup:** Real 4004 + real 4002 chips wired on the multiplexed
|
||||
nibble bus; JS-side bus driver feeds bytes from the firmware
|
||||
image during M1/M2.
|
||||
- **TEST pin handling:** the very first opcode is `JCN c4=1`
|
||||
waiting for the printer-drum encoder pulse. We toggle TEST every
|
||||
~400 phases to mimic the rotating drum, otherwise the firmware
|
||||
spins forever on the first JCN.
|
||||
- **Verifies:** >2000 opcode-fetch cycles, >15 unique PC addresses
|
||||
visited, CMROM strobed >100 times, CMRAM strobed at least once
|
||||
(firmware genuinely talks to RAM during init).
|
||||
|
||||
### Palo Alto Tiny BASIC v2 (8080, 1.9 KB) — `test_8080/tinybasic.test.js`
|
||||
- **Source:** CPUville port of Li-Chen Wang's 1976 Tiny BASIC,
|
||||
distributed as Intel HEX at cpuville.com/Code/.
|
||||
- **License:** Wang's original carries the famous "@COPYLEFT, ALL
|
||||
WRONGS RESERVED" notice (PCC, May 1976) — universally treated as
|
||||
public domain.
|
||||
- **Setup:** ROM at 0x0000..0x07FF, RAM at 0x0800..0x0FFF (stack
|
||||
init `LXI SP, 1000h`), fake polled 8251A UART at I/O port 0x02
|
||||
(data) / 0x03 (status).
|
||||
- **Verifies:** the chip drives `OUT 0x03` (UART mode init) and
|
||||
`OUT 0x02` (TX), and the captured TX stream contains the ASCII
|
||||
"OK" prompt — proving Wang's BASIC interpreter reached its main
|
||||
REPL loop.
|
||||
|
||||
### Tests delta
|
||||
- Total test_intel: 126 → **129 passing**, 0 todo, 0 failed.
|
||||
- New files: `test_4004/busicom.test.js`,
|
||||
`test_8080/tinybasic.test.js`, `test_z80/galaksija.test.js`.
|
||||
- New ROMs under `roms/` (gitignored): `4004/busicom_141pf.bin`
|
||||
(1280 B), `8080/tinybasic.hex` (5235 B), `z80/galaksija_rom_a.bin`
|
||||
(4096 B), `z80/galaksija_rom_b.bin` (4096 B).
|
||||
|
||||
---
|
||||
|
||||
## Phase C extension — completed (2026-04-30)
|
||||
|
||||
### Delivered (the two deferred chips from Phase C)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,168 @@
|
|||
/**
|
||||
* Busicom 141-PF firmware — end-to-end Intel 4004 integration test.
|
||||
*
|
||||
* The Busicom 141-PF was the printing electronic calculator that
|
||||
* Intel built the 4004 *for* in 1971. The full 1 KB firmware (4× 256-
|
||||
* byte 4001 ROMs) was released to the public domain by Intel in 2009
|
||||
* via Tim McNerney's restoration project on 4004.com. This test runs
|
||||
* the original silicon's binary on our clean-room 4004 + 4002.
|
||||
*
|
||||
* What we verify
|
||||
* --------------
|
||||
* 1) The 4004 chip executes >2000 instruction cycles of the real
|
||||
* firmware without crashing or stalling on a single PC.
|
||||
* 2) PC visits a wide spread of unique addresses across the 1 KB
|
||||
* image — proving the chip's full ISA + bus protocol cope with
|
||||
* code Intel actually shipped to customers, not just hand-crafted
|
||||
* micro-tests.
|
||||
* 3) The firmware exercises SRC + WMP + WRR over the shared nibble
|
||||
* bus — visible as CMRAM/CMROM strobes and writes to the 4002.
|
||||
*
|
||||
* What we do NOT model
|
||||
* --------------------
|
||||
* - 4003 shift registers for keyboard / printer scanning. The
|
||||
* firmware's scanning loops will read all-zero (no keys), so the
|
||||
* chip stays in the polling state — that's the correct behaviour
|
||||
* for an unattended Busicom; the goal here is "code executes
|
||||
* without breaking", not "produces a printed receipt".
|
||||
* - 4× 4001 ROM chip-id variants. Instead of compiling 4 separate
|
||||
* chip variants we use a JS-side nibble-bus driver that serves
|
||||
* bytes from the 1 KB image regardless of the chip-id — the 4004
|
||||
* side of the bus protocol is identical, only the source of the
|
||||
* nibbles differs.
|
||||
*/
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { readFileSync, existsSync } from 'fs';
|
||||
import { dirname, join } from 'path';
|
||||
import { fileURLToPath } from 'url';
|
||||
import { BoardHarness } from '../src/BoardHarness.js';
|
||||
import { chipWasmExists } from '../src/helpers.js';
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const ROM_PATH = join(__dirname, '..', 'roms', '4004', 'busicom_141pf.bin');
|
||||
|
||||
const skip = !chipWasmExists('4004') || !chipWasmExists('4002-ram')
|
||||
|| !existsSync(ROM_PATH);
|
||||
|
||||
const CLOCK_NS = 1351; // 4004 ran at 740 kHz → 1351 ns per phase
|
||||
|
||||
function cpuPinMap() {
|
||||
const m = {
|
||||
SYNC: 'SYNC', RESET: 'RESET', TEST: 'TEST',
|
||||
CMROM: 'CMROM',
|
||||
CMRAM0: 'CMRAM0', CMRAM1: 'CMRAM1', CMRAM2: 'CMRAM2', CMRAM3: 'CMRAM3',
|
||||
CLK1: 'CLK1', CLK2: 'CLK2',
|
||||
VDD: 'VDD', VSS: 'VSS',
|
||||
};
|
||||
for (let i = 0; i < 4; i++) m[`D${i}`] = `D${i}`;
|
||||
return m;
|
||||
}
|
||||
|
||||
function ramPinMap() {
|
||||
const m = {
|
||||
SYNC: 'SYNC', CL: 'CLK1', RESET: 'RESET', CM: 'CMRAM0',
|
||||
VDD: 'VDD', VSS: 'VSS',
|
||||
};
|
||||
for (let i = 0; i < 4; i++) m[`D${i}`] = `D${i}`;
|
||||
for (let i = 0; i < 4; i++) m[`O${i}`] = `O${i}`;
|
||||
return m;
|
||||
}
|
||||
|
||||
describe.skipIf(skip)('Busicom 141-PF firmware (4004) integration', () => {
|
||||
|
||||
it('runs >2000 cycles of the original Intel firmware without crashing', async () => {
|
||||
const rom = readFileSync(ROM_PATH);
|
||||
expect(rom.length, 'Busicom firmware must be at least 1 KB').toBeGreaterThanOrEqual(1024);
|
||||
|
||||
// Use the first 1 KB (4× 256-byte ROMs concatenated in order).
|
||||
// The firmware references PCs in [0x000..0x3FF].
|
||||
const PROG = new Uint8Array(0x400);
|
||||
PROG.set(rom.subarray(0, 0x400), 0);
|
||||
|
||||
const board = new BoardHarness();
|
||||
// 4002 first so its on_phase fires before the 4004 (one-frame-behind
|
||||
// protocol, see 4002-ram.c documentation).
|
||||
await board.addChip('4002-ram', ramPinMap());
|
||||
await board.addChip('4004', cpuPinMap());
|
||||
|
||||
// The 4004's TEST pin on a real Busicom is wired to the printer
|
||||
// drum encoder — it pulses every few ms as the drum rotates. The
|
||||
// very first instruction is JCN (jump-if-TEST-low) waiting for
|
||||
// that pulse, so without toggling TEST the firmware spins forever
|
||||
// on the first JCN. Toggle TEST every ~5000 phases of simulated
|
||||
// time below to mimic the drum sync.
|
||||
board.setNet('TEST', true);
|
||||
board.setNet('RESET', true);
|
||||
board.advanceNanos(CLOCK_NS * 12);
|
||||
board.setNet('RESET', false);
|
||||
|
||||
// JS-side nibble-bus driver: feeds opcode high/low nibbles during
|
||||
// M1/M2 from the firmware image. Captures the 4004's PC via the
|
||||
// address drives at A1/A2/A3.
|
||||
let phaseSinceSync = -1;
|
||||
let observedPc = 0;
|
||||
let pcLow = 0, pcMid = 0;
|
||||
const pcHistogram = new Map();
|
||||
const cmramStrobes = [0, 0, 0, 0];
|
||||
let cmromStrobes = 0;
|
||||
|
||||
board.watchNet('SYNC', (high) => { if (high) phaseSinceSync = 0; });
|
||||
for (let i = 0; i < 4; i++) {
|
||||
const idx = i;
|
||||
board.watchNet(`CMRAM${i}`, (high) => { if (high) cmramStrobes[idx]++; });
|
||||
}
|
||||
board.watchNet('CMROM', (high) => { if (high) cmromStrobes++; });
|
||||
|
||||
function driveDNibble(n) {
|
||||
for (let i = 0; i < 4; i++) {
|
||||
board.setNet(`D${i}`, ((n >> i) & 1) === 1);
|
||||
}
|
||||
}
|
||||
|
||||
// 8 phases × 2500 cycles = 20_000 phases ≈ 27 ms simulated time.
|
||||
const PHASES = 8 * 2500;
|
||||
let m1FetchCount = 0;
|
||||
let testHigh = true;
|
||||
for (let p = 0; p < PHASES; p++) {
|
||||
// Pulse TEST every ~400 phases to mimic the printer-drum encoder
|
||||
// sync the firmware polls in its main loop.
|
||||
if ((p % 400) === 0) {
|
||||
testHigh = !testHigh;
|
||||
board.setNet('TEST', testHigh);
|
||||
}
|
||||
if (phaseSinceSync === 3) {
|
||||
driveDNibble((PROG[observedPc & 0x3FF] >> 4) & 0xF);
|
||||
} else if (phaseSinceSync === 4) {
|
||||
driveDNibble(PROG[observedPc & 0x3FF] & 0xF);
|
||||
}
|
||||
board.advanceNanos(CLOCK_NS);
|
||||
if (phaseSinceSync === 0) pcLow = board.readBus('D', 4);
|
||||
else if (phaseSinceSync === 1) pcMid = board.readBus('D', 4);
|
||||
else if (phaseSinceSync === 2) {
|
||||
const pcHigh = board.readBus('D', 4);
|
||||
observedPc = pcLow | (pcMid << 4) | (pcHigh << 8);
|
||||
pcHistogram.set(observedPc, (pcHistogram.get(observedPc) ?? 0) + 1);
|
||||
m1FetchCount++;
|
||||
}
|
||||
if (phaseSinceSync >= 0) phaseSinceSync++;
|
||||
}
|
||||
|
||||
// Sanity: chip kept fetching new instructions across the run.
|
||||
expect(m1FetchCount, 'opcode-fetch cycles in the run').toBeGreaterThan(2000);
|
||||
|
||||
// Sanity: chip explored a meaningful slice of the firmware, not
|
||||
// just a 1-byte halt loop. Real Busicom firmware visits dozens
|
||||
// of distinct addresses even in its idle keyboard-scan state.
|
||||
expect(pcHistogram.size, 'unique PC addresses visited').toBeGreaterThan(15);
|
||||
|
||||
// Sanity: bus protocol fired CMROM (instruction fetch strobe)
|
||||
// many times, and at least one CMRAM strobe (firmware does talk
|
||||
// to RAM during init).
|
||||
expect(cmromStrobes, 'CMROM strobes during the run').toBeGreaterThan(100);
|
||||
const totalCmram = cmramStrobes.reduce((a, b) => a + b, 0);
|
||||
expect(totalCmram, 'CMRAM strobes during the run').toBeGreaterThan(0);
|
||||
|
||||
board.dispose();
|
||||
}, { timeout: 30_000 });
|
||||
|
||||
});
|
||||
|
|
@ -0,0 +1,162 @@
|
|||
/**
|
||||
* Palo Alto Tiny BASIC v2 — end-to-end Intel 8080 integration test.
|
||||
*
|
||||
* Origin: Li-Chen Wang's Tiny BASIC (Pittsburgh People's Computer
|
||||
* Company, May 1976; "@COPYLEFT, ALL WRONGS RESERVED" notice = PD).
|
||||
* The .hex distributed by CPUville (`tinybasic2dms_hex.txt`) is a
|
||||
* port to the CPUville 8080 board with a polled 8251A UART. ~1.9 KB
|
||||
* of code fitting in 0x0000..0x07FF.
|
||||
*
|
||||
* I/O ports (polled 8251A):
|
||||
* 0x02 — UART data register (read RX, write TX)
|
||||
* 0x03 — UART status (bit 0 = TX ready, bit 1 = RX ready)
|
||||
*
|
||||
* What we verify
|
||||
* --------------
|
||||
* 1) The 8080 chip executes Wang's 1976 PD Tiny BASIC ROM end-to-
|
||||
* end far enough for the prompt routine to run.
|
||||
* 2) The chip drives `OUT 0x03` (8251 mode init) and `OUT 0x02`
|
||||
* (TX data) — i.e. our chip's port-I/O bus protocol is correct
|
||||
* against real-world historic ROM.
|
||||
* 3) The TX stream contains the ASCII "OK" prompt (with surrounding
|
||||
* CR/LF), proving the BASIC interpreter reached its main loop.
|
||||
*/
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { readFileSync, existsSync } from 'fs';
|
||||
import { dirname, join } from 'path';
|
||||
import { fileURLToPath } from 'url';
|
||||
import { BoardHarness } from '../src/BoardHarness.js';
|
||||
import { chipWasmExists } from '../src/helpers.js';
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const HEX_PATH = join(__dirname, '..', 'roms', '8080', 'tinybasic.hex');
|
||||
|
||||
const skip = !chipWasmExists('8080') || !existsSync(HEX_PATH);
|
||||
|
||||
const CLOCK_NS = 500; // 2 MHz 8080
|
||||
|
||||
/** Parse Intel HEX format into a flat byte array. */
|
||||
function parseIntelHex(text) {
|
||||
const out = new Uint8Array(0x1000);
|
||||
for (const raw of text.split(/\r?\n/)) {
|
||||
const line = raw.trim();
|
||||
if (!line.startsWith(':')) continue;
|
||||
const len = parseInt(line.substr(1, 2), 16);
|
||||
const addr = parseInt(line.substr(3, 4), 16);
|
||||
const type = parseInt(line.substr(7, 2), 16);
|
||||
if (type === 0x01) break; // EOF record
|
||||
if (type !== 0x00) continue;
|
||||
for (let i = 0; i < len; i++) {
|
||||
out[addr + i] = parseInt(line.substr(9 + i * 2, 2), 16);
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function fullPinMap() {
|
||||
// Same shape as test_8080/8080.test.js's fullPinMap.
|
||||
const m = {
|
||||
SYNC: 'SYNC', DBIN: 'DBIN', WR: 'WR', WAIT: 'WAIT',
|
||||
READY: 'READY', HOLD: 'HOLD', HLDA: 'HLDA',
|
||||
INT: 'INT', INTE: 'INTE', RESET: 'RESET',
|
||||
PHI1: 'PHI1', PHI2: 'PHI2',
|
||||
VCC: 'VCC', VDD: 'VDD', VBB: 'VBB', GND: 'GND',
|
||||
};
|
||||
for (let i = 0; i < 16; i++) m[`A${i}`] = `A${i}`;
|
||||
for (let i = 0; i < 8; i++) m[`D${i}`] = `D${i}`;
|
||||
return m;
|
||||
}
|
||||
|
||||
describe.skipIf(skip)('Palo Alto Tiny BASIC v2 (8080) integration', () => {
|
||||
|
||||
it('boots Wang\'s 1976 Tiny BASIC and emits "OK" via the 8251 UART', async () => {
|
||||
const program = parseIntelHex(readFileSync(HEX_PATH, 'utf8'));
|
||||
|
||||
const board = new BoardHarness();
|
||||
await board.addChip('8080', fullPinMap());
|
||||
|
||||
// ROM at 0x0000..0x07FF (Tiny BASIC code).
|
||||
board.installFakeRom(program, {
|
||||
addrPrefix: 'A', addrWidth: 16,
|
||||
dataPrefix: 'D', dataWidth: 8,
|
||||
rd: 'DBIN', rdActiveLow: false,
|
||||
baseAddr: 0,
|
||||
});
|
||||
// RAM at 0x0800..0x0FFF (vars + stack to 0x1000 per `LXI SP,1000h`).
|
||||
board.installFakeRam(0x0800, {
|
||||
addrPrefix: 'A', addrWidth: 16,
|
||||
dataPrefix: 'D', dataWidth: 8,
|
||||
rd: 'DBIN', rdActiveLow: false,
|
||||
wr: 'WR',
|
||||
baseAddr: 0x0800,
|
||||
});
|
||||
|
||||
// Fake 8251 UART at ports 0x02 (data) / 0x03 (status).
|
||||
// The 8080 distinguishes I/O from memory via the status byte at
|
||||
// T1 — but our fake is simpler: we just watch WR̅ + DBIN with
|
||||
// the address bus at the known port number on A0..A7.
|
||||
//
|
||||
// The chip drives I/O port number on A0..A7 AND A8..A15 (mirrored)
|
||||
// during IN/OUT cycles. We watch the low byte.
|
||||
const uartTx = [];
|
||||
let uartStatus = 0x01; // TX always ready, RX never has data
|
||||
let prevWr = true;
|
||||
let prevDbin = false;
|
||||
|
||||
board.watchNet('WR', (level) => {
|
||||
if (level !== false || prevWr === false) { // falling edge: WR̅ asserted
|
||||
prevWr = level;
|
||||
return;
|
||||
}
|
||||
prevWr = level;
|
||||
const port = board.readBus('A', 8);
|
||||
if (port === 0x02) {
|
||||
uartTx.push(board.readBus('D', 8));
|
||||
}
|
||||
// port 0x03 writes are 8251 mode/command — ignore for this test.
|
||||
});
|
||||
|
||||
board.watchNet('DBIN', (level) => {
|
||||
const rising = (level === true && prevDbin === false);
|
||||
prevDbin = level;
|
||||
if (!rising) return;
|
||||
const port = board.readBus('A', 8);
|
||||
// Detect IN cycle by status byte at T1 (we don't decode it; the
|
||||
// simpler heuristic is: if A0..A7 is a low-byte port and A8..A15
|
||||
// mirrors it (8080 IN convention), drive the value).
|
||||
const portHi = board.readBus('A', 16) >> 8;
|
||||
if (port === portHi) {
|
||||
if (port === 0x03) {
|
||||
for (let i = 0; i < 8; i++) {
|
||||
board.setNet(`D${i}`, ((uartStatus >> i) & 1) === 1);
|
||||
}
|
||||
} else if (port === 0x02) {
|
||||
for (let i = 0; i < 8; i++) board.setNet(`D${i}`, false); // RX = 0
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// Quiet inputs.
|
||||
board.setNet('READY', true);
|
||||
board.setNet('HOLD', false);
|
||||
board.setNet('INT', false);
|
||||
|
||||
board.setNet('RESET', true);
|
||||
board.advanceNanos(CLOCK_NS * 4);
|
||||
board.setNet('RESET', false);
|
||||
|
||||
// Run for plenty of cycles. Booting + UART init + writing "OK\r\n"
|
||||
// is well under 100K instructions on real hardware.
|
||||
const TARGET_CYCLES = 400_000;
|
||||
for (let i = 0; i < TARGET_CYCLES; i++) board.advanceNanos(CLOCK_NS);
|
||||
|
||||
// Decode TX stream as ASCII (filtering nulls and clearing high
|
||||
// bits — Tiny BASIC sometimes drives bit 7 high for echo control).
|
||||
const txText = String.fromCharCode(...uartTx.map(b => b & 0x7F).filter(b => b > 0));
|
||||
|
||||
// Should contain "OK" somewhere — it's the BASIC ready prompt.
|
||||
expect(uartTx.length, 'BASIC must transmit characters via OUT 0x02').toBeGreaterThan(0);
|
||||
expect(txText, 'TX stream should contain the BASIC "OK" prompt').toContain('OK');
|
||||
}, { timeout: 30_000 });
|
||||
|
||||
});
|
||||
|
|
@ -0,0 +1,158 @@
|
|||
/**
|
||||
* Galaksija — end-to-end Z80 ROM integration test.
|
||||
*
|
||||
* Galaksija is a 1983 Yugoslav DIY home computer designed by Voja
|
||||
* Antonić. The complete schematics + ROM source were published in
|
||||
* the magazine "Galaksija" #6 and explicitly placed in the public
|
||||
* domain by the author.
|
||||
*
|
||||
* ROMs:
|
||||
* ROM A (4 KB) at 0x0000..0x0FFF — Z80 monitor + integer BASIC.
|
||||
* ROM B (4 KB) at 0x1000..0x1FFF — floating-point + extra BASIC.
|
||||
*
|
||||
* RAM (this ROM A "init ver 29"):
|
||||
* 0x2000..0x27FF — main RAM (system stack grows down from 0x2800).
|
||||
* 0x2800..0x3FFF — video + user RAM. The "READY" banner string
|
||||
* appears at 0x2802 after init completes.
|
||||
*
|
||||
* Boot path (from ROM A, verified by disassembly):
|
||||
* 0x0000: DI ; disable interrupts
|
||||
* 0x0001: SUB A ; A=0, all flags set
|
||||
* 0x0002: JP 0x03DA ; main init
|
||||
*
|
||||
* What we verify
|
||||
* --------------
|
||||
* 1) The chip executes the boot sequence without locking up — PC
|
||||
* visits the JP target 0x03DA within the first few hundred
|
||||
* machine cycles, and continues past it.
|
||||
* 2) After running for a few hundred thousand cycles, the ASCII
|
||||
* string "READY" appears in RAM. That's the Galaksija monitor's
|
||||
* "ready for input" prompt — a real, recognisable boot artifact
|
||||
* that proves: the Z80 chip's full ISA is correct enough to run
|
||||
* a ~500-instruction-long initialisation sequence end-to-end,
|
||||
* its bus protocol drives MREQ̅+RD̅ correctly across 4 KB of ROM,
|
||||
* and writes via WR̅ correctly land in fake RAM.
|
||||
*
|
||||
* We don't simulate the keyboard — Galaksija scans rows by issuing
|
||||
* `IN A,(0xnn)` and decoding the address bus, which is irrelevant to
|
||||
* proving boot. The CPU sees no keys pressed and stays in the input
|
||||
* polling loop after init, which is exactly the right behaviour to
|
||||
* observe.
|
||||
*/
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { readFileSync, existsSync } from 'fs';
|
||||
import { dirname, join } from 'path';
|
||||
import { fileURLToPath } from 'url';
|
||||
import { BoardHarness } from '../src/BoardHarness.js';
|
||||
import { chipWasmExists } from '../src/helpers.js';
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const ROM_PATH = join(__dirname, '..', 'roms', 'z80', 'galaksija_rom_a.bin');
|
||||
const ROM_B_PATH = join(__dirname, '..', 'roms', 'z80', 'galaksija_rom_b.bin');
|
||||
|
||||
const skip = !chipWasmExists('z80') || !existsSync(ROM_PATH);
|
||||
|
||||
const CLOCK_NS = 250; // 4 MHz Z80 (Galaksija ran at 3.072 MHz, close enough)
|
||||
|
||||
function fullPinMap() {
|
||||
const m = {
|
||||
M1: 'M1', MREQ: 'MREQ', IORQ: 'IORQ', RD: 'RD', WR: 'WR',
|
||||
RFSH: 'RFSH', HALT: 'HALT', WAIT: 'WAIT',
|
||||
INT: 'INT', NMI: 'NMI', RESET: 'RESET', BUSREQ: 'BUSREQ',
|
||||
BUSACK: 'BUSACK', CLK: 'CLK', VCC: 'VCC', GND: 'GND',
|
||||
};
|
||||
for (let i = 0; i < 16; i++) m[`A${i}`] = `A${i}`;
|
||||
for (let i = 0; i < 8; i++) m[`D${i}`] = `D${i}`;
|
||||
return m;
|
||||
}
|
||||
|
||||
describe.skipIf(skip)('Galaksija ROM (Z80) integration', () => {
|
||||
|
||||
it('Z80 boots Galaksija ROM A and initialises video framebuffer', async () => {
|
||||
const romA = readFileSync(ROM_PATH);
|
||||
expect(romA.length, 'ROM A must be exactly 4 KB').toBe(4096);
|
||||
|
||||
// Concatenate ROM A + ROM B → 8 KB image at 0x0000..0x1FFF.
|
||||
let romImage = new Uint8Array(8192);
|
||||
romImage.set(romA, 0);
|
||||
if (existsSync(ROM_B_PATH)) {
|
||||
const romB = readFileSync(ROM_B_PATH);
|
||||
romImage.set(romB, 0x1000);
|
||||
}
|
||||
|
||||
const board = new BoardHarness();
|
||||
await board.addChip('z80', fullPinMap());
|
||||
|
||||
// ROM at 0x0000..0x1FFF (read-only, MREQ̅+RD̅).
|
||||
board.installFakeRom(romImage, {
|
||||
rd: 'RD', rdActiveLow: true,
|
||||
cs: 'MREQ', csActiveLow: true,
|
||||
baseAddr: 0,
|
||||
});
|
||||
|
||||
// System RAM at 0x2000..0x3FFF (writable).
|
||||
const ram = board.installFakeRam(0x2000, {
|
||||
rd: 'RD', wr: 'WR',
|
||||
cs: 'MREQ', csActiveLow: true,
|
||||
baseAddr: 0x2000,
|
||||
});
|
||||
|
||||
// The 0x4000..0xFFFF region isn't mapped on a real Galaksija;
|
||||
// any access there returns floating bus. We don't model that —
|
||||
// the Z80 should never go there if the ROM is correct.
|
||||
|
||||
// Watch M1 fetches so we can prove PC advances and visits the
|
||||
// JP target 0x03DA from the reset vector.
|
||||
const m1Addrs = [];
|
||||
let visited3DA = false;
|
||||
let lastPc = -1;
|
||||
let stuckCount = 0;
|
||||
let everMoved = false;
|
||||
board.watchNet('M1', (low) => {
|
||||
if (low === false) {
|
||||
const pc = board.readBus('A', 16);
|
||||
m1Addrs.push(pc);
|
||||
if (pc === 0x03DA) visited3DA = true;
|
||||
if (pc !== lastPc) { everMoved = true; stuckCount = 0; }
|
||||
else stuckCount++;
|
||||
lastPc = pc;
|
||||
}
|
||||
});
|
||||
|
||||
// Quiet inputs.
|
||||
board.setNet('WAIT', true);
|
||||
board.setNet('INT', true);
|
||||
board.setNet('NMI', true);
|
||||
board.setNet('BUSREQ', true);
|
||||
board.setNet('RESET', false);
|
||||
board.advanceNanos(CLOCK_NS * 4);
|
||||
board.setNet('RESET', true);
|
||||
|
||||
// Run a few hundred thousand cycles. ROM A's init routine clears
|
||||
// the screen + draws the welcome banner; that's well under 100K
|
||||
// cycles even on real hardware (~3 MHz).
|
||||
const TARGET_CYCLES = 500_000;
|
||||
for (let i = 0; i < TARGET_CYCLES; i++) board.advanceNanos(CLOCK_NS);
|
||||
|
||||
expect(everMoved, 'PC must advance past 0x0000 (chip not stuck at reset)').toBe(true);
|
||||
expect(visited3DA, 'PC must reach 0x03DA (the JP target from reset)').toBe(true);
|
||||
expect(m1Addrs.length, 'M1 fetches counted during the run').toBeGreaterThan(1000);
|
||||
|
||||
// Search RAM for the ASCII string "READY". The Galaksija monitor
|
||||
// writes this prompt during init.
|
||||
const READY = [0x52, 0x45, 0x41, 0x44, 0x59]; // 'R','E','A','D','Y'
|
||||
let readyAt = -1;
|
||||
for (let addr = 0x2000; addr < 0x3FFB && readyAt === -1; addr++) {
|
||||
let match = true;
|
||||
for (let i = 0; i < 5; i++) {
|
||||
if (ram.peek(addr + i) !== READY[i]) { match = false; break; }
|
||||
}
|
||||
if (match) readyAt = addr;
|
||||
}
|
||||
expect(readyAt, 'ASCII "READY" prompt must appear in RAM after init')
|
||||
.toBeGreaterThanOrEqual(0);
|
||||
|
||||
board.dispose();
|
||||
}, { timeout: 30_000 });
|
||||
|
||||
});
|
||||
Loading…
Reference in New Issue