zxplay_go Debuggers

zxplay_go ships two complementary debuggers:

1. Visual debugger — a Fyne window inside the running GUI, with live-updating panels for registers, flags, disassembly, hex memory, memory paging, and (on Spectrum Next) NextReg state. Best for interactive exploration.
2. Telnet (ZRCP-style) debugger — a line-oriented TCP server you connect to with nc / telnet / a script. Best for scripted reproductions, headless CI runs, and anything you want to drive from a shell pipeline.

Both share the same CPU underneath, so anything you observe in one is observable in the other. You can run both at the same time.

There is also a third, emulator-independent option: hwdebug/ drives a real ZX Spectrum Next over a joystick-port serial cable (dezogif + a standalone DZRP client) — scriptable breakpoints, memory/NextReg reads and .nex loading on actual silicon. Use it for ground-truth A/B runs against either emulator debugger when conformance is in question.

The emulator also ships extensive headless diagnostics (provenance tracer, trace-DB, crash detector, time-travel, …); run zxplay_go --help for the flags.

Contents

• Visual debugger
  • Opening it
  • Layout
  • Toolbar
  • Registers panel
  • Flags panel
  • Disassembly panel
  • Memory hex dump panel
  • Memory-paging diagram
  • Tools tabs
  • Edit Regs / Write Mem dialogs
  • Breakpoint workflow
• Telnet debugger
  • Starting the listener
  • Connecting
  • Protocol shape
  • Address syntax
  • Command reference
  • Implicit pause behaviour
  • Bank-aware breakpoints
  • Symbol-map annotation
  • Worked examples
• Memory watchpoints in headless mode
• Common workflows

Visual debugger

A live, interactive debugger that runs inside the GUI process. It refreshes at ~20 Hz so registers and the disassembly cursor animate as the emulator runs.

Opening it

Emulator → Debugger from the menu bar. The window opens alongside the main emulator window and survives model switches.

Layout

Four main panels arranged in a 2×2 grid, plus a top toolbar and (on Spectrum Next) a right-hand sidebar.

┌──────────────────────────────────────────────────────────┐
│  Toolbar  [Pause] [Step] [Step Frame] [Run] [Go to PC]  │
│           [Edit Regs...] [Write Mem...] [Clear BPs]     │
├──────────────────────┬───────────────────────────────────┤
│                      │                                   │
│   REGISTERS panel    │     DISASSEMBLY panel             │
│   (PC, AF/BC/DE/HL,  │     (Z80 disassembly from PC,     │
│    alt set, I/R, SP, │      click line = breakpoint)     │
│    flags, etc.)      │                                   │
│                      │                                   │
├──────────────────────┼───────────────────────────────────┤
│                      │                                   │
│   MEMORY hex dump    │     PAGE MAP diagram              │
│   ($0000-$FFFF, hex  │     +                             │
│    + ASCII, address  │     TOOLS TABS (Next State /      │
│    entry at top)     │     Bank / Backtrace / History /  │
│                      │     NextReg / Breakpoints /       │
│                      │     Palette / Sprites / Layer 2 / │
│                      │     Tilemap)                      │
└──────────────────────┴───────────────────────────────────┘

Splits between panels are draggable. The graphical Palette / Sprites / Layer 2 / Tilemap tabs are only meaningful on Spectrum Next.

Toolbar

Buttons across the top of the window:

A "running / paused" status indicator sits next to the buttons.

Registers panel

Live readout of every Z80 register the CPU tracks:

