crabstone 3.0.3 → 4.0.0

data/lib/crabstone/binding/4/instruction.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# THIS FILE WAS AUTO-GENERATED -- DO NOT EDIT!
+
+require 'ffi'
+
+require_relative 'detail'
+
+module Crabstone
+  module Binding
+    class Instruction < FFI::ManagedStruct
+      layout(
+        :id, :uint32,
+        :address, :uint64,
+        :size, :uint16,
+        :bytes, [:uint8, 16],
+        :mnemonic, [:char, 32],
+        :op_str, [:char, 160],
+        :detail, Detail.by_ref
+      )
+    end
+  end
+end

data/lib/crabstone/binding/structs.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+require 'crabstone/cs_version'
+Crabstone.version_require 'crabstone/binding/%v/instruction'
+
+module Crabstone
+  module Binding
+    # This is because JRuby FFI on x64 Windows thinks size_t is 32 bit
+    typedef(FFI::Platform::ADDRESS_SIZE == 32 ? :ulong : :ulong_long, :size_t)
+
+    # If one day these definitions change, move them to <version>/ dir.
+
+    typedef :size_t, :csh
+    typedef :size_t, :cs_opt_value
+    typedef :uint, :cs_opt_type
+    typedef :uint, :cs_err
+    typedef :uint, :cs_arch
+    typedef :uint, :cs_mode
+
+    callback :skipdata_cb, %i[pointer size_t size_t pointer], :size_t
+
+    class SkipdataConfig < FFI::Struct
+      layout(
+        :mnemonic, :pointer,
+        :callback, :skipdata_cb,
+        :unused, :pointer
+      )
+    end
+  end
+end

data/lib/crabstone/constants.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# XXX: Auto-gerneate this file?
+# Constants in this file might be added in a newer Capstone version,
+# but I expect they are always backward compatible.
+
+require 'crabstone/version'
+
+module Crabstone
+  # API version
+  BINDING_MAJ = VERSION.split('.').first.to_i
+
+  # architectures
+  ARCH_ARM = 0
+  ARCH_ARM64 = 1
+  ARCH_MIPS = 2
+  ARCH_X86 = 3
+  ARCH_PPC = 4
+  ARCH_SPARC = 5
+  ARCH_SYSZ = 6
+  ARCH_XCORE = 7
+  ARCH_M68K = 8
+  ARCH_TMS320C64X = 9
+  ARCH_M680X = 10
+  ARCH_EVM = 11
+  ARCH_MAX = 12
+  ARCH_ALL = 0xFFFF
+
+  # disasm mode
+  MODE_LITTLE_ENDIAN = 0 # little-endian mode (default mode)
+  MODE_ARM = 0 # 32-bit ARM
+  MODE_16 = 1 << 1 # 16-bit mode (X86)
+  MODE_32 = 1 << 2 # 32-bit mode (X86)
+  MODE_64 = 1 << 3 # 64-bit mode (X86, PPC)
+  MODE_THUMB = 1 << 4 # ARM's Thumb mode, including Thumb-2
+  MODE_MCLASS = 1 << 5 # ARM's Cortex-M series
+  MODE_V8 = 1 << 6 # ARMv8 A32 encodings for ARM
+  MODE_MICRO = 1 << 4 # MicroMips mode (MIPS)
+  MODE_MIPS3 = 1 << 5 # Mips III ISA
+  MODE_MIPS32R6 = 1 << 6 # Mips32r6 ISA
+  MODE_MIPSGP64 = 1 << 7 # General Purpose Registers are 64-bit wide (MIPS)
+  MODE_MODE_MIPS2 = 1 << 7 # Mips II ISA
+  MODE_V9 = 1 << 4 # SparcV9 mode (Sparc)
+  MODE_QPX = 1 << 4 # Quad Processing eXtensions mode (PPC)
+  MODE_M68K_000 = 1 << 1 # M68K 68000 mode
+  MODE_M68K_010 = 1 << 2 # M68K 68010 mode
+  MODE_M68K_020 = 1 << 3 # M68K 68020 mode
+  MODE_M68K_030 = 1 << 4 # M68K 68030 mode
+  MODE_M68K_040 = 1 << 5 # M68K 68040 mode
+  MODE_M68K_060 = 1 << 6 # M68K 68060 mode
+  MODE_BIG_ENDIAN = 1 << 31 # big-endian mode
+  MODE_MIPS32 = MODE_32 # Mips32 ISA (Mips)
+  MODE_MIPS64 = MODE_64 # Mips64 ISA (Mips)
+  MODE_M680X_6301 = 1 << 1 # M680X HD6301/3 mode
+  MODE_M680X_6309 = 1 << 2 # M680X HD6309 mode
+  MODE_M680X_6800 = 1 << 3 # M680X M6800/2 mode
+  MODE_M680X_6801 = 1 << 4 # M680X M6801/3 mode
+  MODE_M680X_6805 = 1 << 5 # M680X M6805 mode
+  MODE_M680X_6808 = 1 << 6 # M680X M68HC08 mode
+  MODE_M680X_6809 = 1 << 7 # M680X M6809 mode
+  MODE_M680X_6811 = 1 << 8 # M680X M68HC11 mode
+  MODE_M680X_CPU12 = 1 << 9 # M680X CPU12 mode
+  MODE_M680X_HCS08 = 1 << 10 # M680X HCS08 mode
+
+  # Capstone option type
+  OPT_SYNTAX = 1 # Intel X86 asm syntax (ARCH_X86 arch)
+  OPT_DETAIL = 2 # Break down instruction structure into details
+  OPT_MODE = 3 # Change engine's mode at run-time
+  OPT_MEM  = 4 # Change engine's mode at run-time
+  OPT_SKIPDATA = 5 # Skip data when disassembling
+  OPT_SKIPDATA_SETUP = 6 # Setup user-defined function for SKIPDATA option
+  OPT_MNEMONIC = 7 # Customize instruction mnemonic
+  OPT_UNSIGNED = 8 # Print immediate in unsigned form
+
+  # Capstone option value
+  OPT_OFF = 0 # Turn OFF an option - default option of OPT_DETAIL
+  OPT_ON = 3 # Turn ON an option (OPT_DETAIL)
+
+  # Common instruction operand types - to be consistent across all architectures.
+  OP_INVALID = 0
+  OP_REG = 1
+  OP_IMM = 2
+  OP_MEM = 3
+  OP_FP = 4
+
+  # Common instruction groups - to be consistent across all architectures.
+  GRP_INVALID = 0 # uninitialized/invalid group.
+  GRP_JUMP = 1 # all jump instructions (conditional+direct+indirect jumps)
+  GRP_CALL = 2 # all call instructions
+  GRP_RET = 3 # all return instructions
+  GRP_INT = 4 # all interrupt instructions (int+syscall)
+  GRP_IRET = 5 # all interrupt return instructions
+  GRP_PRIVILEGE = 6 # all privileged instructions
+
+  # Access types for instruction operands.
+  AC_INVALID = 0 # Invalid/unitialized access type.
+  AC_READ = 1 << 0 # Operand that is read from.
+  AC_WRITE = 1 << 1 # Operand that is written to.
+
+  # Capstone syntax value
+  OPT_SYNTAX_DEFAULT = 0 # Default assembly syntax of all platforms (OPT_SYNTAX)
+  OPT_SYNTAX_INTEL = 1 # Intel X86 asm syntax - default syntax on X86 (OPT_SYNTAX, ARCH_X86)
+  OPT_SYNTAX_ATT = 2 # ATT asm syntax (OPT_SYNTAX, ARCH_X86)
+  OPT_SYNTAX_NOREGNAME = 3 # Asm syntax prints register name with only number - (OPT_SYNTAX, ARCH_PPC, ARCH_ARM)
+  OPT_SYNTAX_MASM = 4 # MASM syntax (CS_OPT_SYNTAX, CS_ARCH_X86)
+
+  # query id for cs_support()
+  SUPPORT_DIET = ARCH_ALL + 1
+  SUPPORT_X86_REDUCE = ARCH_ALL + 2
+end

