From 686bc44b961ff2b960e8bf92fe3114dd14305a52 Mon Sep 17 00:00:00 2001
From: Devon R <sansgorialis@gmail.com>
Date: Thu, 5 Mar 2026 12:55:26 +0000
Subject: [PATCH 1/8] Update symbol_addrs script to work with current codebase

---
 tools/update_symbol_addrs.py | 121 +++++++++++++++++++----------------
 1 file changed, 67 insertions(+), 54 deletions(-)

diff --git a/tools/update_symbol_addrs.py b/tools/update_symbol_addrs.py
index c3df51f049e..93d842045cf 100755
--- a/tools/update_symbol_addrs.py
+++ b/tools/update_symbol_addrs.py
@@ -1,60 +1,86 @@
 #!/usr/bin/env python3
 
-import os
+import pathlib
 import re
 import subprocess
 import sys
+import typing
+
 import tqdm
 
-script_dir = os.path.dirname(os.path.realpath(__file__))
-root_dir = script_dir + "/../"
 
-current_ver_dir = script_dir + "/../ver/current/"
-asm_dir = root_dir + "asm/nonmatchings/"
+# Always the same
+SCRIPT_DIRECTORY = pathlib.Path(__file__).parent
+ROOT_DIRECTORY = SCRIPT_DIRECTORY.parent
+VERSION_DIRECTORY = ROOT_DIRECTORY / 'ver'
+AVAILABLE_VERSIONS = [item.name for item in VERSION_DIRECTORY.iterdir() if item.is_dir()]
+
+ASM_DIRECTORY = ROOT_DIRECTORY / 'asm' / 'nonmatchings'
+IGNORES_PATH = ROOT_DIRECTORY / 'tools' / 'ignored_funcs.txt'
+
+IGNORE_RE = re.compile(r"(?P<symbol>\S+)\s*=\s*0[xX](?P<address>[0-9a-fA-F]+);")
+MAP_BLOCK_RE = re.compile(r"(?:\.(?P<label>\S+))?\s+0[xX](?P<ram>[0-9a-fA-F]+)\s+0[xX](?P<size>[0-9a-fA-F]+) load address 0[xX](?P<rom>[0-9a-fA-F]+)")
+MAP_ENTRY_RE = re.compile(r"(?:\.(?P<bss_label>\S+))?\s+0[xX](?P<ram>[0-9a-fA-F]+)\s+(?:0[xX](?P<bss_size>[0-9a-fA-F]+)\s+)?(?P<label>\S+)")
+SYMBOL_ADDR_RE = re.compile(r"(?:(?P<symbol>\S+))?\s*=\s*0[xX](?P<addr>[0-9a-fA-F]+);(?:\s*//\s*(?P<opts>.+?)\s*)?$")
+SYMBOL_ADDR_OPT_RE = re.compile(r"(?P<key>\S+):(?P<value>\S*)")
 
-symbol_addrs_path = os.path.join(current_ver_dir, "symbol_addrs.txt")
-elf_path = os.path.join(current_ver_dir, "build", "papermario.elf")
-map_path = os.path.join(current_ver_dir, "build", "papermario.map")
-ignores_path = os.path.join(root_dir, "tools", "ignored_funcs.txt")
+# Varies on version
+current_ver = sys.argv[1] if len(sys.argv) > 1 else 'current'
+current_ver_dir = VERSION_DIRECTORY / current_ver
+assert current_ver_dir.is_dir(), f"first argument passed (`{current_ver}`) should be a valid version, available: {', '.join(AVAILABLE_VERSIONS)}"
 
+symbol_addrs_path = current_ver_dir / 'symbol_addrs.txt'
+elf_path = current_ver_dir / 'build' / 'papermario.elf'
+map_path = current_ver_dir / 'build' / 'papermario.map'
+
+# Runtime
 map_symbols = {}
 symbol_addrs = []
 dead_symbols = []
 elf_symbols = []
 
-ignores = set()
+ignores: typing.Set[str] = set()
 
 verbose = False
 
 
 def read_ignores():
-    with open(ignores_path) as f:
+    with open(IGNORES_PATH) as f:
         lines = f.readlines()
 
     for line in lines:
-        name = line.split(" = ")[0].strip()
-        if name != "":
-            ignores.add(name)
+        ignore = IGNORE_RE.match(line)
+
+        if ignore:
+            ignores.add(ignore.group('symbol'))
 
 
 def scan_map():
     ram_offset = None
     cur_file = "<no file>"
-    prev_line = ""
+
     with open(map_path) as f:
         for line in f:
             if "load address" in line:
-                ram = int(line[16 : 16 + 18], 0)
-                rom = int(line[59 : 59 + 18], 0)
+                block = MAP_BLOCK_RE.match(line)
+
+                if block is None:
+                    continue
+
+                ram = int(block.group('ram'), 16)
+                rom = int(block.group('rom'), 16)
                 ram_offset = ram - rom
                 continue
 
-            prev_line = line
-
             if ram_offset is None or "=" in line or "*fill*" in line or " 0x" not in line:
                 continue
 
-            ram = int(line[16 : 16 + 18], 0)
+            entry = MAP_ENTRY_RE.match(line)
+
+            if entry is None:
+                continue
+
+            ram = int(entry.group('ram'), 16)
             rom = ram - ram_offset
             sym = line.split()[-1]
 
@@ -69,7 +95,7 @@ def scan_map():
 
 
 def read_symbol_addrs():
-    unique_lines = set()
+    unique_lines: typing.Set[str] = set()
 
     with open(symbol_addrs_path, "r") as f:
         for line in f.readlines():
@@ -79,48 +105,35 @@ def read_symbol_addrs():
             if "_ROM_START" in line or "_ROM_END" in line:
                 continue
 
