match_functions

Tool tools/triage/match_functions.py (program, Triage). Match the functions of two builds of a game, and carry your labels from one to the other: a patch, another release, a demo, a version for another platform with the same compiler.

Run it with ./gameframe run match_functions ARGS or python3 tools/triage/match_functions.py. Source on GitHub.

Its own help

This is the help text in the tool itself, as ./gameframe tool match_functions prints it.

Match the functions of two builds of a game, and carry your labels from one to the other:
a patch, another release, a demo, a version for another platform with the same compiler.

Usage: match_functions.py EXPORT_A EXPORT_B [--labels A_NAMES.tsv --out B_NAMES.tsv]
                          [--min 0.8] [--all] [--json]

  EXPORT_A, EXPORT_B   two Ghidra exports of one binary each (analysis/export/<binary>/, made
                       by scripts/ghidra-export.sh), with decomp.c and functions.tsv
  --labels FILE        your labels for build A (labels/names.tsv: address, label, evidence)
  --out FILE           write those labels for build B, at the matched addresses, with the
                       match as evidence. Review the file before you apply it (ghidra-run labels)
  --min R              the lowest similarity accepted for a fuzzy match (default 0.8)
  --all                also print the functions left unmatched

Months of naming functions belong to one build. When a patch or another release arrives, the
addresses move, but most functions stay the same. This tool finds them again in four passes:

1. exact      the pseudocode is the same once addresses and generated names are removed;
2. similar    the closest function by shared pieces of pseudocode, when it is clearly the closest;
3. calls      the callees of two matched functions, paired by their position in the call order;
4. repeat     passes 2 and 3 again, until nothing new matches.

Every fuzzy match is a lead. Check the ones your port depends on. Ghidra's own Version
Tracking and BSim do this inside Ghidra with more detail (docs/working/ghidra.md); this tool
works on the text exports, with no database and no Ghidra session. Standard library only.

Named by

Skills: re-ghidra.