mapfile-parser 2.7.2__cp39-cp39-win32.whl

mapfile_parser/__init__.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+
+# SPDX-FileCopyrightText: © 2022-2024 Decompollaborate
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+__version_info__ = (2, 7, 2)
+__version__ = ".".join(map(str, __version_info__))# + "-dev0"
+__author__ = "Decompollaborate"
+
+from . import utils as utils
+
+from .mapfile import MapFile as MapFile
+from .mapfile import Symbol as Symbol
+from .mapfile import File as File
+from .mapfile import Segment as Segment
+from .mapfile import FoundSymbolInfo as FoundSymbolInfo
+from .mapfile import SymbolComparisonInfo as SymbolComparisonInfo
+from .mapfile import MapsComparisonInfo as MapsComparisonInfo
+
+from .progress_stats import ProgressStats as ProgressStats
+
+from . import frontends as frontends

mapfile_parser/__main__.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+
+# SPDX-FileCopyrightText: © 2022-2024 Decompollaborate
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import argparse
+
+import mapfile_parser
+
+
+def mapfileParserMain():
+    parser = argparse.ArgumentParser(description="Interface to call any of the mapfile_parser's CLI utilities", prog="mapfile_parser")
+
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {mapfile_parser.__version__}")
+
+    subparsers = parser.add_subparsers(description="action", help="the action to perform", required=True)
+
+    mapfile_parser.frontends.bss_check.addSubparser(subparsers)
+    mapfile_parser.frontends.first_diff.addSubparser(subparsers)
+    mapfile_parser.frontends.jsonify.addSubparser(subparsers)
+    mapfile_parser.frontends.pj64_syms.addSubparser(subparsers)
+    mapfile_parser.frontends.progress.addSubparser(subparsers)
+    mapfile_parser.frontends.sym_info.addSubparser(subparsers)
+    mapfile_parser.frontends.symbol_sizes_csv.addSubparser(subparsers)
+    mapfile_parser.frontends.upload_frogress.addSubparser(subparsers)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    mapfileParserMain()

mapfile_parser/frontends/__init__.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+
+# SPDX-FileCopyrightText: © 2022-2024 Decompollaborate
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+
+from . import bss_check as bss_check
+from . import first_diff as first_diff
+from . import jsonify as jsonify
+from . import pj64_syms as pj64_syms
+from . import progress as progress
+from . import sym_info as sym_info
+from . import symbol_sizes_csv as symbol_sizes_csv
+from . import upload_frogress as upload_frogress

mapfile_parser/frontends/bss_check.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+
+# SPDX-FileCopyrightText: © 2023-2024 Decompollaborate
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+
+from .. import mapfile
+from .. import utils
+
+
+def getComparison(mapPath: Path, expectedMapPath: Path, *, reverseCheck: bool=True) -> mapfile.MapsComparisonInfo:
+    buildMap = mapfile.MapFile()
+    buildMap.readMapFile(mapPath)
+    buildMap = buildMap.filterBySectionType(".bss")
+
+    expectedMap = mapfile.MapFile()
+    expectedMap.readMapFile(expectedMapPath)
+    expectedMap = expectedMap.filterBySectionType(".bss")
+
+    return buildMap.compareFilesAndSymbols(expectedMap, checkOtherOnSelf=reverseCheck)
+
+def printSymbolComparisonAsCsv(comparisonInfo: mapfile.MapsComparisonInfo, printAll: bool=False, printGoods: bool=True):
+    print("Symbol Name,Build Address,Build File,Expected Address,Expected File,Difference,GOOD/BAD/MISSING")
+
+    # If it's bad or missing, don't need to do anything special.
+    # If it's good, check for if it's in a file with bad or missing stuff, and check if print all is on. If none of these, print it.
+
+    for symbolInfo in comparisonInfo.comparedList:
+        buildFile = symbolInfo.buildFile
+        expectedFile = symbolInfo.expectedFile
+        buildFilePath = buildFile.filepath if buildFile is not None else None
+        expectedFilePath = expectedFile.filepath if expectedFile is not None else None
+
+        if symbolInfo.diff is None:
+            print(f"{symbolInfo.symbol.name},{symbolInfo.buildAddress:X},{buildFilePath},{symbolInfo.expectedAddress:X},{expectedFilePath},{symbolInfo.diff},MISSING")
+            continue
+
+        symbolState = "BAD"
+        if symbolInfo.diff == 0:
+            symbolState = "GOOD"
+            if not buildFile in comparisonInfo.badFiles and not expectedFile in comparisonInfo.badFiles:
+                if not buildFile in comparisonInfo.badFiles and not expectedFile in comparisonInfo.badFiles:
+                    if not printAll:
+                        continue
+
+        if not printGoods and symbolState == "GOOD":
+            continue
+
+        if buildFile != expectedFile:
+            symbolState += " MOVED"
+        print(f"{symbolInfo.symbol.name},{symbolInfo.buildAddress:X},{buildFilePath},{symbolInfo.expectedAddress:X},{expectedFilePath},{symbolInfo.diff:X},{symbolState}")
+
+def printSymbolComparisonAsListing(comparisonInfo: mapfile.MapsComparisonInfo, printAll: bool=False, printGoods: bool=True):
+    # print("Symbol Name,Build Address,Build File,Expected Address,Expected File,Difference,GOOD/BAD/MISSING")
+
+    # If it's bad or missing, don't need to do anything special.
+    # If it's good, check for if it's in a file with bad or missing stuff, and check if print all is on. If none of these, print it.
+
+    for symbolInfo in comparisonInfo.comparedList:
+        buildFile = symbolInfo.buildFile
+        expectedFile = symbolInfo.expectedFile
+        buildFilePath = buildFile.filepath if buildFile is not None else None
+        expectedFilePath = expectedFile.filepath if expectedFile is not None else None
+
+        if symbolInfo.diff is None:
+            print(f"Symbol: {symbolInfo.symbol.name} (MISSING)")
+            if symbolInfo.buildAddress != -1:
+                print(f"    Build:      0x{symbolInfo.buildAddress:08X} (file: {buildFilePath})")
+            if symbolInfo.expectedAddress != -1:
+                print(f"    Expected:   0x{symbolInfo.expectedAddress:08X} (file: {expectedFilePath})")
+            continue
+
+        symbolState = "BAD"
+        if symbolInfo.diff == 0:
+            symbolState = "GOOD"
+            if not buildFile in comparisonInfo.badFiles and not expectedFile in comparisonInfo.badFiles:
+                if not buildFile in comparisonInfo.badFiles and not expectedFile in comparisonInfo.badFiles:
+                    if not printAll:
+                        continue
+
+        if not printGoods and symbolState == "GOOD":
+            continue
+
+        if buildFile != expectedFile:
+            symbolState += " MOVED"
+
+        if symbolInfo.diff < 0:
+            diffStr = f"-0x{-symbolInfo.diff:02X}"
+        else:
+            diffStr = f"0x{symbolInfo.diff:02X}"
+
+        print(f"Symbol: {symbolInfo.symbol.name} ({symbolState}) (diff: {diffStr})")
+        print(f"    Build:      0x{symbolInfo.buildAddress:08X} (file: {buildFilePath})")
+        print(f"    Expected:   0x{symbolInfo.expectedAddress:08X} (file: {expectedFilePath})")
+
+def printSymbolComparison(comparisonInfo: mapfile.MapsComparisonInfo, printAll: bool=False, printGoods: bool=True, printingStyle: str="csv"):
+    if printingStyle == "csv":
+        printSymbolComparisonAsCsv(comparisonInfo, printAll, printGoods)
+    elif printingStyle == "listing":
+        printSymbolComparisonAsListing(comparisonInfo, printAll, printGoods)
+    else:
+        printSymbolComparisonAsListing(comparisonInfo, printAll, printGoods)
+
+def printFileComparison(comparisonInfo: mapfile.MapsComparisonInfo):
+    utils.eprint("")
+
+    if len(comparisonInfo.badFiles) != 0:
+        utils.eprint("  BAD")
+
+        for file in comparisonInfo.badFiles:
+            utils.eprint(f"bss reordering in {file.filepath}")
+        utils.eprint("")
+
+    if len(comparisonInfo.missingFiles) != 0:
+        utils.eprint("  MISSING")
+
+        for file in comparisonInfo.missingFiles:
+            utils.eprint(f"Symbols missing from {file.filepath}")
+        utils.eprint("")
+
+        utils.eprint("Some files appear to be missing symbols. Have they been renamed or declared as static? You may need to remake 'expected'")
+
+
+def doBssCheck(mapPath: Path, expectedMapPath: Path, *, printAll: bool=False, reverseCheck: bool=True) -> int:
+    if not mapPath.exists():
+        utils.eprint(f"{mapPath} must exist")
+        return 1
+    if not expectedMapPath.exists():
+        utils.eprint(f"{expectedMapPath} must exist")
+        return 1
+
+    comparisonInfo = getComparison(mapPath, expectedMapPath, reverseCheck=reverseCheck)
+    printSymbolComparison(comparisonInfo, printAll)
+
+    if len(comparisonInfo.badFiles) + len(comparisonInfo.missingFiles) != 0:
+        printFileComparison(comparisonInfo)
+        return 1
+
+    utils.eprint("")
+    utils.eprint("  GOOD")
+
+    return 0
+
+
+def processArguments(args: argparse.Namespace):
+    mapPath: Path = args.mapfile
+    expectedMapPath: Path = args.expectedmap
+
+    printAll: bool = args.print_all
+    reverseCheck: bool = not args.no_reverse_check
+
+    exit(doBssCheck(mapPath, expectedMapPath, printAll=printAll, reverseCheck=reverseCheck))
+
+
+def addSubparser(subparser: argparse._SubParsersAction[argparse.ArgumentParser]):
+    parser = subparser.add_parser("bss_check", help="Check that globally visible bss has not been reordered.")
+
+    parser.add_argument("mapfile", help="Path to a map file", type=Path)
+    parser.add_argument("expectedmap", help="Path to the map file in the expected dir", type=Path)
+
+    parser.add_argument("-a", "--print-all", help="Print all bss, not just non-matching.", action="store_true")
+    parser.add_argument("--no-reverse-check", help="Disable looking for symbols on the expected map that are missing on the built map file.", action="store_true")
+
+    parser.set_defaults(func=processArguments)

