spimdisasm

spimdisasm (whole name is lowercase) is a matching MIPS disassembler API with built-in instruction analysis.

Currently supports the instruction set for MIPS I, II, III and IV.

Mainly focused on supporting binaries from videogame platforms like the Nintendo 64, PlayStation 1, PlayStation 2, and PlayStation Portable.

A matching disassembler generates assembly that can be assembled back into the same original binary it was produced from, performing a clean round-trip.

Features

• Generates assembly that can be assembled back into the original binary. This is known as matching disassembly.
• Fully written in Rust.
  • Full no_std support, but does require the Rust alloc crate.
• Supports .text, .data, .rodata and .bss disassembly.
• Generates separated files for each section of a file (.text, .data, .rodata and .bss).
• Supports spliting multiple assembly files from a single input binary.
• Automatic function detection.
  • Can detect the limits of when a function starts and end with pretty high success rate.
  • Can detect if a function is handwritten too to a certain degree.
• Can identify symbols identification and actually symbolize them for a more flexible generated assembly.
• Reloc pairing (i.e. %hi/%lo relocs) with high success rate.
• Function spliting with rodata migration.
• Supports inference of multiple data types, like floats, doubles, strings, jumptables, bytes and shorts.
• String detection with medium to high success rate.
• Allows to set user-defined symbol metadata, like names, type, sizes, etc.
• Support for big and little endian.
• Autogenerated symbols can be named after the section they come from (RO_ and B_ for .rodata and .bss sections) or its type (STR_, FLT_ and DBL_ for string, floats and doubles respectively).
• Simple file boundary detection.
  • Detects boundaries on .text and .rodata sections.
• Very customizable: Many features can be toggled on and off.
• MIPS instructions features:
  • Named registers for MIPS VR4300's coprocessors.
  • Support for many pseudoinstructions.
  • Properly handle move to/from coprocessor instructions.
  • Support for o32, n32, n64, EABI32 and EABI64 ABI register names.
• Some workarounds for some specific compilers/assemblers:
  • SN64/PSYQ:
    • div/divu fix: tweaks a bit the produced div, divu and break instructions.
• Support for specific MIPS instruction set extensions:
  • N64's RSP instruction disassembly support.
    • RSP decoding has been tested to build back to matching assemblies with armips.
  • PS1's R3000 GTE instruction set support.
  • PSP's R4000 ALLEGREX instruction set support.
  • PS2's R5900 EE instruction set support.
• Support for disassembling sections with overlapping addresses.

Minimum Supported Rust Version (MSRV)

The current version of spimdisasm requires Rust 1.83.0 or greater.

The current policy is that this may be bumped in minor spimdisasm updates.

Installation

spimdisasm is available on crates.io and can be included in your Cargo enabled project like this:

[dependencies]
spimdisasm = "2.0.0-alpha.1"

Crate features

There are a few compilation features. Currently none of them are enabled by default.

• Misc:
  • std: Turns on std (or turn off no_std, depending on how you prefer it). This currently doesn't do much.
    • Enables the std feature on dependencies.
  • hash_tables: Toggles the internal implementation of some unordered maps to use HashMaps instead of BTreeMaps, allowing for possible (unmeasured) performance improvements.
    • Enables the std feature.

The other features are meant for internal use only.

Versioning and changelog

This library follows Semantic Versioning. We try to always keep backwards compatibility, so no breaking changes should happen until a major release (i.e. jumping from 1.X.X to 2.0.0).

To see what changed on each release check either the CHANGELOG.md file or check the releases page on Github. You can also use this link to check the latest release.