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

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. - -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.