spimdisasm 2.0.0-alpha.1

MIPS disassembler
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# spimdisasm

![GitHub](https://img.shields.io/github/license/Decompollaborate/spimdisasm)
![crate.io](https://img.shields.io/crates/dv/spimdisasm)
![Crates.io MSRV](https://img.shields.io/crates/msrv/spimdisasm)
![GitHub License](https://img.shields.io/github/license/Decompollaborate/spimdisasm)
![GitHub contributors](https://img.shields.io/github/contributors/Decompollaborate/spimdisasm?logo=purple)

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.

<!--
## Quick example

```rust
```

Check the documentation at [crates.io](https://crates.io/crates/spimdisasm).
-->

## 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](https://github.com/Kingcom/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](https://crates.io/crates/spimdisasm) and
can be included in your Cargo enabled project like this:

```toml
[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 `HashMap`s instead of `BTreeMap`s, 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](https://semver.org/spec/v2.0.0.html).
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).

<!--
TODO change this link when we do the first stable release
-->
To see what changed on each release check either the
[CHANGELOG.md](https://github.com/Decompollaborate/spimdisasm/blob/rs/CHANGELOG.md)
file or check the [releases page on Github](https://github.com/Decompollaborate/spimdisasm/releases).
You can also use [this link](https://github.com/Decompollaborate/spimdisasm/releases/latest)
to check the latest release.