Hatstone
This is a very simple wrapper around Capstone. Capstone is a library that disassembles binary data in to assembly code. This library, Hatstone, offers a Ruby interface to the Capstone library.
Why a new library?
Crabstone is a different wrapper for Capstone. I've been using Crabstone for quite a while and I really love it. However, I've been running in to problems with libffi, and especially problems on my M1 Mac where I have both the ARM64 installation and x86 installation of Capstone on the same system (via two installations of Homebrew).
This C extension finds the right Capstone library at gem installation time, so you can be assured that if you can install this gem, you can use this gem (hopefully!!)
Installation
Make sure you have Capstone installed. On macOS this is brew install capstone.
Then install this gem via the normal method gem install hatstone.
Note: RISCV support is only available in Capstone version 5 or later.
Example Usage
In this example we'll assemble some simple ARM64 instructions and then use Hatstone to disassemble them.
require "hatstone"
# ARM64 movz instruction
def movz reg, imm
insn = 0b0_10_100101_00_0000000000000000_00000
insn |= (1 << 31) # 64 bit
insn |= (imm << 5) # immediate
insn |= reg # reg
end
# ARM64 ret instruction
def ret xn = 30
insn = 0b1101011_0_0_10_11111_0000_0_0_00000_00000
insn |= (xn << 5)
insn
end
# Assemble some instructions
insns = [
movz(0, 0x2a), # mov X0, 0x2a
ret # ret
].pack("L<L<")
# Now disassemble the instructions with Hatstone
hs = Hatstone.new(Hatstone::ARCH_ARM64, Hatstone::MODE_ARM)
hs.disasm(insns, 0x0).each do |insn|
puts "%#05x %s %s" % [insn.address, insn.mnemonic, insn.op_str]
endAnother example, this time for RISCV64
require 'hatstone'
def lui reg, imm
insn = 0b00000000000000000000_00000_0110111
insn |= (reg << 7) # Set destination register
insn |= (imm & 0xFFFFF) << 12 # Set 20-bit immediate
insn
end
def auipc reg, imm
insn = 0b00000000000000000000_00000_0010111 # auipc base
insn |= (reg << 7) # Set destination register
insn |= (imm & 0xFFFFF) << 12 # Set 20-bit immediate
insn
end
def addi reg, imm
insn = 0b00000000000000000000_00000_0010011 # addi base
insn |= (reg << 7) # Set destination register
insn |= (reg << 15) # Set source register
insn |= (imm & 0xFFF) << 20 # Set 12-bit immediate
insn
end
insns = [
lui(17, 64), # lui a7,64
lui(10, 1), # lui a0,1
auipc(0, 0), # auipc a0,0x0
addi(0, 36), # addi a0,a0,36
].pack("L<*")
hs = Hatstone.new(Hatstone::ARCH_RISCV, Hatstone::MODE_RISCV64)
hs.disasm(insns, 0x0).each do |insn|
puts "%#05x %s %s" % [insn.address, insn.mnemonic, insn.op_str]
end