# Built in Debugger

The Debugger is a 6502/Z80/ARM disassembler and monitoring tool. When the debug window is first opened it leaves BeebEm running. It's best to leave the Freeze when inactive option switched off (which happens automatically when you open the Debugger window) otherwise BeebEm will only run when you bring the main window to the front.

The Debugger provides the following controls:

Control | Description
--- | ---
Break | Stops BeebEm running. If currently executing in the OS or ROM area and OS/ROM debug is not enabled then BeebEm will only stop when execution moves out of the OS/ROM. When execution stops the current instruction is displayed
Continue / Cancel | Starts BeebEm running
Trace | Shows accesses to the various bits of hardware
Break | Breaks execution when the hardware is accessed
BRK instruction | Breaks when the BRK instruction is executed
Attach to Host | Debugs the host processor
Attach to Parasite | Debugs the Tube second processor
Attach to ROM | Debugs the ROM code (addresses 8000-BFFF)
Attach to OS | Debugs the OS code (addresses C000-FFFF)
Breakpoints | Breaks execution when the address hits one of the configured breakpoints
Watches | Shows contents of configured memory locations
Execute Command | Runs the debug command entered into the command box

The disassembler shows the following information:

> Address OPCodes Instruction A X Y SR Flags

Parasite instructions are shifted right so it's easier to follow both host and parasite when debugging tube code.

## Debugger Commands

Parameters in [] are optional. p can be specified in some commands to specify the parasite (Tube) processor. Labels (preceded by a ".") may be used in place of addresses.

Command | Aliases | Description
--- | --- | ---
breakpoint <start>[-<end>] [<name>] | b, bp | Set or clear a breakpoint or break range. The breakpoint can be given a name, which defaults to the label for the start address if name is not given
labels <load|show|clear> [p] [<filename>] | l | Load labels from a VICE or Swift / BeebAsm format file, display known labels, or clear all labels
help <item> | ?, q | Display help for the specified command or memory address
break | . | Break or continue
set <option> <on|off> |  | Turn various UI checkboxes on or off. The option parameter should be one of the following: host, parasite, rom, os, endian, breakpoints, decimal, brk
next [<count>] | n | Execute the specified number instructions, default 1
over | o | Step over JSR (host only)
peek [p] [<start>] [<count>] | m | Dump memory to the console. If not given, the start address continues from the last memory region dumped
code [p] [<start>] [<count>] | d | Disassemble the specified memory range. If not given, the start address continues from the last address disassembled
watch [p] <addr> [<b|w|d>] [<name>] | e | Set or clear a byte, word, or dword memory watch at a given address. The watch can be given a name, which defaults to the label for the given address if name is not given
state <device> | s | Display device state. The device option is one of: v (Video), u (User VIA), s (System VIA), e (Serial), n (Econet ADLC), t (Tube), m (Memory), or r (ROMs)
save [<count>] [<filename>] | w | Write console lines to file. If filename is not given, a file prompt is shown
poke [p] <start> <byte> [<byte> ...] | c | Write bytes to memory
goto [p] <addr> | g | Jump to address
file <r|w> [p] <addr> [<count>] [<filename>] | f | Read or write memory at address from/to file. If filename is not given, a file prompt is shown
echo <string> | ! | Write the given string to the console
script [<filename>] |  | Execute a debugger script. If filename is not given, a file prompt is shown
clear |  | Clear the console

## Scripting

Batches of debugger commands can be executed from script files, using the script command or the -DebugScript command line option. Script files can contain comments, preceded by either # or ;.