data/lib/crabstone/cs_version.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+require 'crabstone/version'
+
+module Crabstone
+  module_function
+
+  # Since some constants/structures are different in different Capstone versions,
+  # some scripts in Crabstone use this method to require the version-sensitive Ruby scripts.
+  # @param [String] path_tpl
+  # @return [Boolean]
+  # @example
+  #   version_require 'crabstone/binding/%v/structs'
+  #   # equivalent to "require 'crabstone/binding/4/structs'" if Capstone is version 4.
+  def version_require(path_tpl)
+    version_compatitable!
+    path = path_tpl.gsub('%v', cs_major_version.to_s)
+    require path
+  end
+
+  # Get the major version of capstone library.
+  #
+  # @return [Integer]
+  #   Returns the major version of Capstone.
+  def cs_major_version
+    return @cs_major_version if defined?(@cs_major_version)
+
+    maj = FFI::MemoryPointer.new(:int)
+    min = FFI::MemoryPointer.new(:int)
+    Binding.cs_version(maj, min)
+    @cs_major_version = maj.read_int
+  end
+
+  # Checks the cs_major is less or equal to Crabstone::VERSION.
+  def version_compatitable!
+    @version_compatitable ||=
+      cs_major_version <= Crabstone::VERSION.split('.').first.to_i && cs_major_version >= 3
+  end
+
+  # @private
+  module Binding
+    extend FFI::Library
+    ffi_lib ['capstone', 'libcapstone.so.4', 'libcapstone.so.3']
+
+    attach_function :cs_version, %i[pointer pointer], :uint
+  end
+end

data/lib/crabstone/disassembler.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+require 'crabstone/binding'
+require 'crabstone/error'
+require 'crabstone/instruction'
+require 'crabstone/version'
+
+module Crabstone
+  class Disassembler
+    SYNTAX = {
+      intel: 1,
+      att: 2,
+      no_regname: 3 # for PPC only
+    }.freeze
+
+    DETAIL = {
+      true => 3, # trololol
+      false => 0
+    }.freeze
+
+    SKIPDATA = {
+      true => 3, # trololol
+      false => 0
+    }.freeze
+
+    attr_reader :arch, :mode, :csh, :syntax, :decomposer
+
+    def initialize(arch, mode)
+      maj, min = version
+      raise "FATAL: Crabstone v#{VERSION} doesn't support binding Capstone v#{maj}.#{min}" if maj > BINDING_MAJ
+
+      @arch = arch
+      @mode = mode
+      @p_csh = FFI::MemoryPointer.new(:ulong_long)
+      safe { Binding.cs_open(arch, mode, @p_csh) }
+
+      @csh = @p_csh.read_ulong_long
+    end
+
+    # After you close the engine, don't use it anymore. Can't believe I even
+    # have to write this.
+    #
+    # @return [void]
+    def close
+      safe { Binding.cs_close(@p_csh) }
+    end
+
+    def syntax=(new_stx)
+      Crabstone::Error.raise!(ErrOption) unless SYNTAX[new_stx]
+      set_raw_option(OPT_SYNTAX, SYNTAX[new_stx])
+      @syntax = new_stx
+    end
+
+    # @param [Boolean] new_val
+    def decomposer=(new_val)
+      Crabstone::Error.raise!(ErrOption) unless DETAIL[new_val]
+      set_raw_option(OPT_DETAIL, DETAIL[new_val])
+      @decomposer = new_val
+    end
+
+    def version
+      maj = FFI::MemoryPointer.new(:int)
+      min = FFI::MemoryPointer.new(:int)
+      Binding.cs_version(maj, min)
+      [maj.read_int, min.read_int]
+    end
+
+    def diet?
+      DIET_MODE
+    end
+
+    def errno
+      Binding.cs_errno(@csh)
+    end
+
+    def skipdata(mnemonic = '.byte')
+      cfg = Binding::SkipdataConfig.new
+      cfg[:mnemonic] = FFI::MemoryPointer.from_string(mnemonic.to_s)
+
+      if block_given?
+        cfg[:callback] = FFI::Function.new(
+          :size_t,
+          %i[pointer size_t size_t pointer]
+        ) do |code, sz, offset, _|
+          code = code.read_array_of_uchar(sz).pack('c*')
+          begin
+            Integer(yield(code, offset))
+          rescue StandardError
+            warn "Error in skipdata callback: #{$ERROR_INFO}"
+            # It will go on to crash, but now at least there's more info :)
+          end
+        end
+      end
+
+      set_raw_option(OPT_SKIPDATA_SETUP, cfg.pointer.address)
+      set_raw_option(OPT_SKIPDATA, SKIPDATA[true])
+    end
+
+    def skipdata_off
+      set_raw_option(OPT_SKIPDATA, SKIPDATA[false])
+    end
+
+    def reg_name(regid)
+      Crabstone::Error.raise!(ErrDiet) if DIET_MODE
+      name = Binding.cs_reg_name(csh, regid)
+      Crabstone::Error.raise!(ErrCsh) unless name
+      name
+    end
+
+    # @return [Array<Crabstone::Instruction>]
+    def disasm(code, offset, count = 0)
+      return [] if code.empty?
+
+      insn_ptr   = FFI::MemoryPointer.new(:pointer)
+      insn_count = Binding.cs_disasm(
+        @csh,
+        code,
+        code.bytesize,
+        offset,
+        count,
+        insn_ptr
+      )
+      Crabstone::Error.raise_errno!(errno) if insn_count.zero?
+
+      convert_disasm_result(insn_ptr, insn_count).tap { Binding.free(insn_ptr.read_pointer) }
+    end
+
+    def set_raw_option(opt, val)
+      safe { Binding.cs_option(csh, opt, val) }
+    end
+
+    private
+
+    # Convert the insn_ptr from cs_disasm into Ruby instruction objects.
+    # @param [FFI::MemoryPointer] insn_ptr
+    # @param [Integer] insn_count
+    # @return [Array<Crabstone::Instruction>]
+    def convert_disasm_result(insn_ptr, insn_count)
+      insn_sz = Binding::Instruction.size
+      Array.new(insn_count) do |i|
+        cs_insn_ptr = Binding.malloc(insn_sz)
+        Binding.memcpy(cs_insn_ptr, insn_ptr.read_pointer + i * insn_sz, insn_sz)
+        Crabstone::Instruction.new(@csh, Binding::Instruction.new(cs_insn_ptr), @arch)
+      end
+    end
+
+    def safe
+      yield.tap { |res| Crabstone.raise_errno(res) unless res.zero? }
+    end
+  end
+end

