The debugger window

Press Cmd+B on macOS or Alt+B on Linux/Windows (or select Debugger from the status bar menu) to pause emulation and open the debugger tool window. Closing the window restores the previous execution state.

The debugger, Frame Analyzer, and Console operate in separate host windows, allowing them to remain open simultaneously while inspecting CPU, custom chipset, and bus activity. Emulation and register queries are non-intrusive and do not alter hardware state.

Tabs¶

CPU¶

Displays the 68000 register file (D0-D7, A0-A7), status register (SR with decoded flags), program counter (PC), and live disassembly centered on the current instruction. Enter a hexadecimal address in the address input box to inspect code elsewhere in memory; clear the box to return to the active PC.

Chipset¶

Decodes custom chipset registers in real time: raster beam position, frame counter, DMACON, INTENA, INTREQ, Copper pointers (COP1LC, COP2LC, COPPC), display window controls (BPLCONx, DIWSTRT, DIWSTOP, DDFSTRT, DDFSTOP), bitplane and sprite pointers, and color palette entries.

Copper¶

Dedicated Copper list inspector and disassembler. Shows COP1LC, COP2LC, active Copper PC, and execution state (running, waiting, or halted).

• CBreak +/-: Toggles a Copper breakpoint at the specified hex address.

• CStep (C): Steps forward by one Copper instruction (advances through WAIT instructions to the subsequent instruction).

Video¶

Displays the active display pipeline configuration and provides bitplane and sprite layer isolation toggles:

• Toggle individual bitplanes (1-8) or sprites (0-7) to isolate visual elements without altering collision detection or emulation state.

• Decodes sprite registers (SPRxPOS, SPRxCTL), armed status, and DMA line counts.

• Displays full 32-color (OCS/ECS) or 256-color (AGA) palette grids.

Audio¶

Decodes Paula audio channels (0-3) and expansion sound devices (CD-DA, MT-32, Coppersynth, Toccata, MHI). Displays channel DMA state machine status, period, volume, active buffer pointers, and real-time audio waveform scopes. Channels can be muted individually.

Memory¶

Hexadecimal and ASCII memory dump viewer (256 bytes per page).

• Find: Searches memory for specified byte sequences.

• Save...: Dumps address ranges to a file.

• Writer?: Queries the reverse execution snapshot ring to identify the instruction that last wrote to the specified address.

• Bits: Displays raw 1-bit-per-pixel bitplane visualizations with configurable stride.

IO Map¶

Interactive memory map of custom chipset registers ($DFF000 - $DFF1FE). Selecting a register decodes its individual bitfields (e.g. DMACON, INTENA, BPLCON0, ADKCON).

Break¶

Manages active breakpoints, memory watchpoints, and custom register write traps.

Wave¶

Interface for arming and configuring VCD logic analyzer waveform exports (see Waveform export (VCD logic analyzer)).

Breakpoints, watchpoints, and traps¶

From the Break tab, enter a target address or identifier:

• Break: PC breakpoint. Execution halts before the instruction executes.

• Watch: Memory watchpoint. Halts when memory at the specified address is modified by CPU, Blitter, or DMA channels.

• Reg: Custom register write trap (e.g. DMACON or 96). Halts whenever CPU or Copper writes to the register.

• Beam: Raster beam trap. Halts when the beam reaches the specified decimal VPOS (and optional HPOS).

• Catch: Exception vector trap (e.g. irq 3, trap 0, vec 2).

Conditional and counted breakpoints¶

The breakpoint address field accepts conditional expressions and ignore counts:

ADDR [LHS OP RHS] [IGN N]

• Operands: Registers (D0-D7, A0-A7, PC, SR), memory words (M<hex>, e.g. MC00002), or hex constants.

• Operators: EQ, NE, LT, GT, LE, GE, AND (bitwise test).

• Ignore count (IGN N): Skips the first N qualifying hits.

Examples:

• C033C2 D0 EQ 5: Breaks at $C033C2 only when D0 equals 5.

• 40 MC00002 AND 4000 IGN A: Breaks at $40 when bit $4000 of word $C00002 is set, after skipping 10 occurrences.

Transport controls¶

Frame Analyzer¶

Open the Frame Analyzer via the status bar menu to inspect chip-bus slot allocations and memory access patterns.

Beam tab¶

Displays a 2D heatmap indexed by raster beam coordinates (X = colour clock HPOS, Y = scanline VPOS). Each cell indicates which subsystem owned the chip bus during that colour clock cycle (CPU, Copper, Blitter, Bitplane, Sprite, Audio, Disk, Refresh, Idle).

• Picture underlay (U): Overlays the rendered video frame beneath the bus heatmap.

• Beam scrub (B): Progressively displays the frame up to the selected raster position.

• To slot (T): Advances execution until the beam reaches the selected colour clock.

Memory heatmap tab¶

The Memory tab displays a 256x256 grid representing memory activity across configured RAM banks (Chip, Slow, Fast, Motherboard, Zorro II/III). Cells reflect recent read/write activity by subsystem and fade over 32 frames.