diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/dalvik-bytecode.html | 2 | ||||
| -rw-r--r-- | docs/debugger.html | 211 | ||||
| -rw-r--r-- | docs/instruction-formats.html | 10 | ||||
| -rw-r--r-- | docs/libraries.html | 2 |
4 files changed, 7 insertions, 218 deletions
diff --git a/docs/dalvik-bytecode.html b/docs/dalvik-bytecode.html index 4945d60f4..2bbffe6b0 100644 --- a/docs/dalvik-bytecode.html +++ b/docs/dalvik-bytecode.html @@ -1170,7 +1170,7 @@ round-to-nearest and gradual underflow, except where stated otherwise.</p> <td>float a;<br/> int64 result = (int64) a; </td> - <td>Conversion of <code>float</code> to <code>int64</code>, using + <td>Conversion of <code>float</code> to <code>int32</code>, using round-toward-zero. The same special case rules as for <code>float-to-int</code> apply here, except that out-of-range values get converted to either <code>0x7fffffffffffffff</code> or diff --git a/docs/debugger.html b/docs/debugger.html deleted file mode 100644 index 6e23f0df2..000000000 --- a/docs/debugger.html +++ /dev/null @@ -1,211 +0,0 @@ -<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> diff --git a/docs/instruction-formats.html b/docs/instruction-formats.html index d7bf69057..941689eb6 100644 --- a/docs/instruction-formats.html +++ b/docs/instruction-formats.html @@ -366,15 +366,15 @@ the correspondence.</p> <tr> <td>B|A|<i>op</i> DDCC H|G|F|E</td> <td>35fs</td> - <td><i>[<code>B=5</code>] <code>op</code></i> {vE, vF, vG, vH, vA}, + <td><i>[<code>B=5</code>] <code>op</code></i> vB, {vE, vF, vG, vH, vA}, vtaboff@CC, iface@DD<br/> - <i>[<code>B=4</code>] <code>op</code></i> {vE, vF, vG, vH}, + <i>[<code>B=4</code>] <code>op</code></i> vB, {vE, vF, vG, vH}, vtaboff@CC, iface@DD<br/> - <i>[<code>B=3</code>] <code>op</code></i> {vE, vF, vG}, + <i>[<code>B=3</code>] <code>op</code></i> vB, {vE, vF, vG}, vtaboff@CC, iface@DD<br/> - <i>[<code>B=2</code>] <code>op</code></i> {vE, vF}, + <i>[<code>B=2</code>] <code>op</code></i> vB, {vE, vF}, vtaboff@CC, iface@DD<br/> - <i>[<code>B=1</code>] <code>op</code></i> {vE}, + <i>[<code>B=1</code>] <code>op</code></i> vB, {vE}, vtaboff@CC, iface@DD<br/> </td> <td><i>(suggested format for statically linked <code>invoke-interface</code> diff --git a/docs/libraries.html b/docs/libraries.html index e1c3035f1..9fd199cca 100644 --- a/docs/libraries.html +++ b/docs/libraries.html @@ -34,7 +34,7 @@ concurrency, I/O, and more.</p> <ul> <li><a href="#vm-specific">Dalvik VM-specific libraries</a></li> - <li><a href="#interop">Java programming language interoperability + <li><a href="#interop">Jave programming language interoperability libraries</a></li> </ul> |