Subscribe to me on YouTube 
Icons by neorelic

Debug with Gens KMod


► Presentation

Thanks to the awesome work of Graz and some help of Prophet36, GensKMod is now GDB-ready
Version 0.7.2 was the first one which included GDB server but 0.7.3 made debugging with GensKMod an easy thing to do.

► Compilation

To debug a Genny game, you first need to include the debug information on the object used to create the ROM.
If you use SGDK makefile.gen, you should use
make -f makefile.gen debug

Note: if you need to debug the SGDK lib or step in SGDK functions, first call
make -f makelib.gen clean
make -f makelib.gen debug
make -f makefile.gen clean

If you compile using your own makefile or thought the CLI, remember to use these flags
-B$(GCC_PATH)/bin -m68000 -Wall -fno-builtin -O -ggdb -DDEBUG=1

In the end, you should find on your source folder at least these 2 files: rom.bin and rom.out

► Configure GensKMod

Download GensKMod 0.7.3 from the official page or from the dev build repository
Launch GensKMod
On the Option > Debug... menu, be sure to select

  • Blue Screen pause (help to be sure game is paused and not crashed)
  • Single instance
  • use GDB
Default values for GDB Stub port could be used (ex: 6868)

Load the rom.bin on GensKMod
Let it start like usual and jump to GDB



Get GDB on the upcoming SGDK release or from

CLI mode
This mode is the not the easier to use but it will help to check everything is in place

Launch GDB.exe (or m68k-elf-gdb.exe)
↳This will launch a shell with a (gdb) prompt

Type in the prompt
file the/path/to/my/game/source/rom.out
↳This will give to GDB all the infos it need to debug the game

Type in the prompt
target remote localhost:6868
↳This will connect GDB with GensKMod

If the game was still running on GensKMod, it should pause it and you'll see the break on GDB prompt.
Congratulations ! You're ready to debug !
Now add your breakpoints using all the commands available. For ex:
break myFunc
Will add a breakpoint on the start of myFunc()
Type cotinue or c on prompt
On KMod, reset the game using 'TAB'
Move the part of your game where myFunc is called
GensKMod pause and GDB break, awaiting for order

The main command you'll use are
  • 's' or 'step' : step on next line, called functions included
  • 'n' or 'next' : step over
  • 'c' or 'continue' : run up to next break point if any
  • 'info vars' : print any vars with its value
  • 'break xxx' : add a breakpoint to func, address, line number
  • 'clear n' : delete breakpoint number
  • 'info break' : list all the breackpoints (number included)
  • 'quit'

UI mode

If GDB CLI is working, everything is set up : time to move on debug with an UI client
I'm used to Eclise so here's how I did on Eclipse
I assume your project is ready on Eclipse, following or not the old tutorial
Your Make targets are defined and so you were able to create a rom.bin and rom.out
rom.bin is loaded on GensKMod
If not already done, create a debug configuration:
  • Select Run > Debug Configurations...
  • add a 'C/C++ Remote Application'
  • give your debug config a name (on top of the tabs)
  • select tab 'Main'
  • at the bottom, be sure 'Using GDB (DSF) Manual Remote Debugging launcher is selected (if not, do it!)
  • 'C/C++ Application' is your rom.out
  • 'Project' should be defined
  • Select (unless you know what's you're doing) 'Disable auto build'
  • Move to 'Debugger' tab
  • Check (or not) 'Stop on startup at main' (this will create a invisible first breakpoint at main()
  • Main > GDB debugger : select SGDK's gdb.exe (or m68k-elf-gdb.exe)
  • Share lib : keep it like this
  • Connection : Type 'TCP' / Host name 'localhost' / Port number '6868'
  • Move to 'Common' tab
  • Check 'Debug' on 'Display in favorites menu'
Launch the debug configuration through the debug icon on the menu bar
On KMod, reset the game using 'TAB'
KMod pauses and Eclipse breaks on 'main()'
Add the breakpoints if not already done and good debug session !

► Thanks

Graz for his wonderful works on 0.7.2
Prophet36 for its awesome hint when I was dying failling to make gdb's "next" command working