fold/docs/internal/ghidra-pcode-integration-research.md

Ghidra Decompiler → SSA P-Code Integration Research (Phase 0)

Generated 2026-05-31. Phase 0 of the "vendor Ghidra decompiler" plan. Docs-first: understand the engine's API, source layout, and build before writing any glue. Sources are the Ghidra repo (NationalSecurityAgency/ghidra) and angr/pypcode (a lift-only vendor we mirror for the build approach).

Decision recap

• Vendor Ghidra's full decompiler C++ engine (Apache-2.0) at a pinned commit — we control the version, so no ABI skew (the failure mode of the r2ghidra plugin). Consume its SSA high P-Code (Funcdata). Ghidra does data-flow/SSA/variable recovery; fold does Z3 path-reasoning + findings via the existing SafetyObserver::*Ir hooks.
• Pin: tag Ghidra_12.1_build (Ghidra 12.1, released 2026-05-13). Record the exact 40-char SHA in third_party/ghidra-decompiler/VENDOR.md at clone time.
• License: Apache-2.0 — vendorable; carry upstream LICENSE + a NOTICE listing the vendored tree, commit SHA, and modifications (build glue only).

1. P-Code semantics (what we consume)

P-Code is a register-transfer IL; every architecture lowers to the same op set, so the encoder is written once. The opcode enum is OpCode in opcodes.hh (CPUI_*). Two levels:

• Raw P-Code — straight from SLEIGH lifting; per-instruction, no data-flow. (This is all pypcode exposes.)
• High P-Code (SSA) — after the decompiler's analysis actions run on a Funcdata: SSA form (each Varnode written once), dead code removed, variables/types recovered, def-use explicit. This is what we want — it adds CPUI_MULTIEQUAL (SSA phi), CPUI_INDIRECT, CPUI_PTRADD/CPUI_PTRSUB, CPUI_CAST over the raw set.

Varnode = (address space, offset, size). Spaces we care about: const (immediates → Z3 bv_val), register, unique (temporaries), ram (memory), plus the stack space. A Varnode in const space with offset 0 is the literal zero our current const-hazard pass hunts for — but here it falls out of SSA naturally.

Core ops fold maps to SafetyObserver hooks (the "~25-op core"):

P-Code op	fold hook	Finding
CPUI_INT_SDIV / INT_UDIV / INT_SREM / INT_REM	onDivision / onBinaryArith(Div)	div-by-zero (CWE-369) when divisor SAT==0 under path
CPUI_LOAD / CPUI_STORE	onPointerDerefIr	null-deref (CWE-476) when addr Varnode SAT==0
CPUI_INT_ADD / INT_SUB / INT_MULT	onBinaryArith	int-overflow (CWE-190); reuse source guard heuristics to avoid every-op FP
CPUI_CALL / CPUI_CALLIND	onCallExprIr / onLibraryCall	free/malloc/strcpy models → UAF/buffer via existing observers
CPUI_CBRANCH	(path predicate)	real path-sensitivity → covers div_by_zero_variable / null_deref_conditional
CPUI_COPY / INT_ZEXT / INT_SEXT / SUBPIECE / PIECE	value propagation in encoder	—
CPUI_MULTIEQUAL (phi)	Z3 ite/merge at block joins	SSA join
CPUI_INT_EQUAL / INT_SLESS / INT_LESS …	branch conditions	path constraints

Reference: Ghidra/Features/Decompiler/src/decompile/cpp/opcodes.hh and the rendered P-Code reference Ghidra/Features/Decompiler/src/main/doc/pcoderef.xml.

2. Decompiler C++ embedding API (the glue surface)

Confine all of this to src/binary/ghidra_lifter.cpp (Ghidra types never leak into fold::ir, per the M30 *_clang.cpp convention).

• LoadImage (loadimage.hh) — abstract byte source. Subclass it to serve a function's bytes from r2 (r2 gives us arch/bits/endian, the function vaddr+size, and raw bytes via p8/prj). Implement loadFill(uint1*, int4, const Address&) + getArchType/adjustVma.
• SleighArchitecture / Architecture (sleigh_arch.hh, architecture.hh) — owns the translator, spec databases, and the action pipeline. Built from a spec id; specs are loaded via DocumentStorage (xml.hh) reading the .ldefs/.pspec/.cspec and the compiled .sla. Call arch->init(store) to bring up sleigh + types + the default action set.
• Decompile a function: obtain a Funcdata* for the entry address from the architecture's scope, then run the analysis pipeline: arch->allacts.getCurrent()->reset(*fd); arch->allacts.getCurrent()->perform(*fd); After perform, fd holds high (SSA) P-Code. Iterate ops via fd->beginOpAll() / fd->endOpAll() (each PcodeOp has getOpcode(), getOut(), getIn(i) Varnodes) and basic blocks via fd->getBasicBlocks(). The canonical example is the interactive console consolemain.cc (the decomp_opt binary) and the doxygen "Building a Project" page.
• Thread-safety: the decompiler uses process/global state (it was designed to run as a one-function-at-a-time child process, ghidra_process). Treat an Architecture as not thread-safe → one instance per fold worker thread, or serialize lifting.

3. Source layout + what to vendor

From Ghidra/Features/Decompiler/src/decompile/cpp/Makefile (authoritative file lists):

• CORE (lifting/serialization base): xml marshal space float address pcoderaw translate opcodes globalcontext
• SLEIGH (the lifter): sleigh pcodeparse pcodecompile sleighbase slghsymbol slghpatexpress slghpattern semantics context slaformat compression filemanage
• DECCORE (the full decompiler / SSA engine — this is the delta over pypcode's lift-only vendor): capability architecture options graph cover block cast typeop database cpool comment stringmanage modelrules fspec action loadimage grammar varnode op type variable varmap jumptable emulate emulateutil flow userop expression multiprecision funcdata funcdata_block funcdata_op funcdata_varnode unionresolve pcodeinject heritage prefersplit rangeutil ruleaction subflow blockaction merge double transform constseq bitfield coreaction condexe override dynamic crc32 prettyprint printlanguage printc printjava memstate opbehavior paramid signature
  • SSA-relevant: heritage (SSA construction), funcdata* (the SSA container), action/ruleaction/coreaction (the simplification rules), merge, flow, blockaction, jumptable.
• Targets: vendor builds libdecomp.a (= CORE + DECCORE + SLEIGH) and links it into fold. (libsla.a = CORE + SLEIGH only is the lift-only library; not enough for SSA.) sleigh (the spec compiler) is also built to produce .sla.
• bison/flex generated files: grammar.cc←grammar.y, xml.cc←xml.y, pcodeparse.cc←pcodeparse.y, slghparse.cc/.hh←slghparse.y, slghscan.cc←slghscan.l, ruleparse.cc/.hh←ruleparse.y. → Pre-generate these at vendor time and check the .cc/.hh in, so fold's build needs no bison/flex (matches the "trade runtime-debugging for up-front work" goal).
• Processor specs: Ghidra/Processors/<arch>/data/languages/*.{slaspec,ldefs,pspec,cspec,sinc}. Compile .slaspec→.sla once with the vendored sleigh binary and check the .sla + .ldefs/.pspec/.cspec in under third_party/ghidra-decompiler/specs/<arch>/. Vendor only the arches we target (below) to keep the tree small.

4. Target architectures (match corpus + bug-bounty reality)

x86 (32) + x86-64, AARCH64 (corpus is arm64 Mach-O), ARM (LE/BE), MIPS (LE/BE). These cover the CTF corpus and the common closed-source targets. More arches are just more checked-in .sla files later — no code change.

5. Build approach (meson)

• third_party/ghidra-decompiler/ holds the pinned cpp/ sources (with pre-generated parser/lexer .cc/.hh) + specs/<arch>/*.sla + LICENSE + NOTICE + VENDOR.md (commit SHA + the exact upstream paths + the pre-generation/compile commands used).
• meson: a static-lib target libghidra_decompiler.a over the CORE+DECCORE+SLEIGH .cc set (a files() list mirroring the Makefile vars); C++17, -DLOCAL_ZLIB/bundled zlib as pypcode does, define -DFOLD_HAVE_GHIDRA=1. Gate behind a -Dghidra=auto|enabled|disabled option mirroring the existing radare2 option (meson.build:35), so builds without it fall back to the shipped r2-disasm passes.
• Smoke: tools/pcode_dump.cpp links the lib, lifts one function from a corpus dylib, prints SSA P-Code ops — validates vendor + spec loading before any fold integration.

6. Reference: pypcode (mirror its build mechanics, not its scope)

angr/pypcode CMakeLists.txt compiles SLEIGH_COMMON (= our CORE+SLEIGH, lift-only: address compression context float globalcontext marshal opcodes pcodecompile pcodeparse pcoderaw semantics slaformat sleigh sleighbase slghpatexpress slghpattern slghsymbol space translate xml), builds the sleigh compiler from + filemanage slgh_compile slghparse slghscan, and runs sleigh -a <processors-dir> at build time to compile .sla. We extend the file set with DECCORE (for SSA) and pre-compile .sla at vendor time instead of at fold build time. pypcode is Apache-2.0/BSD and a good build reference.

7. Open items resolved in later phases

• Exact pinned SHA for Ghidra_12.1_build → recorded in VENDOR.md at clone (Phase 1).
• Whether to also expose decompiled C (printc) for a future decompile→Clang→source-detector path → out of scope now; printc is in DECCORE so it's available for free later.
• Per-function decompile cost vs the binary_backend test budget → measured in Phase 1 with pcode_dump; cap/deadline designed in Phase 4.