ds-decomp

Toolkit for decompiling DS games, dsd for short.

Join the discussion in the #dsd channel of our Discord server!

Contents

• Goals
• Commands
  • rom extract
  • rom build
  • rom config
  • init
  • delink
  • dis
  • objdiff
  • lcf
  • json delinks
  • check modules
  • check symbols
  • apply
  • sig apply
  • sig list
  • format
  • diff new
  • diff apply

Goals

• Automate decomp project setup with zero user input, saving months of manual setup time.
• Allow developers to easily delink code into individual translation units and to quickly give names to symbols.
• Generate linker scripts with correct link order.
• Integrate with other decompilation tools, including objdiff.

Commands

rom extract

Extracts a DS ROM into separate files for code and assets.

$ dsd rom extract --rom path/to/rom.nds --output-path path/to/extract/

Options:

• -r, --rom: Path to ROM file.
• -7, --arm7-bios: Path to ARM7 BIOS file, needed for decryption.
• -o, --output-path: Path to extract directory.

rom build

Builds a DS ROM from an extract directory.

$ dsd rom build --config path/to/extract/config.yaml --rom path/to/built_rom.nds

Options:

• -c, --config: Path to config.yaml in the extract directory.
• -7, --arm7-bios: Path to ARM7 BIOS file, needed for encryption.
• -o, --rom: Path to ROM file.

rom config

Creates a ds-rom configuration to build a ROM from linked binaries.

$ dsd rom config --elf path/to/final_link.o --config path/to/config.yaml

Options:

• -e, --elf: Path to the final linked ELF file, generated by the LCF and the linker.
• -c, --config: Path to config.yaml generated by init.

init

Initialize a new dsd configuration from a given extract directory generated by rom extract. This will analyze the code and generate config files.

$ dsd init --rom-config path/to/extract/config.yaml --output-path path/to/output/ --build-path path/to/build/

Options:

• -r, --rom-config: Path to config.yaml in the extract directory.
• -o, --output-path: Output path for dsd config files.
• -d, --dry: Dry run, only perform analysis but don't write any files.
• -b, --build-path: Output path for delinks and the LCF.

delink

Delinks the game into relocatable ELF files. The output directory is determined by delinks_path in config.yaml.

$ dsd delink --config-path path/to/config.yaml

Options:

• -c, --config-path: Path to config.yaml generated by init.

dis

Disassembles the game into assembly files. Used for informational purposes, doesn't target a specific assembler.

$ dsd dis --config-path path/to/config.yaml --asm-path path/to/asm/

Options:

• -c, --config-path: Path to config.yaml generated by init.
• -a, --asm-path: Output path for assembly files.

objdiff

Generates an objdiff configuration.

$ dsd objdiff --config-path path/to/config.yaml

Options:

• -c, --config-path: Path to config.yaml generated by init.
• -o, --output-path: Path to directory to generate objdiff.json.
• --stdout: Print to stdout instead of writing to a file.
• -s, --scratch: Include decomp.me scratches.
• -C, --compiler: Name of compiler in decomp.me, see https://decomp.me/api/compiler for compilers for the nds_arm9 platform.
• -f, --c-flags: Compiler flags, as a single string.
• -p, --preset-id: Preset ID to use in decomp.me.
• -m, --custom-make: Custom build command for objdiff.
• -M, --custom-args: Arguments to custom build command. Can be passed multiple times to append more arguments.

lcf

Generates a linker command file (LCF) for mwldarm.

$ dsd lcf --config-path path/to/config.yaml --lcf-file path/to/linker_script.lcf --objects-file path/to/objects.txt

Options:

• -c, --config-path: Path to config.yaml generated by init.
• -l, --lcf-file: Output path to LCF file.
• -o, --objects-file: Output path to objects list, to be passed to the linker.

json delinks

Meant to be used by build systems. Outputs a JSON-formatted object containing information about which files delink generates and files needed for linking.

$ dsd json delinks --config-path path/to/config.yaml

Options:

• -c, --config-path: Path to config.yaml generated by init.

check modules

Verifies that built modules are matching the base ROM.

$ dsd check modules --config-path path/to/config.yaml

Options:

• -c, --config-path: Path to config.yaml generated by init.
• -f, --fail: Return failing exit code if a module doesn't pass the checks.

check symbols

Verifies that all symbols from every symbols.txt file exist in the final linked ELF file.

$ dsd check symbols --config-path path/to/config.yaml --elf-path path/to/final_link.o

Options:

• -c, --config-path: Path to config.yaml generated by init.
• -e, --elf-path: Path to the final linked ELF file, generated by the LCF and the linker.
• -f, --fail: Return failing exit code if a symbol didn't match.

apply

Applies symbol data from the final linked ELF to symbols.txt files.

$ dsd apply --config-path path/to/config.yaml --elf-path path/to/final_link.o

Options:

• -c, --config-path: Path to config.yaml generated by init.
• -e, --elf-path: Path to the final linked ELF file, generated by the LCF and the linker.
• -d, --dry: Dry run, do not write to any files.
• -v, --verbose: Verbose output.

sig apply

Searches for a function using a signature. If found, the functions and its related objects get renamed.

$ dsd sig spply --config-path path/to/config.yaml --all

Options:

• -c, --config-path: Path to config.yaml generated by init.
• -s, --signature: Name of signature to apply.
• -a, --all: Apply all known signatures.
• -d, --dry: Dry run, do not write to any files.

sig list

Lists all known signatures that can be applied with sig apply

$ dsd sig list

format

Formats configs associated with the given config.yaml file.

• Sections in delinks.txt are sorted by address.
• Delink files in delinks.txt are sorted by link order.
• Symbols in symbols.txt are sorted by address.
• Relocations in relocs.txt are sorted by source address.

$ dsd format --config-path path/to/config.yaml

Options:

• -c, --config-path: Path to config.yaml generated by init.

diff new

Compares two dsd projects and generates a YAML file of diff actions. See diff apply for applying diff actions.

This subcommand can be used to bring improved analysis results of newer dsd versions to old dsd projects. It's recommended to pass all the --skip-* options when doing so, as it will exclude many regressive diff actions.

$ dsd diff new --config-before path/to/old/config.yaml --config-after path/to/new/config.yaml

Options:

• -1, --config-before: Path to config.yaml generated by init for the first project.
• -2, --config-after: Path to config.yaml generated by init for the second project.
• -o, --output-path: Path to diff output file, defaults to dsd_diff.yaml.
• --skip-files: Skips diff actions that affect delink files.
• --skip-default-names: Skips diff actions that rename symbols to their default names.
• --skip-broadened-relocs: Skips diff actions that add more overlay candidates to ambiguous relocations.
• --skip-zeroed-addends: Skips diff actions that set a relocation's addend to zero.
• --skip-globalized-symbols: Skips diff actions that turn a local symbol to global.
• --skip-sizeless-data: Skips diff actions that removes the explicit size of BSS/data symbols.
• --skip-ambiguous-symbols: Skips diff actions that add symbols marked with ambiguous.

diff apply

Opens an interactive TUI for applying or rejecting diff actions generated by diff new.

$ dsd diff apply

Options:

• -i, --input-path: Path to diff actions YAML file generated by diff new, defaults to dsd_diff.yaml.
• --all: Skips the interactive TUI and applies all actions.

Controls:

Key	Description
Q	Quit the TUI.
Ctrl+C	Force quit the TUI without saving.
↓ (down)	Select next diff action. Hold Ctrl to go faster.
↑ (up)	Select previous diff action. Hold Ctrl to go faster.
Home	Select first diff action.
End	Select last diff action.
1	Mark selected diff action as "good".
2	Mark selected diff action as "bad".
3	Mark selected diff action as "skipped" (default).
↵ (return)	Apply good actions, discard bad actions, and remove both from the diff actions file. All the skipped actions will remain.
J	Scroll the description window down.
K	Scroll the description window up.