# 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:
- 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/).
- 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.9.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.
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.9.5"
```
See this crate at .
## References
- MIPS CPU:
- MIPS IV Instruction Set (Revision 3.2):
- MIPS Calling Convention Summary:
- mipt-mips pseudo instructions:
- 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:
-
- R5900:
- EmotionEngine instruction decoding:
- Official documentation from Toshiba:
- VU instruction manual:
- GNU binutils: