README.md

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