data/lib/crabstone/error.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# XXX: Auto-gerneate this file?
+# Error classes might be added in a newer Capstone version,
+# but this should not be frequent, currently this file is updated manually.
+
+module Crabstone
+  # @private
+  class Error < StandardError; end
+
+  class ErrArch < Error; end
+  class ErrCsh < Error; end
+  class ErrHandle < Error; end
+  class ErrMem < Error; end
+  class ErrMode < Error; end
+  class ErrOK < Error; end
+  class ErrOption < Error; end
+  class ErrDetail < Error; end
+  class ErrMemSetup < Error; end
+  class ErrVersion < Error; end
+  class ErrDiet < Error; end
+  class ErrSkipData < Error; end
+  class ErrX86ATT < Error; end
+  class ErrX86Intel < Error; end
+  class ErrX86MASM < Error; end
+
+  class Error
+    ERRNO = {
+      0 => ErrOK,
+      1 => ErrMem,
+      2 => ErrArch,
+      3 => ErrHandle,
+      4 => ErrCsh,
+      5 => ErrMode,
+      6 => ErrOption,
+      7 => ErrDetail,
+      8 => ErrMemSetup,
+      9 => ErrVersion,
+      10 => ErrDiet,
+      11 => ErrSkipData,
+      12 => ErrX86ATT,
+      13 => ErrX86Intel,
+      14 => ErrX86MASM
+    }.freeze
+
+    def self.raise_errno!(errno)
+      err_klass = ERRNO[errno]
+      raise 'Internal Error: Tried to raise unknown errno' unless err_klass
+
+      err_str = Binding.cs_strerror(errno)
+      raise err_klass, err_str
+    end
+
+    def self.raise!(klass)
+      raise "Invalid error class: #{klass}" unless klass.superclass == self
+
+      raise_errno!(ERRNO.invert[klass])
+    end
+  end
+end

