Depending on what way you want to debug, there are a few differences on the GDB code stub you put in your code. No matter what method you use, you should link your program with the db library (-ldb), and include debug.h in your program.

When you have done the above, debugging using

1. Build your project with debug symbols. You should have a elf file and a dol file after doing this.
2. Transfer the dol file to an SD card or similar way to run homebrew. If you have a modded GameCube, you might be able to burn a mini DVD or similar instead.
3. Run the dol file. Remember to have the USB Gecko connected to your GameCube and computer, or have the network details ready if you debug using the network.

4. Connect using powerpc-eabi-gdb (included in DevkitPPC). You can use the elf-file as an argument to get symbols loaded. If you don't use it as an argument, you can specify it later in GDB with symbol-file myelf.elf.

   Once gdb has started, you need to specify where to connect. This is either a device file for USB Gecko, or a connection string for network debugging. The syntax for connecting is target remote conn where conn is either the device file or the connection string.

   USB Gecko: This should point to the USB Gecko device file. On my Macbook Air this is /dev/cu.usbserial-GECKUSB0. On a Windows device (after installing drivers), it will be something like COM4.

   Network debugging: In this case, you use the ip of the GameCube, as well as the port you specified in the GDB init stub. You should know of the ip from configuring the debug stub. The target should be ip:port (e.g, 10.0.0.106:5555).

5. Debug your application like you are used to

You can read about the various commands that GDB supports in the man page for GDB (or this online version of it).

While this works pretty well, it is a bit tedious to what we are used to with modern and more visual debuggers. This brings us to…

Thanks to VSCode, we have the Debug Adapter Protocol. This standard provides a common way for editors to talk to debuggers, and is implemented in many editors including VSCode, Vim and Emacs. While GDB doesn't provide a way for us to connect using this protocol, there are middleware that do. WebFreak001 provides a VSCode extension that connects to GDB and visualizes the breakpoints, variables etc. like we are used to. The debug adapter part can be used by almost any editor, and we will use it from Emacs in the next section. Using this extension we can easily create launch configurations:

{
    "name": "GameCube debug",
    "request": "attach",
    "type": "gdbserver",
    "gdbpath": "/path/to/powerpc-eabi-gdb",
    "target": "10.0.0.106:5555",
    "executable": "/path/to/my.elf",
    "cwd": "/my/workspace/root"
}

(if you want to debug using USB Gecko, simply replace the target with your device file!)

What this will do is automatically load the symbol file (elf), connect to the target, and then start the debugging. You should probably set a few breakpoints in the code before connecting. Now we can debug like you are used to visually. If you create a launch.json, it should even work in Emacs given that you have set up dap-gdb-lldb (might not work if the rest of the project is not using LSP).

While Emacs has a built-in GDB command we could use, we would still need to write GDB commands the old fashioned way. To make our debugging more comfortable, we can use dap-mode. dap-mode makes it simple to use the debugger part of the extension mentioned above, as you only need to run a interactive command in Emacs after requiring dap-gdb-lldb. After that is done, we can create a debug template:

(dap-register-debug-template "GameCube debug"
			     (list :name "GameCube debug"
				   :type "gdbserver"
				   :request "attach"
				   :gdbpath "/path/to/powerpc-eabi-gdb"
				   :target "10.0.0.106:5555"
				   :executable "/path/to/my.elf"
				   :cwd "/my/workspace/root"))

As you can see, we have to specify our projects elf file each time. Most DevkitPPC projects will produce this elf-file in the root of the project. This is one of the assumptions of my Emacs GameCube debug package. Just run gamecube-debug-program from your source file, and the debugging information is setup automatically.

No matter how you choose to debug from Emacs, it will look something like this: