42 stable releases
2.0.0-alpha.1 | Apr 2, 2025 |
---|---|
1.13.0 | Apr 4, 2025 |
1.12.6 | Feb 6, 2025 |
1.12.5 | Dec 16, 2024 |
1.5.8 | Dec 20, 2022 |
#46 in Hardware support
268 downloads per month
Used in objdiff-core
1.5MB
42K
SLoC
rabbitizer
rabbitizer (whole name is lowercase) is a MIPS instruction decoder API.
Quick example
use rabbitizer::{Instruction, Vram, InstructionFlags, InstructionDisplayFlags};
use rabbitizer::isa::IsaVersion;
use rabbitizer::opcodes::Opcode;
let vram = Vram::new(0x80000000);
let flags = InstructionFlags::new(IsaVersion::MIPS_I);
// The instruction word to be decoded.
let word = 0x3C088001;
// Decode the instruction.
let instr = Instruction::new(word, vram, flags);
// Check the decoded instruction.
assert_eq!(instr.opcode(), Opcode::core_lui);
// Produce an assemblable representation.
// `InstructionDisplayFlags` allows to configure the generated representation.
let display_flags = InstructionDisplayFlags::new();
let display = instr.display::<&str>(&display_flags, None, 0);
assert_eq!(
&display.to_string(),
"lui $t0, 0x8001"
);
Check the documentation at crates.io.
Features
- Able to produce an assembly representation of the decoded words that assembles back to the original data. This is known as matching disassembly.
- Fully written in Rust.
- Written with
no_std
and "no alloc". const
decoding. It is possible to decode MIPS instructions at compile time.
- Written with
- Simple per-word instruction decoding.
- The library doesn't try to be too smart by processing multiple instructions at a time, neither trying to handle endianness.
- Can perform validation checks for decoded instructions.
- For example, it can check if a given instruction has garbage data on bits where the it should contain zeroes.
- 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.
- i.e. Check for
.does_link()
instead of checking forjal
,jalr
,bal
bltzal
, etc.
- i.e. Check for
- Configurable, many features can be turned on and off.
- MIPS instructions features:
- Support for ABI register names: o32, n32, o64, n64, eabi32 and eabi64.
- You can also turn off ABI names and use numeric names for registers if preferred.
- Configurable behavior for the
jalr
instruction, allowing to disassemble the 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.
- Pseudo-instruction detection can be turned off per pseudo.
- Support for ABI register names: o32, n32, o64, n64, eabi32 and eabi64.
- Some workarounds for some specific compilers/assemblers:
SN64
:div
/divu
fix: tweaks a bit the produceddiv
,divu
andbreak
instructions.gccee
: Many workarounds for R5900EE specific instructions to support the differences between the original toolchain and modern gas.
- Multiple MIPS ISAs versions and ISA extensions are supported:
- MIPS I, II and III ISAs.
- Partial support for MIPS IV too.
- N64 RSP instruction support.
- RSP decoding has been tested to build back to matching assemblies with armips.
- R3000 GTE (PSX's CPU) support.
- R4000 ALLEGREX (PSP's CPU) support.
- R5900 EE (PS2's Emotion Engine processor) support.
- Which ISA version/extension pair is used to decode an instruction can be selected at runtime.
- ISAs are "feature gated", so you can only pay for what you use. See Crate features for more info.
- MIPS I, II and III ISAs.
Planned features
- Bindings for other programming languages, so you can unleash rabbitizer's
power on your prefered language.
- Python bindings
- C bindings.
- C++ bindings
Non-features
In order to keep it simple the following features will never be supported:
- Pseudo-instructions which expands to more than one instruction.
Minimum Supported Rust Version (MSRV)
The current version of rabbitizer requires Rust 1.82.0 or greater.
The current policy is that this may be bumped in minor rabbitizer updates.
Installation
rabbitizer is available on crates.io and can be included in your Cargo enabled project like this:
[dependencies]
rabbitizer = "2.0.0-alpha.1"
Crate features
There are a few compilation features. Currently none of them are enabled by default.
- ISA versions:
MIPS_II
: Enables support for MIPS II instructions.MIPS_III
: Enables support for MIPS III instructions.- Enables the
MIPS_II
feature.
- Enables the
MIPS_IV
: Enables support for MIPS IV instructions.- Enables the
MIPS_III
feature.
- Enables the
- ISA extensions:
RSP
: Enables support for the RSP extension set.- Enables the
MIPS_III
feature.
- Enables the
R3000GTE
: Enables support for the R3000GTE extension set.R4000ALLEGREX
: Enables support for the R4000ALLEGREX extension set.- Enables the
MIPS_III
feature.
- Enables the
R5900EE
: Enables support for the R5900EE extension set.- Enables the
MIPS_IV
feature.
- Enables the
RspViceMsp
: Enables support for the Vice Msp extension set, which is an extension for the RSP instruction set.- Enables the
RSP
feature.
- Enables the
- Blanket featues:
all_extensions
: Enables all common extensions. Currently enablesRSP
,R3000GTE
,R4000ALLEGREX
andR5900EE
features.all_gated_extensions
: Enables gated extensions. Currently enablesall_extensions
andRspViceMsp
features.
- Misc:
std
: Turns onstd
(or turn offno_std
, depending on how you prefer it). This currently doesn't do much besides internally usingstd::error
instead ofcore::error
, which may lower the MSRV.bindings_c
: Expose C bindings. NOT WORKING YET.pyo3
: Expose Python3 bindings. NOT WORKING YET.- Enables the
std
,all_extensions
andall_gated_extensions
features. - It also enables the
pyo3
dependency.
- Enables the
Dependencies
~74–780KB
~16K SLoC