diff options
| author | The Android Open Source Project <initial-contribution@android.com> | 2009-03-02 22:54:18 -0800 |
|---|---|---|
| committer | The Android Open Source Project <initial-contribution@android.com> | 2009-03-02 22:54:18 -0800 |
| commit | 6dcac3deb3c19dc634470eb30b2daedf2b201bd4 (patch) | |
| tree | 2aa25fa8c8c3a9caeecf98fd8ac4cd9b12717997 /docs/debugger.html | |
| parent | 077f9d75d9701778830742b9c2afad4742635b58 (diff) | |
| download | android_dalvik-6dcac3deb3c19dc634470eb30b2daedf2b201bd4.tar.gz android_dalvik-6dcac3deb3c19dc634470eb30b2daedf2b201bd4.tar.bz2 android_dalvik-6dcac3deb3c19dc634470eb30b2daedf2b201bd4.zip | |
auto import from //depot/cupcake/@137055
Diffstat (limited to 'docs/debugger.html')
| -rw-r--r-- | docs/debugger.html | 211 |
1 files changed, 211 insertions, 0 deletions
diff --git a/docs/debugger.html b/docs/debugger.html new file mode 100644 index 000000000..6e23f0df2 --- /dev/null +++ b/docs/debugger.html @@ -0,0 +1,211 @@ +<html> +<head> +<title>Dalvik Debugger Support</title> +</head> + +<body> +<h1>Dalvik Debugger Support</h1> + +<p> +The Dalvik virtual machine supports source-level debugging with many popular +development environments. Any tool that allows remote debugging over JDWP +(the +<a href="http://java.sun.com/javase/6/docs/technotes/guides/jpda/jdwp-spec.html"> +Java Debug Wire Protocol</a>) is expected work. Supported debuggers +include jdb, Eclipse, IntelliJ, and JSwat. +</p><p> +The VM does not support tools based on JVMTI (Java Virtual +Machine Tool Interface). This is a relatively intrusive approach that +relies on bytecode insertion, something the Dalvik VM does not currently +support. +</p><p> +Dalvik's implementation of JDWP also includes hooks for supporting +DDM (Dalvik Debug Monitor) features, notably as implemented by DDMS +(Dalvik Debug Monitor Server) and the Eclipse ADT plugin. The protocol +and VM interaction is described in some detail +<a href="debugmon.html">here</a>. +</p><p> +All of the debugger support in the VM lives in the <code>dalvik/vm/jdwp</code> +directory, and is almost entirely isolated from the rest of the VM sources. +<code>dalvik/vm/Debugger.c</code> bridges the gap. The goal in doing so +was to make it easier to re-use the JDWP code in other projects. +</p><p> + + +<h2>Implementation</h2> + +<p> +Every VM that has debugging enabled starts a "JDWP" thread. The thread +typically sits idle until DDMS or a debugger connects. The thread is +only responsible for handling requests from the debugger; VM-initated +communication, such as notifying the debugger when the VM has stopped at +a breakpoint, are sent from the affected thread. +</p><p> +When the VM is embedded in the Android framework, +debugging is enabled in the VM unless the system property +<code>ro.secure</code> is set to </code>1</code>. On these +"secure" devices, debugging is only enabled in app processes whose +manifest contains <code>android:debuggable="true"</code> in the +<code><application></code> element. + +</p><p> +The VM recognizes the difference between a connection from DDMS and a +connection from a debugger (either directly or in concert with DDMS). +A connection from DDMS alone doesn't result in a change in VM behavior, +but when the VM sees debugger packets it allocates additional data +structures and may switch to a different implementation of the interpreter. +</p><p> +Because Dalvik maps bytecode into memory read-only, some common +techniques are difficult to implement without allocating additional memory. +For example, suppose the debugger sets a breakpoint in a method. The +quick way to handle this is to insert a breakpoint instruction directly +into the code. When the instruction is reached, the breakpoint handler +engages. Without this, it's necessary to perform an "is there a breakpoint +here" scan. Even with some optimizations, the debug-enabled interpreter +is much slower than the regular interpreter (perhaps 5x). +</p><p> +The JDWP protocol is stateless, so the VM handles individual debugger +requests as they arrive, and posts events to the debugger as they happen. +</p><p> + + +<h2>Debug Data</h2> +<p> Source code debug data, which includes mappings of source code to +bytecode and lists describing which registers are used to hold method +arguments and local variables, are optionally emitted by the Java compiler. +When <code>dx</code> converts Java bytecode to Dalvik bytecode, it must +also convert this debug data. +</p><p> +<code>dx</code> must also ensure that it doesn't perform operations +that confuse the debugger. For example, re-using registers that hold +method arguments and the "<code>this</code>" pointer is allowed in +Dalvik bytecode if the values are never used or no longer needed. +This can be very confusing for the debugger (and the programmer) +since the values have method scope and aren't expected to disappear. For +this reason, <code>dx</code> generates sub-optimal code in some situations +when debugging support is enabled. +</p><p> +Some of the debug data is used for other purposes; in particular, having +filename and line number data is necessary for generating useful exception +stack traces. This data can be omitted by <code>dx</code> to make the DEX +file smaller. +</p><p> + + +<h2>Usage</h2> + +<p> +The Dalvik VM supports many of the same command-line flags that other popular +desktop VMs do. To start a VM with debugging enabled, you add a command-line +flag with some basic options. The basic incantation looks something +like this: + +<pre>-Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=y</pre> +or +<pre>-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=y</pre> + +</p><p> +After the initial prefix, options are provided as name=value pairs. The +options currently supported by the Dalvik VM are: +<dl> + <dt>transport (no default)</dt> + <dd>Communication transport mechanism to use. Dalvik supports + TCP/IP sockets (<code>dt_socket</code>) and connection over USB + through ADB (<code>dt_android_adb</code>). + </dd> + + <dt>server (default='n')</dt> + <dd>Determines whether the VM acts as a client or a server. When + acting as a server, the VM waits for a debugger to connect to it. + When acting as a client, the VM attempts to connect to a waiting + debugger. + </dd> + + <dt>suspend (default='n')</dt> + <dd>If set to 'y', the VM will wait for a debugger connection + before executing application code. When the debugger connects (or + when the VM finishes connecting to the debugger), the VM tells the + debugger that it has suspended, and will not proceed until told + to resume. If set to 'n', the VM just plows ahead. + </dd> + + <dt>address (default="")</dt> + <dd>This must be <code>hostname:port</code> when <code>server=n</code>, + but can be just <code>port</code> when <code>server=y</code>. This + specifies the IP address and port number to connect or listen to. + <br> + Listening on port 0 has a special meaning: try to + listen on port 8000; if that fails, try 8001, 8002, and so on. (This + behavior is non-standard and may be removed from a future release.) + <br>This option has no meaning for <code>transport=dt_android_adb</code>. + </dd> + + <dt>help (no arguments)</dt> + <dd>If this is the only option, a brief usage message is displayed. + </dd> + + <dt>launch, onthrow, oncaught, timeout</dt> + <dd>These options are accepted but ignored. + </dd> +</dl> + +</p><p> +To debug a program on an Android device using DDMS over USB, you could +use a command like this: +<pre>% dalvikvm -agentlib:jdwp=transport=dt_android_adb,suspend=y,server=y -cp /data/foo.jar Foo</pre> + +This tells the Dalvik VM to run the program with debugging enabled, listening +for a connection from DDMS, and waiting for a debugger. The program will show +up with an app name of "?" in the process list, because it wasn't started +from the Android application framework. From here you would connect your +debugger to the appropriate DDMS listen port (e.g. +<code>jdb -attach localhost:8700</code> after selecting it in the app list). + +</p><p> +To debug a program on an Android device using TCP/IP bridged across ADB, +you would first need to set up forwarding: +<pre>% adb forward tcp:8000 tcp:8000 +% adb shell dalvikvm -agentlib:jdwp=transport=dt_socket,address=8000,suspend=y,server=y -cp /data/foo.jar Foo</pre> +and then <code>jdb -attach localhost:8000</code>. +</p><p> +(In the above examples, the VM will be suspended when you attach. In jdb, +type <code>cont</code> to continue.) +</p><p> +The DDMS integration makes the <code>dt_android_adb</code> transport much +more convenient when debugging on an Android device, but when working with +Dalvik on the desktop it makes sense to use the TCP/IP transport. +</p><p> + + +<h2>Known Issues and Limitations</h2> + +</p><p> +Most of the optional features JDWP allows are not implemented. These +include field access watchpoints and better tracking of monitors. +</p><p> +Not all JDWP requests are implemented. In particular, anything that +never gets emitted by the debuggers we've used is not supported and will +result in error messages being logged. Support will be added when a +use case is uncovered. +</p><p> + +</p><p> +The debugger and garbage collector are somewhat loosely +integrated at present. The VM currently guarantees that any object the +debugger is aware of will not be garbage collected until after the +debugger disconnects. This can result in a build-up over time while the +debugger is connected. +</p><p> +The situation is exacerbated by a flaw in the exception processing code, +which results in nearly all exceptions being added to the "do not discard" +list, even if the debugger never sees them. Having a debugger attached +to a program that throws lots of exceptions can result in out-of-memory +errors. This will be fixed in a future release. +</p><p> + + +<address>Copyright © 2009 The Android Open Source Project</address> +</p> + +</body> +</html> |