-            main_split = line.rstrip().split(";")
-            main = main_split[0]
-
-            dead = False
-            opts = []
-            type = ""
-            rom = -1
-
-            if len(main_split) > 1:
-                ext = main_split[1]
-                opts = ext.split("//")[-1].strip().split(" ")
-
-                for opt in list(opts):
-                    if opt.strip() == "":
-                        opts.remove(opt)
-                    if "type:" in opt:
-                        type = opt.split(":")[1]
-                        opts.remove(opt)
-                    elif "rom:" in opt:
-                        rom = int(opt.split(":")[1], 16)
-                        opts.remove(opt)
-                    elif "dead:" in opt:
-                        dead = True
-
-            eqsplit = main.split(" = ")
-            if len(eqsplit) != 2:
-                print(f"Line malformed: '{main}'")
-                sys.exit(1)
-
-            name, addr = main.split(" = ")
+            entry = SYMBOL_ADDR_RE.match(line)
+
+            if entry is None:
+                continue
+
+            name = entry.group('symbol')
+            addr = int(entry.group('addr'), 16)
+            opts_group = entry.group('opts')
+            opts: typing.Dict[str, str] = {}
+
+            if opts_group is not None:
+                for opt_group in SYMBOL_ADDR_OPT_RE.finditer(opts_group):
+                    opts[opt_group.group('key')] = opt_group.group('value')
+
+            dead = 'dead' in opts
+            type = opts.get('type', '')
+            rom = int(opts['rom'], 16) if 'rom' in opts else -1
 
             if not dead:
-                symbol_addrs.append([name, int(addr, 0), type, rom, opts])
+                symbol_addrs.append([name, addr, type, rom, opts])
             else:
-                dead_symbols.append([name, int(addr, 0), type, rom, opts])
+                dead_symbols.append([name, addr, type, rom, opts])
 
 
 def read_elf():
     try:
         result = subprocess.run(["mips-linux-gnu-objdump", "-x", elf_path], stdout=subprocess.PIPE)
         objdump_lines = result.stdout.decode().split("\n")
-    except:
+    except Exception:
         print(f"Error: Could not run objdump on {elf_path} - make sure that the project is built")
         sys.exit(1)
 

From 08c01c217b9f81b5495b92e0c55271bf0cfb2239 Mon Sep 17 00:00:00 2001
From: Devon R <sansgorialis@gmail.com>
Date: Thu, 5 Mar 2026 13:29:03 +0000
Subject: [PATCH 2/8] Improve typing in update_symbol_addrs

---
 tools/update_symbol_addrs.py | 154 +++++++++++++++++++++--------------
 1 file changed, 95 insertions(+), 59 deletions(-)

diff --git a/tools/update_symbol_addrs.py b/tools/update_symbol_addrs.py
index 93d842045cf..2f858f6adde 100755
--- a/tools/update_symbol_addrs.py
+++ b/tools/update_symbol_addrs.py
@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 
+import dataclasses
 import pathlib
 import re
 import subprocess
@@ -24,6 +25,39 @@
 SYMBOL_ADDR_RE = re.compile(r"(?:(?P<symbol>\S+))?\s*=\s*0[xX](?P<addr>[0-9a-fA-F]+);(?:\s*//\s*(?P<opts>.+?)\s*)?$")
 SYMBOL_ADDR_OPT_RE = re.compile(r"(?P<key>\S+):(?P<value>\S*)")
 
+
+# Dataclass definitions
+@dataclasses.dataclass
+class MapSymbol:
+    rom: int
+    file: str
+    ram: int
+
+@dataclasses.dataclass
+class ELFSymbol:
+    name: str
+    addr: int
+    type: str
+    rom: typing.Optional[int]
+    opts: typing.Dict[str, str]
+
+    def ordering(self):
+        return (not self.rom, self.rom, self.addr, self.name)
+
+    def format(self) -> str:
+        line = f"{self.name} = 0x{self.addr:X}; //"
+
+        if self.type and len(self.type) > 0:
+            line += f" type:{self.type}"
+        if self.rom:
+            line += f" rom:0x{self.rom:X}"
+        if self.opts:
+            for key, value in self.opts.items():
+                line += f" {key}:{value}"
+
+        return line
+
+
 # Varies on version
 current_ver = sys.argv[1] if len(sys.argv) > 1 else 'current'
 current_ver_dir = VERSION_DIRECTORY / current_ver
@@ -33,11 +67,12 @@
 elf_path = current_ver_dir / 'build' / 'papermario.elf'
 map_path = current_ver_dir / 'build' / 'papermario.map'
 
+
 # Runtime
-map_symbols = {}
-symbol_addrs = []
-dead_symbols = []
-elf_symbols = []
+map_symbols: typing.Dict[str, MapSymbol] = {}
+symbol_addrs: typing.List[ELFSymbol] = []
+dead_symbols: typing.List[ELFSymbol] = []
+elf_symbols: typing.List[ELFSymbol] = []
 
 ignores: typing.Set[str] = set()
 
@@ -91,7 +126,11 @@ def scan_map():
                 cur_file = sym
                 continue
 
-            map_symbols[sym] = (rom, cur_file, ram)
+            map_symbols[sym] = MapSymbol(
+                rom=rom,
+                file=cur_file,
+                ram=ram
+            )
 
 
 def read_symbol_addrs():
@@ -120,13 +159,17 @@ def read_symbol_addrs():
                     opts[opt_group.group('key')] = opt_group.group('value')
 
             dead = 'dead' in opts
-            type = opts.get('type', '')
-            rom = int(opts['rom'], 16) if 'rom' in opts else -1
+            type = opts.pop('type', '')
+            rom = int(opts.pop('rom'), 16) if 'rom' in opts else None
 
             if not dead:
-                symbol_addrs.append([name, addr, type, rom, opts])
+                symbol_addrs.append(ELFSymbol(
+                    name=name, addr=addr, type=type, rom=rom, opts=opts
+                ))
             else:
-                dead_symbols.append([name, addr, type, rom, opts])
+                dead_symbols.append(ELFSymbol(
+                    name=name, addr=addr, type=type, rom=rom, opts=opts
+                ))
 
 
 def read_elf():
@@ -165,14 +208,20 @@ def read_elf():
             rom = None
 
             if name in map_symbols:
-                rom = map_symbols[name][0]
+                rom = map_symbols[name].rom
             elif re.match(".*_[0-9A-F]{8}_[0-9A-F]{6}", name):
                 rom = int(name.split("_")[-1], 16)
 
