Files
reverse-engineering-anything/docs/specs/native/ppc64-elfv2/spec.md
T
0e0c5a8fea feat(ghidra): admit ELFv2 PPC64 executables through a Power ISA 3.0 lane (#12517)
* feat(ghidra): admit ELFv2 PPC64 executables through a Power ISA 3.0 lane

An EM_PPC64 ELF has been classified in the powerpc family since #12089, but
the Ghidra lane still refused every ELF64 file. It now admits ELF64 ET_EXEC
files that declare the ELFv2 ABI, little or big endian, and imports them with
PowerPC:LE:64:A2ALT or PowerPC:BE:64:A2ALT by byte order.

Ghidra's 64-bit "default" languages decode the G2-era instruction set and
stop at the first VSX instruction in POWER8 or POWER9 code; the A2ALT
languages are Power ISA 3.0 and decode it. The ELF loader selects A2ALT
today, and the lane passes it explicitly and records it as provider-pinned.

ELFv1 (.opd function descriptors), an undeclared ABI, other e_flags bits,
ET_DYN and ET_REL are refused with their own reasons. The 32-bit lane is
unchanged.

npm run verify:ghidra:ppc64 builds a source-owned ELFv2 fixture in both byte
orders and checks it against GNU readelf and real Ghidra through MCP and the
CLI: the bound language, fixed instruction bytes including a VSX xxlor, the
global-entry thunk to each function's local entry, direct calls, snapshot
identity, and a shared object refused before Ghidra starts.

Refs #12085

* fix(ghidra): supervise PPC64 verifier compiler and CLI processes

Timeouts on bare execFile stop only the direct child, so a linker can
outlive Clang and disappear from the parent-tree cleanup check. Launch
those commands through the shared command owner, pass that runner into
the PPC64 fixture builder, and close the owner before the lineage check.
A failed close stays registered for retry and the diagnostic workspace
is retained.

* docs(ghidra): record the PPC64 ELFv2 Power ISA 3.0 lane

Add the feature specification, plan, and tasks for the lane, and index
them with the other feature records.

* fix(ghidra): finish shared PowerPC verifier command ownership

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
2026-11-19 18:27:31 -05:00

4.3 KiB

PPC64 ELFv2 Power ISA 3.0 lane

Problem and outcome

EM_PPC64 is already classified in the provider-neutral powerpc family, but the Ghidra lane refused every ELF64 file. This feature admits ELF64 ET_EXEC files that declare the ELFv2 ABI, in either byte order, through the existing Ghidra provider. rea analyze, rea function, and the MCP session tools then work on those executables. The lane does not execute PowerPC code.

PowerPC ELF analysis through Ghidra describes the current behavior. This directory is the feature specification, implementation plan, and task list. The guide does not replace these files.

The 32-bit big-endian lane remains the first milestone of #1741. This lane answers #12085.

Requirements

  1. Admit an ELF64 ET_EXEC whose e_flags ABI field (the low two bits) is 2 (ELFv2), for little-endian and big-endian images. The family stays powerpc. An ELF32 header that claims EM_PPC64 stays unrecognized.
  2. Import with PowerPC:LE:64:A2ALT or PowerPC:BE:64:A2ALT by byte order and compiler spec default, committed as language_selection: "provider-pinned". A2ALT is the Power ISA 3.0 language. The G2-era PowerPC:LE:64:default and PowerPC:BE:64:default languages are not the lane default: they do not decode VSX, including the lane's xxlor probe. Passing A2ALT explicitly keeps a later loader preference from changing how these files decode. REA_GHIDRA_LANGUAGE_ID replaces the pin and is recorded as language_selection: "configured". Readback checks the observed language_id and compiler_spec_id.
  3. Commit powerpc_support_lane: "elf64-elfv2-exec-isa3" and the header facts (elf_class, byte_order, type, flags) on the analysis profile, so the interpretation is part of snapshot identity. A 32-bit profile stays elf32-be-exec-generic and is otherwise unchanged.
  4. Refuse every other PPC64 shape before provider startup. Support status is unsupported with code architecture_unsupported, and profile resolution fails with AnalysisUnsupportedTargetError. The refused shapes are an ELFv1 ABI (1), an undeclared ABI (0), any other value in the ABI field, e_flags bits outside that field, ET_DYN (shared objects and position-independent executables), and ET_REL.
  5. Report an ELFv2 global entry as Ghidra models it: classification.thunk is true and classification.thunk_target is the local entry. Direct calls resolve to the callee's local entry. Pseudocode presence is a liveness check, not semantic equivalence.
  6. Leave the 32-bit lane, Hopper, and IDA unchanged. Hopper and IDA still report the powerpc family unsupported. Windows Ghidra P0 stays PE x86/x86-64 only.
  7. Real-provider acceptance is npm run verify:ghidra:ppc64 on a caller-supplied Linux or macOS Ghidra host. Clang, GNU readelf and the one-shot CLI run through the shared command owner, including the runner passed into the shared fixture builder. That owner is closed before the process-lineage check. A failed close stays registered for retry and the diagnostic workspace is retained. The fixtures are never executed.

Acceptance

  • Profile tests cover both byte orders' pinned language, compiler spec, language_selection, powerpc_support_lane, and header facts; a configured language replacing the pin; and refusal of the shapes above with status unsupported and AnalysisUnsupportedTargetError. Hopper and IDA stay unsupported for the family, including an admitted PPC64 target.
  • The independent readelf boundary, probe words in file byte order, a VSX word whose status is not-in-listing, the doubleword in both byte orders, and the thunk fields are covered without a Ghidra-derived oracle.
  • The real-provider verifier checks the observed language, the lane id, the thunk pair, and an ET_DYN refusal before provider startup, then confirms an empty process lineage. Compiler, reader and CLI process groups are owned by the shared command runner.

Non-goals

ELFv1 (including .opd function descriptors), ET_DYN and PIE load verification, ET_REL, 32-bit little-endian PowerPC, VLE, XCOFF, executing the image, and any new CLI command, MCP tool, or schema.