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 little

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)