#

# Debugger Documentation

Last updated January 5, 2013
Valid as of Mednafen 0.9.28-WIP

## Notes and Cautions:

Saving and loading states in step mode may lead to malfunctions or emulator crashes/aborts, due to deficiencies in the emulation models coupled with debugger hooks; hence, it is not recommended(though it may work adequately on some emulated systems). This issue will be corrected in a future version.
A similar issue occurs on some emulated systems(e.g. PSX) in regards to triggering power/reset while in step mode.

High-frequency counters(for timers) as seen in the register section of the CPU debugger view may not be updated properly after each step while in step mode on all emulated systems and devices, due to the event system and performance optimizations and deficiencies in the current driver->core interface. This issue will be corrected in a future version.

Opcode, operand, and prefix(in WonderSwan case) fetches will trigger read breakpoints in the NES, PC Engine, and WonderSwan debuggers.

PC breakpoints are evaluated only for the state of PC at the start of the instruction(or start of prefixes for an instruction in the case of V30MZ); IE, a PC breakpoint set on the address of an operand byte(6502, HuC6280, V30MZ) or the second 16-bits of a 32-bit instruction(V810) will not be triggered when the instruction is executed.

When the CPU debugger view is not active, the branch history will only be updated reliably when at least one breakpoint is active/installed.

## Quick Key Reference

Key | Action
--- | ---
ALT+D | Master debugger view toggle.
ALT+1 | CPU debugger view.
ALT+2 | Graphics viewer.
ALT+3 | Memory editor.
ALT+4 | Log viewer.
-/+ | Decrease/Increase debugger background opacity.
CPU Debugger
R | Run
S | Step
T | Toggle disassembly mode. Currently only used for selecting between Intel and AT&T syntaxes for the WonderSwan debugger.
Return | Edit disassembly address, or edit selected register.
SHIFT+Return | Edit watch address.
Space | Toggle PC breakpoint on selected disassembly address.
SHIFT+R | Edit read breakpoints.
SHIFT+W | Edit write breakpoints.
CTRL+SHIFT+R | Edit I/O read breakpoints(for PC-FX and WonderSwan; I/O instructions on VB go through regular read/write breakpoints).
CTRL+SHIFT+W | Edit I/O write breakpoints(for PC-FX and WonderSwan; I/O instructions on VB go through regular read/write breakpoints).
CTRL+R | Edit Aux read breakpoints.
CTRL+W | Edit Aux write breakpoints.
SHIFT+O | Edit opcode breakpoints(PC Engine only for now).
Up, Left, Right, Down, PageUp, PageDown | Select disassembly address or select register.
SHIFT + (Up, Left, Right, Down, PageUp, PageDown) | Select watch address.
M | Toggle watch window between logical and physical(if available) addressing.
P | Poke a value to memory.
SHIFT + P | High-level poke a value to the underlying ROM or RAM.
Graphics Viewer
< | Decrease palette bank number.
> | Increase palette bank number.
Up, Down | Scroll up or down.
Left, Right | Select graphics layer.
-/+ | Select line number(not necessarily visible line number...) to decode graphics on.
Memory Editor
> D | Dump memory from the selected address space to a file. Two specification string are recognized:
>     start_address end_address(inclusive) filename

>     Example: 0 1fff dump.bin
> and
>     start_address +count filename

>     Example: 0 +2000 dump.bin
L | Load memory from file into selected address space. Uses the same format of specification string as the "dump memory" function.
S | Byte(hex)-string search.
R | 8-bit relative byte-string search.
T | Text search.
<, > | Select address space.
Up, Down, Left, Right | Move the cursor around and possibly scroll.
PageUp, PageDown | Scroll up, or scroll down, one page(256 bytes).
Home | Move cursor to address 0.
End | Move cursor to the end of the address space minus 16.
Insert | Enter edit mode.
Log Viewer(PC Engine CD and PC-FX only for now)
T | Toggle logging on/off.

## Memory Poking

High-level poking will attempt to write the desired value to the underlying storage(ROM or RAM). Normal(low-level) poking will go through the same write handlers as the virtual CPU operates through. Note that high-level poking is not implemented for all systems.

The format for the string to enter when poking memory(highlevel or lowlevel), is "[*]address value [size]", with values in brackets being optional. Prefixing the address with a "*" will cause the address to be treated as a physical address, which is currently only meaningful on systems that have paging registers internal to the CPU, such as the PC Engine/TurboGrafx 16.

## Read and Write Breakpoints

You may enter either a single address to break on, or a range. Read and write breakpoints operate on logical addresses, unless you prefix the address with a "*", or the first address in the case of a range.
Exception: WonderSwan read/write breakpoints only operate on 20-bit physical addresses for the time being. Furthermore, only the lower 8 bits of WonderSwan I/O breakpoints are considered.

Multiple entries should be separated by one space character. Examples:

       2000-2007 4014 4015
       0000 1800 2300-23ff
       *1fe000

You may also use "segment:offset" form with absolute addresses with PC Engine emulation, such as:

       *ff:0000-ff:03ff

...which will cause a break on any writes to the VDC, including the ST0, ST1, ST2 instructions. Note that the offset is internally ANDed with 0x1FFF, so 0x2000 and 0x0000 would be equivalent offsets.

WonderSwan notes:
Segment(16-bit):offset(16-bit) form can also be used with the WonderSwan debugger, but you still need to prefix it with a "*", even though logical address breakpoints aren't supported with WonderSwan emulation currently. Also, the segment:offset pair is internally translated to a 20-bit address, and because segments overlap, you can get breakpoints to occur on writes with other segments than the one you specified.

### Aux Read and Write Breakpoints

Aux r/w breakpoints operate on secondary storage reads and writes.

PC-FX
00000-3FFFF | KING Page 0
40000-7FFFF | KING Page 1
80000-8FFFF | VDC-A
90000-9FFFF | VDC-B

PC Engine
0000-7FFF | VDC
10000-17FFF | VDC-B(SuperGrafx only!)