ragweed 0.2.3-java → 0.2.4-java

data/README.rdoc

@@ -4,21 +4,20 @@
 
 == DESCRIPTION:
 
-* Ragweed is a set of scriptable debugging tools written mostly in native ruby.
+* Ragweed is a set of scriptable debugging tools written in native ruby.
 
-* Where required the Ruby/DL and Win32API libraries are used to interface the machine
+* Where required the FFI and Win32API libraries are used to interface the machine
   and OS native system calls.
 
+* There are no third party dependencies
+
 == Supported Platforms
 
 Ragweed is supported and has been tested on the following platforms (32bit intel only):
 
-  Windows 7
-  Windows XP
-  Linux Ubuntu 10.4
-  Linux Ubuntu 9.10
-  Mac OS X 10.6
-  Mac OS X 10.5
+  Windows XP, 7
+  Linux Ubuntu 9.04 -> 11.04
+  Mac OS X 10.5, 10.6
 
 Ragweed works with Ruby 1.8.7, 1.9.1 and 1.9.2 and should work with any Ruby that includes FFI support on 32bit WinXP, Win7, Linux 2.6 and OSX 10.6.
 We are actively investigating 64 bit support for each platform. Unfortunately, this will require significant changes to Ragweed.
@@ -48,7 +47,8 @@ Please see the examples directory for more. There are hit tracers for each platf
 == INSTALL:
 
   sudo gem install ragweed
-  # relax with a tasty beverage, you're done
+
+  # yep, thats it. you're done.
 
 == LICENSE:
 

data/VERSION

@@ -1 +1 @@
-0.2.3
+0.2.4

data/examples/hittracerx.rb

@@ -4,7 +4,8 @@
 # FILE is CSV file,address
 # PID is the proces id to attach to.
 
-require 'debuggerosx'
+require 'rubygems'
+require 'ragweed'
 require 'pp'
 require 'irb'
 include Ragweed
@@ -12,10 +13,18 @@ include Ragweed
 filename = ARGV[0]
 pid = ARGV[1].to_i
 
-raise "hittracerosx.rb FILE PID" if (ARGV.size < 2 or pid <= 0)
+raise "hittracerx.rb FILE PID" if (ARGV.size < 2 or pid <= 0)
+
+class HitTracer < Ragweed::Debuggerosx
+  attr_accessor :counts
+  
+  def initialize(*args)
+    @counts = Hash.new(0)
+    super
+  end
 
-class Debuggerosx
   def on_exit
+    pp @counts
     exit(1)
   end
 
@@ -25,39 +34,51 @@ class Debuggerosx
   def on_segv(thread)
     pp self.get_registers(thread)
     pp self.threads
-    self.threads.each {|thread| puts Wraposx::ThreadContext.get(thread).dump}
-    self.threads.each {|thread| puts Wraposx::ThreadInfo.get(thread).dump}
+    self.threads.each {|thread| puts self.get_registers(thread).dump}
+    self.threads.each {|thread| puts Ragweed::Wraposx::thread_info(thread, Ragweed::Wraposx::ThreadInfo::BASIC_INFO).dump}
     throw(:break)
   end
     
   def on_bus(thread)
+    puts "BUS!"
     throw(:break)
   end
 end
 
-d = Debuggerosx.new(pid)
+d = HitTracer.new(pid)
 d.attach
 
+puts "attached"
+
 File.open(filename, "r") do |fd|
-  lines = fd.readlines
-  lines.map {|x| x.chomp}
-  lines.each do |tl|
-    fn, addr = tl.split(",", 2)
-    d.breakpoint_set(addr.to_i(16), fn, (bpl = lambda do | t, r, s | puts "#{ s.breakpoints[r.eip].first.function } hit in thread #{ t }\n"; end))
+  fd.each_line do |tl|
+    fn, addr = tl.split(",", 2).map{|x| x.strip}
+    pp [fn, addr.to_i(16).to_s(16)]
+    d.breakpoint_set(addr.to_i(16), fn, (bpl = lambda do | tid, regs, slf |
+        puts "#{ slf.breakpoints[regs.eip].first.function } hit in thread #{ tid }\n"
+        d.counts[slf.breakpoints[regs.eip].first.function] += 1
+      end))
   end
 end
 
+puts "breakpoints loaded"
+
 d.install_bps
+puts "breakpoints installed"
 d.continue
-catch(:throw) { d.loop }
+puts "continued"
+catch(:throw) { d.loop(nil) }
+puts 'thrown'
 pp d.wait 1
 pp d.threads
 
-d.threads.each do |t|
-  r = Wraposx::ThreadContext.get(t)
-  i = Wraposx::ThreadInfo.get(t)
+d.threads.each do |tid|
+  r = d.get_registers(tid)
+  i = Wraposx::thread_info(tid, Wraposx::ThreadInfo::BASIC_INFO)
   pp r
   puts r.dump
   pp i
   puts i.dump
 end
+
+

data/lib/ragweed/debugger32.rb

@@ -12,14 +12,14 @@ require ::File.join(::File.dirname(__FILE__),'wrap32')
 class Ragweed::Debugger32
   include Ragweed
 
-  ## This will preserve the last event seen, but as read only
-  ## useful if you want to pass around the ragweed object after
-  ## an event has occured (post-mortem crash analysis)
+  # This will preserve the last event seen, but as read only
+  # useful if you want to pass around the ragweed object after
+  # an event has occured (post-mortem crash analysis)
   attr_reader :event
 
-  ## Breakpoint class. Handles the actual setting,
-  ## removal and triggers for breakpoints.
-  ## no user servicable parts.
+  # Breakpoint class. Handles the actual setting,
+  # removal and triggers for breakpoints.
+  # no user servicable parts.
   class Breakpoint
 
     INT3 = 0xCC
@@ -64,9 +64,9 @@ class Ragweed::Debugger32
     end
 
     def call(*args); @callable.call(*args); end    
-  end ## End Breakpoint class
+  end # End Breakpoint class
 
-  ## Get a handle to the process so you can mess with it.
+  # Get a handle to the process so you can mess with it.
   def process; @p; end
   
   def self.find_by_regex(rx)
@@ -79,7 +79,7 @@ class Ragweed::Debugger32
   end
 
   def initialize(p)
-    ## grab debug privilege at least once
+    # grab debug privilege at least once
     @@token ||= Ragweed::Wrap32::ProcessToken.new.grant('seDebugPrivilege')
 
     p = Process.new(p) if p.kind_of? Numeric
@@ -96,10 +96,10 @@ class Ragweed::Debugger32
     @ntdll_dbg_break_point = @p.get_proc_remote('ntdll!DbgBreakPoint')
   end
 
-  ## single-step the thread (by TID). "callable" is something that honors
-  ## .call, like a Proc. In a dubious design decision: the "handle" to the
-  ## single stepper is the Proc object itself. See Debugger#on_breakpoint
-  ## for an example of how to use this.
+  # single-step the thread (by TID). "callable" is something that honors
+  # .call, like a Proc. In a dubious design decision: the "handle" to the
+  # single stepper is the Proc object itself. See Debugger#on_breakpoint
+  # for an example of how to use this.
   def step(tid, callable)
     if @steppers.empty?
       Ragweed::Wrap32::open_thread(tid) do |h|
@@ -111,9 +111,9 @@ class Ragweed::Debugger32
     @steppers << callable    
   end
 
-  ## turn off single-stepping for one callable (you can have more than one
-  ## at a time). In other words, when you pass a Proc to Debugger#step, save
-  ## it somewhere, and later pass it to "unstep" to turn it off. 
+  # turn off single-stepping for one callable (you can have more than one
+  # at a time). In other words, when you pass a Proc to Debugger#step, save
+  # it somewhere, and later pass it to "unstep" to turn it off. 
   def unstep(tid, callable)
     @steppers = @steppers.reject {|x| x == callable}
     if @steppers.empty?
