Skip to content

ADR 0002 — v1.1.0: DAP, NES variant, per-cycle bus ticker

  • Status: Accepted
  • Release: v1.1.0 (2026-05-15)
  • Theme: Make chippy a debug-adapter server and the reusable core under a NES emulator (nessy).

D1 — Debug Adapter Protocol server + client library

  • Context: want editor-driven debugging (VS Code, nvim-dap) and a programmatic client.
  • Decision: transport-agnostic dap.Server over io.Reader/Writer (stdio / TCP); a dap.Client library; -dap-attach Phase A (handshake) → B/C (live remote TUI).
  • Consequences: the protocol becomes chippy's extension seam (custom requests, host hooks, inproc transport all build on it later — ADR 0006, 0008).

D2 — Source interface: local in-process vs remote DAP-backed

  • Context: the TUI must drive either the in-process CPU or a remote server identically.
  • Decision: a Source abstraction (LocalSource / RemoteSource) owns step/reset/continue/breakpoints; display panels read a CPU+RAM mirror the source keeps populated.
  • Consequences: one TUI, two backends. This is the lever the v1.5.0 TUI-via-DAP migration pulls (ADR 0008 D2).

D3 — VariantNES (Ricoh 2A03 = NMOS minus decimal)

  • Decision: add a CPU variant whose ADC/SBC ignore the D flag (the 2A03 disables BCD), reusing the NMOS table otherwise.
  • Consequences: nessy runs on the chippy core. Caveat that bit later work: the per-cycle path is gated on VariantNES, and it disables decimal — so the Tom Harte bus-trace harness keeps VariantNMOS and force-enables the per-cycle path (ADR 0008 D4).

D4 — Bus-ticker hook + cached Ticker assertion

  • Context: peripherals (PPU/APU/cart) must advance per CPU cycle, but the bare debugger CPU must stay single-digit-ns per step.
  • Decision: an optional cpu.Ticker on the bus; SetBus caches the type assertion so Step checks a field, not a per-call assertion.
  • Consequences: zero cost when no ticker; the hook later carries the full per-cycle interleave (ADR 0004) and the access-tracking heatmap (ADR 0008 D5).

D5 — Monorepo now, nessy built on the core, split later (YAGNI three-way)

  • Context: nessy (NES emulator) needs the 6502 core; a separate repo adds friction early.
  • Decision: keep chippy + nessy in one repo with a monorepo-aware release split; two-process design (emulator + DAP); defer the repo split and reject a speculative three-way split.
  • Consequences: fast iteration; the split is executed at v1.2.0 (ADR 0004 D3) once the public API stabilized.