# rabbitizer
[](https://pypi.org/project/rabbitizer/)
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.5,<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 .
### 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.5"
```
See this crate at .
## References
- MIPS CPU:
- MIPS IV Instruction Set (Revision 3.2):
- MIPS Calling Convention Summary:
- mipt-mips pseudo instructions:
- IDT R30xx Family Software Reference Manual, page 325 (for `rfe`):
- N64's RSP (Reality Signal Processor):
- Nintendo Ultra64 RSP Programmer’s Guide:
- N64brew Reality Signal Processor/CPU Core:
- R3000 GTE:
- PSYQ SDK headers:
- no$psx documentation:
- no$psx documentation:
-
- R4000 ALLEGREX:
- ALLEGREX-Instruction_Manual-English
- FPU-Instruction_Manual-English
- VFPU-Instruction_Manual-English
- VFPU-Users_Manual-English
- yet another PlayStationPortable Documentation
- Chapter "4.8 Allegrex Instructions"
- GNU binutils:
- R5900:
- EmotionEngine instruction decoding:
- Official documentation from Toshiba:
- VU instruction manual:
- GNU binutils: