Opdis 1.3.0

data/LICENSE.README

@@ -0,0 +1,8 @@
+The Opdis Ruby extension is released under the GNU Public License version 3.0,
+distributed in this package as LICENSE.
+
+The intent of this license choice is not to restrict distribution, but for
+compatibility with the distribution terms of opdis and GNU binutils.
+
+Contact community@thoughtgang.org for alternative licensing arrangements if
+the GPLv3 is too restrictive.

data/README

@@ -0,0 +1,101 @@
+				Opdis
+
+A Ruby C extension (and gem) for the opdis library, available from
+	http://freshmeat.net/projects/opdis .
+
+BUILD
+-----
+
+The standard C extension build process is used:
+
+	bash# ruby1.9 extconf.rb
+	bash# make
+
+Note that the Ruby headers must be installed. On Ubuntu, these are in the
+ruby-dev or ruby1.9-dev package.
+
+
+The gem is built using the standard gem build command:
+
+	bash# gem build Opdis.gemspec
+
+
+The top-level Makefile supports each of these builds with the commands
+'make' and 'make gem'.
+
+	bash# make
+	# builds C extension
+	bash# make gem
+	# builds the gem
+
+
+BINUTILS AND SUPPORTED ARCHITECTURES
+------------------------------------
+
+The implementation of binutils (and libopcodes) does not provide a way to 
+determine the supported platforms at compile time, unless the config.h file 
+used to build the binutils package is present.
+
+The extconf.rb file has been modified in order to detect the architectures
+supported by the local copy of binutils, and to allow the user to specify
+which architectures they want supported.
+
+It does this using the following steps:
+
+	1. run objdump -i to get the supported architectures
+	2. each line that matches one of binutils' known architectures is
+           added as a #define to CPPFLAGS
+	3. if no architectures have been found, or if objdump failed to run,
+	   default to the i386 architecture.
+
+The binary used in step 1 can be specified by the user via the --with-objdump
+flag. For example:
+
+	bash# cat /tmp/objdump.sh
+	#/bin/sh
+	echo 'arm'
+	echo 'sparc'
+	echo 'm68k'
+	bash# ruby1.9 extconf.rb --with-objdump=/tmp/objdump.sh
+        checking for init_disassemble_info() in -lopcodes... yes
+        Adding architecture 'arm'
+        Adding architecture 'sparc'
+        Adding architecture 'm68k'
+        creating Makefile
+
+This makes it possible to force compilation of support for specific 
+architectures when there is no working objdump present. Note that libopcodes
+must have been compiled with support for the architectures, or you will get
+runtime errors.
+
+
+EXAMPLES
+
+Extended examples are provided in the 'examples' directory. The following
+code snippets give a brief overview of using the BFD and Opdis extensions
+together.
+
+require 'BFD'
+require 'Opdis'
+
+Bfd::Target.new('/tmp/a.out') do |tgt|
+	Opdis::Disassembler.new do |dis|
+		dis.disasm_entry( tgt ) { |insn| puts insn }
+	end
+end
+
+tgt = Bfd::Target.new('/tmp/a.out')
+tgt.sections.values.each { |s| puts s.name } }
+Opdis::Disassembler.new do |dis|
+	dis.disasm_section( tgt.sections['.text.] ) { |i| puts i }
+end
+
+Opdis::Disassembler.architectures.each { |arch| puts arch }
+
+Opdis::Disassembler.new( arch: 'x86_64_intel' ) do |dis|
+	dis.disassemble( [0x90, 0xCC, 0x90] ) { |insn| puts insn }
+end
+
+Opdis::Disassembler.new( arch: 'x86_intel' ) do |dis|
+	dis.disassemble( "\x90\xCC\x90" ) { |insn| puts insn }
+end

data/examples/array_linear.rb

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# Opdis Example: Array
+# Linear disassembly of array of bytes
+# Copyright 2010 Thoughtgang <http://www.thoughtgang.org>
+
+require 'Opdis'
+
+def disasm_bytes( arch, bytes )
+  Opdis::Disassembler.new( :arch => arch ) do |dis|
+    dis.disassemble( bytes ) { |i| puts i }
+  end
+end
+
+def hex_to_array( bytes )
+  bytes.collect { |b| b.hex }
+end
+
+if __FILE__ == $0
+  raise "Usage: #{$0} ARCH BYTE [BYTE...]" if ARGV.length < 2
+
+  arch = ARGV.shift
+  disasm_bytes( arch, hex_to_array(ARGV) )
+end

data/examples/bfd_entry.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# Opdis Example: BFD Entry Point
+# Control-flow disassembly of a BFD object file from its entry point
+# Copyright 2010 Thoughtgang <http://www.thoughtgang.org>
+
+require 'BFD'
+require 'Opdis'
+
+def disasm_entry( tgt )
+  Opdis::Disassembler.new() do |dis|
+    # NOTE: This will print instructions as they are disassembled
+    #       (i.e. not in order)
+    dis.disasm_entry( tgt ) { |i| puts i }
+  end
+end
+
+if __FILE__ == $0
+  raise "Usage: #{$0} FILE [FILE...]" if ARGV.length == 0
+
+  ARGV.each do |filename| 
+    Bfd::Target.new(filename) { |f| disasm_entry( f ) }
+  end
+
+end

data/examples/bfd_section.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# Opdis Example: BFD Section
+# Linear disassembly of a section in a BFD object file
+# Copyright 2010 Thoughtgang <http://www.thoughtgang.org>
+
+require 'BFD'
+require 'Opdis'
+
+def disasm_section( sec )
+  puts "Section not found in BFD" if not sec
+
+  puts "#{sec.name}:"
+  Opdis::Disassembler.new() do |dis|
+    dis.disasm_section( sec ) { |i| puts "\t#{i}" }
+  end
+end
+
+if __FILE__ == $0
+  raise "Usage: #{$0} FILE SECTION [SECTION...]" if ARGV.length == 0
+
+  Bfd::Target.new(ARGV.shift) do |tgt| 
+    ARGV.each { |name| disasm_section( tgt.sections[name] ) }
+  end
+end

data/examples/bfd_symbol.rb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# Opdis Example: BFD Symbol
+# Disassembly of a BFD object file from named symbols
+# Copyright 2010 Thoughtgang <http://www.thoughtgang.org>
+
+require 'BFD'
+require 'Opdis'
+
+def disasm_symbol( sym )
+  raise "Symbol not found in BFD" if not sym
+  raise "Symbol #{sym.name} has no VMA!" if not sym.value
+
+  puts "#{sym.name}:"
+  Opdis::Disassembler.new() do |dis|
+    # NOTE: This will print instructions as they are disassembled
+    #       i.e. not necessarily in order
+    dis.disasm_symbol( sym ) { |i| puts "\t#{i}" }
+  end
+end
+
+if __FILE__ == $0
+  raise "Usage: #{$0} FILE SYMBOL [SYMBOL...]" if ARGV.length == 0
+
+  Bfd::Target.new(ARGV.shift) do |tgt|
+    ARGV.each { |name| disasm_symbol( tgt.symbols[name] ) }
+  end
+end

data/examples/buf_linear.rb

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+# Opdis Example: String
+# Linear disassembly of string of bytes
+# Copyright 2010 Thoughtgang <http://www.thoughtgang.org>
+
+require 'Opdis'
+
+def disasm_bytes( arch, bytes )
+
+  Opdis::Disassembler.new( :arch => arch ) do |dis|
+    dis.disassemble( bytes ) { |i| puts i }
+  end
+
+end
+
+def hex_to_string( bytes )
+  bytes.collect { |b| b.hex }.pack( 'C' * bytes.length )
+end
+
+if __FILE__ == $0
+  raise "Usage: #{$0} ARCH BYTE [BYTE...]" if ARGV.length < 2
+
+  arch = ARGV.shift
+  disasm_bytes( arch, hex_to_string(ARGV) )
+end

data/examples/decoder.rb

@@ -0,0 +1,45 @@
+#!/usr/bin/env ruby
+# Opdis Example: Decoder
+# Custom Instruction Decoder used in linear disassembly of array of bytes
+# Copyright 2010 Thoughtgang <http://www.thoughtgang.org>
+
+require 'BFD'
+require 'Opdis'
+
+# ----------------------------------------------------------------------
+# Decoder that wraps Generic Decoder. This bypasses the X86Decoder processing.
+class CustomDecoder < Opdis::InstructionDecoder
+
+  def decode(insn, hash)
+    # TODO
+  end
+
+end
+
+# ----------------------------------------------------------------------
+# print an instruction in the standard disasm listing format:
+#       VMA 8_hex_bytes instruction
+def print_insn(insn)
+  hex_str = insn.bytes.collect { |b| "%02X" % b }.join(' ')
+  puts "%08X %-23.23s %s" % [ insn.vma, hex_str, insn.ascii ]
+end
+
+# ----------------------------------------------------------------------
+def disasm_bytes( bytes )
+  # custom decoder to use in disassembler
+  decoder = CustomDecoder.new
+
+  Opdis::Disassembler.new( :insn_decoder => decoder ) do |dis|
+
+    dis.disasm_entry( bytes ) { |i| print_insn(i) }
+
+  end
+end
+
+# ----------------------------------------------------------------------
+if __FILE__ == $0
+  raise "Usage: #{$0} ARCH BYTE [BYTE...]" if ARGV.length < 2
+
+  arch = ARGV.shift
+  disasm_bytes( arch, ARGV.collect { |b| b.hex } )
+end

data/examples/file_linear.rb

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# Copyright 2010 Thoughtgang <http://www.thoughtgang.org>
+# Linear disassembly of a section in a BFD object file
+
+require 'Opdis'
+
+def disasm_file( file, arch, offset, length )
+  if not length
+    file.seek( 0, IO::SEEK_END )
+    length = file.tell - offset
+    file.rewind
+  end
+
+  Opdis::Disassembler.new( :arch => arch ) do |dis|
+    opts = { :vma => offset, :buffer_vma => 0, :length=> length }
+    dis.disassemble( file, opts ) do |i|
+      puts "%08X\t%s" % [i.vma, i.to_s]
+    end
+  end
+end
+
+if __FILE__ == $0
+  raise "Usage: #{$0} FILE ARCH [OFFSET] [LENGTH]" if ARGV.length == 0
+
+  filename = ARGV.shift
+  arch = ARGV.shift
+  offset = ARGV.length > 0 ? ARGV.shift.to_i : 0
+  length = ARGV.length > 0 ? ARGV.shift.to_i : nil
+
+  File.open(filename, 'rb') { |f| disasm_file( f, arch, offset, length ) }
+end

data/examples/libopcodes_options.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# Copyright 2010 Thoughtgang <http://www.thoughtgang.org>
+# Print available libopcodes options to STDOUT
+
+require 'Opdis'
+
+if __FILE__ == $0
+
+  Opdis::Disassembler.options.each { |line| puts line }
+
+end

data/examples/resolver.rb

@@ -0,0 +1,191 @@
+#!/usr/bin/env ruby
+# Opdis Example: Resolver
+# Custom Address Resolver used in control-flow disassembly of BFD entry point
+# Copyright 2010 Thoughtgang <http://www.thoughtgang.org>
+
+require 'BFD'
+require 'Opdis'
+
+# ----------------------------------------------------------------------
+class Opdis::ImmediateOperand
+  # return immediate operand value
+  def resolve( ign )
+    return @vma
+  end
+end
+
+# ----------------------------------------------------------------------
+class Opdis::AddressExpressionOperand
+  # attempt to resolve address expression [if stack-register only]
+  def resolve( vm )
+    # TODO: if base is stack or frame register, return item from vm.stack;
+    # otherwise, return nil (need to be able to deref mem addr for
+    # general addr expressions).
+    return nil
+  end
+end
+
+# ----------------------------------------------------------------------
+class Opdis::AbsoluteAddressOperand
+  # attempt to resolve absolute address [segment reg + addr]
+  def resolve( vm )
+    # TODO: lookup segment register in VM; return reg value + addr
+    return nil
+  end
+end
+
+# ----------------------------------------------------------------------
+class Opdis::RegisterOperand
+  # attempt to resolve register operand
+  def resolve( vm )
+    # TODO: lookup register name in vm.registers and return stored value
+    return nil
+  end
+end
+
+# ----------------------------------------------------------------------
+include Opdis
+class CustomResolver < AddressResolver
+  attr_reader :registers  # reg name -> value
+  attr_reader :stack      # array of pushed values
+  attr_reader :stack_ptr  # index (into @stack) of 'top' of stack
+  attr_reader :frame_ptr  # index (into @stack) of start of frame
+
+  def initialize()
+    @registers = {}
+    @stack = []
+    @stack_ptr = @frame_ptr = nil
+  end
+
+  # return VMA for target operand or nil
+  def resolve(insn)
+    return insn.target ? insn.target.resolve(self) : nil
+  end
+
+  # -- Stack Management --
+  def stack_push( val )
+    @stack.push val
+    @stack_ptr = @stack.length - 1
+  end
+
+  def stack_pop()
+    val = @stack.push
+    @stack_ptr = @stack.length - 1
+    return val
+  end
+
+  def stack_frame()
+    @frame_ptr = @stack_ptr
+  end
+
+  def stack_unframe()
+    @stack_ptr = @frame_ptr
+  end
+
+  def stack_adjust( val )
+    if val < 0 
+      val.abs.times { @stack.push 0 }
+    else
+      val.abs.times { @stack.pop }
+    end
+
+    @stack_ptr = @stack.length - 1
+  end
+
+  # -- Register Management --
+  # -- Instruction Handlers --
+  # call insn
+  def call(insn, ign, ignn)
+    stack_push insn.vma + insn.size
+  end
+
+  # return insn
+  def ret(insn, ign, ignn)
+    stack_pop
+  end
+
+  # push insn
+  def push(ign, op, ignn)
+    # TODO: stack_push op.value
+  end
+
+  # pop insn
+  def pop(ign, op, ignn)
+    val = stack_pop
+    # TODO: if dest is reg, move val to reg, otherwise discard
+  end
+
+  # frame insn
+  def frame(ign, ignn, ignnn)
+    stack_frame
+  end
+
+  # unframe insn
+  def unframe(ign, ignn, ignnn)
+    stack_unframe
+  end
+
+  # load/store insn
+  def lost(ign, src, dest)
+    # TODO: if dest is addr_expr for stack, set stack item to reg.value
+    #       if dest is reg, fill reg with src.value
+  end
+
+  INSN_HANDLERS = [
+    [Instruction::CAT_CFLOW, Instruction::FLG_CALL, :call],
+    [Instruction::CAT_CFLOW, Instruction::FLG_CALLCC, :call],
+    [Instruction::CAT_CFLOW, Instruction::FLG_RET, :ret],
+    [Instruction::CAT_STACK, Instruction::FLG_PUSH, :push],
+    [Instruction::CAT_STACK, Instruction::FLG_POP, :pop],
+    [Instruction::CAT_STACK, Instruction::FLG_FRAME, :frame],
+    [Instruction::CAT_STACK, Instruction::FLG_UNFRAME, :unframe],
+    #[Instruction::CAT_MATH, Instruction::FLG_ADD, :add],
+    #[Instruction::CAT_MATH, Instruction::FLG_SUB, :sub],
+    [Instruction::CAT_LOADSTORE, nil, :lost]
+  ]
+
+  # Modify stack/insn contents based on insn
+  def process(insn)
+    INSN_HANDLERS.each do |hdlr|
+      if insn.category == hdlr[0] && (not hdlr[1] or insn.flags & hdlr[1])
+        # Invoke handler method with instruction and src, dest operands
+        self.send( hdlr[2], insn, insn.src, insn.dest )
+      end
+    end
+  end
+
+end
+
+# ----------------------------------------------------------------------
+# print an instruction in the standard disasm listing format:
+#       VMA 8_hex_bytes instruction
+def print_insn(insn)
+  hex_str = insn.bytes.bytes.collect { |b| "%02X" % b }.join(' ')
+  puts "%08X %-23.23s %s" % [ insn.vma, hex_str, insn.ascii ]
+end
+
+# ----------------------------------------------------------------------
+def disasm_entry( tgt )
+  # custom resolver to use in disassembler
+  vm = CustomResolver.new
+
+  Disassembler.new( :resolver => vm ) do |dis|
+
+    dis.disasm_entry( tgt ) do |insn|
+      # Set register/stack contents based on insn
+      vm.process(insn)
+
+    # Print instructions in order of VMA
+    end.values.sort_by{ |i| i.vma }.each { |i| print_insn(i) }
+  end
+end
+
+# ----------------------------------------------------------------------
+if __FILE__ == $0
+  raise "Usage: #{$0} FILE [FILE...]" if ARGV.length == 0
+
+  ARGV.each do |filename| 
+    Bfd::Target.new(filename) { |f| disasm_entry( f ) }
+  end
+
+end