some code cleanup and commenting to make decisions more clear

.gitignore

@@ -78,7 +78,8 @@ cmake-build-*
 diff.txt
 
 .vs/
-.vscode/
+.vscode/*
+!.vscode/launch.json
 
 temp_asm/
 asm_old/

.vscode/launch.json

@@ -0,0 +1,39 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Debug in melonDS",
+            "type": "cppdbg",
+            "request": "launch",
+            "program": "${workspaceFolder}/build/debug.nef",
+            "MIMode": "gdb",
+            "cwd": "${workspaceFolder}",
+            "externalConsole": true,
+            "miDebuggerServerAddress": "localhost:3333",
+            // point this to your own gdb path...
+            "miDebuggerPath": "/home/ziddia/Desktop/PokePlat/binutils-gdb/gdb/gdb",
+            //"miDebuggerPath": "gdb-multiarch",
+            "setupCommands": [
+                {
+                    "description": "Enable pretty-printing",
+                    "text": "-enable-pretty-printing",
+                    "ignoreFailures": true
+                },
+                {
+                    "description": "Set architecture",
+                    "text": "set architecture armv5te"
+                },
+                {
+                    "description": "Enable overlays",
+                    "text": "overlay auto"
+                },
+                {
+                    "description": "Enable overlay map",
+                    "text": "overlay map build/overlay.map"
+                }
+            ],
+            "stopAtConnect": false,
+            "stopAtEntry": false
+        }
+    ]
+}

include/game_overlay.h

@@ -13,18 +13,28 @@ void Overlay_UnloadByID(const FSOverlayID param0);
 int Overlay_GetLoadDestination(const FSOverlayID param0);
 BOOL Overlay_LoadByID(const FSOverlayID param0, int param1);
 
+// TODO: this should integrate into build system instead of a manual define here.
+// to turn off overlay debugging and build a matching ROM, undefine this.
+#define GDB_DEBUGGING
+
+#ifdef GDB_DEBUGGING
+// describes a single overlay entry, which GDB can inspect to determine which overlays are loaded.
 typedef struct {
     unsigned long vma;
     unsigned long size;
-    FSOverlayID ovly_id;
+    FSOverlayID id;
     unsigned long mapped;
 } struct_overlayTable;
 
+// this is set based on the current number of overlays, other projects might need more!
 #define MAX_OVERLAYS 128
 
+// externs required for GDB to access overlay state
 extern unsigned long _novlys;
 extern struct_overlayTable _ovly_table[MAX_OVERLAYS];
 
+// event callback which GDB will hook and use to refresh overlay state
 static void _ovly_debug_event(void);
+#endif // GDB_DEBUGGING
 
 #endif // POKEPLATINUM_UNK_020064F0_H

src/game_overlay.c

@@ -34,42 +34,44 @@ BOOL Overlay_LoadByID(const FSOverlayID param0, int param1);
 
 static UnkStruct_021BF370 Unk_021BF370;
 
+#ifdef GDB_DEBUGGING
+
 /* Added to support GDB overlay debugging. */
 unsigned long _novlys = MAX_OVERLAYS;
 struct_overlayTable _ovly_table[MAX_OVERLAYS] = {};
+// this does nothing, but needs to be defined for GDB to refresh overlay state automatically.
 static void _ovly_debug_event(void) {}
+
+// helper function to mark a specific overlay as unmapped.
 void UnloadOverlayGDB(const FSOverlayID overlayID)
 {
     GF_ASSERT(overlayID < _novlys);
-    _ovly_table[overlayID].mapped = 0;
+    _ovly_table[overlayID].mapped--;
     _ovly_debug_event();
 }
+// helper function to mark a specific overlay as mapped, and provide its RAM address and size to GDB.
 void LoadOverlayGDB(const FSOverlayID overlayID)
 {
     FSOverlayInfo overlayInfo;
-    FSFileID fileInfo;
 
-    // dummy to force symbols to exist
     GF_ASSERT(overlayID < _novlys);
 
-    if(_ovly_table[overlayID].mapped != 0) return;
-
     // 1. fetch overlay info to identify vma
     GF_ASSERT(FS_LoadOverlayInfo(&overlayInfo, MI_PROCESSOR_ARM9, overlayID) == TRUE);
-    fileInfo = FS_GetOverlayFileID(&overlayInfo);
 
     // 2. add entry to _ovly_table
     // note that this is a little hacky. the VMA is correct but the LMA is not exposed by the OverlayManager
     // and the size field is not correct compared to what's stored in the NEF.
     // the standard overlay manager in GDB bases comparisons on VMA and LMA, so it's not viable here.
-    // requires a custom GDB build which uses overlay mappings and which can override section size.
+    // requires a custom GDB build which maps based on section ID and can override section size.
     // see https://github.com/joshua-smith-12/binutils-gdb-nds
     _ovly_table[overlayID].vma = overlayInfo.header.ram_address;
-    _ovly_table[overlayID].ovly_id = overlayID;
+    _ovly_table[overlayID].id = overlayID;
     _ovly_table[overlayID].size = overlayInfo.header.ram_size;
-    _ovly_table[overlayID].mapped = 1;
+    _ovly_table[overlayID].mapped++;
     _ovly_debug_event();
 }