-            elf_symbols.append((name, addr, type, rom))
+            elf_symbols.append(ELFSymbol(
+                name=name,
+                addr=addr,
+                type=type,
+                rom=rom,
+                opts={}
+            ))
 
 
-def log(s):
+def log(s: str):
     if verbose:
         print(s)
 
@@ -180,72 +229,59 @@ def log(s):
 def reconcile_symbols():
     print(f"Processing {str(len(elf_symbols))} elf symbols...")
 
-    for i, elf_sym in tqdm.tqdm(enumerate(elf_symbols), total=len(elf_symbols)):
-        name_match = None
-        rom_match = None
+    for elf_sym in tqdm.tqdm(elf_symbols, total=len(elf_symbols)):
+        name_match: typing.Optional[ELFSymbol] = None
+        rom_match: typing.Optional[ELFSymbol] = None
 
         for known_sym in symbol_addrs:
             # Name
             if not name_match:
-                if elf_sym[0] == known_sym[0]:
+                if elf_sym.name == known_sym.name:
                     name_match = known_sym
 
-                    if elf_sym[1] != known_sym[1]:
+                    if elf_sym.addr != known_sym.addr:
                         log(
-                            f"Ram mismatch! {elf_sym[0]} is 0x{elf_sym[1]:X} in the elf and 0x{known_sym[1]} in symbol_addrs"
+                            f"Ram mismatch! {elf_sym.name} is 0x{elf_sym.addr:X} in the elf and 0x{known_sym.addr} in symbol_addrs"
                         )
 
             # Rom
             if not rom_match:
                 # Todo account for either or both syms not containing a rom addr
-                if elf_sym[3]:
-                    if elf_sym[3] == known_sym[3]:
+                if elf_sym.rom:
+                    if elf_sym.rom == known_sym.rom:
                         rom_match = known_sym
 
-        if not name_match and not rom_match:
-            log(f"Creating new symbol {elf_sym[0]}")
-            symbol_addrs.append(
-                [
-                    elf_sym[0],
-                    elf_sym[1],
-                    elf_sym[2],
-                    elf_sym[3] if elf_sym[3] else -1,
-                    [],
-                ]
-            )
-        elif not name_match:
-            log(f"Renaming identical rom address symbol {rom_match[0]} to {elf_sym[0]}")
-            rom_match[0] = elf_sym[0]
-        elif not rom_match and elf_sym[3]:
-            if name_match[3] >= 0:
-                log(f"Correcting rom address {name_match[3]} to {elf_sym[3]} for symbol {name_match[0]}")
+        if not name_match:
+            if not rom_match:
+                log(f"Creating new symbol {elf_sym.name}")
+                symbol_addrs.append(
+                    ELFSymbol(
+                        name=elf_sym.name,
+                        addr=elf_sym.addr,
+                        type=elf_sym.type,
+                        rom=elf_sym.rom,
+                        opts={},
+                    )
+                )
             else:
-                log(f"Adding rom address {elf_sym[3]} to symbol {name_match[0]}")
-            name_match[3] = elf_sym[3]
+                log(f"Renaming identical rom address symbol {rom_match.name} to {elf_sym.name}")
+                rom_match.name = elf_sym.name
+
+        elif not rom_match and elf_sym.rom:
+            if name_match.rom:
+                log(f"Correcting rom address {name_match.rom} to {elf_sym.rom} for symbol {name_match.name}")
+            else:
+                log(f"Adding rom address {elf_sym.rom} to symbol {name_match.name}")
+            name_match.rom = elf_sym.rom
 
 
 def write_new_symbol_addrs():
     with open(symbol_addrs_path, "w", newline="\n") as f:
-        for symbol in sorted(symbol_addrs, key=lambda x: (x[3] == -1, x[3], x[1], x[0])):
-            line = f"{symbol[0]} = 0x{symbol[1]:X}; //"
-            if symbol[2] and len(symbol[2]) > 0:
-                line += f" type:{symbol[2]}"
-            if symbol[3] >= 0:
-                line += f" rom:0x{symbol[3]:X}"
-            if len(symbol[4]) > 0:
-                for thing in symbol[4]:
-                    line += f" {thing}"
-            f.write(line + "\n")
-        for symbol in sorted(dead_symbols, key=lambda x: (x[3] == -1, x[3], x[1], x[0])):
-            line = f"{symbol[0]} = 0x{symbol[1]:X}; //"
-            if symbol[2] and len(symbol[2]) > 0:
-                line += f" type:{symbol[2]}"
-            if symbol[3] >= 0:
-                line += f" rom:0x{symbol[3]:X}"
-            if len(symbol[4]) > 0:
-                for thing in symbol[4]:
-                    line += f" {thing}"
-            f.write(line + "\n")
+        for symbol in sorted(symbol_addrs, key=ELFSymbol.ordering):
+            f.write(symbol.format() + "\n")
+
+        for symbol in sorted(dead_symbols, key=ELFSymbol.ordering):
+            f.write(symbol.format() + "\n")
 
 
 read_ignores()

From 116a1465b48e2b23b86a6e1a20b7b076cb241861 Mon Sep 17 00:00:00 2001
From: Devon R <sansgorialis@gmail.com>
Date: Thu, 5 Mar 2026 13:38:49 +0000
Subject: [PATCH 3/8] Black formatting for update_symbol_addrs

---
 tools/update_symbol_addrs.py | 72 ++++++++++++++++--------------------
 1 file changed, 32 insertions(+), 40 deletions(-)

diff --git a/tools/update_symbol_addrs.py b/tools/update_symbol_addrs.py
index 2f858f6adde..7c0246b4801 100755
--- a/tools/update_symbol_addrs.py
+++ b/tools/update_symbol_addrs.py
@@ -9,19 +9,22 @@
 
 import tqdm
 
-
 # Always the same
 SCRIPT_DIRECTORY = pathlib.Path(__file__).parent
 ROOT_DIRECTORY = SCRIPT_DIRECTORY.parent