data/lib/crabstone/instruction.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require 'crabstone/arch'
+require 'crabstone/binding'
+require 'crabstone/constants'
+require 'crabstone/error'
+
+module Crabstone
+  class Instruction
+    attr_reader :csh, :raw_insn
+
+    def initialize(csh, insn, arch)
+      @arch_module = Arch.module_of(arch)
+      @csh = csh
+      @raw_insn = insn
+      init_detail(insn[:detail]) if detailed?
+    end
+
+    def name
+      raise_if_diet
+      name = Binding.cs_insn_name(csh, id)
+      Crabstone::Error.raise!(ErrCsh) unless name
+      name
+    end
+
+    def group_name(grp)
+      raise_if_diet
+      name = Binding.cs_group_name(csh, Integer(grp))
+      Crabstone::Error.raise!(ErrCsh) unless name
+      name
+    end
+
+    # It's more informative to raise if CS_DETAIL is off than just return nil
+    def detailed?
+      !@raw_insn[:detail].pointer.null?
+    end
+
+    def detail
+      raise_unless_detailed
+      @detail
+    end
+
+    def regs_read
+      raise_unless_detailed
+      raise_if_diet
+      @regs_read
+    end
+
+    def regs_write
+      raise_unless_detailed
+      raise_if_diet
+      @regs_write
+    end
+
+    def groups
+      raise_unless_detailed
+      raise_if_diet
+      @groups
+    end
+
+    def group?(group_id)
+      raise_unless_detailed
+      raise_if_diet
+      Binding.cs_insn_group(csh, raw_insn, group_id)
+    end
+
+    def reads_reg?(reg)
+      raise_unless_detailed
+      raise_if_diet
+      Binding.cs_reg_read(csh, raw_insn, @arch_module.register(reg))
+    end
+
+    def writes_reg?(reg)
+      raise_unless_detailed
+      raise_if_diet
+      Binding.cs_reg_write(csh, raw_insn, @arch_module.register(reg))
+    end
+
+    # @return [{:regs_read => Array<Integer>, :regs_write => Array<Integer>}]
+    def regs_access
+      raise_unless_detailed
+      raise_if_diet
+
+      # XXX: Becare of if `typedef uint16_t cs_regs[64];` changes
+      regs_read = FFI::MemoryPointer.new(:uint16, 64)
+      regs_read_count = FFI::MemoryPointer.new(:uint8)
+      regs_write = FFI::MemoryPointer.new(:uint16, 64)
+      regs_write_count = FFI::MemoryPointer.new(:uint8)
+      err = Binding.cs_regs_access(csh, raw_insn, regs_read, regs_read_count, regs_write, regs_write_count)
+      Crabstone::Error.raise_errno(err) if err.nonzero?
+      {
+        regs_read: regs_read.read_array_of_short(regs_read_count.read_int8),
+        regs_write: regs_write.read_array_of_short(regs_write_count.read_int8)
+      }
+    end
+
+    def mnemonic
+      raise_if_diet
+      raw_insn[:mnemonic]
+    end
+
+    def op_str
+      raise_if_diet
+      raw_insn[:op_str]
+    end
+
+    def op_count(op_type = nil)
+      raise_unless_detailed
+      if op_type
+        Binding.cs_op_count(csh, raw_insn, op_type)
+      else
+        operands.size
+      end
+    end
+
+    def bytes
+      raw_insn[:bytes].first(raw_insn[:size])
+    end
+
+    # So an Instruction should respond to all the methods in Instruction, and
+    # all the methods in the Arch specific Instruction class. The methods /
+    # members that have special handling for detail mode or diet mode are
+    # handled above. The rest is dynamically dispatched below.
+    def method_missing(meth, *args)
+      if raw_insn.members.include?(meth)
+        # Dispatch to toplevel Instruction class ( this file )
+        raw_insn[meth]
+      else
+        # Nothing else is available without details.
+        unless detailed?
+          raise(
+            NoMethodError,
+            "Either CS_DETAIL is off, or #{self.class} doesn't implement #{meth}"
+          )
+        end
+        # Dispatch to the architecture specific Instruction ( in arch/ )
+        if @arch_insn.respond_to?(meth)
+          @arch_insn.__send__(meth, *args)
+        elsif @arch_insn.members.include?(meth)
+          @arch_insn[meth]
+        else
+          super
+        end
+      end
+    end
+
+    def respond_to_missing?(meth, include_private = true)
+      return true if raw_insn.members.include?(meth)
+      return super unless detailed?
+      return true if @arch_insn.respond_to?(meth)
+      return true if @arch_insn.members.include?(meth)
+
+      super
+    end
+
+    private
+
+    def raise_unless_detailed
+      Crabstone::Error.raise!(ErrDetail) unless detailed?
+    end
+
+    def raise_if_diet
+      Crabstone::Error.raise!(ErrDiet) if DIET_MODE
+    end
+
+    def init_detail(detail)
+      @detail     = detail
+      @arch_insn  = @detail[:arch][arch_field]
+      @regs_read  = @detail[:regs_read].first(@detail[:regs_read_count])
+      @regs_write = @detail[:regs_write].first(@detail[:regs_write_count])
+      @groups     = @detail[:groups].first(@detail[:groups_count])
+    end
+
+    # Find the field name of Architecture.
+    def arch_field
+      klass = @arch_module.const_get(:Instruction)
+      obj = Binding::Architecture.new
+      Binding::Architecture.members.find do |sym|
+        obj[sym].instance_of?(klass)
+      end
+    end
+  end
+end