Skip to content

Debugger

WacKEDmaN edited this page Nov 7, 2026 · 3 revisions

Debugger

Open the debugger windows from the Debug menu or the Window menu: Debugger (the CPU), Chips, Memory, Logic analyser, Expansion port, Profiler, and GFX9000 (refer to GFX9000).

While a debugger window has the focus, the keys go to the debugger, not to the CPC.

The Debugger window

Run and step

Button Key What it does
Run / Pause F5 Runs or stops the machine
Into F7 Step into: one instruction
Over F8 Step over: a CALL, RST or block instruction runs to its end
Out Shift+F8 Step out: runs until the current routine returns
Back Shift+F7 One instruction back
Frame back To the start of the frame before
Run back Shift+F5 Back to the last time a breakpoint was hit
Last write to ... Go Type an address, then Go: back to the instruction that last wrote it

The back steps use the timeline (refer to Snapshots, save slots and the timeline). It must be on.

Registers, flags and stack

  • REGISTERS: AF, BC, DE, HL, IX, IY, SP, PC, the shadow set, I, R, IM, IFF1 and IFF2. Type a new hex value in a field to change it.
  • The flags S, Z, H, P/V, N, C, as letters.
  • STACK: the words on the stack, with labels.

TIMING

The machine's clock, counted from a zero that you set:

  • Zero counts from 0 from here. The machine's own clock runs on; only the count shown starts again.
  • T/NOP shows T-states, or NOPs (4 T-states, one microsecond each, as CPC programmers count).

The disassembly

  • The disassembly shows the code with the labels from the assembler or from a symbol file.
  • Follow PC keeps the PC in view.
  • Type an address or a label in the go-to field to show it.
  • Click in the gutter of a line to set or remove a breakpoint.
  • The right-click menu of a line: Toggle breakpoint, Run to here, Set PC here, Show in memory.
  • With the profiler recording, each line shows its share of the time as a bar.

Breakpoints

BREAKPOINTS: type an address (or a label) and a condition, then Add. Each breakpoint can be on or off, and shows how many times it was hit.

Debug → Toggle breakpoint at PC, Remove all breakpoints.

The condition language (also used by DeZog and the command API):

  • Registers: A F B C D E H L AF BC DE HL IX IY SP PC I R IM, the shadow set AF2 BC2 DE2 HL2.
  • Flags: SF ZF HF PF NF CF.
  • HITS (the number of hits), BANK, ROM, MMR.
  • Memory: [addr] or MEM(addr) (a byte), WORD(addr), BIT(v,n).
  • Numbers: &FF, $FF or decimal.
  • Operators: == != < > <= >= && || ! + - * / & | ^ << >>.

For example: A==&3F && HITS>2, [&BE80]!=0, WORD(SP)==&0038.

A breakpoint with no condition stops each time. Labels named BRK... in an assembled program become breakpoints (refer to Assembler).

Watchpoints

WATCHPOINTS (memory): an address, an optional end address ("to"), and read, write or both, then Add. The machine stops on the instruction that reads or writes there.

Debug → Remove all watchpoints.

The Chips window

Live views of each chip, as tabs:

Tab What it shows
CRTC The registers R0 to R17, the counters (C0, C4, C5, C9), VMA, the state of HSYNC, VSYNC and DISPEN
Gate Array The mode, the inks (pens 0 to 15 and the border, as hardware colour numbers), the ROM and RAM configuration, the interrupt counter
Monitor The monitor set, the horizontal flywheel and the vertical lock, the output pins
Plus ASIC The palette, the sprites, the DMA sound channels, the raster interrupt, the split screen, the soft scroll
PSG The AY's 16 registers, as notes and volumes
PPI Port A, port B (reads), port C (writes), the control
Keyboard The 10 x 8 key matrix, as the CPC sees it
Disc The disc controller's state and the drives
Tape The tape's block and position, the motor, the signal

The Memory window

  • Hex: a hex editor. Choose the view: CPU view (as the Z80 sees it, with the ROMs), physical RAM (all the banks), or the ASIC page of a Plus. Type an address or a label to go there. Click a byte to change it. The right-click menu has Watch writes here, Watch reads here and Show in disassembly.
  • Map: one pixel for each byte of a 64K bank. While the window is open, it tags every memory access of the Z80: opcode fetch, operand, read or write, each in its own colour. Code that was also written (self-modifying code, or code loaded while recording) has its own colour. Clear starts again. An option shows only what was touched since the last frame. Click a pixel to show it in the hex view; double-click to show it in the disassembly.

Back in time

  • Back (Shift+F7): one instruction back.
  • Frame back: to the start of the frame before.
  • Run back (Shift+F5): to the last time a breakpoint was hit.
  • Last write to (a field in the Debugger window's toolbar): type an address, then Go: back to the instruction that last wrote that address.

From there, Run or a step replays the inputs as they came.

The logic analyser

Debug → Logic analyser: the machine's signals as traces, one sample a microsecond (one CRTC character).

  • Signals: HSYNC, VSYNC, C-SYNC, DISPEN, INT, HALT, the cassette motor and input, the disc controller's interrupt, the Gate Array mode, the CRTC counters C0, C4, C9, MA and R52, the Z80's PC and the three AY channels. Traces... chooses the signals that are shown.
  • Zoom with the mouse wheel. Two markers measure the time between two points.
  • Keep the newest sample at the right edge follows the live signals.
  • The trigger stops the CPC on a VSYNC, HSYNC or INT edge, a mode change, or a PC value. It fires once: the CPC stops on that sample and the view goes to it.
  • It records only while the window is open.

The expansion port

Debug → Expansion port: the CPC's 50-way expansion connector, and the boards on it.

  • The pins: the 50 pins, numbered as on the connector (odd pins on the left, even pins on the right). Each pin has a lamp that lights while its signal is active and then fades, so a short pulse (/NMI, /RESET, LPEN) can be seen. The colours group the signals: address, data, CPU control, memory map (ROMEN, ROMDIS, RAMRD, RAMDIS), sound and power.
    • A15 to A0 and D7 to D0 show the last I/O cycle.
    • ROMDIS lights while the Z80 runs a ROM from a board: an expansion ROM, the AMSDOS of a 464 (its DDI-1), the Multiface II, or a cartridge on a classic CPC.
    • RAMDIS lights while the Multiface II is paged in.
    • Put the mouse on a pin for what it does, how much of the last second it was active, and how often it switched on.
  • Boards on the bus: each fitted board, with a lamp that lights on an access, its reads and writes each second, the ports it decodes, and its last access. A board that decodes only some address bits shows a bit pattern, for example 1111 10xx xxx0 xxxx (x: either value).
  • Port clashes: the ports that two fitted boards both answer, for example the SSA-1 and the Kempston mouse at &FBEE. A real bus has the same clash. In the emulator, only one of the two boards gets that cycle.
  • I/O log: the last 256 I/O cycles: the time, the PC, IN or OUT, the port, the value and the devices that answered. A cycle that two boards answer is red. Log the boards' space only shows &F8xx to &FFxx and the boards' ports; turn it off to log every I/O cycle.
  • Stop on access: choose boards (or CPC chips). The CPC stops, as at a breakpoint, on an I/O cycle that reaches one of them.
  • It samples only while the window is open.

The profiler

Debug → Profiler:

  1. Press Record and let the program run.
  2. Press Stop.
  • Routines: the time of each routine (entered by a CALL, an RST or an interrupt), its own and with what it calls.
  • Instructions: the busiest instructions.
  • Map: the time spent in each part of the 64K.
  • Click an entry to show it in the disassembly. The disassembly shows the time of each line as a bar.
  • It records only while the window is open.

The raster timing overlay

Debug → Raster timing overlay: a tick on the picture at each place where the program wrote to the CRTC (select and data), the Gate Array (pen, ink, mode/ROM, RAM), the PPI or AY, or the Plus palette, as the beam swept it. A key with the colours is in the top right corner of the picture. Use it to see where in the frame a program changes the colours or the screen.

Symbols

The debugger takes labels from:

  • the assembler window (each assembly);
  • a C build (with the C source lines; refer to C programs);
  • a symbol file given with --symbols, or loaded through the command API (RASM, sjasmplus, pasmo, WinAPE, VICE/TRSE and name EQU value files).

External debuggers

DeZog (VS Code) and gdb can connect to the emulator. Refer to External debugging.

Clone this wiki locally