a2nr
/
velxio
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
velxio/test/test_intel/test_buses/README.md

2.7 KiB
Raw Blame History

test_buses — External memory chips for retro CPUs

Real PCBs from 1976 don't put RAM/ROM inside the CPU package. Faithful emulation requires the same separation: the CPU drives address pins, chip-select, and RD̅/WR̅; separate memory chips on the canvas listen.

These chips are reusable across all five Intel/Z80 CPU projects.

Chips planned

Chip Pins Source file Status
rom-32k 27 rom-32k.c ✅ Implemented — 6/6 tests passing
ram-64k 29 ram-64k.c ✅ Implemented — 7/7 tests passing
latch-8282 20 latch-8282.c 📋 Spec only (only needed for 8086)

Why we still test these C chips even though tests use installFakeRom

The BoardHarness.installFakeRom() and installFakeRam() helpers emulate memory in JS for CPU unit tests. They are fast, flexible, and don't require a per-test compile.

The real rom-32k.c / ram-64k.c chips are needed because:

  1. End users wire them on the canvas. A user dropping a Z80 into velxio expects a draggable ROM and RAM next to it. The C chips ARE that user-visible primitive.
  2. Integration tests need the real chip. Once a CPU is verified in unit tests with a fake ROM, an integration test runs the same CPU with the real rom-32k.wasm, proving the on-canvas demo will work.

So the test split is:

  • *.unit.test.js → uses installFakeRom / installFakeRam, tests instruction semantics and bus protocol
  • *.integration.test.js → uses real compiled bus chips, proves the user-visible demo works

For now we have rom-32k.test.js and ram-64k.test.js covering the C chip behavior in isolation — pin contract + read/write protocol with hand-crafted bus stimuli.

ROM image loading — the SDK constraint

The velxio chip SDK does not (yet) support arbitrary-length blob attributes. vx_attr_register only takes a double. So a 32 KB ROM image cannot be passed in via .chip.json properties.

Workaround for now: the C source contains const uint8_t rom_image[32768] = { /* baked-in */ };. Each "ROM variant" is a separate compiled chip. For shipping examples we will generate one variant per demo program; for tests we use a small image embedded directly in rom-32k.c.

A follow-up SDK proposal — adding vx_attr_register_blob() or an "asset" import mechanism — is tracked in ../autosearch/05_open_questions.md.

ram-64k notes

The RAM chip is simpler — no embedded image, just a static uint8_t mem[65536] zero-initialized at chip_setup. No SDK extension required.