@@ -125,7 +125,7 @@ class Ragweed::Debugger32
     end
   end
 
-  ## convenience: either from a TID or a BreakpointEvent, get the thread context.
+  # convenience: either from a TID or a BreakpointEvent, get the thread context.
   def context(tid_or_event)
     if not tid_or_event.kind_of? Numeric
       tid = tid_or_event.tid
@@ -135,16 +135,16 @@ class Ragweed::Debugger32
     Ragweed::Wrap32::open_thread(tid) { |h| Ragweed::Wrap32::get_thread_context(h) }
   end
 
-  ## set a breakpoint given an address, which can also be a string in the form
-  ## "module!function", as in, "user32!SendMessageW". Be aware that the symbol
-  ## lookup takes place in an injected thread; it's safer to use literal addresses
-  ## when possible.
+  # set a breakpoint given an address, which can also be a string in the form
+  # "module!function", as in, "user32!SendMessageW". Be aware that the symbol
+  # lookup takes place in an injected thread; it's safer to use literal addresses
+  # when possible.
   #
-  ## to handle the breakpoint, pass a block to this method, which will be called
-  ## when the breakpoint hits.
+  # to handle the breakpoint, pass a block to this method, which will be called
+  # when the breakpoint hits.
   #
-  ## breakpoints are always re-set after firing. If you don't want them to be
-  ## re-set, unset them manually.
+  # breakpoints are always re-set after firing. If you don't want them to be
+  # re-set, unset them manually.
   def breakpoint_set(ip, callable=nil, &block)
     if not callable and block_given?
       callable = block
@@ -152,7 +152,7 @@ class Ragweed::Debugger32
 
     def_status = false
 
-    ## This is usually 'Module!Function' or 'Module!0x1234'
+    # This is usually 'Module!Function' or 'Module!0x1234'
     if @p.is_breakpoint_deferred(ip) == true
         def_status = true
     else
@@ -160,23 +160,23 @@ class Ragweed::Debugger32
         ip = @p.get_proc_remote(ip)
     end
 
-    ## If we cant immediately set the breakpoint
-    ## mark it as deferred and wait till later
-    ## Sometimes *_proc_remote() will return the
-    ## name indicating failure (just in case)
+    # If we cant immediately set the breakpoint
+    # mark it as deferred and wait till later
+    # Sometimes *_proc_remote() will return the
+    # name indicating failure (just in case)
     if ip == 0 or ip == 0xFFFFFFFF or ip.kind_of? String
       def_status = true
     else
       def_status = false
     end
 
-    ## Dont want duplicate breakpoint objects
+    # Dont want duplicate breakpoint objects
     @breakpoints.each_key { |k| if k == ip then return end }
     bp = Breakpoint.new(@p, ip, def_status, callable)
     @breakpoints[ip] = bp
   end
 
-  ## Clear a breakpoint by ip
+  # Clear a breakpoint by ip
   def breakpoint_clear(ip)
     bp = @breakpoints[ip]
 
@@ -188,8 +188,8 @@ class Ragweed::Debugger32
     @breakpoints.delete(ip)
   end 
   
-  ## handle a breakpoint event:
-  ## call handlers for the breakpoint, step past and reset it.
+  # handle a breakpoint event:
+  # call handlers for the breakpoint, step past and reset it.
   def on_breakpoint(ev)
       ctx = context(ev)
       eip = ev.exception_address
@@ -200,34 +200,34 @@ class Ragweed::Debugger32
 
       @breakpoints[eip].uninstall
 
-      ## Call the block passed to breakpoint_set
-      ## which may have been passed through hook()
+      # Call the block passed to breakpoint_set
+      # which may have been passed through hook()
       @breakpoints[eip].call(ev, ctx)
 
-      ## single step past the instruction...
+      # single step past the instruction...
       step(ev.tid, (onestep = lambda do |ev, ctx|
         if ev.exception_address != eip
-          ## ... then re-install the breakpoint ...
+          # ... then re-install the breakpoint ...
           if not @breakpoints[eip].nil?
             @breakpoints[eip].install
           end
-          ## ... and stop single-stepping.
+          # ... and stop single-stepping.
           unstep(ev.tid, onestep)
         end
       end))
 
-      ## Put execution back where it's supposed to be...
+      # Put execution back where it's supposed to be...
       Ragweed::Wrap32::open_thread(ev.tid) do |h|
         ctx = context(ev)
         ctx.eip = eip ## eip was ev.exception_address
         Ragweed::Wrap32::set_thread_context(h, ctx)
       end
   
-    ## Tell the target to stop handling this event
+    # Tell the target to stop handling this event
     @handled = Ragweed::Wrap32::ContinueCodes::CONTINUE
   end
 
-  ## FIX: this method should be a bit more descriptive in its naming
+  # FIX: this method should be a bit more descriptive in its naming
   def get_dll_name(ev)
     name = Ragweed::Wrap32::get_mapped_filename(@p.handle, ev.base_of_dll, 256)
     name.gsub!(/[\n]+/,'')
@@ -264,7 +264,7 @@ class Ragweed::Debugger32
     end
   end
 
-  ## handle a single-step event  
+  # handle a single-step event  
   def on_single_step(ev)
     ctx = context(ev)
     Ragweed::Wrap32::open_thread(ev.tid) do |h|
@@ -279,36 +279,54 @@ class Ragweed::Debugger32
     @handled = Ragweed::Wrap32::ContinueCodes::CONTINUE
   end
 
-  ## This is sort of insane but most of my programs are just
-  ## debug loops, so if you don't do this, they just hang when
-  ## the target closes.
+  # This is sort of insane but most of my programs are just
+  # debug loops, so if you don't do this, they just hang when
+  # the target closes.
   def on_exit_process(ev)
     exit(1)
   end
 
-  ## TODO: Implement each of these
+  # @abstract
   def on_create_process(ev)       end
+  # @abstract
   def on_create_thread(ev)        end
+  # @abstract
   def on_exit_thread(ev)          end
+  # @abstract
   def on_output_debug_string(ev)  end
+  # @abstract
   def on_rip(ev)                  end
+  # @abstract
   def on_unload_dll(ev)           end
+  # @abstract
   def on_guard_page(ev)           end
+  # @abstract
   def on_alignment(ev)            end
+  # @abstract
   def on_bounds(ev)               end
+  # @abstract
   def on_divide_by_zero(ev)       end
+  # @abstract
   def on_int_overflow(ev)         end
+  # @abstract
   def on_invalid_handle(ev)       end
+  # @abstract
   def on_illegal_instruction(ev)  end
+  # @abstract
   def on_priv_instruction(ev)     end
+  # @abstract
   def on_stack_overflow(ev)       end
+  # @abstract
   def on_heap_corruption(ev)      end
+  # @abstract
   def on_buffer_overrun(ev)       end
+  # @abstract
   def on_invalid_disposition(ev)  end
+  # @abstract
   def on_attach()                 end
 
-  ## Read through me to see all the random events
-  ## you can hook in a subclass.
+  # Read through me to see all the random events
+  # you can hook in a subclass.
   def wait
     self.attach() if not @attached
 
@@ -370,15 +388,15 @@ class Ragweed::Debugger32
     @handled = Ragweed::Wrap32::ContinueCodes::UNHANDLED
   end
 
-  ## Debug loop
+  # Debug loop
   def loop
     while true
       wait
     end
   end
   
-  ## This is called implicitly by Debugger#wait.
-  ## Attaches to the child process for debugging
+  # This is called implicitly by Debugger#wait.
+  # Attaches to the child process for debugging
   def attach
     Ragweed::Wrap32::debug_active_process(@p.pid)
     Ragweed::Wrap32::debug_set_process_kill_on_exit
