rabbitizer/README.md

# rabbitizer

[![PyPI - Downloads](https://img.shields.io/pypi/dm/rabbitizer)](https://pypi.org/project/rabbitizer/)
![GitHub](https://img.shields.io/github/license/Decompollaborate/rabbitizer)
![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/Decompollaborate/rabbitizer)
![PyPI](https://img.shields.io/pypi/v/rabbitizer)
![crate.io](https://img.shields.io/crates/dv/rabbitizer)
![GitHub contributors](https://img.shields.io/github/contributors/Decompollaborate/rabbitizer?logo=purple)

MIPS instruction decoder API.

## Features

- Should produce matching assembly.
- Fully written in C for fast decoding.
  - The library is completely allocation-less, in other words `rabbitizer`
  doesn't allocate in anything in the heap by itself.
- Other language bindings supported in this repo:
  - Python bindings
    - The minimal Python version is 3.7, older versions are not guaranteed to
      work.
  - C++ bindings
  - Rust bindings
- Simple per-word instruction decoding.
  - The library doesn't try to be too smart by processing multiple instructions
    at a time.
- Can perform validation checks for instructions.
- Provides many examination/grouping functions for instructions, allowing to
  simplify checking characteristics of an instruction and minimizing the need to
  check for specific instructions in a hardcoded way.
- Includes some minor tools to build your own pointer/symbol detection.
- Configurable, many features can be turned on and off.
- MIPS instructions features:
  - Configurable behavior for the `jalr` instruction, allowing to disassemble
    that instruction using an implicit or explicit `rd` register depending if
    that register is `$ra` or not.
  - Named registers for MIPS VR4300's coprocessors.
  - Support for many pseudo-instructions.
  - Properly handle move to/from coprocessor instructions.
  - Support for numeric, o32, n32 and n64 ABI register names.
- Some workarounds for some specific compilers/assemblers:
  - `SN64`:
    - `div`/`divu` fix: tweaks a bit the produced `div`, `divu` and `break` instructions.
- Multiple MIPS architectures are supported:
  - Main focus on MIPS I, II and III architectures. Partial support for MIPS IV too.
  - N64 RSP instruction decoding support.
    - RSP decoding has been tested to build back to matching assemblies with [armips](https://github.com/Kingcom/armips/).
  - R3000 GTE (PSX's CPU) decoding support.
  - R4000 ALLEGREX (PSP's CPU) decoding support.
  - R5900 (PS2's Emotion Engine processor) decoding support.

## Non-features

In order to keep it simple and fast the following features will not be added:

- Pseudo-instructions which expands to more than one instruction.

## Installing

### Python bindings

The recommended way to install is using from the PyPi release, via `pip`:

```bash
python3 -m pip install -U rabbitizer
```

If you use a `requirements.txt` file in your repository, then you can add this
library with the following line:

```txt
rabbitizer>=1.12.3,<2.0.0
```

### Development version

The unstable development version is located at the
[develop](https://github.com/Decompollaborate/rabbitizer/tree/develop)
branch. PRs should be made into that branch instead of the main one.

Note that building the Python bindings from source require the Python
development package. Under Ubuntu/Debian based distros it can be installed with:

```bash
apt install python3-dev
```

In case you want to mess with the latest development version without wanting to
clone the repository, then you could use the following command:

```bash
python3 -m pip uninstall rabbitizer
python3 -m pip install git+https://github.com/Decompollaborate/rabbitizer.git@develop
```

NOTE: Installing the development version is not recommended. Proceed at your own
risk.

See this package at <https://pypi.org/project/rabbitizer/>.

### Rust bindings

Add this crate to your project with Cargo:

```bash
cargo add rabbitizer
```

Or you can add it manually to your `Cargo.toml`:

```toml
rabbitizer = "1.12.3"
```

See this crate at <https://crates.io/crates/rabbitizer>.

## References

- MIPS CPU:
  - MIPS IV Instruction Set (Revision 3.2): <https://www.cs.cmu.edu/afs/cs/academic/class/15740-f97/public/doc/mips-isa.pdf>
  - MIPS Calling Convention Summary: <https://courses.cs.washington.edu/courses/cse410/09sp/examples/MIPSCallingConventionsSummary.pdf>
  - mipt-mips pseudo instructions: <https://github.com/MIPT-ILab/mipt-mips/wiki/MIPS-pseudo-instructions>
  - IDT R30xx Family Software Reference Manual, page 325 (for `rfe`): <https://psx.arthus.net/docs/R3000.pdf>

- N64's RSP (Reality Signal Processor):
  - Nintendo Ultra64 RSP Programmer’s Guide: <https://ultra64.ca/files/documentation/silicon-graphics/SGI_Nintendo_64_RSP_Programmers_Guide.pdf>
  - N64brew Reality Signal Processor/CPU Core: <https://n64brew.dev/wiki/Reality_Signal_Processor/CPU_Core>

- R3000 GTE:
  - PSYQ SDK headers: <https://github.com/FoxdieTeam/psyq_sdk/blob/master/psyq_4.4/INCLUDE/INLINE_A.H>
  - no$psx documentation: <https://problemkaputt.de/psxspx-gte-opcode-summary.htm>
  - no$psx documentation: <http://problemkaputt.de/psx-spx.htm#geometrytransformationenginegte>
  - <http://www.raphnet.net/electronique/psx_adaptor/Playstation.txt>

- R4000 ALLEGREX:
  - ALLEGREX-Instruction_Manual-English <https://github.com/Decompollaborate/rabbitizer/files/11356332/ALLEGREX-Instruction_Manual-English.pdf>
  - FPU-Instruction_Manual-English <https://github.com/Decompollaborate/rabbitizer/files/14950191/FPU-Instruction_Manual-English.pdf>
  - VFPU-Instruction_Manual-English <https://github.com/Decompollaborate/rabbitizer/files/11356335/VFPU-Instruction_Manual-English.pdf>
  - VFPU-Users_Manual-English <https://github.com/Decompollaborate/rabbitizer/files/11356333/VFPU-Users_Manual-English.pdf>
  - yet another PlayStationPortable Documentation <http://hitmen.c02.at/files/yapspd/psp_doc/frames.html>
    - Chapter "4.8  Allegrex Instructions" <http://hitmen.c02.at/files/yapspd/psp_doc/chap4.html#sec4.8>
  - GNU binutils: <https://github.com/bminor/binutils-gdb/compare/011365b...a0176d8>

- R5900:
  - EmotionEngine instruction decoding: <https://psi-rockin.github.io/ps2tek/#eeinstructiondecoding>
  - Official documentation from Toshiba: <https://wiki.qemu.org/images/2/2a/C790.pdf>
  - VU instruction manual: <http://lukasz.dk/files/vu-instruction-manual.pdf>
  - GNU binutils: <https://github.com/bminor/binutils-gdb/blob/master/opcodes/mips-opc.c>