pr

.gdbinit

@@ -0,0 +1,2 @@
+set confirm off
+source /home/pheenoh/git/cpp/decompgz/build/GZ2E01/load_rel_symbols.py

.gitignore

@@ -62,3 +62,6 @@ test*.py
 
 # gz patches
 *.patch
+
+# GDB init (generated by ninja post-build)
+.gdbinit

.vscode/launch.json

@@ -0,0 +1,47 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Penumbra: Attach to Nintendont",
+      "type": "penumbra",
+      "request": "attach",
+      "program": "${workspaceFolder}/build/${input:gameId}/framework.elf",
+      "debugInfo": "${workspaceFolder}/build/${input:gameId}/debug_info.o",
+      "target": "${input:wiiAddress}:${input:gdbPort}"
+    },
+    {
+      "name": "Penumbra: Attach to Dolphin",
+      "type": "penumbra",
+      "request": "attach",
+      "program": "${workspaceFolder}/build/${input:gameId}/framework.elf",
+      "debugInfo": "${workspaceFolder}/build/${input:gameId}/debug_info.o",
+      "target": "${input:dolphinAddress}:${input:gdbPort}"
+    }
+  ],
+  "inputs": [
+    {
+      "id": "gameId",
+      "type": "promptString",
+      "description": "Game ID (e.g. GZ2E01)",
+      "default": "GZ2E01"
+    },
+    {
+      "id": "wiiAddress",
+      "type": "promptString",
+      "description": "Wii IP address",
+      "default": "192.168.1.100"
+    },
+    {
+      "id": "dolphinAddress",
+      "type": "promptString",
+      "description": "Dolphin IP address",
+      "default": "127.0.0.1"
+    },
+    {
+      "id": "gdbPort",
+      "type": "promptString",
+      "description": "GDB port",
+      "default": "2159"
+    }
+  ]
+}

.vscode/penumbra-debug/extension.js

@@ -0,0 +1,28 @@
+const vscode = require('vscode');
+const path = require('path');
+const fs = require('fs');
+
+function activate(context) {
+    const exe = process.platform === 'win32' ? 'penumbra.exe' : 'penumbra';
+    context.subscriptions.push(
+        vscode.debug.registerDebugAdapterDescriptorFactory('penumbra', {
+            createDebugAdapterDescriptor(_session) {
+                // Look for penumbra in build/binutils/ (downloaded by build system)
+                const workspaceFolder = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
+                if (workspaceFolder) {
+                    const buildPath = path.join(workspaceFolder, 'build', 'binutils', exe);
+                    if (fs.existsSync(buildPath)) {
+                        return new vscode.DebugAdapterExecutable(buildPath, ['--dap']);
+                    }
+                }
+
+                // Fallback to PATH
+                return new vscode.DebugAdapterExecutable(exe, ['--dap']);
+            }
+        })
+    );
+}
+
+function deactivate() {}
+
+module.exports = { activate, deactivate };