@@ -389,7 +407,7 @@ class Ragweed::Debugger32
     end
   end
 
-  ## Let go of the target.
+  # Let go of the target.
   def release
     Ragweed::Wrap32::debug_active_process_stop(@p.pid)
     @attached = false

data/lib/ragweed/debuggerosx.rb

@@ -21,7 +21,6 @@ class Ragweed::Debuggerosx
   attr_accessor :breakpoints
 
   class Breakpoint
-    #    include Ragweed::Wraposx
     INT3 = 0xCC
     attr_accessor :orig
     attr_accessor :bpid
@@ -70,14 +69,14 @@ class Ragweed::Debuggerosx
     def method_missing(meth, *args); @bp.send(meth, *args); end
   end
 
-  #init object
-  #p: pid of process to be debugged
-  #opts: default options for automatically doing things (attach, install, and hook)
+  # init object
+  # p: pid of process to be debugged
+  # opts: default options for automatically doing things (attach, install, and hook)
   def initialize(p,opts={})
     if p.kind_of? Numeric
       @pid = p
     else
-      #coming soon: find process by name
+      # coming soon: find process by name
       raise "Provide a PID"
     end
     @opts = opts
@@ -97,8 +96,11 @@ class Ragweed::Debuggerosx
     @opts.each {|k, v| try(k) if v}
   end
 
-  #loop calls to wait
-  #times: number of times to loop
+  # loop calls to wait.
+  # This is the main mode this class will be used at runtime.
+  # First, install the desired breakpoints. Then, run loop().
+  # 
+  # times: number of times to loop
   #       if nil this will loop until @exited is set
   def loop(times=nil)
     if times.kind_of? Numeric
@@ -111,6 +113,7 @@ class Ragweed::Debuggerosx
   end
 
   # wait for process and run callback on return then continue child
+  # This is usually called by loop()
   # FIXME - need to do signal handling better (loop through threads only for breakpoints and stepping)
   # opts: option flags to waitpid(2)
   #
@@ -165,27 +168,38 @@ class Ragweed::Debuggerosx
   end
 
   # these event functions are stubs. Implementations should override these
+
+  # Fired when attaching to the child process succeeds.
   def on_attach
   end
 
+  # Fired when detaching from the child process succeeds.
   def on_detach
   end
 
+  # Fired when single stepping at every step
+  # Not currently used in OSX
   def on_single_step
-    #puts Ragweed::Wraposx::ThreadInfo.get(thread).inspect
   end
 
+  # Called with the child process's status on exit
+  # Implementations overriding this function should either set @exited to true or call super.
   def on_exit(status)
     @exited = true
   end
 
+  # Called with the signal used to exit kill the child process
+  # Implementations overriding this function should either set @exited to true or call super.
   def on_signal(signal)
     @exited = true
   end
 
+  # Called when the child process is stopped with the signal used.
   def on_stop(signal)
   end
 
+  # Called when the child process is continued.
+  # If used by an implementation, this will be a very noisy function.
   def on_continue
   end
 
@@ -235,16 +249,19 @@ class Ragweed::Debuggerosx
   # get task port for @pid and store in @task so mach calls can be made
   # opts is a hash for automatically firing other functions as an overide for @opts
   # returns the task port for @pid
+  # @deprecated - This function will change to attach_mach and instead become similar to the Debugger32#hook function used for tracing the entry and exit of functions in the child.
   def hook(opts=@opts)
     @task = Ragweed::Wraposx::task_for_pid(@pid)
     @hooked = true
     self.attach(opts) if opts[:attach] and not @attached
     return @task
   end
+  alias attach_mach hook
 
   # theoretically to close the task port but,
   # no way to close the port has yet been found.
   # This function currently does little/nothing.
