# Velxio custom-chip capabilities (as of 2026-04-29)

Sourced by reading the in-repo SDK and runtime; no external lookups
needed.

## Toolchain

- C source → WASM via **clang + WASI-SDK**, driven by
  `backend/app/services/chip_compile.py`.
- Build flags (from the same file):

  ```
  clang --target=wasm32-unknown-wasip1 -O2 -nostartfiles
        -Wl,--import-memory -Wl,--export-table -Wl,--no-entry
        -Wl,--export=chip_setup -Wl,--allow-undefined
        -I sdk/ chip.c -o chip.wasm
  ```

- Single mandatory export: `void chip_setup(void)`. Everything else is
  reactive: pin watch callbacks, timer callbacks, I²C/SPI/UART
  callbacks. There is no host-driven main loop and no
  `chip_loop()`-style polling hook.

## Memory per chip instance

From `frontend/src/simulation/customChips/ChipRuntime.ts:170`:

```ts
this.memory = new WebAssembly.Memory({ initial: 2, maximum: 16 });
```

- 2 pages × 64 KB = **128 KB initial**.
- Up to **16 pages = 1 MB max** per instance.
- Each chip instance gets its own linear memory — no shared globals
  between two instances of the same chip.
- WASI-SDK ships `malloc`/`free`/`memset`/etc., so dynamic allocation
  for register files, decoder tables, and prefetch queues is fine.

## Pin API (from `backend/sdk/velxio-chip.h`)

- `vx_pin_t vx_pin_register(const char* name, vx_pin_dir dir);`
- `vx_pin_read`, `vx_pin_write`, `vx_pin_set_dir` — for digital I/O.
- `vx_pin_watch(pin, edge, callback, user_data)` — edge can be
  `VX_RISING`, `VX_FALLING`, or `VX_BOTH`.
- `vx_pin_dac_write` / `vx_pin_read_analog` — analog (not needed for
  these CPUs but available).

There is **no fixed pin-count cap**. The SDK uses a dynamic `PinEntry[]`
table. The 40-pin DIP CPUs in scope (8080 / Z80 / 8086) are well within
this.

## Time and clocks

- `uint64_t vx_sim_now_nanos(void)` — simulated time, monotonic.
- `vx_timer_t vx_timer_create(void);`
- `vx_timer_start(timer, period_nanos, repeating, callback, user_data)`
- `vx_timer_stop(timer)`

This is the mechanism we will lean on hardest: a CPU emulator schedules
a repeating timer at the chip's clock period (e.g. 250 ns for 4 MHz Z80)
and the callback executes one instruction (or one machine cycle) per
firing.

## I/O helpers we will *not* use

I²C, SPI, UART, framebuffer helpers exist (see
`docs/wiki/custom-chips-api-reference.md`) but they are higher-level
slave/master abstractions. CPUs drive raw pins (RD, WR, MREQ, IORQ,
ALE, etc.), so we will register those as plain GPIOs and bit-bang the
bus protocol from the chip itself.

## Existing precedent in the repo

Eleven example chips live in `test/test_custom_chips/sdk/examples/`.
Closest relatives to a CPU:

- **`sn74hc595.c`** — proves a multi-step, clocked, stateful protocol
  (SPI shift-register + latch) works under the reactive callback model.
- **`ds3231.c`** — proves persistent register files (19 BCD registers
  with auto-increment) work.
- **`pulse-counter.c`** — proves a chip can react to many edges per
  second without dropping events.

No full CPU emulator exists yet in the repo; this folder is the first.

## Hard limits that matter for CPUs

| Limit                 | Value                | Comfortable for…           |
| --------------------- | -------------------- | --------------------------- |
| Linear memory         | 1 MB / instance      | Even a 64 KB Z80 RAM model + decoder tables fits, but external RAM should still live in a separate chip. |
| Pin count             | No hard cap          | 40-pin packages are fine. |
| Timer resolution      | Nanoseconds          | Up to ~10 MHz instruction rates are fine; sub-ns is not. |
| WASM execution budget | Set by host loop     | Need to keep per-callback work bounded — no infinite spin. |

## What is *not* available

- No direct shared-memory bus between chips. Two chips talk only via
  pin transitions on wires.
- No interrupt controller primitive — interrupts are just pin edges
  the CPU watches and reacts to (which is how the real silicon works
  anyway).
- No SPICE / analog simulation guarantees timing accuracy at the
  nanosecond level under load — we will treat the simulated nanosecond
  clock as the source of truth, not wall time.