.vscode/penumbra-debug/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "penumbra-debug",
+  "displayName": "Penumbra Debug Adapter",
+  "description": "Debug adapter for PowerPC targets via GDB Remote Serial Protocol",
+  "version": "0.0.2",
+  "publisher": "pheenoh",
+  "engines": {
+    "vscode": "^1.80.0"
+  },
+  "categories": [
+    "Debuggers"
+  ],
+  "activationEvents": [
+    "onDebugResolve:penumbra"
+  ],
+  "main": "./extension.js",
+  "contributes": {
+    "debuggers": [
+      {
+        "type": "penumbra",
+        "label": "Penumbra",
+        "configurationAttributes": {
+          "attach": {
+            "required": [
+              "program",
+              "target"
+            ],
+            "properties": {
+              "program": {
+                "type": "string",
+                "description": "Path to the ELF executable (e.g. build/GZ2E01/framework.elf)"
+              },
+              "debugInfo": {
+                "type": "string",
+                "description": "Path to the DWARF debug info object (e.g. build/GZ2E01/debug_info.o)"
+              },
+              "target": {
+                "type": "string",
+                "description": "RSP target as ip:port (e.g. 192.168.1.100:2159)"
+              },
+              "verbose": {
+                "type": "boolean",
+                "description": "Enable verbose diagnostic output in the debug console",
+                "default": false
+              }
+            }
+          }
+        },
+        "configurationSnippets": [
+          {
+            "label": "Penumbra: Attach to Nintendont",
+            "description": "Attach to a Wii running Nintendont with GDB stub",
+            "body": {
+              "type": "penumbra",
+              "request": "attach",
+              "name": "Attach to Nintendont",
+              "program": "^\"\\${workspaceFolder}/build/\\${input:gameId}/framework.elf\"",
+              "debugInfo": "^\"\\${workspaceFolder}/build/\\${input:gameId}/debug_info.o\"",
+              "target": "^\"\\${input:wiiAddress}:\\${input:gdbPort}\""
+            }
+          },
+          {
+            "label": "Penumbra: Attach to Dolphin",
+            "description": "Attach to Dolphin emulator with GDB stub",
+            "body": {
+              "type": "penumbra",
+              "request": "attach",
+              "name": "Attach to Dolphin",
+              "program": "^\"\\${workspaceFolder}/build/\\${input:gameId}/framework.elf\"",
+              "debugInfo": "^\"\\${workspaceFolder}/build/\\${input:gameId}/debug_info.o\"",
+              "target": "^\"\\${input:dolphinAddress}:\\${input:gdbPort}\""
+            }
+          }
+        ]
+      }
+    ]
+  }
+}

README.md

@@ -97,6 +97,36 @@ To add new features to the practice ROM:
 - Look at existing custom files in `src/gz/` for examples of how to structure and integrate new code
 - Re-run `python configure.py -v VERSION` and `ninja` to include your changes
 
