Bramble #

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 directbltarget found by a single linear disassembly pass over.textbecomes 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, resolvedbl— indirect calls (function pointers/vtables) still need the manual review the project plan already flags for those. Seerecomp/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 resolvebltargets directly by address instead) andR_PPC_ADDR16_HA/R_PPC_ADDR16_LO(alis+ load/store/addipair addressing a symbol). Global/static variables (.data/.bss, and — as of a correctness fix, see below —.rodata*too) get a real synthetic address inPpcContext::mem, consistently assigned per-section (preserving relative offsets between symbols in the same section, so indexed access into an array works correctly) byassign_global_addrs— the generated code also emits appc_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 samelis+addiidiom, 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 asbl-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 wholelis+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+lacomputing&table, thenlwzxindexing 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 — seeis_synthetic_addr_lo_relocincodegen.cppandtestdata/rodata_table.c, which specifically exercises the bug that motivated this (aswitchcompiled 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 directbl) are handled via a generatedppc_dispatch(ctx, addr)function (emitted inmain.cpp, alongsideppc_init_globals) that switches on the function's real address and calls the matching generatedppc_<name>.mtctrmoves a value into a newPpcContext::ctrfield;bctrlcompiles to a call toppc_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, resolvedbl) — 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 generalrlwinm/rlwimimask 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 —cmplwfor the matching unsigned compare, pluscmplwi), 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,fctiwzfor float-to-int conversion). FPRs are modeled asdoubleper real PPC hardware, with single-precision ops rounded viappc_frsp— seerecomp/include/ppc_runtime.hfor the known fidelity gaps (no FP exception flags, no rounding-mode control). Memory is genuinely big-endian (byte-order-explicit load/store, not host-nativememcpy), which turned out to matter for real correctness —fctiwzstores 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 fromzig ccoutput at any optimization level" was wrong; they do, just only at-O2and above (seetestdata/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#errornaming 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:
- Discord
- Email: aaron@aaronworld.uk