The ADP debugger

The Advanced Debugging Protocol (ADP) is a plain-text, line-oriented TCP protocol on port 11001. Send a command line, read the text reply. Any socket client can drive the machine with no recompile — ideal for scripting and for quick, editor-independent inspection. It’s the primary, verified debugging surface in Bizmuth (Rhai scripting is built on top).

The core is single-threaded: the CPU, video, memory and debugger all run on one thread, and commands are applied between instructions — never mid-instruction — so state you read is always consistent. Numeric arguments accept decimal or 0x/$ hex.

Connecting

The ADP server is on by default (change the port with --adp-port, or pick protocols with --debug-protocol adp|dzrp|both|none). Connect however you like:

nc localhost 11001            # interactive: type a command, read the reply

help (or ?) prints the live command list; an unknown verb replies unknown command '…' (try 'help').

Message framing. Every message block — the banner, a command reply, or an async event — ends with a blank line, so a client can frame a multi-line reply (mem, disasm, reg, bp list) by reading lines until an empty one. A first line beginning with * is an unsolicited async event, not a reply. For automated/CI use, --headless runs the server with no window until the process is killed.

Execution control

Step-back replays saved full-machine snapshots — exact, not heuristic, but only reaches as far back as the snapshot history (snapshots are taken before each step/pause, not during free-run). no earlier state in history means you free-ran past the recorded window — re-run and step in.

Async stop events. While the machine is free-running (after continue/runto/finish/next), a stop is pushed to the client as an unsolicited line prefixed with * — so you learn of a breakpoint hit without polling: *stopped pc=XXXX reason=bp id=N. The leading * marks it apart from command replies, so a DAP / IDE bridge maps it straight to a DAP stopped event.

Inspection

mem / disasm resolve through the live MMU and overlays (bootrom, Layer 2 paging, config mode, DivMMC, Multiface), so they show exactly what the CPU would fetch — not raw bank RAM.

Video, sprites & DMA

See Inspecting hardware for these in depth.

Breakpoints & watchpoints

The optional if <cond> is only evaluated once the address already matched, so the hot path stays a cheap compare — see Conditional breakpoints for the full condition language (registers, flags, memory derefs, nr[]/nrraw[] nextregs).

State & snapshots

State round-trips faithfully; behaviour after a load can still diverge for programs that read the host-backed RTC (live wall-clock). The frame counter resumes at the saved frame, so on_frame handlers keyed off absolute frame numbers should use load-relative offsets.

Paths with spaces must be double-quoted — savestate "/tmp/my save.azst" (inside quotes, \ escapes the next char). The tokenizer is quote-aware, so every path-bearing command (savestate, loadstate, loadsnapshot, screenshot, script load) handles spaces.

Input injection

Drive the machine with no window — navigate the NextZXOS browser and launch programs headlessly.

Tokens map to the ZX key matrix; cursor keys use the NextZXOS browser mapping (down = key 6, up = key 7). Keys only advance while the engine is running (continue), not while paused — e.g. down×N then enter to launch a browser entry.

Scripting & session

See Rhai scripting for the scripting layer.

get — state interrogation

get <path> walks the machine’s serialized state tree — the same fields the savestate captures — and prints the addressed value as JSON. Paths are dotted, with [index] for arrays:

get bus.memory.mmu.slots        → [255,255,10,11,4,5,0,1]   (the 8 MMU slot banks)
get bus.next_regs.regs[192]     → 8                          ($C0 raw, decimal index 192)
get bus.ula.frame               → 1386                       (the ULA frame counter)
get cpu                         → {…}                         (the whole CPU sub-object)

Useful roots: cpu, bus, bus.memory.mmu.slots, bus.next_regs.regs (the raw 256-entry nextreg array — the stored/written byte), bus.layer2.*, bus.lores.*, bus.sprites.*. A missing field replies no such field: <name> and an out-of-range index index N out of range, so you can probe the tree incrementally. Large RAM blobs are elided.

Example session

> state
pc=0C8F sp=5BF3 af=0344 bc=02DF de=7D30 hl=5C3B ix=DBD0 iy=5C3A i=09 im=1 iff=11
> nr 22
nr 22 = 00 (raw 00)
> bp add pc 0x8000 if a == 0x1e
bp #0 added
> mem 0x4000 8
4000  00 00 FE 01 FE 01 FE 00
> screenshot /tmp/frame.png layer2,sprites
saved screenshot (640x256) to /tmp/frame.png
> c
running

For automation, layer conditions and reacting to hardware events, build on ADP with Rhai scripting.