The reverse-engineering toolchain¶

Everything in Running the tools needs nothing but uv. Everything on this page is for the other half of the work: reading PowerPC, writing PowerPC, and comparing two firmware versions. None of it is bundled — it is per-machine, and it is the same whether you are on the Mac or the Windows box.

Two of these tools are already used by the repository's own analysis:

capstone and unicorn — used by tools/ppcdis.py and tools/ppcemu.py — are not in this list because the dev extra already installs them.

Installing¶

brew install llvm lld rizin ghidra

LLVM="$(brew --prefix llvm)/bin"

winget install -e --id LLVM.LLVM
winget install -e --id Gyan.FFmpeg

Reading the image¶

The repository's own tools read a raw image directly:

uv run tools/unpack.py SMEG_PLUS_UPG/NAV/AppBin/f_BigQuick.bin app_nav.bin
uv run tools/ppcdis.py app_nav.bin abs_symbols_base.txt 0x0230331c 0x02303460

For anything larger than a function or two, wrap it into an ELF and use a real disassembler or decompiler. tools/mkelf.py attaches the shipped symbol map, so the names come with it:

uv run tools/mkelf.py app_nav.bin abs_symbols_base.txt app_nav.elf
llvm-objdump -d --triple=powerpc app_nav.elf

To decompile rather than read assembly, import app_nav.elf into Ghidra and pick PowerPC:BE:32:default as the language. There is deliberately no e300 language ID — Ghidra's PowerPC list has 4xx, e500, e500mc, MPC8270, QUICC and default, and the e300 is none of the specific ones, which matches the architecture notes calling it plain PowerPC with no vendor extensions. Import the ELF, not the raw image: the symbols are the reason to bother.

Ghidra from Claude Code (optional)¶

The repository's .mcp.json points Claude Code at a pyghidra-mcp server on http://127.0.0.1:8000/mcp. Nothing is shipped for it, because the ELF is vendor material and stays outside the repository. To use it, run one server against your own ELF and leave it running:

export GHIDRA_INSTALL_DIR=/path/to/ghidra        # Homebrew: $(brew --prefix ghidra)/libexec
export JAVA_HOME=/path/to/jdk-21                  # Ghidra wants 21; newer JDKs may not work
uvx pyghidra-mcp --transport streamable-http --port 8000 \
  --project-path ~/ghidra-work/projects --project-name smeg ~/ghidra-work/app_nav.elf

The first start analyses the whole image, which takes a long time; later starts reuse the project.

Run one server, over HTTP, never one per session. Ghidra lets a single process hold a project. A stdio server configured at user scope is started by every Claude session, and every copy after the first fails with LockException: Unable to lock project, which Claude Code reports only as "connection closed". Sessions and the desktop app can all share the one HTTP server. Without it running, the entry simply fails to connect and nothing else is affected.

Writing PowerPC¶

For a handful of instructions — which is what most entries in patches/*.json are — you do not need a compiler or a linker. llvm-mc assembles text and prints the encoding, so the bytes field can be written from source rather than from memory:

$LLVM/llvm-mc --triple=powerpc --show-encoding <<'EOF'
    li 3, 1
    blr
EOF
#   li   3, 1        # encoding: [0x38,0x60,0x00,0x01]
#   blr              # encoding: [0x4e,0x80,0x00,0x20]

That is the aux-always-available patch, and it is worth noticing why this works: the encoding 38 60 00 01 4e 80 00 20 is exactly what patches/aux-always-available.json carries. The patch was hand-assembled, and the compiler agrees with it byte for byte.

For a whole function, compile and link it. All three steps are needed, because the linker is what places the code at the address the patch expects:

LLVM="$(brew --prefix llvm)/bin"          # Windows: C:\Program Files\LLVM\bin
LLD="$(brew --prefix lld)/bin"            # Windows: in the LLVM bin directory

$LLVM/clang --target=powerpc-unknown-none-eabi -mbig-endian -O2 -ffreestanding \
    -c mycode.c -o mycode.o

$LLD/ld.lld -m elf32ppc --image-base=0 -Ttext=0x02247718 \
    -e my_function mycode.o -o mycode.elf

$LLVM/llvm-objcopy -O binary --only-section=.text mycode.elf mycode.bin
xxd mycode.bin

-ffreestanding because there is no libc to link against. -e names the entry point.

ld.lld: error: section '.text' address (0x2247718) is smaller than image base (0x10000000);
specify --image-base

To check the result before trusting it, disassemble the ELF — which, unlike the flat binary, still carries the load address and the symbol:

$LLVM/llvm-objdump -d --triple=powerpc mycode.elf

Comparing two firmware versions¶

Addresses move between firmware versions — the NAV image from SMEG_5.42.B.R4 is the 5.43 one displaced by a constant 152 bytes — so this comes up every time. rz-diff does it without unpacking either side into a disassembler:

rz-diff -t raw app_nav_542.bin app_nav_543.bin

What is verified, and what is not¶

The macOS commands above have been run end to end: a C function compiled to PowerPC, linked at 0x02247718, emitted as a flat binary and disassembled gives 38 60 00 01 4e 80 00 20 — li r3,1 ; blr, the same sequence the shipped patch carries.

The Windows instructions are written from the vendors' own installers and have not been run on a Windows machine here. Treat the paths as right and the tools as untested.

Two things are deliberately not claimed:

• Nothing here has been flashed. The toolchain produces the bytes a patch wants; whether a given patch works on a car is a separate question, answered in Hardware verification.
• A routine larger than its patch site is not solved, but the blocker is characterised. There is no usable code cave in .text — every large zero-run is .rodata (sqlite3 and utf8proc tables), so live data. A trampoline would have to live past the end of the image, and that is expressible: the container header holds the inflated size at offset 0x04 and no compressed size (the zlib stream is self-delimiting), so the image can be grown. Whether the loader maps the appended region executable is untested — so fitting the edit into the words already there remains the way that works.