Setting up Flycast GDB

Clone dev branch of Flycast

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

Build with GDB Support

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_GDB_SERVER=ON ..
make -j$(nproc)

Enable GDB in Config File

Briefly launch Flycast to make sure config file exists

./flycast

Edit config file to enable GDB

Path on Linux: ~/.config/flycast/emu.cfg

Under "[config]" make sure GDBEnabled is set to yes

[config]
...
Debug.GDBEnabled = yes
Debug.GDBPort = 3263
...

Start GDB Session

Start a gdb with SH4 support, I use gdb-multiarch from my package manager

gdb-multiarch

In the GDB shell run the following commands to configure the GDB session

set arch sh4
set endian big

Note: If run in big endian mode, even and odd instructions will be swapped. This can be worked around by changing lines 37 & 38 in code/debug/debug_agent.h to:

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

And then use set endian little and GDB will work as expected.

Start Flycast Emulation and then connect to running core

target remote :3263

This will pause execution of the game upon connecting

From here you can set breakpoints, instruction step, and read/write memory using normal GDB commands Handy reference: GDB Cheat Sheet

The following commands show a terminal interface of the registers and instructions:

layout asm on
layout regs on

Single Instruction Step

nexti

Pressing Enter with no command typed will just repeat the last command (good for stepping)