• PC — highlighted in yellow. Annotated with the symbol-map name when a symbol is loaded (e.g. PC=$00EF (POST_RESET)).
• AF / BC / DE / HL — main register pairs, shown as 16-bit and as paired 8-bit (A=$3E F=$50 etc.)
• AF' / BC' / DE' / HL' — alternate set (the EXX / EX AF,AF' shadow).
• IX / IY — index registers.
• SP — stack pointer.
• I / R — interrupt vector base + memory-refresh register.
• Interrupt state — IFF1, IFF2, IM (interrupt mode).
• Halted — true if the CPU is in HALT.
• Stack preview — 4 16-bit words from SP upward.

All values are hex unless explicitly labelled. The panel refreshes at 20 Hz so values animate while the emulator runs.

Flags panel

Sits in the top-right of the registers area. Shows the eight Z80 flag bits as individual indicators:

Each flag is shown green when set, dim when clear. Bits 3 and 5 (the "undocumented" Y/X flags) are not shown but are still tracked by the CPU.

Disassembly panel

Scrollable Z80 disassembly starting at the current PC. Every prefix group is decoded:

• Base opcodes
• CB (bit / rotate / shift)
• ED (extended Z80 instructions including Z80N NEXTREG opcodes)
• DD (IX-based)
• FD (IY-based)
• DDCB / FDCB (indexed bit ops)

Annotations:

• A yellow > marks the current instruction.
• A red * marks any active breakpoint at that PC.
• Symbols from a loaded --symbol-map file appear next to addresses (CALL $00EF (POST_RESET)).

Click any disassembly line to toggle a breakpoint at that PC. The line goes red. Click again to clear.

The disassembly window also re-anchors when you click "Go to PC" — you can scroll freely without losing the cursor.

Memory hex dump panel

Full $0000-$FFFF address space, formatted in 16-byte rows with hex columns + ASCII. Live-updates as the CPU writes memory.

A control row at the top:

• Addr: — type an address to jump to. Accepts $XXXX, 0xXXXX, decimal, or octal — the base selector dropdown picks how the field is interpreted.

For Spectrum Next, the dump shows the effective byte at each CPU address — i.e. what an LD A,(HL) would actually read, taking the active MMU slot, ROM bank, and divMMC overlay into account.

Memory-paging diagram

A graphical view of which physical memory page (ROM bank, RAM bank, divMMC ROM/RAM bank) is mapped at each 16-KB (classic) or 8-KB (Next) slot of the CPU's address space.

• Classic models (48K, 128K, +2, +2A, +3): four 16-KB slots, labelled 0x0000-0x3FFF, 0x4000-0x7FFF, 0x8000-0xBFFF, 0xC000-0xFFFF.
• Spectrum Next: eight 8-KB slots, labelled 0x0000-0x1FFF … 0xE000-0xFFFF, plus the divMMC overlay's paged-in state shown as an overlay band.

Slots that are write-protected (ROM) are shown in a different colour from RAM slots. The currently-active ROM bank for the Z80's view is labelled at the top.

Tools tabs

The bottom-right area is an icon-led tab strip (Next State, Bank Inspect, Backtrace, History, NextReg, Breakpoints, Watchpoints, Heatmap, Time Travel, Palette, Sprites, Layer 2, Tilemap). The text panels mirror a feature of the telnet debugger so the two surfaces stay feature-equivalent; the last four are graphical Next inspectors (live-rendered each tick) that match the visual viewers in GUI emulators like jnext:

• 🎨 Palette — the active 256-entry palette as a 16×16 colour-swatch grid (each cell the real expanded RGB of that entry).
• ▦ Sprites — every visible sprite's 16×16 pattern drawn as actual pixels through the sprite palette, tiled into a sheet, with a live count.
• 🖼 Layer 2 — the live Layer-2 framebuffer (256×192) rendered through the Layer-2 palette, with a resolution/enable status line.
• ⛶ Tilemap — the tilemap layer (tiles + attributes) rendered through the tilemap palette.

These read live emulator state and repaint on every pause/step, so you can see what the guest has drawn — even mid-boot. They're the visual counterparts to the telnet palette-dump / sprite-list / layer-state commands.

Shared backend (telnet ↔ GUI)

The visual and telnet debuggers are two surfaces over one shared backend, so state set on either appears (and acts) on the other:

• Breakpoints — one shared store. A set-breakpoint over telnet shows up in the GUI's Breakpoints tab and on the disassembly gutter, and a click-to-toggle in the GUI is listed by list-breakpoints.
• Watchpoints (register watches) — one shared set. watch-reg and the Watchpoints tab edit the same list; a watch fires the CPU pause regardless of which surface added it.
• Time Travel — one emulator-owned snapshot ring. tt-on / tt-snap / tt-rewind and the Time Travel tab (enable, snapshot-now, tap-a-row-to-rewind, clear) drive the same buffer.
• Heatmap tab — hot-PC / call / ret / rst views over the same M1 history ring as hot / callgraph / retgraph / rstgraph (recomputed on demand via its Refresh button).
• The toolbar also has Step Over (run past a CALL/RST to its return) and the register panel shows IRQ taken / rejected counts (the GUI equivalent of step-over and irq-stats).

Watch types other than register watches (watch-mem / watch-read / watch-port / watch-zero) and the streaming trace commands (trace-*, nr-trace, tracepoints) remain telnet-primary — they install hooks that stream to the log rather than mapping to a panel.

Next State

Only meaningful when the emulator is in ModelNext. Lists:

• MMU shadow — slots 0..7 with their current 8-KB page indices.
• divMMC state — paged_in / mapram / automap.
• Selected NextRegs — a fixed set of the most useful registers, listed below.

The fixed NextReg view (chosen for boot-debugging value):

Bank Inspect

A direct front-end for the bank-peek / bank-poke telnet commands. Pick a Kind (ram / rom / altrom / divmmc-ram), set Bank + Off + Len, hit Dump for an xxd-style hexdump of physical bytes — regardless of what the CPU has paged in. Write the same way: type bytes into the Bytes field (space- or comma-separated, hex) and hit Poke.

pool-scan HEXBYTES [KIND] — search every physical bank of KIND (default ram) for a byte pattern, reporting kind:bank:$offset per hit (max 32). Finds where a DOS load or DMA landed regardless of CPU mapping.

This is the surface to use when you want to confirm "what does bank 5 actually contain right now" while bank 0 is mapped, or to pre-stage bytes into alt-ROM buffers before flipping the redirect.

Backtrace

Renders debugger.Backtrace()'s output. Set Depth and hit Refresh (the CPU should be paused). Each line shows the stack address, the 16-bit word, a heuristic classification (from CALL nn / from CALL cc / from RST / speculative), and — for non-speculative frames — three instructions of disassembly at the return target.

History

Front-end for the M1-fetch ring buffer. Prev N shows the last N entries; Full dumps the whole ring. Each row has the global instruction counter, PC, SP, AF, IFF1, IM, Halted, and the active ROM bank.

The ring is shared with the telnet history / prev commands. If you launched with --debugger-history N, both surfaces read from the same buffer; otherwise the visual debugger creates a default 4096-entry ring on first open.

NextReg

Equivalent to the telnet nextreg-read / nextreg-write commands. Type a Reg index, hit Read to dump the value (also shown in binary), or type a Val and hit Write to commit it (firing any OnWrite hooks just like a real NEXTREG $XX,$YY).

Breakpoints

The conditional / bank-filtered breakpoint surface. The form mirrors the telnet set-breakpoint ADDR [bank=N] [if EXPR] syntax:

• PC — target address (hex)
• Bank — ROM bank filter, or -1 for "any bank"
• If — guard expression in the same grammar the telnet debugger accepts (see Conditional breakpoints)

Add commits the entry; tap a row in the list to remove it; Clear all wipes the set. Plain-tap breakpoints (set by clicking a line in the disassembly) appear here too, alongside richer entries.

Edit Regs / Write Mem dialogs

Edit Regs… opens a dialog with one entry per 16-bit register pair. Type a new value (hex by default), Apply. The CPU's register file is updated immediately.

Write Mem… opens a small dialog with two fields: address and byte value. Apply writes a single byte through the normal memory bus — i.e. it goes through MMU translation, ROM-write filtering, divMMC overlay routing, etc.

Breakpoint workflow

1. Pause the CPU.
2. Click the line in the disassembly where you want to break. The line turns red with *.
3. Run. The emulator executes until PC hits that line, then auto-pauses.
4. To clear a single breakpoint, click the same line again.
5. To clear them all, Clear BPs.

Breakpoints set via the visual debugger fire alongside those set via the telnet debugger — there's one shared breakpoint set on the CPU.

Breakpoints are kept in memory only; they are not persisted across bin/zxplay_go restarts.

Telnet debugger

A line-oriented ZRCP-style remote-debug protocol over TCP. One command per line; one response per line; trivially scriptable.

Starting the listener

Pass --debugger-port=N to enable. The listener opens on localhost:N.

./bin/zxplay_go --next --headless --debugger-port=10000

Optional:

You can combine --debugger-port with --headless (CI / scripted) or with the GUI (run the listener in parallel with the visual debugger). Both work.

Connecting

Any TCP client works:

nc localhost 10000

or telnet localhost 10000. On connect you'll see:

OK welcome to zxplay_go remote debugger

Type help for the command list.

Multiple connections are allowed; they share the CPU. Each command runs to completion atomically — there's no command interleaving.

Protocol shape

• Plain text. One command per line, LF or CRLF terminated.
• Case-insensitive command words.
• Hex arguments accept $XXXX, 0xXXXX, or bare hex (e.g. 5C3A).
• Decimal is not accepted in addresses or values — Spectrum addresses are universally written in hex.
• Every response begins with OK on success or ERR on failure so scripts can parse by prefix.
• One line of output per command, except disassemble which spans multiple lines (one per instruction).

Address syntax

All of these are equivalent:

$5C3A
0x5C3A
5C3A
0X5C3A

Trailing whitespace is trimmed. Numbers larger than 16-bit error out.

Command reference

CPU control

Inspection

Mutation

Breakpoints

Tracepoints (non-halting)

Interrupts

NextReg snapshots

Heatmaps

Time-travel buffer

An in-memory rolling ring of full-state emulator snapshots. The buffer auto-captures every N Z80 instructions while the CPU runs; the user can then tt-rewind to restore state to any captured moment, or tt-find-pc to locate every snapshot that passed through a given PC. Backed by the same snapshot machinery that powers snapshot-on-bp (CPU + visible 8 RAM pages + 7FFD/1FFD + border colour).

Capture scope. On classic models the Phase-1 snapshot (CPU + visible 64 K + border + 7FFD/1FFD) is loss-free. On the Next, each snapshot additionally captures the complete machine state (Phase 2b): the full 2 MB RAM pool (all 128 × 16 K banks, not just the visible 8), the MMU8 slot table (NR$50-$57), the divMMC RAM (16 × 8 K), the entire 256-byte NextReg file, and the paging ports. tt-rewind restores all of it, so forward re-execution from a Next rewind point is faithful — upper-bank state (Layer 2 framebuffer, divMMC channel/descriptor scratch, alt-ROM windows) is fully recoverable.

Cost: on the Next each snapshot is ~2 MB, so the ring is ~KEEP × 2 MB (logged at startup); lower --time-travel-keep if memory is tight. Phase 2a additionally records per-snapshot bank/paging context for tt-status (see below). A future Phase 2c may add changed-bank deltas to shrink the ring.

The --time-travel=N CLI flag (with optional --time-travel-keep=K) installs the same buffer at headless startup — useful for catching boot-time states the user would never have time to manually tt-snap.

Typical workflow on the menu-RETURN freeze:

./bin/zxplay_go --next --headless --time-travel=50000 \
    --debugger-port=10000 --press-key=space@200,enter@600 &
nc localhost 10000
> pause                                # at the freeze
> tt-status
OK time-travel on every=50000 keep=16 entries=12
  insn=50000   PC=$0038
  insn=100000  PC=$11A0
  ...
  insn=600000  PC=$1D47                # crash site
> tt-rewind 550000                     # roll back ~50K insns
OK rewound to insn=500000 PC=$1A6B
> backtrace ; prev 20                  # inspect pre-crash state

Provenance tracer + trace database (headless)

Where time-travel answers "what was the state at time T?", the provenance tracer answers "which instruction wrote this byte?" — the data-lineage axis for cracking bad-jump / corrupt-stack traps. Three headless CLI flags:

Example — find the instruction that jumps into the bank-2 $0000 trap, then who pushed the bad return word:

./bin/zxplay_go --next --headless --frames 400 --why-pc-at '$0000:2'
... why-pc-at: re-entry ... jumped_from=$C02D opcode=$C7
... jumping-instruction provenance (physical) phys_bank=111 phys_off=$002D ...

Query a captured trace DB for control transfers that crossed a ROM bank in the window:

./bin/zxplay_go --next --headless --frames 360 --trace-db /tmp/boot.db
sqlite3 /tmp/boot.db \
  "SELECT a.insn, printf('\$%04X',a.pc), a.bank, printf('\$%04X',b.pc), b.bank
   FROM m1 a JOIN m1 b ON b.seq=a.seq+1 WHERE a.bank<>b.bank LIMIT 20;"

Two trace DBs (e.g. ours vs a reference run) can be diffed with the _tools/tracediff helper, which prints the first aligned row where PC / bank / SP / registers differ — the first-divergence finder.

Crash detection

Heuristic patterns that nearly always indicate the guest has crashed. Each heuristic fires exactly once per re-arm window — when the failing condition clears the heuristic re-arms so a later crash is still caught. Fires log an slog.Info("crash-detected") line with kind, pc, detail, and the instruction count.

Five heuristics:

• nop-slide — PC walking through N consecutive $00 opcodes. Catches the guest falling through past valid code into a zero-filled region.
• sp-low — SP drops below a chosen threshold. Catches stack underrun (popped past the stack base).
• sp-high — SP rises above a chosen threshold. Opt-in; many routines legitimately push past high SP, so this stays off by default.
• pc-region — PC enters a forbidden range (e.g. screen RAM $4000-$5AFF). Opt-in — Layer 2 framebuffer reads can look like screen-RAM execution on the Next, so the default is no regions.
• halt-no-iff — HALT executed with IFF1=0. Only NMI can wake the CPU, in practice a true deadlock.

Live workflow: pause at the suspect moment → crash-detect on → crash-detect pause-on-fire → continue → CPU halts at the offending PC; backtrace, prev 50, and disasm are then positioned exactly at the crash site.

Snapshots on hit

Foreign-emulator comparison

When a workload boots correctly under one emulator but not another, the fastest path to the divergence is a state diff at a chosen sync point. compare-foreign fetches a snapshot from another emulator via that emulator's debug protocol, builds our own snapshot at the moment of invocation, and renders a side-by-side diff highlighting only the differing fields. Provider plugins live in cmd/zxplay_go/foreign_*.go.

To add a provider (a gdb-stub backend, real hardware via a Pi probe, …): implement ForeignProvider / ForeignEmulator in cmd/zxplay_go/foreign_<name>.go and register it via init(). The diff command is provider-agnostic — adding one is roughly 150 LoC of protocol adapter plus a foreignRegister(yourProvider{}) call.

Worked example — boot-divergence isolation (reference-emulator details elided per project policy; substitute your own reference binary + remote-protocol port number below):

$ ./bin/zxplay_go --next --headless --debugger-port=10000 &       # ours
$ /path/to/reference-emulator --remote-protocol-port 10020 &  # foreign
$ nc localhost 10000
> compare-foreign PROVIDER localhost:10020 nr=03,04,8E,8C,56,57 bank=0
OK compare-foreign
  mine    = zxplay_go (self)
  foreign = PROVIDER@localhost:10020

--- NextRegs ---
  NR$04: $00  != $03  *
  NR$56: $DE  != $00  *
  NR$57: $DF  != $01  *
  NR$8E: $03  != $08  *
  NR$8C: $00
  NR$03: $B0  != $B3  *

--- RAM bank 0 (16K) ---
  size: mine=16384 foreign=16384  match=5428/16384 (33.1%)
  first divergence at offset $0000
  mine    $0000: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 …
  foreign $0000: F3 C3 25 01 45 30 06 42 C3 EC 05 2A 2E 2A FF 00 …

Combined with load-bin ram 0 0 /path/to/zes_bank0.bin, you can OVERLAY the foreign state on ours and ask "does our boot progress correctly from this state?" to isolate WHICH of our differences is load-bearing.

Implicit pause behaviour

Commands that read CPU or memory state are dangerous to run on a running CPU — the read could land mid-instruction. The telnet debugger handles this by implicitly pausing the CPU before any read-state command, and waiting until the headless loop has acknowledged the pause before reading.

The implicit-pause set is:

get-registers, regs, get-stack, stack, backtrace, bt, history,
hist, prev, p, get-memory, mem, hexdump, read-memory, peek,
write-memory, poke, disassemble, disasm, d, get-mmu, get-divmmc,
nextreg-read, nr-r, bank-peek, bank-poke, load-bin, compare-foreign

After an implicit pause, the CPU stays paused. Use continue to resume.

If the CPU is in a tight HALT or otherwise can't cooperate with the pause handshake, the command times out with ERR pause-ack timeout.

Conditional breakpoints

The if EXPR clause attaches a guard expression evaluated at every potential hit. The breakpoint fires only when the expression evaluates true; non-matching hits silently continue. Combines naturally with bank=N: the bank filter cheaply rejects most fetches before the guard runs.

> bp $6010 if iff1 == 0
OK breakpoint @$6010 if iff1 == 0
> list-bp
OK $6010 if iff1 == 0

The expression grammar (small enough to write by hand, large enough for compound guards):

expr  := term  ( "||" term )*
term  := cmp   ( "&&" cmp  )*
cmp   := atom OP atom        | atom "in" range
OP    := "==" | "!=" | "<" | "<=" | ">" | ">="
range := atom "-" atom
atom  := hex | dec | reg | "read" atom
hex   := "$" XX..XX  |  "0x" XX..XX
reg   := pc | sp | a | f | b | c | d | e | h | l | ix | iy |
         iff1 | iff2 | im | halted | bank |
         dmmc | automap | mapram | conmem

read $ADDR performs a Memory.Read at evaluation time — same path the guest CPU sees, so MMU paging / divMMC overlay / alt-ROM redirect resolve correctly. bank is the current ROM bank (0..3) mapped at $0000-$3FFF.

The divMMC paging predicates (dmmc = paged-in, automap, mapram, conmem) mirror the get-divmmc fields and resolve to 0/1. They are the faithful fix for low-PC bank aliasing: a PC in $0000-$1FFF executes enNxtmmc, a NextZXOS bank, or the bootrom depending on whether divMMC is paged, so an any-bank breakpoint can land on the wrong instance. set-breakpoint $0814 if dmmc == 1 halts only on the divMMC-paged visit — replacing the old if iy < $8000 heuristic. Combine for precise modes, e.g. if automap == 1 && conmem == 0.

Worked examples:

bp $0066 if iff1 == 0                    # NMI vector only when masked
bp $6010 if iff1 == 0 && halted == 0     # the HALT-about-to-fire moment
bp $0038 if a != $80                     # IM 1 vector with an odd register
bp pc in $1FFA-$3FFF if bank == 0        # NOT VALID: pc-in-range guards need an
                                          # outer PC anchor, since the bp itself
                                          # is anchored to ADDR. Use the EXPR for
                                          # state filters; range is for atoms
                                          # (e.g. `a in $80-$FF`).

Bank-aware breakpoints

The Spectrum Next has four 16-KB ROM banks visible at $0000-$3FFF (switched via NextReg $8E or the legacy 7FFD/1FFD ports). The same PC means different code in different banks.

A plain set-breakpoint $1B67 fires whenever PC hits $1B67, regardless of which bank is mapped — usually unhelpful, because three of the four banks have unrelated code at that address.

set-breakpoint $1B67 bank=2 fires only when ROM bank 2 is mapped at $0000. The CPU side checks the bank on every break-test; mismatches don't halt the emulator.

Use get-mmu to see the current bank:

> get-mmu
OK rom_bank=2 slots=FF FF 0A 0B 04 05 00 01

Symbol-map annotation

A symbol-map file is plain text with one symbol per line:

# Lines starting with # or ; are comments.
$0000   RESET_ENTRY
$00EF   POST_RESET
$3BE8   SOFT_RESET_TRAMPOLINE

Pass it via --symbol-map=PATH. When loaded, get-registers, get-stack, disassemble, and list-breakpoints annotate addresses with their names.

_tools/nextzxos.sym ships in the repo with the well-known boot-ROM entry points labelled.

Worked examples

Step through the cold-boot sequence

./bin/zxplay_go --next --headless --debugger-port=10000 \
            --debugger-pause-at-start \
            --symbol-map=_tools/nextzxos.sym &
nc localhost 10000

OK welcome to zxplay_go remote debugger
> get-registers
OK PC=$0000 (RESET_ENTRY) SP=$FFFF AF=$FFFF BC=$FFFF … insns=0
> step
OK stepped
> step
OK stepped
> get-registers
OK PC=$00EF (POST_RESET) SP=$FFFF AF=$FFFF … insns=2
> disasm
OK
  00EF  ED 91 07 03  NEXTREG $07,$03
  00F3  ED 91 03 B0  NEXTREG $03,$B0
  00F7  ED 91 C0 08  NEXTREG $C0,$08
  …

Bank-aware breakpoint

> set-breakpoint $1B67 bank=2
OK breakpoint @$1B67 (bank=2)
> continue
OK continuing
… (the emulator runs until bank 2 is mapped and PC hits $1B67)
> pause
OK paused
> get-registers
OK PC=$1B67 (BANK2_POST_LDIR_CALL_00A3) SP=$5BFB AF=$FFA8 … insns=475797

Inspect sysvars

> read-memory $5C3A
OK $FF
> get-memory $5C3A 16
OK FF 1C 00 00 00 00 00 00 00 00 00 00 00 00 00 00

$FF at $5C3A (ERR_NR) and $1C at $5C3B (FLAGS) is the standard post-NEW state for 128K BASIC.

Walk past a HALT

> disasm $34 8
OK
  0034  CC F2 FF     CALL Z,$FFF2
  0037  FF           RST $38
  0038  FB           EI
  0039  …

Toggle divMMC automap mid-boot

> nextreg-read $0A
OK $00
> nextreg-write $0A $10
OK
> get-divmmc
OK paged_in=false mapram=false automap=true

Poke a byte and verify

> write-memory $4000 $AA
OK
> read-memory $4000
OK $AA

Trace what code led up to a breakpoint hit

--debugger-history=N records the last N M1 fetches in a ring buffer. At a breakpoint, prev N dumps the lead-up — by the time most "why did the CPU end up here?" questions get asked, the relevant instructions have already executed and the only way to inspect them is through a history trace.

./bin/zxplay_go --next --headless --debugger-port=10000 \
            --debugger-history=64 \
            --debugger-pause-at-start

> bp $6010 if iff1 == 0
OK breakpoint @$6010 if iff1 == 0
> continue
OK continuing
*** breakpoint at $6010
> prev 12
OK
  insn=16185725   $1FC9  SP=$FFF9 AF=$07A3  IFF1=false IM=1 Halted=false  bank=0
  insn=16185726   $1FCA  SP=$FFFB AF=$07A3  IFF1=false IM=1 Halted=false  bank=0
  insn=16185727   $1FCB  SP=$FFFD AF=$07A3  IFF1=false IM=1 Halted=false  bank=0
  insn=16185728   $1FCC  SP=$FFFD AF=$07A3  IFF1=false IM=1 Halted=false  bank=0
  insn=16185730   $1FCF  SP=$FFFD AF=$0701  IFF1=false IM=1 Halted=false  bank=0
  insn=16185732   $1FD2  SP=$FFFD AF=$3E01  IFF1=false IM=1 Halted=false  bank=0
  insn=16185734   $1FD5  SP=$FFFD AF=$3D39  IFF1=false IM=1 Halted=false  bank=0
  insn=16185736   $1FD8  SP=$FFFD AF=$3D83  IFF1=false IM=1 Halted=false  bank=0
  insn=16185737   $1FE0  SP=$FFFD AF=$3D83  IFF1=false IM=1 Halted=false  bank=0
  insn=16185739   $1FE3  SP=$FFFD AF=$3D83  IFF1=false IM=1 Halted=false  bank=0
  insn=16185740   $600A  SP=$FFFF AF=$3D83  IFF1=false IM=1 Halted=false  bank=0

The SP transitions $FFF9 → $FFFB → $FFFD → $FFFF make the "three POPs + RET" sequence visible at a glance: the final RET at $1FE3 pops the pre-reset stack frame all the way back to $600A. Without the history ring, reconstructing this took a manual env-var-driven trace + several emulator restarts last session — see project_next_post_soft_reset.md for the full investigation.

Note: history records PC + key register state, NOT memory. True "rewind" (restore SRAM to a past moment) needs full memory snapshots which the snapshot machinery covers separately.

Inspect the call ancestry at a HALT

When the CPU has wedged at a HALT and you need to know how it got there, backtrace walks the stack and classifies each word. Words preceded by a CALL nn opcode are "real" return addresses; those preceded by RST n opcodes are tagged as from RST; everything else is speculative (probably data left on the stack by a PUSH or just uninitialised RAM).

> bp $6010 if iff1 == 0       (once conditional breakpoints land)
> continue
*** breakpoint at $6010
> backtrace 8
OK
  SP = $FFFB  IFF1=false  IM=1  Halted=false
  $FFFB: $0001   from RST  RST $00 @ $0000
          0001  C3 6A 00     JP $006A
          0004  EA 00 ED     JP PE,$ED00
          0007  8A           ADC A,D
  $FFFD: $600A   from CALL nn  CALL $6AFB @ $6007
          600A  C3 10 60     JP $6010
          600D  FF           RST $38
          600E  FF           RST $38
  ...

The "CALL $6AFB @ $6007" annotation tells you exactly which CALL site pushed this return address — saving the manual hex dump

• Z80 decode I had to do to crack #149's "the RET pops a

boot.bin pre-reset stack frame" insight.

Clean exit

> quit
OK bye

The connection closes; the TCP listener and emulator stay running.

Memory watchpoints in headless mode

For batch / CI investigations where the GUI debugger isn't running, two headless flags cover the workflow:

--watch-writes NAME@ADDR[=VAL][,…]

Logs every guest write to ADDR. The slog event includes the source PC plus the full routing context at the moment of the write — ROM bank, alt-ROM shadow (NR$8C), MMU0/MMU1 slot values, and divMMC paged/E3 state — so a hit on a $0000-$3FFF address is immediately attributable to the right overlay (machine ROM vs esxDOS vs divMMC RAM bank) without a second run.

ZX_GO_USE_FPGA_BOOTROM=1 ./bin/zxplay_go --next \
    --watch-writes "DRIVE-STATE@E579" \
    --dump-state 600 \
    --log-level=debug 2>&1 | grep watch-write

… DEBUG watch-write name=DRIVE-STATE addr=$E579 val=$20 pc=$4045 rom_bank=3 alt=$C0 mmu0=$FF mmu1=$FF div=paged=true,E3=$00
… DEBUG watch-write name=DRIVE-STATE addr=$E579 val=$02 pc=$11DE rom_bank=3 alt=$C0 mmu0=$FF mmu1=$FF div=paged=true,E3=$00
…

Break-on-write: NAME@ADDR=VAL

Append =VAL to upgrade a watch entry into a break-point. When a write of the matching value lands at ADDR, headless mode emits the same break-on-write slog event, dumps full state (CPU + sysvars + non-zero NextRegs + every --dump-mem range), and exits cleanly.

ZX_GO_USE_FPGA_BOOTROM=1 ./bin/zxplay_go --next \
    --watch-writes "BUG@E579=15" \
    --dump-mem "E570:20,F660:10" \
    --dump-state 600

If the trap fires, the output includes a full state dump exactly as --dump-state would emit, plus the configured --dump-mem grids. If the trap never fires, the normal end-of-run --dump-state runs as usual.

The value form is the right tool for finding _when_ a specific poisoned byte first appears. The log form (no =VAL) is for catching the _writer_ of any value, e.g. when reverse-engineering which routine touches a sysvar.

--dump-mem ADDR:LEN[,ADDR:LEN…]

Adds arbitrary memory ranges to --dump-state and to the dump emitted by a break-on-write trap. Ranges are formatted as 16-byte hex rows.

$ ./bin/zxplay_go --next --dump-state 600 --dump-mem "E570:20,F660:10"
…

Memory $E570..$E58F:
  $E570: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
  $E580: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

Memory $F660..$F66F:
  $F660: 80 00 00 00 00 80 00 00 00 00 00 00 00 00 00 00

Reads go through Memory.Read, so they resolve through whatever paging / overlay state is active at dump time (MMU8 slots, alt-ROM, divMMC, FPGA bootrom). Same view the guest CPU would see — never the raw bank backing store.

--detect-uninit — uninitialised-memory read detector

Answers the question that step-tracing and disassembly can't: when a register or pointer holds a garbage value, is it sourced from uninitialised RAM (a missing init step) or computed from bytes the guest actually wrote (a logic / emulation bug)?

On enable, Memory.EnableUninitTracking() marks every allocated RAM byte "not yet written by the guest" — crucially, the power-on cold-RAM fill does not count as a write, so power-on garbage stays flagged. Every guest Write then marks its byte written; a Read of a byte the guest never wrote fires the detector, logging the source PC plus the unified-pool location (bank16k, off). Default off → zero hot-path cost; gated behind a single if m.TrackUninit in the RAM read/write paths.

# Flag uninitialised reads made by code in the NextZXOS SD driver window
$ ./bin/zxplay_go --next --headless --frames 480 \
    --detect-uninit --detect-uninit-pc '$1E00-$1FFF' --detect-uninit-cap 40
DEBUG uninit-read pc=$1ED5 addr=$E022 bank16k=111 off=$2022
DEBUG uninit-read pc=$1ED8 addr=$E023 bank16k=111 off=$2023
DEBUG uninit-read pc=$1EEC addr=$E01C bank16k=111 off=$201C
…

The example reads pc=$1ED5+ show the SD driver pulling a block-address struct out of $E01C-$E02B (RAM bank 111 = $6F) that the guest never initialised — i.e. the garbage LBA is uninitialised RAM, so the fix is to find the missing initialiser (--watch-writes that address), not to hunt an arithmetic bug.

Flags:

• --detect-uninit — enable. Implies --log-level=debug.
• --detect-uninit-pc $LO-$HI — only log reads whose PC is in the window (hi optional). Same syntax as --trace-pc-range. Without it, every uninitialised read logs — very noisy during early boot (stack, scratch buffers), so a window is usually essential.
• --detect-uninit-cap N — stop after N distinct (pc,addr) reports (default 200). Reports are deduped by (pc,addr); the same site read twice logs once.

Notes / limits:

• Tracks the unified RAM pool (Memory.ram, all 128 × 16K banks) via the MMU8 and classic read/write paths. ROM reads and peripheral-served reads are not RAM and never flagged. Config-mode $0000-$3FFF window writes during the bootrom phase are not tracked (that phase is all "writes" anyway).
• It flags every uninitialised read, not just pointer-flowing ones — filter by PC window to the code you're investigating.
• Memory.UninitReadObserver is the programmatic hook (signature func(addr uint16, bank16k int, off uint16)); the headless wiring in cmd/zxplay_go/uninit_cmd.go captures the CPU to add the PC, dedupe, and cap. Telnet/visual wiring can reuse the same observer.

--watch-bank-write BANK:LO-HI

Logs guest writes that land in a specific unified-pool 16K bank at a byte-offset range, keyed on the pool location — unlike --watch-writes (which keys on the CPU address and so conflates every bank that was ever paged there). Format BANK:LO-HI[,…] (bank decimal, offsets hex with $/0x; -HI optional). The companion to --detect-uninit: once the detector flags an uninitialised read at (bank,off), this answers "is that byte ever written, and by whom?"

# Is the struct the SD driver reads (bank 111 $201C-$202B) ever written?
$ ./bin/zxplay_go --next --headless --frames 700 --watch-bank-write '111:$201C-$202B'
# (no output) → never written by the guest → missing initialiser, not
# a late-ordering write. Widen the range to see neighbouring fields
# that ARE written and by which PC.

Implemented via Memory.SetRAMWriteHook (already bank-aware: fires with the 16K bank index + offset on every RAM write), chained so it composes with the debugger's existing write hook.

--time-travel and related flags

Headless launch of the time-travel buffer. Installs the same in-memory ring as the telnet tt-on command but at boot time, so the early instructions are captured before a debugger session even attaches.

./bin/zxplay_go --next --headless --time-travel=10000 --time-travel-keep=64 \
    --debugger-port=10000 --frames=500000 &
nc localhost 10000
> pause
> tt-rewind 50000
OK rewound to insn=50000 PC=$1B40

See the runtime Time-travel buffer section for the live command reference, scope limitations, and example workflow.

--crash-detect and related flags

Drives the same heuristic crash detector as the telnet crash-detect command, but from launch rather than after a pause. Useful in headless CI runs that need to fail fast when the boot wanders off the rails.

./bin/zxplay_go --next --headless --frames 50000 --crash-detect \
    --snapshot-every 5000 --snapshot-prefix /tmp/snap_

--crash-detect enables the conservative default set (nop-slide=32, sp-low=$4000, halt-no-iff). Per-heuristic flags override individual fields and can be used alone (without --crash-detect) to enable just one heuristic:

Each fire emits an slog.Debug("crash-detected") line with kind, pc, detail, and the instruction counter, and also emits a snapshot via the same one-shot path as --snapshot-on-pc / --loop-threshold. Re-arm semantics: a fire is silenced until the failing condition clears (NOP run broken, SP returns to bounds, PC leaves region, HALT cleared), so a long-running headless boot won't flood the log with the same fire.

Combining with --trace

Trace channels and watchpoints stack: pair --trace=nextreg,ports,bankswitch with --watch-writes so that when the break fires you have a structured event log showing every NextReg / I/O / paging change leading up to the bug.

ZX_GO_USE_FPGA_BOOTROM=1 ./bin/zxplay_go --next \
    --watch-writes "BUG@E579=15" \
    --trace=nextreg,ports,bankswitch \
    --trace-output /tmp/trace.jsonl \
    --dump-state 600

On break-fire: stdout has the full state dump; /tmp/trace.jsonl has every NextReg / port event from boot to break with PCs and values. From there it's a quick diff against a known-working trace to find the divergence.

Common workflows

"Why is PC wandering through uninitialised RAM?"

./bin/zxplay_go --next --headless --debugger-port=10000 &
nc localhost 10000
> pause
OK paused
> get-registers
OK PC=$FA40 …  insns=170869
> get-stack
OK sp=$FFC6 words=$082D $FA61 $110F …

Top-of-stack $082D is what the most recent RET will pop. Trace backward from there.

"Catch the moment X register changes"

The telnet protocol doesn't have a hardware watchpoint. Use the headless --watch-writes flag instead — see Memory watchpoints in headless mode below.

"Compare CPU state across two runs"

Both get-registers and get-mmu emit single-line output. Diff them with normal shell tools:

diff <(echo regs | nc localhost 10000) <(echo regs | nc localhost 10001)

"Run the visual debugger and the telnet debugger together"

They coexist. Open Emulator → Debugger in the GUI and ALSO pass --debugger-port=N. Both share the CPU and the breakpoint set; mutations from one are visible in the other.

"Reuse my disasm output in another tool"

The disassembly format is stable: 4-digit hex address, two spaces, hex bytes, two spaces, mnemonic. Each line is one Z80 instruction. Safe to feed to awk / grep.

"Find where two emulators first diverge"

For boot-path-faithfulness investigations against a reference Z80 emulator, the bundled scripts in _tools/zrcp/ are the workhorse:

• cold_boot_lockstep.py — single-step both emulators, compare all CPU registers (PC/SP/AF/BC/DE/HL/IX/IY/I/IM) after each instruction. The undocumented F3/F5 bits are masked because they reflect a known emulator-spec divergence (FUSE-style vs reference) and don't typically alter behaviour. On the first divergence, prints both states and surrounding disassembly. Slow (one ZRCP roundtrip per step per emulator) but reliable; expect ~10 minutes for 100K-step divergence.

• cold_boot_bisect.py — exponential-growth + binary-search version: launch both emulators, advance N instructions (using the bulk step N / reference equivalent), compare. If matched, double N and restart. When divergence found, binary-search the bracket by relaunching both with smaller targets. Each restart ≈ 1.3 s; ~14 iterations to bracket a 64K-step divergence ≈ 18 s total. Much faster than lockstep for finding the approximate divergence step. Falls back on the reference emulator's quirks for fine-grain pinpointing (use lockstep inside the bracket for exact instruction).

Both scripts use the step N, cold-reset, and set-reg commands documented above. Output goes to stdout; redirect to a file to save the trace.

Workflow:

1. Launch the reference Z80 emulator with its remote-protocol port open (the bundled scripts hardcode the path to your installed reference binary — see comments at the top of each).
2. Launch our emulator paused at PC=0 with --debugger-pause-at-start --frames=0.
3. Run the bisect script first to locate the bracket in ~30 s.
4. Run lockstep inside the bracket for exact pinpoint.
5. Inspect both emulators' state at the divergent instruction. Common causes: NextReg power-on default mismatch, port read returning different bytes, undocumented opcode flag-bit difference.

For the full list of debug-instrumentation flags (--snapshot-every, --watch-writes, --snapshot-on-pc, --loop-threshold, --trace=…, etc.), see the "Headless mode and debug instrumentation" section in the main README.