-VERSION_DIRECTORY = ROOT_DIRECTORY / 'ver'
+VERSION_DIRECTORY = ROOT_DIRECTORY / "ver"
 AVAILABLE_VERSIONS = [item.name for item in VERSION_DIRECTORY.iterdir() if item.is_dir()]
 
-ASM_DIRECTORY = ROOT_DIRECTORY / 'asm' / 'nonmatchings'
-IGNORES_PATH = ROOT_DIRECTORY / 'tools' / 'ignored_funcs.txt'
+ASM_DIRECTORY = ROOT_DIRECTORY / "asm" / "nonmatchings"
+IGNORES_PATH = ROOT_DIRECTORY / "tools" / "ignored_funcs.txt"
 
 IGNORE_RE = re.compile(r"(?P<symbol>\S+)\s*=\s*0[xX](?P<address>[0-9a-fA-F]+);")
-MAP_BLOCK_RE = re.compile(r"(?:\.(?P<label>\S+))?\s+0[xX](?P<ram>[0-9a-fA-F]+)\s+0[xX](?P<size>[0-9a-fA-F]+) load address 0[xX](?P<rom>[0-9a-fA-F]+)")
-MAP_ENTRY_RE = re.compile(r"(?:\.(?P<bss_label>\S+))?\s+0[xX](?P<ram>[0-9a-fA-F]+)\s+(?:0[xX](?P<bss_size>[0-9a-fA-F]+)\s+)?(?P<label>\S+)")
+MAP_BLOCK_RE = re.compile(
+    r"(?:\.(?P<label>\S+))?\s+0[xX](?P<ram>[0-9a-fA-F]+)\s+0[xX](?P<size>[0-9a-fA-F]+) load address 0[xX](?P<rom>[0-9a-fA-F]+)"
+)
+MAP_ENTRY_RE = re.compile(
+    r"(?:\.(?P<bss_label>\S+))?\s+0[xX](?P<ram>[0-9a-fA-F]+)\s+(?:0[xX](?P<bss_size>[0-9a-fA-F]+)\s+)?(?P<label>\S+)"
+)
 SYMBOL_ADDR_RE = re.compile(r"(?:(?P<symbol>\S+))?\s*=\s*0[xX](?P<addr>[0-9a-fA-F]+);(?:\s*//\s*(?P<opts>.+?)\s*)?$")
 SYMBOL_ADDR_OPT_RE = re.compile(r"(?P<key>\S+):(?P<value>\S*)")
 
@@ -33,6 +36,7 @@ class MapSymbol:
     file: str
     ram: int
 
+
 @dataclasses.dataclass
 class ELFSymbol:
     name: str
@@ -59,13 +63,15 @@ def format(self) -> str:
 
 
 # Varies on version
-current_ver = sys.argv[1] if len(sys.argv) > 1 else 'current'
+current_ver = sys.argv[1] if len(sys.argv) > 1 else "current"
 current_ver_dir = VERSION_DIRECTORY / current_ver
-assert current_ver_dir.is_dir(), f"first argument passed (`{current_ver}`) should be a valid version, available: {', '.join(AVAILABLE_VERSIONS)}"
+assert (
+    current_ver_dir.is_dir()
+), f"first argument passed (`{current_ver}`) should be a valid version, available: {', '.join(AVAILABLE_VERSIONS)}"
 
-symbol_addrs_path = current_ver_dir / 'symbol_addrs.txt'
-elf_path = current_ver_dir / 'build' / 'papermario.elf'
-map_path = current_ver_dir / 'build' / 'papermario.map'
+symbol_addrs_path = current_ver_dir / "symbol_addrs.txt"
+elf_path = current_ver_dir / "build" / "papermario.elf"
+map_path = current_ver_dir / "build" / "papermario.map"
 
 
 # Runtime
@@ -87,7 +93,7 @@ def read_ignores():
         ignore = IGNORE_RE.match(line)
 
         if ignore:
-            ignores.add(ignore.group('symbol'))
+            ignores.add(ignore.group("symbol"))
 
 
 def scan_map():
@@ -102,8 +108,8 @@ def scan_map():
                 if block is None:
                     continue
 
-                ram = int(block.group('ram'), 16)
-                rom = int(block.group('rom'), 16)
+                ram = int(block.group("ram"), 16)
+                rom = int(block.group("rom"), 16)
                 ram_offset = ram - rom
                 continue
 
@@ -115,7 +121,7 @@ def scan_map():
             if entry is None:
                 continue
 
-            ram = int(entry.group('ram'), 16)
+            ram = int(entry.group("ram"), 16)
             rom = ram - ram_offset
             sym = line.split()[-1]
 
@@ -126,11 +132,7 @@ def scan_map():
                 cur_file = sym
                 continue
 
-            map_symbols[sym] = MapSymbol(
-                rom=rom,
-                file=cur_file,
-                ram=ram
-            )
+            map_symbols[sym] = MapSymbol(rom=rom, file=cur_file, ram=ram)
 
 
 def read_symbol_addrs():
@@ -149,27 +151,23 @@ def read_symbol_addrs():
             if entry is None:
                 continue
 
-            name = entry.group('symbol')
-            addr = int(entry.group('addr'), 16)
-            opts_group = entry.group('opts')
+            name = entry.group("symbol")
+            addr = int(entry.group("addr"), 16)
+            opts_group = entry.group("opts")
             opts: typing.Dict[str, str] = {}
 
             if opts_group is not None:
                 for opt_group in SYMBOL_ADDR_OPT_RE.finditer(opts_group):
-                    opts[opt_group.group('key')] = opt_group.group('value')
+                    opts[opt_group.group("key")] = opt_group.group("value")
 
-            dead = 'dead' in opts
-            type = opts.pop('type', '')
-            rom = int(opts.pop('rom'), 16) if 'rom' in opts else None
+            dead = "dead" in opts
+            type = opts.pop("type", "")
+            rom = int(opts.pop("rom"), 16) if "rom" in opts else None
 
             if not dead:
-                symbol_addrs.append(ELFSymbol(
-                    name=name, addr=addr, type=type, rom=rom, opts=opts
-                ))
+                symbol_addrs.append(ELFSymbol(name=name, addr=addr, type=type, rom=rom, opts=opts))
             else:
-                dead_symbols.append(ELFSymbol(
-                    name=name, addr=addr, type=type, rom=rom, opts=opts
-                ))
+                dead_symbols.append(ELFSymbol(name=name, addr=addr, type=type, rom=rom, opts=opts))
 
 
 def read_elf():
@@ -212,13 +210,7 @@ def read_elf():
             elif re.match(".*_[0-9A-F]{8}_[0-9A-F]{6}", name):
                 rom = int(name.split("_")[-1], 16)
 
-            elf_symbols.append(ELFSymbol(
-                name=name,
-                addr=addr,
-                type=type,
-                rom=rom,
-                opts={}
-            ))
+            elf_symbols.append(ELFSymbol(name=name, addr=addr, type=type, rom=rom, opts={}))
 
 
 def log(s: str):

From 387a0c56c8db38cd808bf2a65b4822b690c4b874 Mon Sep 17 00:00:00 2001
From: Devon R <sansgorialis@gmail.com>
Date: Thu, 5 Mar 2026 13:53:34 +0000
Subject: [PATCH 4/8] Use argparse to allow verbose output for
 update_symbol_addrs

---
 tools/update_symbol_addrs.py | 101 ++++++++++++++---------------------
 1 file changed, 40 insertions(+), 61 deletions(-)

diff --git a/tools/update_symbol_addrs.py b/tools/update_symbol_addrs.py
index 7c0246b4801..46c296e2084 100755
--- a/tools/update_symbol_addrs.py
+++ b/tools/update_symbol_addrs.py
@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 
+import argparse
 import dataclasses
 import pathlib
 import re
@@ -62,29 +63,6 @@ def format(self) -> str:
         return line
 
 
-# Varies on version
-current_ver = sys.argv[1] if len(sys.argv) > 1 else "current"
-current_ver_dir = VERSION_DIRECTORY / current_ver
-assert (
-    current_ver_dir.is_dir()
-), f"first argument passed (`{current_ver}`) should be a valid version, available: {', '.join(AVAILABLE_VERSIONS)}"
-
-symbol_addrs_path = current_ver_dir / "symbol_addrs.txt"
-elf_path = current_ver_dir / "build" / "papermario.elf"
-map_path = current_ver_dir / "build" / "papermario.map"
-
-
-# Runtime
-map_symbols: typing.Dict[str, MapSymbol] = {}
-symbol_addrs: typing.List[ELFSymbol] = []
-dead_symbols: typing.List[ELFSymbol] = []
-elf_symbols: typing.List[ELFSymbol] = []
-
-ignores: typing.Set[str] = set()
-
-verbose = False
-
-
 def read_ignores():
     with open(IGNORES_PATH) as f:
         lines = f.readlines()
@@ -233,7 +211,7 @@ def reconcile_symbols():
 
                     if elf_sym.addr != known_sym.addr:
                         log(
-                            f"Ram mismatch! {elf_sym.name} is 0x{elf_sym.addr:X} in the elf and 0x{known_sym.addr} in symbol_addrs"
+                            f"Ram mismatch! {elf_sym.name} is 0x{elf_sym.addr:X} in the elf and 0x{known_sym.addr:X} in symbol_addrs"
                         )
 
             # Rom
@@ -276,40 +254,41 @@ def write_new_symbol_addrs():
             f.write(symbol.format() + "\n")
 
 
-read_ignores()
-scan_map()
-read_symbol_addrs()
-
-# chicken scratch cod to print out new / renamed symbols
-# with open("tools/new_syms.txt") as f:
-#     new_syms = f.readlines()
-
-# new_sym_dict = {}
-# for sym_line in new_syms:
-#     sym_line = sym_line.strip()
-#     if sym_line:
-#         name, rest = sym_line.split(" = ")
-#         vram = int(rest.split(";")[0], 0)
-#         new_sym_dict[vram] = name
-
-# renames = []
-# adds = []
-# for addr in new_sym_dict:
-#     found = False
-#     for thing in symbol_addrs:
-#         if thing[1] == addr and not thing[0].startswith("func_") and not thing[0].startswith("D_"):
-#             if new_sym_dict[addr] != thing[0]:
-#                 renames.append(f"{thing[0]} -> {new_sym_dict[addr]}")
-#             found = True
-#             break
-#     if not found:
-#         adds.append(f"{new_sym_dict[addr]} = {addr:X}")
-
-# for r in renames:
-#     print(r)
-# for a in adds:
-#     print(a)
-
-read_elf()
-reconcile_symbols()
-write_new_symbol_addrs()
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(
+        description="Updates symbol_addrs.txt files"
+    )
+
+    parser.add_argument('version', type=str, help="The version to use (e.g. 'pal')")
+    parser.add_argument('-v', '--verbose', action='store_true', help='Enable verbose output')
+
+    args = parser.parse_args()
+
+    # Varies on version
+    version: str = args.version
+    verbose: bool = args.verbose
+
+    current_ver_dir = VERSION_DIRECTORY / version
+    assert (
+        current_ver_dir.is_dir()
+    ), f"first argument passed (`{version}`) should be a valid version, available: {', '.join(AVAILABLE_VERSIONS)}"
+
+    symbol_addrs_path = current_ver_dir / "symbol_addrs.txt"
+    elf_path = current_ver_dir / "build" / "papermario.elf"
+    map_path = current_ver_dir / "build" / "papermario.map"
+
+
+    # Runtime
+    map_symbols: typing.Dict[str, MapSymbol] = {}
+    symbol_addrs: typing.List[ELFSymbol] = []
+    dead_symbols: typing.List[ELFSymbol] = []
+    elf_symbols: typing.List[ELFSymbol] = []
+
+    ignores: typing.Set[str] = set()
+
+    read_ignores()
+    scan_map()
+    read_symbol_addrs()
+    read_elf()
+    reconcile_symbols()
+    write_new_symbol_addrs()

From ba60aee0e348f29d3c25a347ef2b3f5eeb5358c6 Mon Sep 17 00:00:00 2001
From: Devon R <sansgorialis@gmail.com>
Date: Thu, 5 Mar 2026 14:03:17 +0000
Subject: [PATCH 5/8] Reduce reliance on global state in update_symbol_addrs

---
 tools/update_symbol_addrs.py | 57 ++++++++++++++++++++++++------------
 1 file changed, 38 insertions(+), 19 deletions(-)

diff --git a/tools/update_symbol_addrs.py b/tools/update_symbol_addrs.py
index 46c296e2084..b425f435981 100755
--- a/tools/update_symbol_addrs.py
+++ b/tools/update_symbol_addrs.py
@@ -63,20 +63,25 @@ def format(self) -> str:
         return line
 
 
-def read_ignores():
+def read_ignores() -> typing.Set[str]:
     with open(IGNORES_PATH) as f:
         lines = f.readlines()
 
+    ignores: typing.Set[str] = set()
+
     for line in lines:
         ignore = IGNORE_RE.match(line)
 
         if ignore:
             ignores.add(ignore.group("symbol"))
 
+    return ignores
+
 
-def scan_map():
+def scan_map(map_path: pathlib.Path):
     ram_offset = None
     cur_file = "<no file>"
+    map_symbols: typing.Dict[str, MapSymbol] = {}
 
     with open(map_path) as f:
         for line in f:
@@ -112,10 +117,15 @@ def scan_map():
 
             map_symbols[sym] = MapSymbol(rom=rom, file=cur_file, ram=ram)
 
+    return map_symbols
+
 
-def read_symbol_addrs():
+def read_symbol_addrs(symbol_addrs_path: pathlib.Path) -> typing.Tuple[typing.List[ELFSymbol], typing.List[ELFSymbol]]:
     unique_lines: typing.Set[str] = set()
 
+    symbol_addrs: typing.List[ELFSymbol] = []
+    dead_symbols: typing.List[ELFSymbol] = []
+
     with open(symbol_addrs_path, "r") as f:
         for line in f.readlines():
             unique_lines.add(line)
@@ -147,8 +157,15 @@ def read_symbol_addrs():
             else:
                 dead_symbols.append(ELFSymbol(name=name, addr=addr, type=type, rom=rom, opts=opts))
 
+    return (symbol_addrs, dead_symbols)
+
+
+def read_elf(
+    elf_path: pathlib.Path,
+    map_symbols: typing.Dict[str, MapSymbol]
+) -> typing.List[ELFSymbol]:
+    elf_symbols: typing.List[ELFSymbol] = []
 
-def read_elf():
     try:
         result = subprocess.run(["mips-linux-gnu-objdump", "-x", elf_path], stdout=subprocess.PIPE)
         objdump_lines = result.stdout.decode().split("\n")
@@ -190,13 +207,18 @@ def read_elf():
 
             elf_symbols.append(ELFSymbol(name=name, addr=addr, type=type, rom=rom, opts={}))
 
+    return elf_symbols
+
 
 def log(s: str):
     if verbose:
         print(s)
 
 
-def reconcile_symbols():
+def reconcile_symbols(
+    elf_symbols: typing.List[ELFSymbol],
+    symbol_addrs: typing.List[ELFSymbol],
+):
     print(f"Processing {str(len(elf_symbols))} elf symbols...")
 
     for elf_sym in tqdm.tqdm(elf_symbols, total=len(elf_symbols)):
@@ -245,7 +267,11 @@ def reconcile_symbols():
             name_match.rom = elf_sym.rom
 
 
-def write_new_symbol_addrs():
+def write_new_symbol_addrs(
+    symbol_addrs_path: pathlib.Path,
+    symbol_addrs: typing.List[ELFSymbol],
+    dead_symbols: typing.List[ELFSymbol],
+):
     with open(symbol_addrs_path, "w", newline="\n") as f:
         for symbol in sorted(symbol_addrs, key=ELFSymbol.ordering):
             f.write(symbol.format() + "\n")
@@ -279,16 +305,9 @@ def write_new_symbol_addrs():
 
 
     # Runtime
-    map_symbols: typing.Dict[str, MapSymbol] = {}
-    symbol_addrs: typing.List[ELFSymbol] = []
-    dead_symbols: typing.List[ELFSymbol] = []
-    elf_symbols: typing.List[ELFSymbol] = []
-
-    ignores: typing.Set[str] = set()
-
-    read_ignores()
-    scan_map()
-    read_symbol_addrs()
-    read_elf()
-    reconcile_symbols()
-    write_new_symbol_addrs()
+    ignores = read_ignores()
+    map_symbols = scan_map(map_path)
+    symbol_addrs, dead_symbols = read_symbol_addrs(symbol_addrs_path)
+    elf_symbols = read_elf(elf_path, map_symbols)
+    reconcile_symbols(elf_symbols, symbol_addrs)
+    write_new_symbol_addrs(symbol_addrs_path, symbol_addrs, dead_symbols)

From 95c6e6d3d5b99061de9f375a945dfdf032be98b3 Mon Sep 17 00:00:00 2001
From: Devon R <sansgorialis@gmail.com>
Date: Thu, 5 Mar 2026 14:11:37 +0000
Subject: [PATCH 6/8] Using logging for log output in update_symbol_addrs

---
 tools/update_symbol_addrs.py | 29 +++++++++++++++--------------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/tools/update_symbol_addrs.py b/tools/update_symbol_addrs.py
index b425f435981..d9625edd5ba 100755
--- a/tools/update_symbol_addrs.py
+++ b/tools/update_symbol_addrs.py
@@ -2,6 +2,7 @@
 
 import argparse
 import dataclasses
+import logging
 import pathlib
 import re
 import subprocess
@@ -11,6 +12,8 @@
 import tqdm
 
 # Always the same
+LOGGER = logging.getLogger('update_symbol_addrs')
+
 SCRIPT_DIRECTORY = pathlib.Path(__file__).parent
 ROOT_DIRECTORY = SCRIPT_DIRECTORY.parent
 VERSION_DIRECTORY = ROOT_DIRECTORY / "ver"