+## GDB Remote Debugging
+
+Umbra includes a GDB remote stub for source-level debugging of game code. It supports both real hardware via [umbra-nintendont](https://github.com/zsrtp/umbra-nintendont) and emulation via [umbra-dolphin](https://github.com/zsrtp/umbra-dolphin).
+
+### Setup
+
+To include debug info (DWARF 2 conversion + REL symbol loader) as part of the default build, configure with `--penumbra`:
+
+```sh
+python configure.py --penumbra
+ninja
+```
+
+This converts MetroWerks DWARF 1 debug info to DWARF 2 and generates the GDB symbol loader script during the normal build. Debug info is regenerated automatically when source files change.
+
+### Connecting
+
+Install the bundled debug adapter extension (one-time setup):
+
+```sh
+code --install-extension .vscode/penumbra-debug.vsix
+```
+
+Then use the launch configurations in `.vscode/launch.json`:
+
+- **Penumbra: Attach to Nintendont** -- connect to a Wii running the GDB stub
+- **Penumbra: Attach to Dolphin** -- connect to Dolphin's GDB stub
+
+Symbols and debug info are loaded automatically on connect.
+
 ## Adding Custom Assets
 
 - Place your custom asset into the `mod_assets` directory. The directory structure will be copied 1:1 to the final disc image.

config/RZDE01_02/symbols.txt

@@ -32765,7 +32765,7 @@ j3dDefaultColInfo = .sdata2:0x80526310; // type:object size:0x4 data:byte
 j3dDefaultAmbInfo = .sdata2:0x80526314; // type:object size:0x4 data:byte
 j3dDefaultNumChans = .sdata2:0x80526318; // type:object size:0x1 data:byte
 j3dDefaultTevOrderInfoNull = .sdata2:0x80526319; // type:object size:0x4 data:4byte
-j3dDefaultIndTexOrderNull = .sdata2:0x8052631D; // type:object size:0x4
+j3dDefaultIndTexOrderNull = .sdata2:0x8052631D; // type:object size:0x4 data:4byte
 j3dDefaultTevColor = .sdata2:0x80526322; // type:object size:0x8 scope:global align:2 data:2byte
 j3dDefaultTevKColor = .sdata2:0x8052632A; // type:object size:0x4 data:byte
 j3dDefaultTevSwapModeTable = .sdata2:0x8052632E; // type:object size:0x4

config/ShieldD/rels/d_a_b_mgnD/splits.txt

@@ -14,4 +14,4 @@ d/actor/d_a_b_mgn.cpp:
 	.ctors      start:0x00000000 end:0x00000004
 	.rodata     start:0x00000000 end:0x000002AC
 	.data       start:0x00000000 end:0x00000734
-	.bss        start:0x00000004 end:0x00000028
+	.bss        start:0x00000000 end:0x00000028

config/ShieldD/rels/d_a_b_mgnD/symbols.txt

@@ -231,7 +231,9 @@ _dtors = .dtors:0x00000000; // type:label scope:global
 @122971 = .rodata:0x00000284; // type:object size:0x4 scope:local align:4 data:float
 cNullVec__6Z2Calc = .rodata:0x00000288; // type:object size:0xC scope:global
 @46916 = .rodata:0x00000294; // type:object size:0x4 scope:local
-lbl_139_rodata_298 = .rodata:0x00000298; // type:object size:0x14
+@LOCAL@signaling_NaN__Q23std17numeric_limits<d>Fv@x = .rodata:0x00000298; // type:object size:0x8 align:8 data:float
+@LOCAL@signaling_NaN_2__Q23std17numeric_limits<d>Fv@x = .rodata:0x000002A0; // type:object size:0x8 align:8 data:float
+@LOCAL@signaling_NaN__Q23std17numeric_limits<f>Fv@x = .rodata:0x000002A8; // type:object size:0x4 align:4 data:float
 @LOCAL@setMidnaBindEffect__FP13fopEn_enemy_cP15Z2CreatureEnemyP4cXyzP4cXyz@e_prim = .data:0x00000000; // type:object size:0x8 scope:local
 @LOCAL@setMidnaBindEffect__FP13fopEn_enemy_cP15Z2CreatureEnemyP4cXyzP4cXyz@e_env@0 = .data:0x00000008; // type:object size:0x8 scope:local
 @LOCAL@setMidnaBindEffect__FP13fopEn_enemy_cP15Z2CreatureEnemyP4cXyzP4cXyz@eff_id@1 = .data:0x00000010; // type:object size:0x6 scope:local
@@ -294,6 +296,14 @@ lbl_139_data_440 = .data:0x00000440; // type:object size:0x24
 @123082 = .data:0x00000648; // type:object size:0xC scope:local
 @123083 = .data:0x0000066C; // type:object size:0x11 scope:local data:string
 @123084 = .data:0x00000694; // type:object size:0xD scope:local data:string
-lbl_139_data_6A1 = .data:0x000006A1; // type:object size:0x93
+@STRING@getJointNodePointer__12J3DJointTreeCFUs@2 = .data:0x000006B0; // type:object size:0x5 scope:local data:string
+@STRING@getJointNodePointer__12J3DJointTreeCFUs@1 = .data:0x000006B8; // type:object size:0xF scope:local data:string
+@STRING@getJointNodePointer__12J3DJointTreeCFUs@0 = .data:0x000006C8; // type:object size:0x14 scope:local data:string
+@STRING@getJointNodePointer__12J3DJointTreeCFUs = .data:0x000006DC; // type:object size:0xF scope:local data:string
+@STRING@getMaterialNodePointer__16J3DMaterialTableCFUs@2 = .data:0x000006EC; // type:object size:0x5 scope:local data:string
+@STRING@getMaterialNodePointer__16J3DMaterialTableCFUs@1 = .data:0x000006F4; // type:object size:0x14 scope:local data:string
+@STRING@getMaterialNodePointer__16J3DMaterialTableCFUs@0 = .data:0x00000708; // type:object size:0x14 scope:local data:string
+@STRING@getMaterialNodePointer__16J3DMaterialTableCFUs = .data:0x0000071C; // type:object size:0x14 scope:local data:string
+@STRING@showAssert__12JUTAssertionFUlPCciPCc = .data:0x00000730; // type:object size:0x3 scope:local data:string
 hio_set = .bss:0x00000000; // type:object size:0x1 scope:local align:1 data:byte
 l_HIO = .bss:0x00000004; // type:object size:0x24 scope:global data:byte

config/ShieldD/rels/d_a_e_cr_eggD/symbols.txt

@@ -30,7 +30,9 @@ _dtors = .dtors:0x00000000; // type:label scope:global
 @116845 = .rodata:0x00000038; // type:object size:0x4 scope:local align:4 data:float
 cNullVec__6Z2Calc = .rodata:0x0000003C; // type:object size:0xC scope:global
 @46916 = .rodata:0x00000048; // type:object size:0x4 scope:local
-lbl_172_rodata_4C = .rodata:0x0000004C; // type:object size:0x18
+@LOCAL@signaling_NaN__Q23std17numeric_limits<d>Fv@x = .rodata:0x00000050; // type:object size:0x8 align:8 data:float
+@LOCAL@signaling_NaN_2__Q23std17numeric_limits<d>Fv@x = .rodata:0x00000058; // type:object size:0x8 align:8 data:float
+@LOCAL@signaling_NaN__Q23std17numeric_limits<f>Fv@x = .rodata:0x00000060; // type:object size:0x4 align:4 data:float
 @LOCAL@e_cr_egg_move__FP14e_cr_egg_class@spy = .data:0x00000000; // type:object size:0xC scope:local
 @116895 = .data:0x0000000C; // type:object size:0x1B scope:local data:string
 @116896 = .data:0x00000028; // type:object size:0x5 scope:local data:string
@@ -60,4 +62,4 @@ lbl_172_data_178 = .data:0x00000178; // type:object size:0x24
 @117050 = .data:0x000002F8; // type:object size:0x10 scope:local data:string
 @117051 = .data:0x0000031C; // type:object size:0x9 scope:local data:string
 @117052 = .data:0x0000033C; // type:object size:0x9 scope:local data:string
-lbl_172_data_345 = .data:0x00000345; // type:object size:0xF
+@STRING@showAssert__12JUTAssertionFUlPCciPCc = .data:0x00000350; // type:object size:0x3 data:string

config/ShieldD/rels/d_a_e_fbD/symbols.txt

@@ -81,7 +81,9 @@ _dtors = .dtors:0x00000000; // type:label scope:global
 @117898 = .rodata:0x000000A0; // type:object size:0x4 scope:local
 cNullVec__6Z2Calc = .rodata:0x000000A4; // type:object size:0xC scope:global
 @46916 = .rodata:0x000000B0; // type:object size:0x4 scope:local
-lbl_179_rodata_B4 = .rodata:0x000000B4; // type:object size:0x18
+@LOCAL@signaling_NaN__Q23std17numeric_limits<d>Fv@x = .rodata:0x000000B8; // type:object size:0x8 align:8 data:float
+@LOCAL@signaling_NaN_2__Q23std17numeric_limits<d>Fv@x = .rodata:0x000000C0; // type:object size:0x8 align:8 data:float
+@LOCAL@signaling_NaN__Q23std17numeric_limits<f>Fv@x = .rodata:0x000000C8; // type:object size:0x4 align:4 data:float
 @117003 = .data:0x00000000; // type:object size:0xF scope:local
 @117004 = .data:0x00000010; // type:object size:0xD scope:local
 @117007 = .data:0x00000020; // type:object size:0x13 scope:local
@@ -142,8 +144,16 @@ lbl_179_data_320 = .data:0x00000320; // type:object size:0x24
 @118009 = .data:0x00000508; // type:object size:0xC scope:local
 @118010 = .data:0x0000052C; // type:object size:0x11 scope:local data:string
 @118011 = .data:0x00000554; // type:object size:0xD scope:local data:string
-lbl_179_data_561 = .data:0x00000561; // type:object size:0x93
+@STRING@getJointNodePointer__12J3DJointTreeCFUs@2 = .data:0x00000570; // type:object size:0x5 scope:local data:string
+@STRING@getJointNodePointer__12J3DJointTreeCFUs@1 = .data:0x00000578; // type:object size:0xF scope:local data:string
+@STRING@getJointNodePointer__12J3DJointTreeCFUs@0 = .data:0x00000588; // type:object size:0x14 scope:local data:string
+@STRING@getJointNodePointer__12J3DJointTreeCFUs = .data:0x0000059C; // type:object size:0xF scope:local data:string
+@STRING@getMaterialNodePointer__16J3DMaterialTableCFUs@2 = .data:0x000005AC; // type:object size:0x5 scope:local data:string
+@STRING@getMaterialNodePointer__16J3DMaterialTableCFUs@1 = .data:0x000005B4; // type:object size:0x14 scope:local data:string
+@STRING@getMaterialNodePointer__16J3DMaterialTableCFUs@0 = .data:0x000005C8; // type:object size:0x14 scope:local data:string
+@STRING@getMaterialNodePointer__16J3DMaterialTableCFUs = .data:0x000005DC; // type:object size:0x14 scope:local data:string
+@STRING@showAssert__12JUTAssertionFUlPCciPCc = .data:0x000005F0; // type:object size:0x3 scope:local data:string
 hio_set = .bss:0x00000000; // type:object size:0x1 scope:local data:byte
 l_HIO = .bss:0x00000004; // type:object size:0x24 scope:global data:byte
 mFireTimer = .bss:0x00000028; // type:object size:0x4 scope:global data:4byte
-lbl_179_bss_2C = .bss:0x0000002C; // type:object size:0x1 data:byte
+lbl_188_bss_7C = .bss:0x0000002C; // type:object size:0x1 data:byte

config/ShieldD/rels/d_a_e_gbD/splits.txt

@@ -14,4 +14,4 @@ d/actor/d_a_e_gb.cpp:
 	.ctors      start:0x00000000 end:0x00000004
 	.rodata     start:0x00000000 end:0x000001D4
 	.data       start:0x00000000 end:0x00000644
-	.bss        start:0x00000008 end:0x00000028
+	.bss        start:0x00000000 end:0x00000028

config/ShieldD/rels/d_a_e_gbD/symbols.txt

@@ -156,7 +156,9 @@ _dtors = .dtors:0x00000000; // type:label scope:global
 @120500 = .rodata:0x000001A8; // type:object size:0x4 scope:local align:4 data:float
 cNullVec__6Z2Calc = .rodata:0x000001AC; // type:object size:0xC scope:global
 @46916 = .rodata:0x000001B8; // type:object size:0x4 scope:local
-lbl_183_rodata_1BC = .rodata:0x000001BC; // type:object size:0x18
+@LOCAL@signaling_NaN__Q23std17numeric_limits<d>Fv@x = .rodata:0x000001C0; // type:object size:0x8 align:8 data:float
+@LOCAL@signaling_NaN_2__Q23std17numeric_limits<d>Fv@x = .rodata:0x000001C8; // type:object size:0x8 align:8 data:float
+@LOCAL@signaling_NaN__Q23std17numeric_limits<f>Fv@x = .rodata:0x000001D0; // type:object size:0x4 align:4 data:float
 @LOCAL@setMidnaBindEffect__FP13fopEn_enemy_cP15Z2CreatureEnemyP4cXyzP4cXyz@e_prim = .data:0x00000000; // type:object size:0x8 scope:local
 @LOCAL@setMidnaBindEffect__FP13fopEn_enemy_cP15Z2CreatureEnemyP4cXyzP4cXyz@e_env@0 = .data:0x00000008; // type:object size:0x8 scope:local
 @LOCAL@setMidnaBindEffect__FP13fopEn_enemy_cP15Z2CreatureEnemyP4cXyzP4cXyz@eff_id@1 = .data:0x00000010; // type:object size:0x6 scope:local
@@ -219,6 +221,6 @@ lbl_183_data_3D0 = .data:0x000003D0; // type:object size:0x24
 @120617 = .data:0x000005D8; // type:object size:0xC scope:local
 @120618 = .data:0x000005FC; // type:object size:0x11 scope:local data:string
 @120619 = .data:0x00000624; // type:object size:0xD scope:local data:string
-lbl_183_data_631 = .data:0x00000631; // type:object size:0x13
-lbl_183_bss_0 = .bss:0x00000000; // type:object size:0x1 data:byte
+@STRING@showAssert__12JUTAssertionFUlPCciPCc = .data:0x00000640; // type:object size:0x3 data:string
+data_806C7928 = .bss:0x00000000; // type:object size:0x1 data:byte
 l_HIO = .bss:0x00000008; // type:object size:0x20 scope:global data:byte

config/ShieldD/rels/d_a_e_hzD/symbols.txt

@@ -133,7 +133,9 @@ _dtors = .dtors:0x00000000; // type:label scope:global
 @122055 = .rodata:0x000000F0; // type:object size:0x4 scope:local
 cNullVec__6Z2Calc = .rodata:0x000000F4; // type:object size:0xC scope:global
 @46916 = .rodata:0x00000100; // type:object size:0x4 scope:local
-lbl_192_rodata_104 = .rodata:0x00000104; // type:object size:0x18
+@LOCAL@signaling_NaN__Q23std17numeric_limits<d>Fv@x = .rodata:0x00000108; // type:object size:0x8 align:8 data:float
+@LOCAL@signaling_NaN_2__Q23std17numeric_limits<d>Fv@x = .rodata:0x00000110; // type:object size:0x8 align:8 data:float
+@LOCAL@signaling_NaN__Q23std17numeric_limits<f>Fv@x = .rodata:0x00000118; // type:object size:0x4 align:4 data:float
 @LOCAL@setMidnaBindEffect__FP13fopEn_enemy_cP15Z2CreatureEnemyP4cXyzP4cXyz@e_prim = .data:0x00000000; // type:object size:0x8 scope:local
 @LOCAL@setMidnaBindEffect__FP13fopEn_enemy_cP15Z2CreatureEnemyP4cXyzP4cXyz@e_env@0 = .data:0x00000008; // type:object size:0x8 scope:local
 @LOCAL@setMidnaBindEffect__FP13fopEn_enemy_cP15Z2CreatureEnemyP4cXyzP4cXyz@eff_id@1 = .data:0x00000010; // type:object size:0x6 scope:local
@@ -193,11 +195,20 @@ lbl_192_data_308 = .data:0x00000308; // type:object size:0x24
 @122166 = .data:0x000004E0; // type:object size:0xE scope:local data:string
 @122167 = .data:0x000004F0; // type:object size:0xC scope:local
 @122168 = .data:0x00000514; // type:object size:0x11 scope:local data:string
-lbl_192_data_525 = .data:0x00000525; // type:object size:0x8F
+@STRING@getJointNodePointer__12J3DJointTreeCFUs@2 = .data:0x00000530; // type:object size:0x5 scope:local data:string
+@STRING@getJointNodePointer__12J3DJointTreeCFUs@1 = .data:0x00000538; // type:object size:0xF scope:local data:string
+@STRING@getJointNodePointer__12J3DJointTreeCFUs@0 = .data:0x00000548; // type:object size:0x14 scope:local data:string
+@STRING@getJointNodePointer__12J3DJointTreeCFUs = .data:0x0000055C; // type:object size:0xF scope:local data:string
+@STRING@getMaterialNodePointer__16J3DMaterialTableCFUs@2 = .data:0x0000056C; // type:object size:0x5 scope:local data:string
+@STRING@getMaterialNodePointer__16J3DMaterialTableCFUs@1 = .data:0x00000574; // type:object size:0x14 scope:local data:string
+@STRING@getMaterialNodePointer__16J3DMaterialTableCFUs@0 = .data:0x00000588; // type:object size:0x14 scope:local data:string
+@STRING@getMaterialNodePointer__16J3DMaterialTableCFUs = .data:0x0000059C; // type:object size:0x14 scope:local data:string
+@STRING@showAssert__12JUTAssertionFUlPCciPCc = .data:0x000005B0; // type:object size:0x3 scope:local data:string
 ...bss.0 = .bss:0x00000000; // type:label scope:local
+hio_set = .bss:0x00000000; // type:object size:0x1 scope:global data:byte
 l_HIO = .bss:0x00000004; // type:object size:0x3C scope:global data:byte
 m_near_bomb = .bss:0x00000040; // type:object size:0x4 scope:global
 m_near_carry = .bss:0x00000044; // type:object size:0x4 scope:global
 m_near_weapon = .bss:0x00000048; // type:object size:0x4 scope:global
-lbl_192_bss_4C = .bss:0x0000004C; // type:object size:0x1 data:byte
+@GUARD@setWaterEffect__8daE_HZ_cFv@sc = .bss:0x0000004C; // type:object size:0x1 data:byte
 @LOCAL@setWaterEffect__8daE_HZ_cFv@sc = .bss:0x00000050; // type:object size:0xC scope:local