Debugging Flycast with gdb‐multiarch

Flycast does not include any debugging features by default, but by compiling it with the gdb server enabled, the gdb debugger can attach to it. gdb-multiarch includes support for the SH-4 architecture, which lends it well to instruction stepping and register monitoring for Dreamcast games. Note that attaching the debugger will reduce performance.

The following instructions are for compiling Flycast in Windows, and using WSL2 to run gdb-multiarch. These instructions are based on a thread by @DerekPascarella and Dreamcast.wiki.

---

Requirements

• CMake
• git
• Visual Studio, with the Desktop development with C++ workload installed
• WSL2

Compiling Flycast

1. Clone the source for the dev branch of Flycast and update submodules:

git clone https://github.com/flyinghead/flycast -b dev
cd flycast
git submodule update --init --recursive

2. Open the directory in Visual Studio and open Project > CMake Settings for flycast.
3. Set the Configuration type to Release.
4. In the CMake variables, click Save and generate CMake cache to load variables.
5. In the newly populated list of variables, check ENABLE_GDB_SERVER and uncheck USE_DX9.
6. Save CMakeSettings.json to apply these changes.
7. A small code change is needed to ensure the debugger prints instructions in the correct order. Open the file core/debug/debug_agent.h. Find these lines and comment them out or delete them:

#define SWAP_32(a) ((((a) & 0xff) << 24)  | (((a) & 0xff00) << 8) | (((a) >> 8) & 0xff00) | (((a) >> 24) & 0xff))
#define SWAP_16(a) ((((a) & 0x00ff) << 8) | (((a) & 0xff00) >> 8))

Add these lines in their place:

#define SWAP_32(a) (a)
#define SWAP_16(a) (a)

8. Build All. By default, builds are generated in a subdirectory named out.
9. Open Flycast to change settings to your preferences and generate emu.cfg. Open emu.cfg in a text editor and change the setting Debug.GDBEnabled to yes.

Installing gdb-multiarch

While a Windows port of gdb-multiarch exists, it is known to be buggy. The native Linux version will be used instead via WSL2.

1. Open WSL and update your Linux environment.
2. Install gdb-multiarch with your distribution's package manager.
3. Open Flycast and load your game, then run gdb-multiarch in the WSL session.
4. Get your PC's local IP address. In the (gdb) shell, run the following commands:

set arch sh4
set endian little
target remote {LOCAL IP}:3263

5. Run these commands to show ASM and registers:

layout asm on
layout regs on

You'll likely need to expand the size of the terminal window to show all of the registers.

6. When the debugger attaches to Flycast, execution will pause. Enter continue or c to resume, and press Ctrl-C to break.
7. To set breakpoints in Dreamcast memory addresses, use pointers instead of plain addresses for the break command, as in break *0x8c177548.

Consult the gdb documentation for more information.