Ghidra setup

Toolchain

• Ghidra 12.x in blacktop/ghidra:latest. Bundles OpenJDK 21 and stock Ghidra at /ghidra.
• Jython 2.7 (bundled with Ghidra) for analysis scripts. Scripts must be ASCII-only - Jython 2 chokes on Unicode in source unless an encoding declaration is added.
• PCSX-Redux for runtime tracing. See overlay capture.

Bringing the service up

Ghidra runs headlessly inside the blacktop/ghidra:latest Docker image, wrapped by docker/ghidra.Dockerfile to map the container user to the host's UID/GID - so files written into the bind-mounted /projects and /scripts directories come back owned by the host user.

# Build (auto-uses USER_ID / GROUP_ID from .env or defaults to 1000:1000)
docker compose build ghidra

# Start the long-running container
docker compose up -d ghidra

The service uses these mounts (from docker-compose.yml):

If you've never built the wrapper before, first run also handles UID/GID matching - see the comment at the top of docker-compose.yml for .env overrides.

Importing SCUS_942.54

PSX executables are PSX-EXE format: skip the 0x800-byte header, base address 0x80010000.

docker compose exec ghidra /ghidra/support/analyzeHeadless \
    /projects legaia \
    -import /data/SCUS_942.54 \
    -loader BinaryLoader \
    -loader-baseAddr 0x80010000 \
    -processor MIPS:LE:32:default

After import, run analysis:

docker compose exec ghidra /ghidra/support/analyzeHeadless \
    /projects legaia -process SCUS_942.54

This takes a few minutes and populates the database with functions, references, and decompilation results.

The LUI+ADDIU gotcha

MIPS has no instruction that loads a full 32-bit constant, so compilers build every address from two 16-bit immediates - and Ghidra's cross-reference database does not stitch the pair back together.

The idiom in question:

lui   r1, 0x801C       ; r1 = 0x801C0000
addiu r1, r1, 0x70F0   ; r1 = 0x801C70F0

Workaround: ghidra/scripts/find_lui_writers.py walks instructions, tracks per-register LUI immediates, and flags addiu / load / store offsets that combine with a tracked LUI to land in a target range.

docker compose exec ghidra /ghidra/support/analyzeHeadless \
    /projects legaia -process SCUS_942.54 -noanalysis \
    -postScript /scripts/find_lui_writers.py

Modify LO / HI constants in the script to scan a different range.

Computed addresses are still missed - lw r4, 0x18(r3) where r3 = 0x80080000 + index*4 can't be statically resolved when index is only known at runtime. Functions reading from arrays via runtime-computed indexing won't appear in xref lists; for these, dynamic analysis with watchpoints is the only static-tool-free path.

Investigation patterns

"Find what writes / reads a global"

Use find_lui_writers.py with LO / HI narrowed to the target address - it catches the LUI+ADDIU/load/store combos that Ghidra's reference manager misses.

"Find callers of a function"

Use find_callers_of.py (edit TARGETS_HEX to the entry point) or dispatcher_callers.py for the asset-dispatcher / LZS chain specifically.

"Is this function actually called?"

The reference manager is unreliable for indirect calls. Use:

• find_callers_of.py for direct jal references.
• find_addr_data.py to find the address as data (function-pointer tables, callbacks).

If both return zero hits, the function has no static caller in the program currently loaded into Ghidra - that's NOT the same as "dead code in retail". Most game logic lives in RAM-loaded overlays at 0x801C0000+ that aren't part of SCUS_942.54. The negative result bounds where the caller can possibly live, but doesn't prove the function unreachable.

"Where does this constant address get used?"

If the address is referenced via lui+addiu, the reference manager will miss it. Use find_lui_writers.py with LO/HI narrowed to your target range.

"Ghidra says nothing writes / reads this global, but I know something does"

Common when the address is materialized by lui+addiu and then passed to a helper (so the actual sw/lw is in the helper, against $a0/$a1), OR when it's stored as a function-argument base that an addu reroutes (so the constant tracker bails and the final sw doesn't appear in the xref database).

