Files
reverse-engineering-anything/docs/ghidra-ppc.md
T
morluto d87be930c4 refactor(providers)!: key Ghidra and Hopper analysis profiles on the producer identity instead of hand-bumped markers (#11320)
* refactor(ghidra)!: key analysis profiles on the producer identity instead of hand-bumped markers

Ghidra snapshot validity depended on 53 hand-maintained "-vN" semantic
markers in the analysis profile; a behaviour fix that forgot to bump its
marker left old snapshots admissible (#3664). #10562 added a digest of the
bridge sources, but TypeScript projection changes still needed a bump and
the REA release was not committed.

- src/filesystem/ProducerIdentity.ts owns the producer identity: the REA
  release plus a framed SHA-256 of a producer's packaged scripts, read once
  per process.
- Ghidra profiles commit `producer` in place of `bridge_sources_sha256` and
  the constant revision markers (shared semantics block, load-image, entry
  seed, PDB, jump-table, DOL import, MIPS ISA-mode markers) are removed.
- Runtime-selected values keep their meaning without a revision suffix
  (language_selection, annotation_policy, relocation/no-return/launch
  policy, MIPS/PowerPC/PSP lanes, MIPS ABI basis). Bridge wire policy ids
  shared with the Java scripts (ilp32-prototype-v1,
  o32-soft-float-prototype-v1) are unchanged.

BREAKING CHANGE: Ghidra Evidence `analysis_profile.parameters` replace the
semantic marker keys and `bridge_sources_sha256` with `producer`
({rea_version, sources_sha256}), and selection values lose their "-vN"
suffix (for example `language_selection: "provider-pinned"`). Ghidra
Evidence IDs and profile digests change, and analysis snapshots saved by
earlier builds are refused at open. Migration: open the target without the
old snapshot and save a fresh one; consumers reading the removed marker keys
should read `producer` instead.

* fix(hopper)!: commit the REA release and bridge script in Hopper analysis profiles (#11324)

Hopper analysis profiles committed the launcher digest and one hand-bumped
marker (function_dossier_coverage "...-v1"), but neither the REA release
nor bridge/hopper_bridge.py. A snapshot saved before a bridge or REA change
replayed results the current bridge would not produce.

HopperBridgeSources owns the packaged bridge script URL (used to launch it)
and hopperProducerIdentity() on the shared ProducerIdentity owner; the
profile commits `producer` in place of the marker.

BREAKING CHANGE: Hopper Evidence `analysis_profile.parameters` replace
`function_dossier_coverage` with `producer` ({rea_version, sources_sha256}).
Hopper profile digests and Evidence IDs change, and analysis snapshots saved
by earlier builds are refused at open. Migration: open the target without
the old snapshot and save a fresh one.

* fix(ghidra): build the legacy reference snapshot from another producer and use the shared temp directory

* refactor(providers): key Kuna exports and the Native AOT profile on the producer identity (#11353)

* fix(ghidra): keep the bridge source table import-free for the Node-loaded verifier

scripts/verify-ghidra-bridge-sources.mjs loads GhidraBridgeSources.ts with
Node type stripping, which does not resolve .js specifiers to .ts sources.
The producer identity import made every verifier run fail with
ERR_MODULE_NOT_FOUND; the identity now lives in GhidraProducerIdentity.ts.

* fix(artifacts): import the moved file source and abort check from their resources owner after merging main
2026-11-16 05:37:57 +08:00

92 lines
4.4 KiB
Markdown

# PowerPC ELF analysis through Ghidra
This lane extends native ELF analysis to 32-bit big-endian PowerPC; it does
not execute PowerPC code. It is the first milestone of
[#1741](https://github.com/morluto/rea/issues/1741). GameCube/Wii DOL
executables are covered by [GameCube DOL analysis](ghidra-dol.md). PPC64 and other
PowerPC variants remain separate follow-ups.
## Admission boundary
ELF `EM_PPC` (20) is retained as the provider-neutral `powerpc` family. The
target also retains class, byte order, `e_type` and raw `e_flags`. Recognition
does not mean every provider or PowerPC variant is supported. `EM_PPC64` (21)
is not recognized as this family.
The Ghidra lane admits ELF32 `ET_EXEC`, big endian. ELF64, little-endian,
relocatable and shared objects are refused with a specific unsupported
constraint. `EF_PPC_EMB` declares an embedded variant and is refused; the
remaining `e_flags` bits only declare relocation conventions and do not change
instruction decoding.
## Bound language
Ghidra's ELF loader selects `PowerPC:BE:32:e500:default` for a plain `EM_PPC`
header with `e_flags` 0. e500 is the embedded Book-E variant whose SPE unit
replaces the classic floating-point unit, so it misinterprets ordinary
750-family code. Nothing in the header distinguishes the two.
The lane therefore imports with `PowerPC:BE:32:default` and compiler spec
`default`, commits that choice in the analysis profile as
`language_selection: "provider-pinned"`, and checks the language Ghidra
reports after import. A different language set through
`REA_GHIDRA_LANGUAGE_ID` (and optionally `REA_GHIDRA_COMPILER_SPEC_ID`)
replaces the lane default and is admitted against the installed language
catalog as usual; for example `PowerPC:BE:32:e500` for genuine e500 code.
PowerPC header facts are committed in the analysis profile so interpretation
changes invalidate profile-bound snapshots. The support-lane identity is
versioned independently of file identity. Evidence, lifecycle outputs and saved
snapshots preserve the `powerpc` family. Hopper and IDA adapters do not
implicitly gain PowerPC support. Windows Ghidra P0 remains PE x86/x86-64 only.
## Use
With a caller-installed Ghidra and compatible JDK on a supported Linux/macOS host:
```bash
rea analyze /absolute/path/to/ppc.elf --provider ghidra --json
rea function /absolute/path/to/ppc.elf function_name --provider ghidra --json
```
MCP uses the existing tools, including `open_binary` with an absolute path and
`provider_id: "ghidra"`. No PowerPC-specific tool catalog or emulator is
introduced.
## Verification
The source-owned freestanding fixture is `tests/conformance/c/ppc.c`. The
optional cross-target lane requires a caller-supplied Clang with the PowerPC
target, LLD, GNU `readelf`, Ghidra and its compatible JDK; ordinary host-native
checks do not acquire these tools. `REA_PPC_CLANG` selects Clang and
`REA_PPC_READELF` selects GNU readelf (for example
`/opt/homebrew/opt/binutils/bin/readelf` on macOS). These are test-time
prerequisites, not REA runtime providers.
```bash
GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra npm run verify:ghidra:ppc
```
The lane compiles the fixture for a 750-family core (`-mcpu=750`) and never
executes it. GNU readelf independently supplies header facts and symbol
addresses, compared with the production REA target resolver before provider
startup. Its version, bounded command output and selected tool path are
retained in the verification report. The parser deliberately recognizes only
this fixture's GNU output, rejecting missing, ambiguous or unexpected fields
rather than substituting defaults.
Existing public MCP operations check Ghidra's **observed** language and
compiler specification and loaded-file hashes; an e500 import fails the lane.
The source-owned `ppc-probe.S` supplies fixed `addi` and conditional-branch
encodings: verification checks bytes, length, immediate and direct destination,
independent of decompiler variable names. Global and string bytes are checked at
independently reported symbol addresses.
CLI/MCP discovery and decompilation, direct calls, target/profile/Evidence
identity, snapshot round-trip and final process cleanup remain covered.
Pseudocode presence is a liveness check, not proof of semantic equivalence.
Instruction decoding and reader agreement do not establish runtime or complete
floating-point semantics. Parser/profile tests are narrower checks, not
substitutes for this real-provider run. Report the actual lanes run and leave
unexecuted verification pending.