[READ-ONLY] Mirror of https://github.com/aaronateataco/thornybush. Static recompilation pipeline porting Skylanders: Spyro's Adventure (Wii thornybush.vercel.app
README.md

Bramble #

Bramble logo: a thorny bramble-ring creature mascot

Static recompilation pipeline that takes a legally-dumped Wii U copy of Skylanders: Spyro's Adventure, translates it into native ARM64 code, and packages the result as a homebrew .nro for Switch — no PowerPC emulation at runtime. Full project plan and phase breakdown: see the linked Notion project page (ask the project owner for the link).

Status #

Milestone 1 (complete): a minimal proof-of-concept PowerPC→C recompiler, validated against a small arithmetic-only test program per the plan's "recommended first step" — see recomp/.

Milestone 2, take 1 (awaiting hardware test): a from-scratch, libnx-free .nro meant only to answer "does the packaging pipeline produce something hbloader will actually boot?" — see switch/README.md.

Milestone 2, take 2 (complete, confirmed on real hardware): a genuine libnx app (switch/native/) that calls the recompiler's actual output and displays the result on screen. Confirmed MATCH, 260 on a real modded Switch — recompiled PowerPC code, running as actual Switch homebrew, producing the correct result. This is the real end-to-end proof of the plan's "Recommended First Step," on real hardware, not simulation. See switch/native/README.md. Needs devkitA64/libnx to build — the base toolchain is now reachable from this project's dev sandbox and make succeeds there too (devkitpro.org itself is still blocked, but the devkitA64+libnx install already present in the sandbox isn't affected). The devkitPro package mirror used to pull additional libraries (portlibs like SDL2, needed by the separate Viridite project) is still unreachable, so that specific limitation isn't fully gone.

Test results/logs go in switch/test-results/.

Milestone 1: PowerPC→C recompiler PoC #

recomp/ is a small C++ CLI tool: given an unstripped, big-endian ELF32 PowerPC relocatable object, it disassembles each function (via Capstone) and emits equivalent portable C against a PpcContext register-state struct (recomp/include/ppc_runtime.h).

