Repository navigation
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.
| 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: 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.
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).
- While the count is 22000 NOPs or less, a line shows the difference to 19968 NOPs (one frame of a CPC):
+when the count is less than a frame,-when it is more.
- 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.
-
Export .asm... saves a range of memory as RASM source. Give the first and the last address. Each jump and call target gets a label (the name from the symbols when there is one). The export is assembled again with RASM: what does not give back the same bytes is written as
db, so the file always assembles to the same bytes.
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 setAF2 BC2 DE2 HL2. - Flags:
SF ZF HF PF NF CF. -
HITS(the number of hits),BANK,ROM,MMR. - Memory:
[addr]orMEM(addr)(a byte),WORD(addr),BIT(v,n). - Numbers:
&FF,$FFor 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 (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.
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. A scope for each channel, and Mute A, Mute B, Mute C (the sound only: the chip does not change) |
| 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 |
-
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.
-
Search: find bytes (in hex,
??is any byte), text (with Any case) or a 16-bit word. Search the Z80's 64K or all the RAM. Up to 1000 results; a click shows one in the hex view.
Window → Watches: a list of addresses and their values, live.
- Type an address (
&C000,#C000,$C000,0xC000,C000hor a decimal number) or a label, with an offset if you want (table+2,buffer-&10). Choose byte or word, then Add. - A value that changed shows in another colour for a second.
- Click a value, type a new one and press Enter to write it into memory.
- The watches are kept in
cpcse.ini.
- 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.
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.
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
&F8xxto&FFxxand 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.
Debug → Profiler:
- Press Record and let the program run.
- 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.
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.
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 andname EQU valuefiles).
DeZog (VS Code) and gdb can connect to the emulator. Refer to External debugging.
Start
The machine
Media
Expansions
Tools
Automation
Help