+  # @deprecated - This will be removed at some point.
   def unhook(opts=@opts)
     self.detach(opts) if opts[:attach] and @attached
     self.unintsall_bps if opts[:install] and @installed
@@ -253,14 +270,14 @@ class Ragweed::Debuggerosx
   # resumes thread that has been suspended via thread_suspend
   # thread: thread id of thread to be resumed
   def resume(thread = nil)
-    thread ||= self.threads.first)
+    thread ||= self.threads.first
     Ragweed::Wraposx::thread_resume(thread)
   end
 
-  # suspends thread
-  # thread: thread id of thread to be suspended
+  # suspends thread (increments the suspend count)
+  # thread: thread id of thread to be suspended defaults to first thread
   def suspend(thread = nil)
-    thread ||= self.threads.first)
+    thread ||= self.threads.first
     Ragweed::Wraposx::thread_suspend(thread)
   end
 
@@ -310,24 +327,24 @@ class Ragweed::Debuggerosx
   # thread: id of the thread stopped at a breakpoint
   def on_breakpoint(thread)
     r = self.get_registers(thread)
-    #rewind eip to correct position
+    # rewind eip to correct position
     r.eip -= 1
-    #don't use r.eip since it may be changed by breakpoint callback
+    # don't use r.eip since it may be changed by breakpoint callback
     eip = r.eip
-    #clear stuff set by INT3
-    #r.esp -=4
-    #r.ebp = r.esp
-    #fire callback
+    # clear stuff set by INT3
+    # r.esp -=4
+    # r.ebp = r.esp
+    # fire callback
     @breakpoints[eip].call(thread, r, self)
     if @breakpoints[eip].first.installed?
-      #uninstall breakpoint to continue past it
+      # uninstall breakpoint to continue past it
       @breakpoints[eip].first.uninstall
-      #set trap flag so we don't go too far before reinserting breakpoint
+      # set trap flag so we don't go too far before reinserting breakpoint
       r.eflags |= Ragweed::Wraposx::EFlags::TRAP
-      #set registers to commit eip and eflags changes
+      # set registers to commit eip and eflags changes
       self.set_registers(thread, r)
 
-      #step once
+      # step once
       self.stepp
 
       # now we wait() to prevent a race condition that'll SIGBUS us
@@ -335,7 +352,7 @@ class Ragweed::Debuggerosx
       # instruction before the parent completes many
       Ragweed::Wraposx::waitpid(@pid,0)
 
-      #reset breakpoint
+      # reset the breakpoint
       @breakpoints[eip].first.install
     end
   end
@@ -359,7 +376,7 @@ class Ragweed::Debuggerosx
   # returns a Ragweed::Wraposx::ThreadContext object containing the register states
   # thread: thread to get the register state of
   def get_registers(thread=nil)
-    thread ||= self.threads.first)
+    thread ||= self.threads.first
     Ragweed::Wraposx.thread_get_state(thread, Ragweed::Wraposx::ThreadContext::X86_THREAD_STATE)
   end
 
@@ -400,6 +417,10 @@ class Ragweed::Debuggerosx
   def attached?; @attached; end
   def installed?; @installed; end
 
+  # returns information about a memory region
+  # addr: address contained in the memory region - usually the start address
+  # flavor: type of information to retrieve. May be specified as either symbol [:basic, :extended, :top] or by integer flavor id.
+  #   Currently, only the basic flavor is supported by Apple.
   def region_info(addr, flavor = :basic)
     flav = case flavor
     when :basic
@@ -425,7 +446,9 @@ class Ragweed::Debuggerosx
   end
 
   # XXX watch this space for an object to hold this information
-  # Return a range via mapping name
+  # Get memory ranges by mapping name
+  # name: name of memory range to search for
+  # exact: if true require an exact match, otherwise use regex
   def get_mapping_by_name name, exact = true
     ret = []
     IO.popen("vmmap -interleaved #{@pid}") do |pipe|