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.9, 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.
  • 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.14.3,<2.0.0

Development version

The development version is located at the 1.x branch.

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, you could use the following command:

python3 -m pip uninstall rabbitizer
python3 -m pip install git+https://github.com/Decompollaborate/rabbitizer.git@1.x

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.14.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