This guide will set up VS Code to work with debugging Wii U apps using the GDB stub plugin for Aroma.
To debug you will need a compatible GDB version installed which supports the powerpc:750 archtitecture.
The one which is bundled with devkitPPC is not recommended, due to being several versions behind.
Edit: It has now been updated to the latest version and can be used without issues. Use /opt/devkitpro/devkitPPC/bin/powerpc-eabi-gdb for the gdb path.
You can also install a PowerPC specific version, or use gdb-multiarch which comes with several linux distributions.
Note down the path to the gdb executable, this is required for the next steps.
Make sure you have the C/C++ extension installed before continuing.
Start by creating a launch.json in the .vscode folder. You can let VS Code do this for you, although it automatically adds a default configuration which is not necessary.
Add the following to the launch.json:
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
]
}To start debugging you will need a supported extension. You can either use cppdbg which is part of the C/C++ extension or use Native Debug.
Both extensions work fine with the GDBStub, but one might give you better results than the other. You can also add both configurations to the launch.json and select one before debugging.
For cppdbg add the following configuration after "configurations": [ (or after the previous configuration seperated by a ,) to the launch.json:
{
"name": "Attach to Wii U (cppdbg)",
"type": "cppdbg",
"request": "launch",
"program": "path-to-program.elf",
"MIMode": "gdb",
"cwd": "${workspaceRoot}",
"miDebuggerPath": "gdb-multiarch",
"miDebuggerServerAddress": "192.168.178.123:3000",
"setupCommands": [
{ "text": "-interpreter-exec console \"set arch powerpc:750\"", "ignoreFailures": false },
{ "text": "-interpreter-exec console \"set endian big\"", "ignoreFailures": false },
{ "text": "-interpreter-exec console \"set remote hardware-watchpoint-limit 1\"", "ignoreFailures": false },
{ "text": "-interpreter-exec console \"set remote hardware-breakpoint-limit 1\"", "ignoreFailures": false },
{ "text": "-enable-pretty-printing", "ignoreFailures": true }
]
},You will need to adjust the following values:
| Value | Description |
|---|---|
| program | Set this to the path of your .elf file (not the .rpx or .wuhb!). |
| miDebuggerPath | Replace this with the path to the GDB executable you installed in #Choosing a GDB version. |
| miDebuggerServerAddress | Replace this with the IP Address of your Wii U. Keep the port as it is (3000). |
For Native Debug make sure to install the Native Debug extension (Ctrl + P and enter ext install webfreak.debug).
Then add the following configuration after "configurations": [ (or after the previous configuration seperated by a ,) to the launch.json:
{
"name": "Attach to Wii U (Native Debug)",
"type": "gdb",
"request": "attach",
"executable": "path-to-program.elf",
"target": "192.168.178.123:3000",
"remote": true,
"cwd": "${workspaceRoot}",
"valuesFormatting": "prettyPrinters",
"gdbpath": "gdb-multiarch",
"autorun": [
"set arch powerpc:750",
"set endian big",
"set remote hardware-watchpoint-limit 1",
"set remote hardware-breakpoint-limit 1",
]
},You will need to adjust the following values:
| Value | Description |
|---|---|
| executable | Set this to the path of your .elf file (not the .rpx or .wuhb!). |
| target | Replace this with the IP Address of your Wii U. Keep the port as it is (3000). |
| gdbpath | Replace this with the path to the GDB executable you installed in #Choosing a GDB version. |
Make sure your Aroma installation is up-to-date before loading the GDBStub plugin. Download the plugin here and extract the gdbstub.wps.
Now launch the application you want to debug (for example by wiiloading the .wuhb/.rpx).
After the application is running wiiload the gdbstub.wps and wait for a few seconds. The GDBStub is now waiting for the client.
In VSCode head over to the Run and Debug tab and select one of the Attach to Wii U configurations at the top.
Start by setting a breakpoint at main (or anywhere else, or don't set one at all).
Now press Start Debugging and VS Code should attach to the Wii U and your breakpoint should be hit (if you set one).
From here on you can debug your application like you would anywhere else.
Hope this guide is useful for debugging your applications. I've attached my full launch.json below.
Happy debugging!