Scope is deliberately reduced versus the full project plan:

  • Function boundaries come from the ELF symbol table when present. For stripped binaries (no usable symtab, or pass --stripped), boundaries are instead recovered heuristically: every direct bl target found by a single linear disassembly pass over .text becomes a candidate function start (valid because PPC instructions are a fixed 4 bytes wide, so linear decoding never desyncs), seeded with the ELF entry point. This only finds functions reached via a direct, resolved bl — indirect calls (function pointers/vtables) still need the manual review the project plan already flags for those. See recomp/src/func_recovery.cpp.
  • Relocation handling covers R_PPC_REL24 (bl-style direct calls in a single relocatable object, resolved to a direct C function call, not true branch-and-link; already-linked binaries resolve bl targets directly by address instead) and R_PPC_ADDR16_HA/R_PPC_ADDR16_LO (a lis + load/store/addi pair addressing a symbol). Global/static variables (.data/.bss, and — as of a correctness fix, see below — .rodata* too) get a real synthetic address in PpcContext::mem, consistently assigned per-section (preserving relative offsets between symbols in the same section, so indexed access into an array works correctly) by assign_global_addrs — the generated code also emits a ppc_init_globals() function copying each section's real initial byte content in, which callers must invoke once before calling any recompiled function. Verified that global state genuinely persists and accumulates correctly across multiple calls, not just that a single call happens to read the right initial value. Function addresses (the same lis+addi idiom, but targeting a function symbol — how a compiler builds a function pointer/vtable entry/callback table) resolve to the function's real address instead, in the same address space as bl-target resolution — see below. Other relocation types (absolute data addresses, cross-module calls) aren't handled yet.
  • Correctness fix: read-only data addressing. An earlier version special-cased .rodata* accesses (float/double literal pools, mainly) by folding the whole lis+load pair to a compile-time literal value at codegen time, instead of giving it a real address like mutable globals. That's only correct for the single narrow case of a direct scalar load — it silently miscompiled anything that takes a rodata array's address for later runtime-indexed access, which is exactly what a compiler-generated switch-statement lookup table is (lis+la computing &table, then lwzx indexing into it at runtime — the index isn't known at codegen time, so there's nothing to fold). Rodata now gets a real synthetic address, same as mutable data, which handles both the scalar-constant and indexed-array cases uniformly and correctly — see is_synthetic_addr_lo_reloc in codegen.cpp and testdata/rodata_table.c, which specifically exercises the bug that motivated this (a switch compiled to a lookup table, not an if/else-if chain).
  • Indirect calls through function pointers (mtctr+bctrl — vtables, callback tables, anything a compiler can't inline to a direct bl) are handled via a generated ppc_dispatch(ctx, addr) function (emitted in main.cpp, alongside ppc_init_globals) that switches on the function's real address and calls the matching generated ppc_<name>. mtctr moves a value into a new PpcContext::ctr field; bctrl compiles to a call to ppc_dispatch. This is a genuinely different problem from the project's own stripped-binary heuristic function recovery (which only finds functions reached via a direct, resolved bl) — indirect targets are only knowable at generated-code runtime, not at recompile time, so dispatch has to happen there instead of being resolved away entirely.
  • Instruction subset covers integer arithmetic/branches/calls (stw[u], lwz, mr, li/lis/ori, addi, add, subf, mulli, mullw, cmpw[i], conditional branches, b, bl, blr, mflr/mtlr, subfic), byte/halfword memory access (lbz, lhz, lha, stb, sth), bitwise ops (and, or, xor, nor, andc, eqv, neg, cntlzw), shift-immediate/sign-extend (slwi, srwi, srawi, extsb, extsh), rotate/mask (rlwinm, rlwimi, clrlwi, rotlwi — the general rlwinm/rlwimi mask is computed at codegen time from the well-established PPC ISA mask formula, not simulated at runtime), carry-propagating arithmetic (addc/adde, for 64-bit/multi-word values held across register pairs — cmplw for the matching unsigned compare, plus cmplwi), integer division (divw/ divwu), indexed (register+register) load/store (lwzx/stwx/lbzx/ stbx/lhzx/sthx — real array-indexing code uses these constantly), high-word multiply (mulhw/mulhwu — what a compiler emits for division-by-constant, so far more common in optimized code than the name suggests), and floating point — both single precision (lfs, stfs, fadds/fsubs/fmuls/fdivs, fmadds, fmr, fneg, fcmpu) and double precision (lfd, stfd, fadd/fsub/fmul/ fdiv, fmadd/fmsub, fctiwz for float-to-int conversion). FPRs are modeled as double per real PPC hardware, with single-precision ops rounded via ppc_frsp — see recomp/include/ppc_runtime.h for the known fidelity gaps (no FP exception flags, no rounding-mode control). Memory is genuinely big-endian (byte-order-explicit load/store, not host-native memcpy), which turned out to matter for real correctness — fctiwz stores its result via a fixed-byte-offset trick that only works if memory layout actually matches PPC's, not just "consistent with itself." CTR-based counted-loop branches (bdnz/bdz) are also handled — turned out an earlier note that these "don't trigger from zig cc output at any optimization level" was wrong; they do, just only at -O2 and above (see testdata/loop_counted.c), which the project's other tests hadn't tried yet since most opcodes here first appeared at -O0/-O1. Known gap, deliberately not guessed at: Altivec/paired-single SIMD is still unhandled. Anything unhandled emits a #error naming the instruction rather than silently mistranslating it.

Toolchain #

devkitpro.org itself is Cloudflare-blocked from this project's dev sandbox, so the package mirror used to install additional devkitPro libraries isn't reachable here — but the devkitA64+libnx toolchain already installed in the sandbox works fine, so switch/native/'s minimal libnx-only build succeeds directly here now too. The recompiler itself still uses a separate, always-reachable toolchain:

  • Zig (zig cc) provides PowerPC and ARM64 cross-compilation, via its bundled clang.
  • Capstone (built from source, PowerPC support) does the disassembly.
  • qemu-aarch64-static runs the cross-compiled ARM64 output without real Switch hardware.

Run tools/setup_toolchain.sh to install all three under ~/devtools (idempotent, safe to re-run).

Build & verify #

tools/setup_toolchain.sh   # one-time
tools/verify.sh            # builds recomp, recompiles both test programs,
                            # checks host + QEMU-ARM64 results match ground truth

tools/verify.sh is the pass/fail signal: it compares a native build of each testdata/*.c program (ground truth) against the recompiler's C output, built both for the host and cross-compiled for ARM64 and run under QEMU — testdata/arithmetic.c (integer/calls/stripped-binary recovery), testdata/floating.c (single-precision FP + rodata constant resolution), testdata/bitops.c (bitwise ops, shifts, byte/halfword memory access), testdata/rotate.c (rlwinm/rlwimi/clrlwi/rotlwi, built at -O1 since these don't show up in -O0 output), testdata/carry.c (addc/adde/cmplw, 64-bit arithmetic via register-pair carry propagation), testdata/division.c (divw/divwu), testdata/indexed.c (lwzx and friends, real array-indexing code), testdata/fcmp.c (fcmpu, float-conditional branching), testdata/mulhw.c (mulhw/mulhwu, built at -O1), testdata/double.c (double precision + fctiwz float-to-int conversion, which also exercises the compiler's int-to-double bias-trick conversion idiom), testdata/misc_bitops.c (cntlzw, andc, eqv, subfic), and testdata/mixed_double.c (an integration test with no new instructions of its own — int-array-to-double accumulation + abs-via-negate — that exists to catch interaction bugs between features that otherwise only get exercised in isolation), testdata/globals.c (global/static variable read-modify-write, including indexed access into a global array, verified across multiple sequential calls to confirm the state genuinely persists), testdata/multifunc_globals.c (the same global resolved consistently from three different functions, not just repeated calls to one), and testdata/fnptr.c (mtctr/bctrl indirect calls: picks between two functions via a function pointer and calls through it, verified to actually dispatch to different functions rather than one hardcoded target), testdata/loop_counted.c (mtctr/bdnz counted-loop branches, built at -O2 since that's the lowest level they show up at), and testdata/rodata_table.c (a switch statement compiled to a lookup table in .rodata, indexed at runtime — the read-only-data addressing correctness fix described above).

See switch/README.md for Milestone 2's first, libnx-free attempt (a minimal boot test, not real game content, and why it doesn't use libnx), and switch/native/README.md for the real, hardware-verified libnx build.

Phase 0: Dumping & Decryption #

tools/phase0_setup.sh + tools/phase0/README.md document and set up the real, existing (not reimplemented) tooling for turning a legally-owned Wii U copy into a decrypted .rpx/.rpl set: disc2app/WUDD for the on-console dump step (can't be automated — needs real hardware) and ihaveamac/wiiu-things for decrypt/extract.

Collaboration #

This is planned as a multi-year, likely multi-contributor effort. If you're working on something similar, or want to help with this project directly: