spm-decomp/CONTRIBUTING.md

Contact

If you're interested in contributing, it's recommended you reach out to us in the #reverse-engineering channel of the SPM Speedrunning Discord first. Here you can ask for any help you might need and discuss what you plan to decompile to prevent any duplicated work.

ppcdis

This project is build around the ppcdis tools. These handle generation of assembly code (you should never edit the assembly output manually) and helpers for allowing partially-decompiled C files to match.

YMLs

Overrides

Overrides allow hints to be given to the analysis / disassembly to improve accuracy or work around issues. Generally you won't need to change anything about analysis (config/analysis_overrides.yml), though changing the disassembly is more common (config/analysis_overrides.yml).

See also the ppcdis documentation of this.

Slices

config/dol_slices.yml / config/rel_slices.yml control how the disassembly is split around the decompiled C code for the dol / rel. See also the ppcdis documentation of this

You must re-run configure.py after changing this file

Symbols

config/symbols.yml controls the naming of functions and data in disassembly.

See also the ppcdis documentation of this

Generated includes

These can be generated by adding the include statement to a C file and re-running configure.py.

Orderstrings

#include orderstrings/XXXXXXXX_YYYYYYYY.inc will generate a workaround for the ordering of strings in a file, with strings starting at address XXXXXXXX (inclusive) and ending at address YYYYYYYY (exclusive).

See also the ppcdis documentation of this

Orderfloats

#include orderfloats/XXXXXXXX_YYYYYYYY.inc will generate a workaround for the ordering of floats in a file, with floats starting at address XXXXXXXX (inclusive) and ending at address YYYYYYYY (exclusive). #include orderfloatsm/XXXXXXXX_YYYYYYYY.inc will generate a 'manual' version of that (see documentation below).

#include orderdoubles/XXXXXXXX_YYYYYYYY.inc will generate a version of that for doubles. 'Manual' doubles are not needed for this project.

See also the ppcdis documentation of this

Jumptable

#include jumptable/XXXXXXXX.inc will generate a workaround for an undecompiled jumptable at address XXXXXXXX.

See also the ppcdis documentation of this

Asm

#include asm/XXXXXXXX.s will generate inline assembly for an undecompiled function.

See also the ppcdis documentation of this

diff.py

A setup for asm-differ is included. To use it:

• First get a matching build and run expected.py
  • If you use the -o flag (see below), this will need to be re-ran whenever you add new source files
• You can now run diff.py symbolName to diff a function
• It's recommended to run it with the flags -mwos, see -h for details on these and the other flags available
• If you want to diff a function in the rel, you'll need to add the -r flag

Project-Specific Tools

decompme.py

Generates a scratch on decomp.me for a function. This gives a web-based UI for editing & diffing a function, and the ability to share it with other people. Usage is decompme.py XXXXXXXX to upload the function at XXXXXXXX. By default, an M2C decompiler compatible context is made, which strips definitions and macros that you have wanted included. You can replace this with a context from makectx.py (see below) after the decompiler runs if you'd like.

getfunction.py

Gets the assembly of a single function. Usage is getfunction.py XXXXXXXX to get the function at XXXXXXXX.

makectx(_m2c).py

Creates a context of all header files in the project concatenated and prints it to stdout. If using makectx_m2c, this will have the C preprocessor ran on it.