35 stable releases
1.12.0 | Jul 21, 2024 |
---|---|
1.11.0 | May 22, 2024 |
1.9.4 | Mar 18, 2024 |
1.8.1 | Dec 25, 2023 |
1.5.8 | Dec 20, 2022 |
#191 in Development tools
35 downloads per month
Used in objdiff-core
1MB
24K
SLoC
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.
- The library is completely allocation-less, in other words
- 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
- Python 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 explicitrd
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.
- Configurable behavior for the
- Some workarounds for some specific compilers/assemblers:
SN64
:div
/divu
fix: tweaks a bit the produceddiv
,divu
andbreak
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.
- 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
:
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:
rabbitizer>=1.12.0,<2.0.0
Development version
The unstable development version is located at the 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:
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:
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:
cargo add rabbitizer
Or you can add it manually to your Cargo.toml
:
rabbitizer = "1.12.0"
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
Dependencies
~1.3–1.9MB
~44K SLoC