mapfile_parser/frontends/first_diff.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+
+# SPDX-FileCopyrightText: © 2022-2024 Decompollaborate
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Callable, Literal
+
+from .. import mapfile
+from .. import utils
+
+
+def doFirstDiff(mapPath: Path, expectedMapPath: Path, romPath: Path, expectedRomPath: Path, diffCount: int=5, mismatchSize: bool=False, addColons: bool=True, bytesConverterCallback:Callable[[bytes, mapfile.MapFile],str|None]|None=None, endian: Literal["big", "little"] ="big") -> int:
+    if not mapPath.exists():
+        print(f"{mapPath} must exist")
+        return 1
+    if not expectedMapPath.exists():
+        print(f"{expectedMapPath} must exist")
+        return 1
+    if not romPath.exists():
+        print(f"{romPath} must exist")
+        return 1
+    if not expectedRomPath.exists():
+        print(f"{expectedRomPath} must exist")
+        return 1
+
+    builtRom = utils.readFileAsBytearray(romPath)
+    expectedRom = utils.readFileAsBytearray(expectedRomPath)
+
+    if len(builtRom) != len(expectedRom):
+        print("Modified ROM has different size...")
+        print(f"It should be 0x{len(expectedRom):X} but it is 0x{len(builtRom):X}")
+        if not mismatchSize:
+            return 1
+
+    if builtRom == expectedRom:
+        print("No differences!")
+        return 0
+
+    builtMapFile = mapfile.MapFile()
+    builtMapFile.readMapFile(mapPath)
+    expectedMapFile = mapfile.MapFile()
+    expectedMapFile.readMapFile(expectedMapPath)
+
+    endian_diff = 0
+    if endian == "little":
+        endian_diff = 3
+
+    map_search_diff: set[str] = set()
+    diffs = 0
+    shift_cap = 1000
+    for i in range(24, min(len(builtRom), len(expectedRom)), 4):
+        # (builtRom[i:i+4] != expectedRom[i:i+4], but that's slightly slower in CPython...)
+        if diffs <= shift_cap and (
+            builtRom[i] != expectedRom[i]
+            or builtRom[i + 1] != expectedRom[i + 1]
+            or builtRom[i + 2] != expectedRom[i + 2]
+            or builtRom[i + 3] != expectedRom[i + 3]
+        ):
+            if diffs == 0:
+                vromInfo, possibleFiles = builtMapFile.findSymbolByVrom(i)
+                extraMessage = ""
+                if vromInfo is not None:
+                    extraMessage = f", {vromInfo.getAsStrPlusOffset()}"
+                elif len(possibleFiles) > 0:
+                    extraMessage = f", in file {possibleFiles[0].asStr()}"
+                print(f"First difference at ROM addr 0x{i:X}{extraMessage}")
+                builtBytes = builtRom[i : i + 4]
+                expectedBytes = expectedRom[i : i + 4]
+                print(f"Bytes: {utils.hexbytes(builtBytes, addColons=addColons)} vs {utils.hexbytes(expectedBytes, addColons=addColons)}")
+                if bytesConverterCallback is not None:
+                    builtConverted = bytesConverterCallback(builtBytes, builtMapFile)
+                    expectedConverted = bytesConverterCallback(expectedBytes, expectedMapFile)
+                    if builtConverted is not None and expectedConverted is not None:
+                        print(f"{builtConverted} vs {expectedConverted}")
+            diffs += 1
+
+        if (
+            len(map_search_diff) < diffCount
+            and builtRom[i+endian_diff] >> 2 != expectedRom[i+endian_diff] >> 2
+        ):
+            vromInfo, possibleFiles = builtMapFile.findSymbolByVrom(i)
+            if vromInfo is not None:
+                vromMessage = vromInfo.getAsStr()
+                if vromMessage not in map_search_diff:
+                    map_search_diff.add(vromMessage)
+
+                    extraMessage = f", {vromInfo.getAsStrPlusOffset()}"
+                    print(f"Instruction difference at ROM addr 0x{i:X}{extraMessage}")
+                    builtBytes = builtRom[i : i + 4]
+                    expectedBytes = expectedRom[i : i + 4]
+                    print(f"Bytes: {utils.hexbytes(builtBytes, addColons=addColons)} vs {utils.hexbytes(expectedBytes, addColons=addColons)}")
+                    if bytesConverterCallback is not None:
+                        builtConverted = bytesConverterCallback(builtBytes, builtMapFile)
+                        expectedConverted = bytesConverterCallback(expectedBytes, expectedMapFile)
+                        if builtConverted is not None and expectedConverted is not None:
+                            print(f"{builtConverted} vs {expectedConverted}")
+            elif len(possibleFiles) > 0:
+                extraMessage = f", in file {possibleFiles[0].asStr()}"
+                print(f"Instruction difference at ROM addr 0x{i:X}{extraMessage}")
+                builtBytes = builtRom[i : i + 4]
+                expectedBytes = expectedRom[i : i + 4]
+                print(f"Bytes: {utils.hexbytes(builtBytes, addColons=addColons)} vs {utils.hexbytes(expectedBytes, addColons=addColons)}")
+                if bytesConverterCallback is not None:
+                    builtConverted = bytesConverterCallback(builtBytes, builtMapFile)
+                    expectedConverted = bytesConverterCallback(expectedBytes, expectedMapFile)
+                    if builtConverted is not None and expectedConverted is not None:
+                        print(f"{builtConverted} vs {expectedConverted}")
+
+        if len(map_search_diff) >= diffCount and diffs > shift_cap:
+            break
+
+    if diffs == 0:
+        print("No differences but ROMs differ?")
+        return 1
+
+    print()
+    definite_shift = diffs > shift_cap
+    if definite_shift:
+        print(f"Over {shift_cap} differing words, must be a shifted ROM.")
+    else:
+        print(f"{diffs} differing word(s).")
+
+    if diffs > 100:
+        firstDifferingSym = builtMapFile.findLowestDifferingSymbol(expectedMapFile)
+        if firstDifferingSym is None:
+            print(f"No ROM shift{' (!?)' if definite_shift else ''}")
+        else:
+            sym, file, prevSym = firstDifferingSym
+            extraMessage = ""
+            if prevSym is not None:
+                extraMessage = f" -- in {prevSym.name}?"
+            print(f"Map appears to have shifted just before {sym.name} ({file.filepath}){extraMessage}")
+            return 1
+
+    return 0
+
+
+def processArguments(args: argparse.Namespace):
+    mapPath: Path = args.mapfile
+    expectedMapPath: Path = args.expectedmap
+    romPath: Path = args.rompath
+    expectedRomPath: Path = args.expectedrom
+
+    diffCount: int = args.count
+    mismatchSize: bool = args.mismatch_size
+
+    endian = args.endian
+
+    exit(doFirstDiff(mapPath, expectedMapPath, romPath, expectedRomPath, diffCount, mismatchSize, endian=endian))
+
+
+def addSubparser(subparser: argparse._SubParsersAction[argparse.ArgumentParser]):
+    parser = subparser.add_parser("first_diff", help="Find the first difference(s) between the built ROM and the base ROM.")
+
+    parser.add_argument("mapfile", help="Path to a map file", type=Path)
+    parser.add_argument("expectedmap", help="Path to the map file in the expected dir", type=Path)
+    parser.add_argument("rompath", help="Path to built ROM", type=Path)
+    parser.add_argument("expectedrom", help="Path to the expected ROM", type=Path)
+
+    parser.add_argument("-c", "--count", type=int, default=5, help="find up to this many instruction difference(s)")
+    parser.add_argument("-m", "--mismatch-size", help="Do not exit early if the ROM sizes does not match", action="store_true")
+    parser.add_argument("-e", "--endian", help="Specify endianness of the binary", choices=["big", "little"], default="big")
+
+    parser.set_defaults(func=processArguments)

mapfile_parser/frontends/jsonify.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+
+# SPDX-FileCopyrightText: © 2023-2024 Decompollaborate
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .. import mapfile
+
+
+def doJsonify(mapPath: Path, outputPath: Path|None, humanReadable: bool=True, applyFixes: bool=False) -> int:
+    if not mapPath.exists():
+        print(f"Could not find mapfile at '{mapPath}'")
+        return 1
+
+    mapFile = mapfile.MapFile()
+    mapFile.readMapFile(mapPath)
+    if applyFixes:
+        mapFile = mapFile.fixupNonMatchingSymbols()
+
+    jsonStr = json.dumps(mapFile.toJson(humanReadable=humanReadable), indent=4)
+
+    if outputPath is None:
+        print(jsonStr)
+    else:
+        outputPath.parent.mkdir(parents=True, exist_ok=True)
+        outputPath.write_text(jsonStr)
+
+    return 0
+
+
+def processArguments(args: argparse.Namespace):
+    mapPath: Path = args.mapfile
+    outputPath: Path|None = Path(args.output) if args.output is not None else None
+    machine: bool = args.machine
+    applyFixes: bool = args.apply_fixes
+
+    exit(doJsonify(mapPath, outputPath, humanReadable=not machine, applyFixes=applyFixes))
+
+def addSubparser(subparser: argparse._SubParsersAction[argparse.ArgumentParser]):
+    parser = subparser.add_parser("jsonify", help="Converts a mapfile into a json format.")
+
+    parser.add_argument("mapfile", help="Path to a map file", type=Path)
+    parser.add_argument("-o", "--output", help="Output path of for the generated json. If omitted then stdout is used instead.")
+    parser.add_argument("-m", "--machine", help="Emit numbers as numbers instead of outputting them as pretty strings.", action="store_true")
+    parser.add_argument("-f", "--apply-fixes", help="Apply certain fixups, like fixing size calculation of because of the existence of fake `.NON_MATCHING` symbols.", action="store_true")
+
+    parser.set_defaults(func=processArguments)

mapfile_parser/frontends/pj64_syms.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+
+# SPDX-FileCopyrightText: © 2022-2024 Decompollaborate
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import TextIO
+import sys
+
+from .. import mapfile
+
+
+def writePj64SymsToFile(mapFile: mapfile.MapFile, outFile: TextIO):
+    for segment in mapFile:
+        for file in segment:
+            for sym in file:
+                symType = "code" if file.sectionType == ".text" else "data"
+                outFile.write(f"{sym.vram:08X},{symType},{sym.name}\n")
+
+def doPj64Syms(mapPath: Path, outputPath: Path|None) -> int:
+    if not mapPath.exists():
+        print(f"Could not find mapfile at '{mapPath}'")
+        return 1
+
+    mapFile = mapfile.MapFile()
+    mapFile.readMapFile(mapPath)
+
+    if outputPath is None:
+        writePj64SymsToFile(mapFile, sys.stdout)
+    else:
+        with outputPath.open("w") as outFile:
+            writePj64SymsToFile(mapFile, outFile)
+
+    return 0
+
+def processArguments(args: argparse.Namespace):
+    mapPath: Path = args.mapfile
+    outputPath: Path = args.output
+
+    exit(doPj64Syms(mapPath, outputPath))
+
+def addSubparser(subparser: argparse._SubParsersAction[argparse.ArgumentParser]):
+    parser = subparser.add_parser("pj64_syms", help="Produce a PJ64 compatible symbol map.")
+
+    parser.add_argument("mapfile", help="Path to a map file", type=Path)
+    parser.add_argument("output", help="Path to output file. If omitted then output will be written to stdout", type=Path, nargs="?")
+
+    parser.set_defaults(func=processArguments)

mapfile_parser/frontends/progress.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+
+# SPDX-FileCopyrightText: © 2022-2024 Decompollaborate
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .. import mapfile
+from .. import progress_stats
+
+
+def getProgress(mapPath: Path, asmPath: Path, nonmatchingsPath: Path, pathIndex: int=2, checkFunctionFiles: bool=True, debugging: bool=False) -> tuple[progress_stats.ProgressStats, dict[str, progress_stats.ProgressStats]]:
+    mapFile = mapfile.MapFile()
+
+    mapFile.debugging = debugging
+    mapFile.readMapFile(mapPath)
+
+    return mapFile.filterBySectionType(".text").fixupNonMatchingSymbols().getProgress(asmPath, nonmatchingsPath, pathIndex=pathIndex, checkFunctionFiles=checkFunctionFiles)
+
+def doProgress(mapPath: Path, asmPath: Path, nonmatchingsPath: Path, pathIndex: int=2, checkFunctionFiles: bool=True, print_json: bool=False, debugging: bool=False) -> int:
+    if not mapPath.exists():
+        print(f"Could not find mapfile at '{mapPath}'")
+        return 1
+
+    totalStats, progressPerFolder = getProgress(mapPath, asmPath, nonmatchingsPath, pathIndex=pathIndex, checkFunctionFiles=checkFunctionFiles, debugging=debugging)
+
+    if print_json:
+        json_temp: dict[str, dict[str, int|float]] = {
+            "all": totalStats.asJsonEntry()
+        }
+        for folder, statsEntry in progressPerFolder.items():
+            json_temp[folder] = statsEntry.asJsonEntry()
+        print(json.dumps(json_temp, indent=4))
+    else:
+        progress_stats.printStats(totalStats, progressPerFolder)
+    return 0
+
+
+def processArguments(args: argparse.Namespace):
+    mapPath: Path = args.mapfile
+    asmPath: Path = args.asmpath
+    nonmatchingsPath: Path = args.nonmatchingspath
+    pathIndex: int = args.path_index
+    checkFunctionFiles: bool = not args.avoid_function_files
+    debugging: bool = args.debugging #! @deprecated
+    print_json: bool = args.json
+
+    exit(doProgress(mapPath, asmPath, nonmatchingsPath, pathIndex=pathIndex, checkFunctionFiles=checkFunctionFiles, print_json=print_json, debugging=debugging))
+
+def addSubparser(subparser: argparse._SubParsersAction[argparse.ArgumentParser]):
+    parser = subparser.add_parser("progress", help="Computes current progress of the matched functions. Relies on a splat (https://github.com/ethteck/splat) folder structure and matched functions not longer having a file.")
+
+    parser.add_argument("mapfile", help="Path to a map file", type=Path)
+    parser.add_argument("asmpath", help="Path to asm folder", type=Path)
+    parser.add_argument("nonmatchingspath", help="Path to nonmatchings folder", type=Path)
+    parser.add_argument("-i", "--path-index", help="Specify the index to start reading the file paths. Defaults to 2", type=int, default=2)
+    parser.add_argument("-f", "--avoid-function-files", help="Avoid checking if the assembly file for a function exists as a way to determine if the function has been matched or not", action="store_true")
+    parser.add_argument("-d", "--debugging", help="Enable debugging prints. This option is deprecated", action="store_true")
+    parser.add_argument("-j", "--json", help="Print the stats as json instead of a human readable format.", action="store_true")
+
+    parser.set_defaults(func=processArguments)

mapfile_parser/frontends/sym_info.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+
+# SPDX-FileCopyrightText: © 2022-2024 Decompollaborate
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .. import mapfile
+from .. import utils
+
+
+def doSymInfo(mapPath: Path, symName: str, *, as_vram: bool=False, as_vrom: bool=False, as_name: bool=False) -> int:
+    if not mapPath.exists():
+        print(f"Could not find mapfile at '{mapPath}'")
+        return 1
+
+    mapFile = mapfile.MapFile()
+    mapFile.readMapFile(mapPath)
+
+    possibleFiles: list[mapfile.File] = []
+
+    if as_vram:
+        address = int(symName, 0)
+        info, possibleFiles = mapFile.findSymbolByVram(address)
+    elif as_vrom:
+        address = int(symName, 0)
+        info, possibleFiles = mapFile.findSymbolByVrom(address)
+    elif as_name:
+        info = mapFile.findSymbolByName(symName)
+
+    # Start the guessing game
+    elif utils.convertibleToInt(symName, 0):
+        address = int(symName, 0)
+        info, possibleFiles = mapFile.findSymbolByVram(address)
+        if info is None:
+            info, possibleFiles2 = mapFile.findSymbolByVrom(address)
+            possibleFiles.extend(possibleFiles2)
+    else:
+        info = mapFile.findSymbolByName(symName)
+
+    if info is not None:
+        print(info.getAsStrPlusOffset(symName))
+        return 0
+    print(f"'{symName}' not found in map file '{mapPath}'")
+    if len(possibleFiles) > 0:
+        print("But it may be a local symbol of either of the following files:")
+        for f in possibleFiles:
+            print(f"    {f.asStr()})")
+    return 1
+
+
+def processArguments(args: argparse.Namespace):
+    mapPath: Path = args.mapfile
+    symName: str = args.symname
+    as_vram: bool = args.vram
+    as_vrom: bool = args.vrom
+    as_name: bool = args.name
+
+    exit(doSymInfo(mapPath, symName, as_vram=as_vram, as_vrom=as_vrom, as_name=as_name))
+
+def addSubparser(subparser: argparse._SubParsersAction[argparse.ArgumentParser]):
+    parser = subparser.add_parser("sym_info", help="Display various information about a symbol or address.")
+
+    parser.add_argument("mapfile", help="Path to a map file.", type=Path)
+    parser.add_argument("symname", help="Symbol name or VROM/VRAM address to lookup. How to treat this argument will be guessed.")
+
+    vram_vrom_group = parser.add_mutually_exclusive_group()
+    vram_vrom_group.add_argument("--vram", help="Treat the argument as a VRAM address instead of guessing.", action="store_true")
+    vram_vrom_group.add_argument("--vrom", help="Treat the argument as a VROM address instead of guessing.", action="store_true")
+    vram_vrom_group.add_argument("--name", help="Treat the argument as a symbol name instead of guessing.", action="store_true")
+
+    parser.set_defaults(func=processArguments)