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> <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 ;.