headless: add --re-module, a static reverse-engineering dump for one PRX

Loads a single module standalone - no game, no boot - and writes a report:
module header and segments, the export and import tables with NIDs resolved to
names through the HLE tables, one annotated disassembly file per function, and
a call graph as JSON.

Reuses the emulator's own loader rather than parsing PRXes a second time, so
decryption, decompression, relocation and import resolution can't drift from
what actually runs. Only enough of the system is brought up to load a module:
memory map, timing, HLE tables and the kernel allocators. Nothing executes.

Two things beyond a plain disassembly, both aimed at the questions that come up
when reading unfamiliar MIPS:

- lui/addiu (and lui/load) pairs are folded and reported as the address they
  form, which is how every global and constant table gets reached.
- Per function, a register evidence block instead of a guessed signature. A
  MIPS function that takes two arguments and passes the second one down often
  never reads it, so 'never read but live across a call' is reported as
  forwarded rather than quietly dropped from the signature.

SetForceRealModuleLoads() is needed because modules like sceAudiocodec_Driver
have no DisableHLEFlags bit and so can't be turned off the normal way - they'd
fake-load and there would be nothing to look at.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

headless/Headless.cpp

@@ -59,6 +59,7 @@
 #include "Core/System.h"
 #include "Core/Util/PSARUnpack.h"
 #include "Core/Util/PkgUnpack.h"
+#include "headless/ReverseEngineer.h"
 #include "Core/WebServer.h"
 #include "Core/HLE/sceUtility.h"
 #include "Core/SaveState.h"
@@ -860,6 +861,18 @@ int main(int argc, const char* argv[]) {
 	}
 	g_Config.nandRootDirectory = GetSysDirectory(DIRECTORY_NAND);
 	coreParameter.nandRoot = g_Config.nandRootDirectory;
+	// Placed here rather than with the other early-exit subcommands above, because resolving a
+	// "flash0:/kd/foo.prx" module path needs nandRootDirectory, which is only settled just above.
+	if (cmdLineOptions.reModule.has_value()) {
+		ReverseEngineerOptions reOptions;
+		reOptions.modulePath = cmdLineOptions.reModule.value();
+		reOptions.outDir = cmdLineOptions.reOut.value_or("re-out");
+		reOptions.funcFilter = cmdLineOptions.reFunc.value_or("");
+		reOptions.symsFile = cmdLineOptions.reSyms.value_or("");
+		reOptions.verbose = testOptions.verbose;
+		return RunReverseEngineer(reOptions);
+	}
+
 
 	// Try to find the assets flash0 directory. Often this is from a subdirectory.
 	// This is needed for our fallback fonts.

headless/Headless.vcxproj

@@ -354,6 +354,7 @@
     </ClCompile>
     <ClCompile Include="..\Windows\W32Util\Misc.cpp" />
     <ClCompile Include="Compare.cpp" />
+    <ClCompile Include="ReverseEngineer.cpp" />
     <ClCompile Include="Headless.cpp">
       <PrecompiledHeader Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">NotUsing</PrecompiledHeader>
       <PrecompiledHeader Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">NotUsing</PrecompiledHeader>
@@ -416,6 +417,7 @@
       <ExcludedFromBuild Condition="'$(Configuration)|$(Platform)'=='Release|x64'">true</ExcludedFromBuild>
     </ClInclude>
     <ClInclude Include="Compare.h" />
+    <ClInclude Include="ReverseEngineer.h" />
     <ClInclude Include="SDLHeadlessGLGraphicsContext.h">
       <ExcludedFromBuild Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">true</ExcludedFromBuild>
       <ExcludedFromBuild Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">true</ExcludedFromBuild>

headless/Headless.vcxproj.filters

@@ -3,6 +3,7 @@
   <ItemGroup>
     <ClCompile Include="Headless.cpp" />
     <ClCompile Include="Compare.cpp" />
+    <ClCompile Include="ReverseEngineer.cpp" />
     <ClCompile Include="..\ext\glew\glew.c" />
     <ClCompile Include="..\Windows\GPU\WindowsGLContext.cpp">
       <Filter>Windows</Filter>
@@ -35,6 +36,7 @@
   </ItemGroup>
   <ItemGroup>
     <ClInclude Include="Compare.h" />
+    <ClInclude Include="ReverseEngineer.h" />
     <ClInclude Include="WindowsHeadlessHost.h">
       <Filter>Windows</Filter>
     </ClInclude>

headless/ReverseEngineer.cpp

@@ -0,0 +1,688 @@
+// Copyright (c) 2026- PPSSPP Project.
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, version 2.0 or later versions.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License 2.0 for more details.
+
+// A copy of the GPL 2.0 should have been included with the program.
+// If not, see http://www.gnu.org/licenses/
+
+// Official git repository and contact information can be found at
+// https://github.com/hrydgard/ppsspp and http://www.ppsspp.org/.
+
+// Static reverse-engineering dump for a single PRX, with no game running.
+//
+// Brings up just enough of the emulator to run the real module loader (decrypt, decompress,
+// relocate, resolve imports/exports, scan for functions), then writes a report: an index of
+// the module's exports/imports/functions, one annotated disassembly file per function, and a
+// call graph.
+//
+// Deliberately reuses the emulator's own loader rather than parsing PRXes a second time - a
+// separate parser would drift from the one that actually runs.
+
+#include <algorithm>
+#include <cstdio>
+#include <cstring>
+#include <map>
+#include <set>
+#include <string>
+#include <vector>
+
+#include "Common/File/FileUtil.h"
+#include "Common/File/Path.h"
+#include "Common/StringUtils.h"
+
+#include "Core/Config.h"
+#include "Core/CoreTiming.h"
+#include "Core/Debugger/DebugInterface.h"
+#include "Core/Debugger/DisassemblyManager.h"
+#include "Core/Debugger/SymbolMap.h"
+#include "Core/FileSystems/DirectoryFileSystem.h"
+#include "Core/FileSystems/MetaFileSystem.h"
+#include "Core/HLE/HLE.h"
+#include "Core/HLE/sceKernel.h"
+#include "Core/HLE/sceKernelMemory.h"
+#include "Core/HLE/sceKernelModule.h"
+#include "Core/MIPS/MIPS.h"
+#include "Core/MIPS/MIPSDebugInterface.h"
+#include "Core/MIPS/MIPSAnalyst.h"
+#include "Core/MIPS/MIPSTables.h"
+#include "Core/MemMap.h"
+#include "Core/System.h"
+
+#include "headless/ReverseEngineer.h"
+
+namespace {
+
+// MIPS register names, in encoding order.
+const char *const kRegNames[32] = {
+	"zero", "at", "v0", "v1", "a0", "a1", "a2", "a3",
+	"t0", "t1", "t2", "t3", "t4", "t5", "t6", "t7",
+	"s0", "s1", "s2", "s3", "s4", "s5", "s6", "s7",
+	"t8", "t9", "k0", "k1", "gp", "sp", "fp", "ra",
+};
+
+enum {
+	REG_V0 = 2,
+	REG_A0 = 4,
+	REG_A3 = 7,
+	REG_SP = 29,
+	REG_RA = 31,
+};
+
+// What one function does with the registers it was handed. We report evidence rather than a
+// signature: MIPS callers routinely leave an argument in place for a callee to pick up, so a
+// register this function never touches can still be a parameter it is passing on. Deciding the
+// real arity means looking at the whole call chain, which is a judgement call for a human, not
+// something to guess here.
+struct RegEvidence {
+	bool readBeforeWritten[32] = {};
+	bool written[32] = {};
+	// Call sites where an argument register still held whatever the caller left in it.
+	std::map<int, std::vector<u32>> forwardedAt;
+	// Call sites where this function set the argument register itself.
+	std::map<int, std::vector<u32>> setLocallyAt;
+	bool writesV0 = false;
+	bool hasCalls = false;
+	bool hasIndirectCalls = false;
+};
+
+struct FuncInfo {
+	u32 start = 0;
+	u32 size = 0;
+	std::string name;
+	std::set<u32> callees;
+	std::set<u32> callers;
+	bool indirectCallees = false;
+	RegEvidence regs;
+};
+
+bool IsJal(u32 op) {
+	return (op >> 26) == 3;
+}
+
+bool IsJalr(u32 op) {
+	return (op >> 26) == 0 && (op & 0x3f) == 9;
+}
+
+u32 JumpTarget(u32 addr, u32 op) {
+	return (addr & 0xF0000000) | ((op & 0x03FFFFFF) << 2);
+}
+
+// Applies one instruction's register reads and writes to the evidence being accumulated.
+void ApplyRegEffects(u32 op, RegEvidence *ev) {
+	const MIPSInfo info = MIPSGetInfo(MIPSOpcode(op));
+	const int rs = (op >> 21) & 0x1f;
+	const int rt = (op >> 16) & 0x1f;
+	const int rd = (op >> 11) & 0x1f;
+
+	if (info & IN_RS) {
+		if (!ev->written[rs]) {
+			ev->readBeforeWritten[rs] = true;
+		}
+	}
+	if (info & IN_RT) {
+		if (!ev->written[rt]) {
+			ev->readBeforeWritten[rt] = true;
+		}
+	}
+	if (info & OUT_RT) {
+		ev->written[rt] = true;
+	}
+	if (info & OUT_RD) {
+		ev->written[rd] = true;
+	}
+	if (info & OUT_RA) {
+		ev->written[REG_RA] = true;
+	}
+	if (((info & OUT_RT) && rt == REG_V0) || ((info & OUT_RD) && rd == REG_V0)) {
+		ev->writesV0 = true;
+	}
+}
+
+// Walks a function once, collecting the call graph and the register evidence.
+//
+// Delay slots matter here: the instruction after a jal executes *before* the call, so a
+// "move a0, s0" sitting in the delay slot is setting up that call's argument, not the next
+// one's. Getting this backwards would report an argument as forwarded when it was set locally.
+void AnalyzeFunction(FuncInfo *func) {
+	RegEvidence &ev = func->regs;
+	const u32 end = func->start + func->size;
+
+	for (u32 addr = func->start; addr < end; addr += 4) {
+		if (!Memory::IsValidAddress(addr)) {
+			break;
+		}
+		const u32 op = Memory::Read_Instruction(addr).encoding;
+		const bool jal = IsJal(op);
+		const bool jalr = IsJalr(op);
+
+		if (!jal && !jalr) {
+			ApplyRegEffects(op, &ev);
+			continue;
+		}
+
+		// A call. The delay slot runs first.
+		const u32 delayAddr = addr + 4;
+		if (delayAddr < end && Memory::IsValidAddress(delayAddr)) {
+			ApplyRegEffects(Memory::Read_Instruction(delayAddr).encoding, &ev);
+		}
+
+		ev.hasCalls = true;
+		for (int reg = REG_A0; reg <= REG_A3; reg++) {
+			if (ev.written[reg]) {
+				ev.setLocallyAt[reg].push_back(addr);
+			} else {
+				ev.forwardedAt[reg].push_back(addr);
+			}
+		}
+
+		if (jal) {
+			func->callees.insert(JumpTarget(addr, op));
+		} else {
+			ev.hasIndirectCalls = true;
+			func->indirectCallees = true;
+		}
+		ApplyRegEffects(op, &ev);
+		// v0 is clobbered by the call, and a0-a3 are caller-saved - but for our purposes the
+		// interesting question is only what the caller left in place, so nothing to reset.
+		addr += 4;  // Skip the delay slot; already accounted for.
+	}
+}
+
+// Names an address formed by a lui/addiu pair, if anything is known about it.
+std::string DescribeAddr(u32 addr) {
+	const std::string label = g_symbolMap->GetLabelString(addr);
+	if (!label.empty()) {
+		return " <" + label + ">";
+	}
+	return "";
+}
+
+std::string SanitizeForFilename(std::string_view name) {
+	std::string out;
+	out.reserve(name.size());
+	for (char c : name) {
+		if (isalnum((unsigned char)c) || c == '_' || c == '.' || c == '-') {
+			out.push_back(c);
+		} else {
+			out.push_back('_');
+		}
+	}
+	return out;
+}
+
+// Brings up the minimum needed to load a module: memory map, timing, HLE tables (so imports
+// resolve to named syscalls), the kernel memory allocators and the object pool. Notably this
+// does *not* start threads, the GPU or any of the HLE subsystems - nothing is going to run.
+bool InitMinimalPSP() {
+	Memory::g_MemorySize = Memory::RAM_DOUBLE_SIZE;
+	Memory::g_PSPModel = PSP_MODEL_SLIM;
+
+	if (g_symbolMap) {
+		delete g_symbolMap;
+	}
+	g_symbolMap = new SymbolMap();
+	MIPSAnalyst::Reset();
+
+	if (!Memory::Init(Memory::MemMapSetupFlags::Default)) {
+		fprintf(stderr, "re: memory init failed\n");
+		return false;
+	}
+
+	mipsr4k.Reset();
+	CoreTiming::Init(&mipsr4k);
+	HLEInit();
+	kernelObjects.Clear();
+	__KernelMemoryInit();
+	return true;
+}
+
+void ShutdownMinimalPSP() {
+	__KernelMemoryShutdown();
+	kernelObjects.Clear();
+	HLEShutdown();
+	CoreTiming::Shutdown();
+	Memory::Shutdown();
+	delete g_symbolMap;
+	g_symbolMap = nullptr;
+}
+
+// Accepts either a host path or a PSP-style "flash0:/kd/foo.prx", which is resolved against the
+// configured NAND directory so firmware modules can be named the way they are on the PSP.
+Path ResolveModulePath(const std::string &input) {
+	if (startsWithNoCase(input, "flash0:/") || startsWithNoCase(input, "flash0:")) {
+		std::string rest = input.substr(input.find(':') + 1);
+		while (!rest.empty() && (rest[0] == '/' || rest[0] == '\\')) {
+			rest = rest.substr(1);
+		}
+		return g_Config.nandRootDirectory / "flash0" / rest;
+	}
+	return Path(input);
+}
+
+void WriteRegEvidence(FILE *f, const FuncInfo &func) {
+	const RegEvidence &ev = func.regs;
+	fprintf(f, "; Register evidence (NOT a signature - see below):\n");
+	for (int reg = REG_A0; reg <= REG_A3; reg++) {
+		const char *name = kRegNames[reg];
+		std::string verdict;
+		if (ev.readBeforeWritten[reg]) {
+			verdict = "READ before written  -> used as a parameter here";
+		} else if (!ev.forwardedAt.count(reg) && !ev.written[reg]) {
+			verdict = "never touched";
+		} else if (!ev.readBeforeWritten[reg] && ev.forwardedAt.count(reg)) {
+			verdict = "never read, but live across a call -> FORWARDED from our caller";
+		} else if (ev.written[reg]) {
+			verdict = "written before any read -> set up locally";
+		} else {
+			verdict = "unclear";
+		}
+		fprintf(f, ";   %-4s %s\n", name, verdict.c_str());
+
+		auto fwd = ev.forwardedAt.find(reg);
+		if (fwd != ev.forwardedAt.end() && !fwd->second.empty()) {
+			fprintf(f, ";        forwarded at:");
+			for (size_t i = 0; i < fwd->second.size() && i < 8; i++) {
+				fprintf(f, " %08x", fwd->second[i]);
+			}
+			if (fwd->second.size() > 8) {
+				fprintf(f, " (+%d more)", (int)(fwd->second.size() - 8));
+			}
+			fprintf(f, "\n");
+		}
+	}
+	fprintf(f, ";   %-4s %s\n", "v0", ev.writesV0 ? "written -> returns a value" : "never written -> returns nothing");
+	if (ev.hasIndirectCalls) {
+		fprintf(f, ";   note: has indirect calls (jalr) - callee list is incomplete\n");
+	}
+	fprintf(f, ";\n");
+	fprintf(f, "; A register this function never reads can still be a parameter: MIPS code often\n");
+	fprintf(f, "; leaves an argument untouched for a callee to pick up. Treat 'FORWARDED' as\n");
+	fprintf(f, "; evidence the real arity is larger than what is read here, and settle it by\n");
+	fprintf(f, "; looking at what the callees do with it.\n");
+}
+
+}  // namespace
+
+int RunReverseEngineer(const ReverseEngineerOptions &opts) {
+	const Path modulePath = ResolveModulePath(opts.modulePath);
+	if (!File::Exists(modulePath)) {
+		fprintf(stderr, "re: no such file: %s\n", modulePath.c_str());
+		return 1;
+	}
+
+	const Path outDir(opts.outDir);
+	if (!File::CreateFullPath(outDir)) {
+		fprintf(stderr, "re: couldn't create output directory: %s\n", outDir.c_str());
+		return 1;
+	}
+
+	// Load every module for real, whatever HLE implementations we may have for it - the whole
+	// point is to look at Sony's code, not to have it quietly replaced by ours.
+	g_Config.iDisableHLE = -1;
+	g_Config.iForceEnableHLE = 0;
+	SetForceRealModuleLoads(true);
+	g_Config.bAutoSaveLoadSymbols = false;
+
+	if (!InitMinimalPSP()) {
+		return 1;
+	}
+
+	// Mount the containing directory so the normal file-backed loader path can be used.
+	const std::string dir = modulePath.GetDirectory();
+	const std::string filename = modulePath.GetFilename();
+	auto hostFs = std::make_shared<DirectoryFileSystem>(&pspFileSystem, Path(dir), FileSystemFlags::FLASH);
+	pspFileSystem.Mount("host0:", hostFs);
+
+	std::string error;
+	const SceUID uid = KernelLoadModule("host0:/" + filename, &error);
+	if (uid < 0) {
+		fprintf(stderr, "re: failed to load %s: %s\n", modulePath.c_str(), error.c_str());
+		ShutdownMinimalPSP();
+		return 1;
+	}
+
+	u32 kerr = 0;
+	PSPModule *module = kernelObjects.Get<PSPModule>(uid, kerr);
+	if (!module) {
+		fprintf(stderr, "re: loaded module vanished (uid %d)\n", uid);
+		ShutdownMinimalPSP();
+		return 1;
+	}
+	if (module->isFake) {
+		fprintf(stderr, "re: module was fake-loaded (HLE stub) rather than really loaded - can't analyze\n");
+		ShutdownMinimalPSP();
+		return 1;
+	}
+
+	const std::string moduleName = module->nm.name;
+	const u32 base = module->memoryBlockAddr;
+	const u32 blockSize = module->memoryBlockSize;
+
+	// The loader's function scan names everything z_un_<addr>. We know better for two whole
+	// categories: exported functions have a NID the HLE tables can often name, and every import
+	// stub is a known library function. Naming them here means every call site in the
+	// disassembly below reads as a name instead of a bare address.
+	const int moduleIdx = g_symbolMap->GetModuleIndexByName(moduleName);
+	int namedExports = 0, namedImports = 0;
+	for (const FuncSymbolExport &exp : module->exportedFuncs) {
+		const char *known = GetHLEFuncName(exp.moduleName, exp.nid);
+		const std::string name = known ? known : StringFromFormat("%s_%08x", exp.moduleName, exp.nid);
+		u32 size = g_symbolMap->GetFunctionSize(exp.symAddr);
+		if (size == SymbolMap::INVALID_ADDRESS) {
+			size = 4;
+		}
+		g_symbolMap->AddFunction(name.c_str(), exp.symAddr, size, moduleIdx, true);
+		namedExports++;
+	}
+	for (const FuncSymbolImport &imp : module->importedFuncs) {
+		const char *known = GetHLEFuncName(imp.moduleName, imp.nid);
+		const std::string name = known ? known : StringFromFormat("%s_%08x", imp.moduleName, imp.nid);
+		g_symbolMap->AddFunction(name.c_str(), imp.stubAddr, 8, moduleIdx, true);
+		namedImports++;
+	}
+
+	// Optional pre-existing names, so the disassembly comes out readable instead of a wall of
+	// z_un_08801234. Uses the same .ppsym format the emulator saves, module-relative. Applied
+	// after the automatic naming above so a hand-written name always wins.
+	if (!opts.symsFile.empty()) {
+		if (moduleIdx < 0) {
+			fprintf(stderr, "re: warning: module '%s' not in the symbol map, can't apply %s\n",
+				moduleName.c_str(), opts.symsFile.c_str());
+		} else if (!g_symbolMap->LoadModuleSymbols(moduleIdx, Path(opts.symsFile))) {
+			fprintf(stderr, "re: warning: couldn't load symbols from %s\n", opts.symsFile.c_str());
+		}
+	}
+
+	// A few modules - sysmem.prx and loadcore.prx among them - carry modinfo pointers that are
+	// file offsets rather than addresses, so the loader's own scan is left with nothing to look
+	// at and finds no functions. For reverse engineering we would still like the disassembly, and
+	// we know exactly which range is code, so scan it ourselves.
+	{
+		bool anyInModule = false;
+		for (const SymbolEntry &sym : g_symbolMap->GetAllActiveSymbols(ST_FUNCTION)) {
+			if (sym.address >= base && sym.address < base + blockSize) {
+				anyInModule = true;
+				break;
+			}
+		}
+		if (!anyInModule && blockSize >= 8) {
+			const u32 textStart = module->nm.text_addr ? (u32)module->nm.text_addr : base;
+			u32 textEnd = textStart + (u32)module->nm.text_size;
+			if (textEnd <= textStart || textEnd > base + blockSize) {
+				textEnd = base + blockSize;
+			}
+			if (Memory::IsValid4AlignedRange(textStart, textEnd - textStart)) {
+				printf("re: loader found no functions, scanning %08x-%08x directly\n", textStart, textEnd);
+				MIPSAnalyst::ScanForFunctions(textStart, textEnd - 4, true);
+			}
+		}
+	}
+
+	// Collect the functions the loader's scan found, restricted to this module.
+	std::vector<FuncInfo> funcs;
+	std::map<u32, size_t> funcByAddr;
+	for (const SymbolEntry &sym : g_symbolMap->GetAllActiveSymbols(ST_FUNCTION)) {
+		if (sym.address < base || sym.address >= base + blockSize) {
+			continue;
+		}
+		// A module with an odd segment layout can leave a symbol at an address that isn't
+		// really code; reading an instruction there trips a debug assert deep in MemMap.
+		if (!Memory::IsValid4AlignedAddress(sym.address) || sym.size == 0) {
+			continue;
+		}
+		FuncInfo f;
+		f.start = sym.address;
+		f.size = sym.size;
+		f.name = sym.name;
+		funcByAddr[f.start] = funcs.size();
+		funcs.push_back(f);
+	}
+	std::sort(funcs.begin(), funcs.end(), [](const FuncInfo &a, const FuncInfo &b) {
+		return a.start < b.start;
+	});
+	funcByAddr.clear();
+	for (size_t i = 0; i < funcs.size(); i++) {
+		funcByAddr[funcs[i].start] = i;
+	}
+
+	for (FuncInfo &f : funcs) {
+		AnalyzeFunction(&f);
+	}
+	// Second pass: invert the call graph.
+	for (const FuncInfo &f : funcs) {
+		for (u32 callee : f.callees) {
+			auto it = funcByAddr.find(callee);
+			if (it != funcByAddr.end()) {
+				funcs[it->second].callers.insert(f.start);
+			}
+		}
+	}
+
+	auto nameOf = [&](u32 addr) -> std::string {
+		auto it = funcByAddr.find(addr);
+		if (it != funcByAddr.end()) {
+			return funcs[it->second].name;
+		}
+		const std::string label = g_symbolMap->GetLabelString(addr);
+		return label.empty() ? StringFromFormat("%08x", addr) : label;
+	};
+
+	// ---- index ----
+	const Path indexPath = outDir / (SanitizeForFilename(moduleName) + ".index.md");
+	FILE *f = File::OpenCFile(indexPath, "w");
+	if (!f) {
+		fprintf(stderr, "re: couldn't write %s\n", indexPath.c_str());
+		ShutdownMinimalPSP();
+		return 1;
+	}
+
+	fprintf(f, "# %s\n\n", moduleName.c_str());
+	fprintf(f, "- file: `%s`\n", modulePath.GetFilename().c_str());
+	fprintf(f, "- crc32: `%08x`  (matches `PSP/SYSTEM/SYMBOLS/%s_%08x.ppsym`)\n", module->crc, moduleName.c_str(), module->crc);
+	fprintf(f, "- attribute: `%04x`%s\n", (u32)module->nm.attribute,
+		(module->nm.attribute & PSP_MODULE_KERNEL_MODE) ? " (kernel mode)" : "");
+	fprintf(f, "- version: %d.%d\n", module->nm.version[1], module->nm.version[0]);
+	fprintf(f, "- loaded at: `%08x`, size `%08x`\n", base, blockSize);
+	fprintf(f, "- text: `%08x`..`%08x`  data: `%x`  bss: `%x`  gp: `%08x`\n",
+		(u32)module->nm.text_addr, (u32)module->nm.text_addr + (u32)module->nm.text_size,
+		(u32)module->nm.data_size, (u32)module->nm.bss_size, (u32)module->nm.gp_value);
+	fprintf(f, "- entry: `%08x`  module_start: `%08x`  module_stop: `%08x`\n\n",
+		(u32)module->nm.entry_addr, (u32)module->nm.module_start_func, (u32)module->nm.module_stop_func);
+
+	fprintf(f, "## Segments\n\n| # | address | size |\n|---|---|---|\n");
+	for (u32 i = 0; i < module->nm.nsegment && i < 4; i++) {
+		fprintf(f, "| %d | `%08x` | `%x` |\n", i, (u32)module->nm.segmentaddr[i], (u32)module->nm.segmentsize[i]);
+	}
+
+	fprintf(f, "\n## Exports (%d functions, %d variables)\n\n",
+		(int)module->exportedFuncs.size(), (int)module->exportedVars.size());
+	fprintf(f, "| library | NID | address | name |\n|---|---|---|---|\n");
+	for (const FuncSymbolExport &exp : module->exportedFuncs) {
+		const char *known = GetHLEFuncName(exp.moduleName, exp.nid);
+		fprintf(f, "| `%s` | `%08x` | `%08x` | %s |\n", exp.moduleName, exp.nid, exp.symAddr,
+			known ? known : nameOf(exp.symAddr).c_str());
+	}
+	for (const VarSymbolExport &exp : module->exportedVars) {
+		fprintf(f, "| `%s` | `%08x` | `%08x` | *(variable)* |\n", exp.moduleName, exp.nid, exp.symAddr);
+	}
+
+	fprintf(f, "\n## Imports (%d functions, %d variables)\n\n",
+		(int)module->importedFuncs.size(), (int)module->importedVars.size());
+	fprintf(f, "| library | NID | stub | name |\n|---|---|---|---|\n");
+	for (const FuncSymbolImport &imp : module->importedFuncs) {
+		const char *known = GetHLEFuncName(imp.moduleName, imp.nid);
+		fprintf(f, "| `%s` | `%08x` | `%08x` | %s |\n", imp.moduleName, imp.nid, imp.stubAddr,
+			known ? known : "*(unknown NID)*");
+	}
+	for (const VarSymbolImport &imp : module->importedVars) {
+		fprintf(f, "| `%s` | `%08x` | `%08x` | *(variable)* |\n", imp.moduleName, imp.nid, imp.stubAddr);
+	}
+
+	fprintf(f, "\n## Functions (%d)\n\n", (int)funcs.size());
+	fprintf(f, "| address | +offset | size | callers | callees | v0 | name |\n|---|---|---|---|---|---|---|\n");
+	for (const FuncInfo &fn : funcs) {
+		fprintf(f, "| `%08x` | `+%05x` | %d | %d | %d | %s | %s |\n",
+			fn.start, fn.start - base, fn.size, (int)fn.callers.size(), (int)fn.callees.size(),
+			fn.regs.writesV0 ? "y" : "-", fn.name.c_str());
+	}
+	fclose(f);
+
+	// ---- call graph ----
+	const Path xrefPath = outDir / (SanitizeForFilename(moduleName) + ".xref.json");
+	f = File::OpenCFile(xrefPath, "w");
+	if (f) {
+		fprintf(f, "{\n  \"module\": \"%s\",\n  \"base\": %u,\n  \"functions\": [\n", moduleName.c_str(), base);
+		for (size_t i = 0; i < funcs.size(); i++) {
+			const FuncInfo &fn = funcs[i];
+			fprintf(f, "    {\"addr\": \"%08x\", \"name\": \"%s\", \"size\": %d, \"callers\": [",
+				fn.start, fn.name.c_str(), fn.size);
+			bool first = true;
+			for (u32 c : fn.callers) {
+				fprintf(f, "%s\"%08x\"", first ? "" : ", ", c);
+				first = false;
+			}
+			fprintf(f, "], \"callees\": [");
+			first = true;
+			for (u32 c : fn.callees) {
+				fprintf(f, "%s\"%08x\"", first ? "" : ", ", c);
+				first = false;
+			}
+			fprintf(f, "]}%s\n", i + 1 < funcs.size() ? "," : "");
+		}
+		fprintf(f, "  ]\n}\n");
+		fclose(f);
+	}
+
+	// ---- per-function disassembly ----
+	// Deliberately not DisassemblyManager: its analyze() refuses to do anything unless a game is
+	// fully booted, and nothing is booted here. DisAsm() is the same formatter its opcode entries
+	// use, minus the gate.
+
+	const Path funcDir = outDir / SanitizeForFilename(moduleName);
+	if (!File::CreateFullPath(funcDir)) {
+		fprintf(stderr, "re: couldn't create %s\n", funcDir.c_str());
+		ShutdownMinimalPSP();
+		return 1;
+	}
+
+	int written = 0;
+	for (const FuncInfo &fn : funcs) {
+		if (!opts.funcFilter.empty()) {
+			const bool byName = fn.name == opts.funcFilter;
+			const bool byAddr = StringFromFormat("%08x", fn.start) == opts.funcFilter ||
+				StringFromFormat("0x%08x", fn.start) == opts.funcFilter;
+			if (!byName && !byAddr) {
+				continue;
+			}
+		}
+
+		const Path path = funcDir / StringFromFormat("%08x_%s.asm", fn.start, SanitizeForFilename(fn.name).c_str());
+		FILE *out = File::OpenCFile(path, "w");
+		if (!out) {
+			continue;
+		}
+
+		fprintf(out, "; %s :: %s\n", moduleName.c_str(), fn.name.c_str());
+		fprintf(out, "; %08x - %08x  (module +%05x, %d bytes)\n",
+			fn.start, fn.start + fn.size, fn.start - base, fn.size);
+		fprintf(out, ";\n");
+
+		fprintf(out, "; Callers (%d):", (int)fn.callers.size());
+		if (fn.callers.empty()) {
+			fprintf(out, " none found (exported, or only called indirectly)");
+		}
+		for (u32 c : fn.callers) {
+			fprintf(out, " %s", nameOf(c).c_str());
+		}
+		fprintf(out, "\n; Callees (%d):", (int)fn.callees.size());
+		for (u32 c : fn.callees) {
+			fprintf(out, " %s", nameOf(c).c_str());
+		}
+		if (fn.indirectCallees) {
+			fprintf(out, " + indirect");
+		}
+		fprintf(out, "\n;\n");
+
+		WriteRegEvidence(out, fn);
+		fprintf(out, "\n");
+
+		// Tracks lui-loaded upper halves so an "lui/addiu" or "lui/lw" pair can be reported as
+		// the address it actually forms. Those pairs are how every global and constant table is
+		// reached, so without this the interesting operands all read as bare halves.
+		u32 luiVal[32] = {};
+		bool luiSet[32] = {};
+
+		const u32 end = fn.start + fn.size;
+		for (u32 addr = fn.start; addr < end; addr += 4) {
+			if (!Memory::IsValidAddress(addr)) {
+				break;
+			}
+			const std::string label = g_symbolMap->GetLabelString(addr);
+			if (!label.empty() && addr != fn.start) {
+				fprintf(out, "\n%s:\n", label.c_str());
+			}
+
+			char text[512];
+			DisAsm(addr, text, sizeof(text));
+			// DisAsm separates mnemonic from operands with a tab.
+			char *tab = strchr(text, '\t');
+			std::string mnemonic = text;
+			std::string operands;
+			if (tab) {
+				*tab = '\0';
+				mnemonic = text;
+				operands = tab + 1;
+			}
+			fprintf(out, "%08x  %-10s %-30s", addr, mnemonic.c_str(), operands.c_str());
+
+			const u32 op = Memory::Read_Instruction(addr).encoding;
+			const u32 opcode = op >> 26;
+			const int rs = (op >> 21) & 0x1f;
+			const int rt = (op >> 16) & 0x1f;
+			const s32 imm = (s16)(op & 0xffff);
+
+			if (IsJal(op)) {
+				fprintf(out, " ; -> %s", nameOf(JumpTarget(addr, op)).c_str());
+			} else if (opcode == 0x0f) {  // lui
+				luiVal[rt] = (u32)(op & 0xffff) << 16;
+				luiSet[rt] = true;
+			} else if (opcode == 0x09 && luiSet[rs]) {  // addiu
+				const u32 target = luiVal[rs] + imm;
+				fprintf(out, " ; = %08x%s", target, DescribeAddr(target).c_str());
+				luiVal[rt] = target;
+				luiSet[rt] = true;
+			} else if (opcode >= 0x20 && opcode <= 0x2e && luiSet[rs]) {  // load/store
+				const u32 target = luiVal[rs] + imm;
+				fprintf(out, " ; @ %08x%s", target, DescribeAddr(target).c_str());
+			} else {
+				// Anything else that writes a register invalidates what we thought it held.
+				const MIPSInfo info = MIPSGetInfo(MIPSOpcode(op));
+				if (info & OUT_RT) {
+					luiSet[rt] = false;
+				}
+				if (info & OUT_RD) {
+					luiSet[(op >> 11) & 0x1f] = false;
+				}
+			}
+			fprintf(out, "\n");
+		}
+		fclose(out);
+		written++;
+	}
+
+	printf("re: %s (crc %08x) at %08x, %d bytes\n", moduleName.c_str(), module->crc, base, blockSize);
+	printf("re: %d exports (%d named), %d imports (%d named), %d functions; wrote %d disassembly file(s)\n",
+		(int)module->exportedFuncs.size(), namedExports, (int)module->importedFuncs.size(), namedImports,
+		(int)funcs.size(), written);
+	printf("re: index at %s\n", indexPath.c_str());
+
+	ShutdownMinimalPSP();
+	return 0;
+}

headless/ReverseEngineer.h

@@ -0,0 +1,37 @@
+// Copyright (c) 2026- PPSSPP Project.
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, version 2.0 or later versions.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License 2.0 for more details.
+
+// A copy of the GPL 2.0 should have been included with the program.
+// If not, see http://www.gnu.org/licenses/
+
+// Official git repository and contact information can be found at
+// https://github.com/hrydgard/ppsspp and http://www.ppsspp.org/.
+
+#pragma once
+
+#include <string>
+
+struct ReverseEngineerOptions {
+	// PRX/ELF to load. A host path, or a PSP path like "flash0:/kd/libmp3.prx" (resolved
+	// against the configured NAND directory).
+	std::string modulePath;
+	// Where to write the report. Created if missing.
+	std::string outDir;
+	// If set, only this function is disassembled (by name, or "0x08801234").
+	std::string funcFilter;
+	// Optional .syms file applied before dumping, so names show up in every caller.
+	std::string symsFile;
+	bool verbose = false;
+};
+
+// Loads a module standalone (no game), analyzes it, and writes a report. Returns a process
+// exit code.
+int RunReverseEngineer(const ReverseEngineerOptions &opts);