Debugging Flycast with gdb‐multiarch

This is a mirror of a page on the wiki for the Sakura Taisen 3 translation project with minor edits.

Flycast being debugged 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


  • 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


I've prepared a binary of Flycast pre-configured to enable the gdb server if you aren't able to compile yourself. It is based on Flycast stable version 2.2 released on October 28, 2023, built with Visual Studio 2022. If you still prefer to build, or if you want a newer version of Flycast, follow the instructions below.

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

    git clone
    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.


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.