+#endif // GDB_DEBUGGING
 
 static void FreeOverlayAllocation(PMiLoadedOverlay *param0)
 {
@@ -89,7 +91,9 @@ void Overlay_UnloadByID(const FSOverlayID overlayID)
     for (i = 0; i < 8; i++) {
         if ((table[i].isActive == 1) && (table[i].id == overlayID)) {
             FreeOverlayAllocation(&table[i]);
+            #ifdef GDB_DEBUGGING
             UnloadOverlayGDB(overlayID);
+            #endif
             return;
         }
     }
@@ -233,7 +237,9 @@ static BOOL GetOverlayRamBounds(const FSOverlayID overlayID, u32 *start, u32 *en
 
 static BOOL LoadOverlayNormal(MIProcessor proc, FSOverlayID overlayID)
 {
+    #ifdef GDB_DEBUGGING
     LoadOverlayGDB(overlayID);
+    #endif
     return FS_LoadOverlay(proc, overlayID);
 }
 
@@ -249,7 +255,9 @@ static BOOL LoadOverlayNoInit(MIProcessor proc, FSOverlayID overlayID)
         return FALSE;
     }
 
+    #ifdef GDB_DEBUGGING
     LoadOverlayGDB(overlayID);
+    #endif
 
     FS_StartOverlay(&info);
     return TRUE;
@@ -264,7 +272,9 @@ static BOOL LoadOverlayNoInitAsync(MIProcessor proc, FSOverlayID overlayID)
         return FALSE;
     }
 
+    #ifdef GDB_DEBUGGING
     LoadOverlayGDB(overlayID);
+    #endif
 
     FS_InitFile(&file);
     FS_LoadOverlayImageAsync(&info, &file);

tools/debug/meson.build

@@ -0,0 +1,2 @@
+nef_fixer_py = find_program('nef_fixer.py', native: true)
+overlay_mapper_py = find_program('overlay_mapper.py', native: true)

tools/debug/nef_fixer.py

@@ -1,4 +1,8 @@
 #!/usr/bin/env python3
+
+### This tool is responsible for using `debugedit` to fix Wine paths in the debuginfo file to real filesystem paths.
+### VSC requires the debuginfo paths to map to real filesystem paths in order for VSC to correctly open sources during a debugging session.
+### (This works fine on my Linux system, but may or may not work on WSL, and will certainly not work on other systems)
 import subprocess
 import os
 import shutil

tools/debug/overlay_mapper.py

@@ -1,4 +1,8 @@
 #!/usr/bin/env python3
+
+### This tool creates a file which maps overlay section names and source file names to overlay IDs.
+### custom GDB build then processes this source map and uses it to identify what overlay a source file belongs to.
+### (This makes it a lot easier to identify which overlapping overlay is used for a given input location).
 import subprocess
 import os
 import shutil

tools/meson.build

@@ -5,6 +5,7 @@ subdir('json2bin')
 subdir('msgenc')
 subdir('postconf')
 subdir('scripts')
+subdir('debug')
 
 # Prebuilt tools
 mwrap_exe = find_program('cw/mwrap', native: true)

tools/scripts/meson.build

@@ -9,6 +9,4 @@ make_pl_growtbl_py = find_program('make_pl_growtbl.py', native: true)
 make_species_tables_py = find_program('make_species_tables.py', native: true)
 make_tutorable_moves_py = find_program('make_tutorable_moves.py', native: true)
 make_pokedex_data_py = find_program('make_pokedex_data.py', native: true)
-make_pokedex_message_banks_py = find_program('make_pokedex_message_banks.py', native: true)
-nef_fixer_py = find_program('nef_fixer.py', native: true)
-overlay_mapper_py = find_program('overlay_mapper.py', native: true)
+make_pokedex_message_banks_py = find_program('make_pokedex_message_banks.py', native: true)