Scripting ZeroBugs with Python

The ZeroBugs debugger allows you to automate debugging tasks using the Python programming language. If you have a build of ZeroBugs that includes the zpython.so plug-in (the Python Gate) then you may specify a script with the command line option --py-run=path to your script.

The python plugin is unloaded if no script is specified in the command line.

As of September 2^nd all builds on the download page include the Python Gate.

"Standard" Debugger Callbacks

The debugger engine broadcasts notifications to the plug-ins. The Python Gate plug-in receives these like any other plug-in, and exposes them to user-written Python scripts. It looks up the user script for a number of functions with predefined names. If found, these functions are invoked when the events they correspond to occur. See example.

These functions are:

• on_init(debugger)
  Called once when the Python plugin starts up. It is safe to assume that when this callback is invoked, all the plugins have been properly initialized.
• on_process(process, thread)
  Called when the debugger attaches to a new process (either by starting it, attaching to an already running process; process in this context also applies to loading a core file and accessing information about the crashed process).
• on_thread(thread)
  Called when the debugger attaches to a new thread
• on_process_detach(process)
  Called when detaching from the debugged target. The process object may be null, so it is recommended to test for null before using it.
• on_thread_detach(thread)
• on_event(event)
  A debugging event occurred. event.type() gives the exact cause, which may be one of:
  • Update -- a notification for the script to update any internal state
  • Signal
  • Breakpoint
  • SysCallEnter -- only received if debugger.set_option(zero.Debugger.Option.TraceSysCalls) is called. See example
  • SysCallLeave -- ditto
  • SingleStep
  • DoneStepping
  • CallReturned -- debuggee returned from function after thread.step(zero.Step.Return)
  NOTE: on_event is not called for scripted breakpoints (i.e. a breakpoint that has a corresponding callback function in the Python script). When such a breakpoint is hit, control is passed directly to the callback function without going through the on_event notification.
• on_progress(message, percentage)
  Called as a notification that a lengthy operation is in progress. Return false to cancel.

Accessing the Debugger Instance

The debugger instance can be accessed from either the Process and Thread objects like so:

process.debugger()
thread.debugger()

Examples

I hope to put some more format documentation together soon, meanwhile please refer to these examples.

1. Standard Callbacks
2. Stack Traces
3. Breakpoints
4. Breakpoints, Stack Traces, CPU Registers
5. Stepping Through Code
6. Monitoring System Calls
7. Zero, Python and GTK
8. Expression Evaluation and Function Invocation

You need to get the glade file and glade project in order to run the Gtk example.

The source code for a more sophisticated Gtk project that wants to replace the current GUI with a lightweight Python implementation can be browsed here and downloaded from here.

This example illustrates how to augment the command line interface. This script attempts to implement the Debugger Machine Interface (work in progress).

Classes

I have generated the documentation for the ZeroBUGS classes and functions that can be used from Python scripts, with the following script:

import zero
import pydoc
import sys

def on_init(debugger):
	f = open("zero.html", "w")
	f.write("")
	doc = pydoc.HTMLDoc()
	f.write(doc.docmodule(zero))
	f.write("")
	f.close()
	sys.exit(0)

I ran the debugger invoking the script, like this:

zero --py-run=gendoc.py