upload android base code part3
This commit is contained in:
August
parent
71b83c22f1
commit
b9e30e05b1
15122 changed files with 2089659 additions and 0 deletions
243
android/dalvik/docs/debugger.html
Normal file
243
android/dalvik/docs/debugger.html
Normal file
|
|
@ -0,0 +1,243 @@
|
|||
<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 started from the Android app framework, debugging is enabled
|
||||
for all applications when the system property <code>ro.debuggable</code>
|
||||
is set to </code>1</code> (use <code>adb shell getprop ro.debuggable</code>
|
||||
to check it). If it's zero, debugging can be enabled via the application's
|
||||
manifest, which must include <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>
|
||||
Pre-Froyo implementations of the Dalvik VM used read-only memory mappings
|
||||
for all bytecode, which made it necessary to scan for breakpoints by
|
||||
comparing the program counter to a set of addresses. In Froyo this was
|
||||
changed to allow insertion of breakpoint opcodes. This allows the VM
|
||||
to execute code more quickly, and does away with the hardcoded limit
|
||||
of 20 breakpoints. Even with this change, however, 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. For example, if the debugger sees a running
|
||||
thread, the associated Thread object will not be collected, even after
|
||||
the thread terminates.
|
||||
</p><p>
|
||||
The only way to "unlock" the references is to detach and reattach the
|
||||
debugger.
|
||||
</p><p>
|
||||
|
||||
</p><p>
|
||||
The translation from Java bytecode to Dalvik bytecode may result in
|
||||
identical sequences of instructions being combined. This can make it
|
||||
look like the wrong bit of code is being executed. For example:
|
||||
<pre> int test(int i) {
|
||||
if (i == 1) {
|
||||
return 0;
|
||||
}
|
||||
return 1;
|
||||
}</pre>
|
||||
The Dalvik bytecode uses a common <code>return</code> instruction for both
|
||||
<code>return</code> statements, so when <code>i</code> is 1 the debugger
|
||||
will single-step through <code>return 0</code> and then <code>return 1</code>.
|
||||
</p><p>
|
||||
|
||||
</p><p>
|
||||
Dalvik handles synchronized methods differently from other VMs.
|
||||
Instead of marking a method as <code>synchronized</code> and expecting
|
||||
the VM to handle the locks, <code>dx</code> inserts a "lock"
|
||||
instruction at the top of the method and an "unlock" instruction in a
|
||||
synthetic <code>finally</code> block. As a result, when single-stepping
|
||||
a <code>return</code> statement, the "current line" cursor may jump to
|
||||
the last line in the method.
|
||||
</p><p>
|
||||
This can also affect the way the debugger processes exceptions. The
|
||||
debugger may decide to break on an
|
||||
exception based on whether that exception is "caught" or "uncaught". To
|
||||
be considered uncaught, there must be no matching <code>catch</code> block
|
||||
or <code>finally</code> clause between the current point of execution and
|
||||
the top of the thread. An exception thrown within or below a synchronized
|
||||
method will always be considered "caught", so the debugger won't stop
|
||||
until the exception is re-thrown from the synthetic <code>finally</code> block.
|
||||
</p><p>
|
||||
|
||||
|
||||
<address>Copyright © 2009 The Android Open Source Project</address>
|
||||
</p>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Loading…
Add table
Add a link
Reference in a new issue