@@ -170,7 +173,7 @@ def read_elf(
         result = subprocess.run(["mips-linux-gnu-objdump", "-x", elf_path], stdout=subprocess.PIPE)
         objdump_lines = result.stdout.decode().split("\n")
     except Exception:
-        print(f"Error: Could not run objdump on {elf_path} - make sure that the project is built")
+        LOGGER.error(f"Error: Could not run objdump on {elf_path} - make sure that the project is built")
         sys.exit(1)
 
     for line in objdump_lines:
@@ -210,16 +213,11 @@ def read_elf(
     return elf_symbols
 
 
-def log(s: str):
-    if verbose:
-        print(s)
-
-
 def reconcile_symbols(
     elf_symbols: typing.List[ELFSymbol],
     symbol_addrs: typing.List[ELFSymbol],
 ):
-    print(f"Processing {str(len(elf_symbols))} elf symbols...")
+    LOGGER.info(f"Processing {str(len(elf_symbols))} elf symbols...")
 
     for elf_sym in tqdm.tqdm(elf_symbols, total=len(elf_symbols)):
         name_match: typing.Optional[ELFSymbol] = None
@@ -232,7 +230,7 @@ def reconcile_symbols(
                     name_match = known_sym
 
                     if elf_sym.addr != known_sym.addr:
-                        log(
+                        LOGGER.debug(
                             f"Ram mismatch! {elf_sym.name} is 0x{elf_sym.addr:X} in the elf and 0x{known_sym.addr:X} in symbol_addrs"
                         )
 
@@ -245,7 +243,7 @@ def reconcile_symbols(
 
         if not name_match:
             if not rom_match:
-                log(f"Creating new symbol {elf_sym.name}")
+                LOGGER.debug(f"Creating new symbol {elf_sym.name}")
                 symbol_addrs.append(
                     ELFSymbol(
                         name=elf_sym.name,
@@ -256,14 +254,14 @@ def reconcile_symbols(
                     )
                 )
             else:
-                log(f"Renaming identical rom address symbol {rom_match.name} to {elf_sym.name}")
+                LOGGER.debug(f"Renaming identical rom address symbol {rom_match.name} to {elf_sym.name}")
                 rom_match.name = elf_sym.name
 
         elif not rom_match and elf_sym.rom:
             if name_match.rom:
-                log(f"Correcting rom address {name_match.rom} to {elf_sym.rom} for symbol {name_match.name}")
+                LOGGER.debug(f"Correcting rom address {name_match.rom} to {elf_sym.rom} for symbol {name_match.name}")
             else:
-                log(f"Adding rom address {elf_sym.rom} to symbol {name_match.name}")
+                LOGGER.debug(f"Adding rom address {elf_sym.rom} to symbol {name_match.name}")
             name_match.rom = elf_sym.rom
 
 
@@ -281,6 +279,7 @@ def write_new_symbol_addrs(
 
 
 if __name__ == '__main__':
+    # Parse arguments
     parser = argparse.ArgumentParser(
         description="Updates symbol_addrs.txt files"
     )
@@ -290,10 +289,13 @@ def write_new_symbol_addrs(
 
     args = parser.parse_args()
 
-    # Varies on version
     version: str = args.version
     verbose: bool = args.verbose
 
+    # Initialize logging
+    logging.basicConfig(level=logging.DEBUG if verbose else logging.INFO)
+
+    # Version-specific files
     current_ver_dir = VERSION_DIRECTORY / version
     assert (
         current_ver_dir.is_dir()
@@ -303,7 +305,6 @@ def write_new_symbol_addrs(
     elf_path = current_ver_dir / "build" / "papermario.elf"
     map_path = current_ver_dir / "build" / "papermario.map"
 
-
     # Runtime
     ignores = read_ignores()
     map_symbols = scan_map(map_path)

From 1ff350b70c1aa1011e53a1d51dd8f8a0249da872 Mon Sep 17 00:00:00 2001
From: Devon R <sansgorialis@gmail.com>
Date: Thu, 5 Mar 2026 14:47:27 +0000
Subject: [PATCH 7/8] Use mapfile_parser in update_symbol_addrs

---
 tools/configure/requirements.txt |  1 +
 tools/update_symbol_addrs.py     | 67 ++++++++++++++------------------
 2 files changed, 30 insertions(+), 38 deletions(-)

diff --git a/tools/configure/requirements.txt b/tools/configure/requirements.txt
index cfdf338d767..5cfda669b6b 100644
--- a/tools/configure/requirements.txt
+++ b/tools/configure/requirements.txt
@@ -15,3 +15,4 @@ crunch64>=0.5.1
 spimdisasm==1.31.0
 splat64==0.31.0
 requests
+mapfile_parser>=2.12.1,<3.0.0
diff --git a/tools/update_symbol_addrs.py b/tools/update_symbol_addrs.py
index d9625edd5ba..c2680d0cfe1 100755
--- a/tools/update_symbol_addrs.py
+++ b/tools/update_symbol_addrs.py
@@ -2,6 +2,7 @@
 
 import argparse
 import dataclasses
+import json
 import logging
 import pathlib
 import re
@@ -10,6 +11,7 @@
 import typing
 
 import tqdm
+import mapfile_parser
 
 # Always the same
 LOGGER = logging.getLogger('update_symbol_addrs')
@@ -36,9 +38,10 @@
 # Dataclass definitions
 @dataclasses.dataclass
 class MapSymbol:
-    rom: int
     file: str
     ram: int
+    size: int
+    rom: typing.Optional[int]
 
 
 @dataclasses.dataclass
@@ -81,44 +84,18 @@ def read_ignores() -> typing.Set[str]:
     return ignores
 
 
-def scan_map(map_path: pathlib.Path):
-    ram_offset = None
-    cur_file = "<no file>"
+def scan_map(map_file: mapfile_parser.MapFile):
     map_symbols: typing.Dict[str, MapSymbol] = {}
 
-    with open(map_path) as f:
-        for line in f:
-            if "load address" in line:
-                block = MAP_BLOCK_RE.match(line)
-
-                if block is None:
-                    continue
-
-                ram = int(block.group("ram"), 16)
-                rom = int(block.group("rom"), 16)
-                ram_offset = ram - rom
-                continue
-
-            if ram_offset is None or "=" in line or "*fill*" in line or " 0x" not in line:
-                continue
-
-            entry = MAP_ENTRY_RE.match(line)
-
-            if entry is None:
-                continue
-
-            ram = int(entry.group("ram"), 16)
-            rom = ram - ram_offset
-            sym = line.split()[-1]
-
-            if "0x" in sym:
-                ram_offset = None
-                continue
-            elif "/" in sym:
-                cur_file = sym
-                continue
-
-            map_symbols[sym] = MapSymbol(rom=rom, file=cur_file, ram=ram)
+    for segment in map_file:
+        for section in segment:
+            for symbol in section:
+                map_symbols[symbol.name] = MapSymbol(
+                    file=str(section.filepath),
+                    ram=symbol.vram,
+                    size=symbol.size,
+                    rom=symbol.vrom,
+                )
 
     return map_symbols
 
@@ -286,6 +263,8 @@ def write_new_symbol_addrs(
 
     parser.add_argument('version', type=str, help="The version to use (e.g. 'pal')")
     parser.add_argument('-v', '--verbose', action='store_true', help='Enable verbose output')
+    parser.add_argument('--output-csv', type=str, default=None, help="An optional path to output a map file CSV to.")
+    parser.add_argument('--output-json', type=str, default=None, help="An optional path to output a map file CSV to.")
 
     args = parser.parse_args()
 
@@ -306,9 +285,21 @@ def write_new_symbol_addrs(
     map_path = current_ver_dir / "build" / "papermario.map"
 
     # Runtime
+    map_file = mapfile_parser.MapFile.newFromMapFile(map_path)
+
+    if args.output_csv:
+        with open(args.output_csv, 'w', encoding='utf-8') as fp:
+            fp.write(map_file.toCsv())
+
+    if args.output_json:
+        with open(args.output_json, 'w', encoding='utf-8') as fp:
+            json.dump(map_file.toJson(), fp)
+
     ignores = read_ignores()
-    map_symbols = scan_map(map_path)
+    map_symbols = scan_map(map_file)
+
     symbol_addrs, dead_symbols = read_symbol_addrs(symbol_addrs_path)
     elf_symbols = read_elf(elf_path, map_symbols)
+
     reconcile_symbols(elf_symbols, symbol_addrs)
     write_new_symbol_addrs(symbol_addrs_path, symbol_addrs, dead_symbols)

From 1f76e3e3ec9ff099a1fc7355463a2c94deeefae6 Mon Sep 17 00:00:00 2001
From: Devon R <sansgorialis@gmail.com>
Date: Thu, 5 Mar 2026 14:49:10 +0000
Subject: [PATCH 8/8] I always forget to do the black formatting

---
 tools/update_symbol_addrs.py | 25 ++++++++++---------------
 1 file changed, 10 insertions(+), 15 deletions(-)

diff --git a/tools/update_symbol_addrs.py b/tools/update_symbol_addrs.py
index c2680d0cfe1..c042335d994 100755
--- a/tools/update_symbol_addrs.py
+++ b/tools/update_symbol_addrs.py
@@ -14,7 +14,7 @@
 import mapfile_parser
 
 # Always the same
-LOGGER = logging.getLogger('update_symbol_addrs')
+LOGGER = logging.getLogger("update_symbol_addrs")
 
 SCRIPT_DIRECTORY = pathlib.Path(__file__).parent
 ROOT_DIRECTORY = SCRIPT_DIRECTORY.parent
@@ -140,10 +140,7 @@ def read_symbol_addrs(symbol_addrs_path: pathlib.Path) -> typing.Tuple[typing.Li
     return (symbol_addrs, dead_symbols)
 
 
-def read_elf(
-    elf_path: pathlib.Path,
-    map_symbols: typing.Dict[str, MapSymbol]
-) -> typing.List[ELFSymbol]:
+def read_elf(elf_path: pathlib.Path, map_symbols: typing.Dict[str, MapSymbol]) -> typing.List[ELFSymbol]:
     elf_symbols: typing.List[ELFSymbol] = []
 
     try:
@@ -255,16 +252,14 @@ def write_new_symbol_addrs(
             f.write(symbol.format() + "\n")
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     # Parse arguments
-    parser = argparse.ArgumentParser(
-        description="Updates symbol_addrs.txt files"
-    )
+    parser = argparse.ArgumentParser(description="Updates symbol_addrs.txt files")
 
-    parser.add_argument('version', type=str, help="The version to use (e.g. 'pal')")
-    parser.add_argument('-v', '--verbose', action='store_true', help='Enable verbose output')
-    parser.add_argument('--output-csv', type=str, default=None, help="An optional path to output a map file CSV to.")
-    parser.add_argument('--output-json', type=str, default=None, help="An optional path to output a map file CSV to.")
+    parser.add_argument("version", type=str, help="The version to use (e.g. 'pal')")
+    parser.add_argument("-v", "--verbose", action="store_true", help="Enable verbose output")
+    parser.add_argument("--output-csv", type=str, default=None, help="An optional path to output a map file CSV to.")
+    parser.add_argument("--output-json", type=str, default=None, help="An optional path to output a map file CSV to.")
 
     args = parser.parse_args()
 
@@ -288,11 +283,11 @@ def write_new_symbol_addrs(
     map_file = mapfile_parser.MapFile.newFromMapFile(map_path)
 
     if args.output_csv:
-        with open(args.output_csv, 'w', encoding='utf-8') as fp:
+        with open(args.output_csv, "w", encoding="utf-8") as fp:
             fp.write(map_file.toCsv())
 
     if args.output_json:
-        with open(args.output_json, 'w', encoding='utf-8') as fp:
+        with open(args.output_json, "w", encoding="utf-8") as fp:
             json.dump(map_file.toJson(), fp)
 
     ignores = read_ignores()