|[ < ]||[ > ]||[ << ]||[ Up ]||[ >> ]||[Top]||[Contents]||[Index]||[ ? ]|
libjit library provides support routines for breakpoint-based
single-step debugging. It isn't a full debugger, but provides the
infrastructure necessary to support one.
The front end virtual machine is responsible for inserting "potential
breakpoints" into the code when functions are built and compiled. This
is performed using
Mark the current position in func as corresponding to a breakpoint location. When a break occurs, the debugging routines are passed func, data1, and data2 as arguments. By convention, data1 is the type of breakpoint (source line, function entry, function exit, etc).
There are two ways for a front end to receive notification about breakpoints.
The bulk of this chapter describes the
which handles most of the ugly details. In addition, a low-level "debug hook
mechanism" is provided for front ends that wish more control over the
process. The debug hook mechanism is described below, under the
This debugger implementation requires a threading system to work successfully. At least two threads are required, in addition to those of the program being debugged:
jit_debugger_wait_eventto receive notifications of breakpoints and other interesting events.
jit_debugger_step, etc, to control the debug process.
These two threads should be set to "unbreakable" with a call to
jit_debugger_set_breakable. This prevents them from accidentally
stopping at a breakpoint, which would cause a system deadlock.
Other housekeeping threads, such as a finalization thread, should
also be set to "unbreakable" for the same reason.
Events have the following members:
The type of event (see the next table for details).
The thread that the event occurred on.
The function that the breakpoint occurred within.
The data values at the breakpoint. These values are inserted into
the function's code with
The identifier for the breakpoint.
The stack trace corresponding to the location where the breakpoint
occurred. This value is automatically freed upon the next call
jit_debugger_wait_event. If you wish to preserve the
value, then you must call
The following event types are currently supported:
A thread called
jit_debugger_quit, indicating that it wanted the
event thread to terminate.
A thread stopped at a hard breakpoint. That is, a breakpoint defined
by a call to
A thread stopped at a breakpoint that wasn't explicitly defined by
a call to
jit_debugger_add_breakpoint. This typicaly results
from a call to a "step" function like
execution stopped at the next line but there isn't an explicit breakpoint
on that line.
A thread stopped because of a call to
A thread called
of the event is set to the value of
stop_immediately for the call.
A thread called
This function is similar to
jit_insn_mark_breakpoint except that values
in data1 and data2 can be computed at runtime. You can use this
function for example to get address of local variable.
Determine if debugging is possible. i.e. that threading is available and compatible with the debugger's requirements.
Create a new debugger instance and attach it to a JIT context. If the context already has a debugger associated with it, then this function will return the previous debugger.
Destroy a debugger instance.
Get the JIT context that is associated with a debugger instance.
Get the debugger that is currently associated with a JIT context, or NULL if there is no debugger associated with the context.
Get the thread identifier associated with the current thread. The return values are normally values like 1, 2, 3, etc, allowing the user interface to report messages like "thread 3 has stopped at a breakpoint".
Get the thread identifier for a specific native thread. The
native_thread pointer is assumed to point at a block
of memory containing a native thread handle. This would be a
pthread_t on Pthreads platforms or a
on Win32 platforms. If the native thread has not been seen
previously, then a new thread identifier is allocated.
Get the native thread handle associated with a debugger thread identifier. Returns non-zero if OK, or zero if the debugger thread identifier is not yet associated with a native thread handle.
Set a flag that indicates if a native thread can stop at breakpoints. If set to 1 (the default), breakpoints will be active on the thread. If set to 0, breakpoints will be ignored on the thread. Typically this is used to mark threads associated with the debugger's user interface, or the virtual machine's finalization thread, so that they aren't accidentally suspended by the debugger (which might cause a deadlock).
Attach the current thread to a debugger. If stop_immediately
is non-zero, then the current thread immediately suspends, waiting for
the user to start it with
jit_debugger_run. This function is
typically called in a thread's startup code just before any "real work"
Detach the current thread from the debugger. This is typically called just before the thread exits.
Wait for the next debugger event to arrive. Debugger events typically indicate breakpoints that have occurred. The timeout is in milliseconds, or -1 for an infinite timeout period. Returns non-zero if an event has arrived, or zero on timeout.
Add a hard breakpoint to a debugger instance. The info structure defines the conditions under which the breakpoint should fire. The fields of info are as follows:
Flags that indicate which of the following fields should be matched.
If a flag is not present, then all possible values of the field will match.
Valid flags are
The thread to match against, if
JIT_DEBUGGER_FLAG_THREAD is set.
The function to match against, if
JIT_DEBUGGER_FLAG_FUNCTION is set.
data1 value to match against, if
data2 value to match against, if
The following special values for
data1 are recommended for marking
breakpoint locations with
Breakpoint location that corresponds to a source line. This is used to determine where to continue to upon a "step".
Breakpoint location that corresponds to the start of a function.
Breakpoint location that corresponds to the end of a function, just
prior to a
return statement. This is used to determine where
to continue to upon a "finish".
Breakpoint location that corresponds to an exception throw.
Remove a previously defined breakpoint from a debugger instance.
Remove all breakpoints from a debugger instance.
Determine if a particular thread is still alive.
Determine if a particular thread is currently running (non-zero) or stopped (zero).
Start the specified thread running, or continue from the last breakpoint.
This function, and the others that follow, sends a request to the specified thread and then returns to the caller immediately.
Step over a single line of code. If the line performs a method call, then this will step into the call. The request will be ignored if the thread is currently running.
Step over a single line of code but do not step into method calls. The request will be ignored if the thread is currently running.
Keep running until the end of the current function. The request will be ignored if the thread is currently running.
Force an explicit user breakpoint at the current location within the current thread. Control returns to the caller when the debugger calls one of the above "run" or "step" functions in another thread.
Sends a request to the thread that called
indicating that the debugger should quit.
Set a debugger hook on a JIT context. Returns the previous hook.
Debug hooks are a very low-level breakpoint mechanism. Upon reaching each breakpoint in a function, a user-supplied hook function is called. It is up to the hook function to decide whether to stop execution or to ignore the breakpoint. The hook function has the following prototype:
void hook(jit_function_t func, jit_nint data1, jit_nint data2);
func argument indicates the function that the breakpoint
occurred within. The
data2 arguments are
those supplied to
jit_insn_mark_breakpoint. The debugger can use
these values to indicate information about the breakpoint's type
Hook functions can be used for other purposes besides breakpoint debugging. For example, a program could be instrumented with hooks that tally up the number of times that each function is called, or which profile the amount of time spent in each function.
data1 values less than 10000 are intended for
use by user-defined hook functions. Values of 10000 and greater are
reserved for the full-blown debugger system described earlier.
|[ << ]||[ >> ]||[Top]||[Contents]||[Index]||[ ? ]|
This document was generated by Klaus Treichel on May, 11 2008 using texi2html 1.78.