Use find_addr_materializers.py to walk every instruction in a program, track per-register lui + addiu pairs, and report every site where the combined value lands on one of your target addresses - plus the next 6 instructions for use-classification (store base = writer, load base = reader, jal/jalr follows = address passed as argument).

docker compose exec ghidra /ghidra/support/analyzeHeadless \
    /projects legaia -process SCUS_942.54 -noanalysis \
    -postScript /scripts/find_addr_materializers.py \
    0x8007C018 0x8007BB38 0x8007B7DC

Arguments may be decimal or hex (0x... prefix). Multiple addresses are scanned in a single pass. Alternative: set GHIDRA_FIND_ADDRS='0x8007c018,0x8007bb38' and run without args.

The pattern this catches (the actual installer for DAT_8007C018 at FUN_80026B4C - missed by the reference manager):

lui   v0, 0x8008
lui   v1, 0x8008
lw    v1, -0x488c(v1)     ; v1 = *DAT_8007B774 (index counter)
addiu v0, v0, -0x3fe8     ; v0 = 0x8007C018   <-- the materializer site
sll   v1, v1, 0x2         ; v1 = idx * 4
addu  v1, v1, v0          ; v1 = idx*4 + 0x8007C018
sw    a0, 0(v1)           ; store to table    <-- the missed writer

The reference manager tracks lui+addiu pairs but bails when addu mixes the propagated constant with a value loaded from memory. So sw a0, 0(v1) is invisible to it - but the addiu v0, v0, -0x3fe8 site IS visible to a manual scanner that knows the combination forms the target address. Once you see the materializer, the surrounding 6 instructions usually make the role obvious.

"What format does this PROT entry use?"

Empirical workflow:

1. xxd extracted/PROT/<entry>.BIN | head -5 - eyeball the header.
2. Try each known parser:
   • asset stream <file> - DATA_FIELD streaming.
   • asset describe <file> - descriptor format (when applicable).
   • lzs-decode raw --size N <file> - top-level LZS.
   • asset categorize <DIR> - runs every detector and emits a per-class breakdown.
3. If nothing matches, dig into the function that loads it (find by reversing the call site).

Adding a new function dump

1. Edit ghidra/scripts/dump_funcs.py's TARGETS list to add the entry-point address.
2. Run the dump:

   docker compose exec ghidra /ghidra/support/analyzeHeadless \
       /projects legaia -process SCUS_942.54 -noanalysis \
       -postScript /scripts/dump_funcs.py

3. Open ghidra/scripts/funcs/<addr>.txt and analyze.
4. Update reference/functions.md if it's a notable entry point.

Script catalogue

The Ghidra-side scripts (Jython, run inside the container) live in ghidra/scripts/. Edit the TARGETS / LO / HI constants at the top of any script to point at the addresses you want to trace.

Symbol re-application (apply_known_symbols.py)

Re-applies this project's pinned function names to a fresh import of SCUS_942.54. A raw-blob import names every function FUN_<addr>; the script reads the curated (address, name, role-comment) table in known_symbols.py and names each function + sets a one-line PLATE comment, so the asset/loader/CD/dispatch cluster is readable immediately. The clean-room counterpart to a PsyQ FidDB pass (replays our own RE labels, no external SDK). SCUS-resident (0x80010000..0x8007C000) only - RAM overlays alias by address, so naming them blind would mislabel.

Cross-cutting helpers under scripts/ (host-side, not Ghidra):

Known dev paths in the binary

SCUS_942.54 contains leftover Windows paths from the dev environment. Useful for guessing format families:

h:\PROT\FIELD\
DATA\FIELD\
data\field\player.lzs
h:\prot\all\data\field\player.lzs
h:\prot\field\card\tim.dat
h:\prot\battle\etim.dat
\tim.dat
\move.mdt

The h:\ prefix indicates a Windows dev box. The runtime doesn't actually open these paths in retail (no real h:\ drive on a PSX); the strings are leftover format artefacts that point at where each subsystem's data lives in PROT.

See also