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
  • Visual Studio Community 2019 and 2022 have been tested for this guide.
• WSL2

Compiling Flycast

1. Clone the source for Flycast and update submodules, as if building from source normally:

git clone https://github.com/flyinghead/flycast
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, check ENABLE_GDB_SERVER and uncheck USE_DX9.
5. Save CMakeSettings.json to apply these changes.
6. After saving, the ENABLE_GDB_SERVER flag may have been unset. Check that it is still enabled, and if necessary, check the box again and save CMakeSettings.json.
7. Build All. By default, builds are generated in a subdirectory named out.
8. Open Flycast to change settings to your preferences and generate emu.cfg. Close Flycast, then open emu.cfg in a text editor and change the setting Debug.GDBEnabled to yes.

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.