docs/debugger.html

   1 <html>
   2 <head>
   3 <title>Dalvik Debugger Support</title>
   4 </head>
   5
   6 <body>
   7 <h1>Dalvik Debugger Support</h1>
   8
   9 <p>
  10 The Dalvik virtual machine supports source-level debugging with many popular
  11 development environments.  Any tool that allows remote debugging over JDWP
  12 (the
  13 <a href="http://java.sun.com/javase/6/docs/technotes/guides/jpda/jdwp-spec.html">
  14 Java Debug Wire Protocol</a>) is expected work.  Supported debuggers
  15 include jdb, Eclipse, IntelliJ, and JSwat.
  16 </p><p>
  17 The VM does not support tools based on JVMTI (Java Virtual
  18 Machine Tool Interface).  This is a relatively intrusive approach that
  19 relies on bytecode insertion, something the Dalvik VM does not currently
  20 support.
  21 </p><p>
  22 Dalvik's implementation of JDWP also includes hooks for supporting
  23 DDM (Dalvik Debug Monitor) features, notably as implemented by DDMS
  24 (Dalvik Debug Monitor Server) and the Eclipse ADT plugin.  The protocol
  25 and VM interaction is described in some detail
  26 <a href="debugmon.html">here</a>.
  27 </p><p>
  28 All of the debugger support in the VM lives in the <code>dalvik/vm/jdwp</code>
  29 directory, and is almost entirely isolated from the rest of the VM sources.
  30 <code>dalvik/vm/Debugger.c</code> bridges the gap.  The goal in doing so
  31 was to make it easier to re-use the JDWP code in other projects.
  32 </p><p>
  33
  34
  35 <h2>Implementation</h2>
  36
  37 <p>
  38 Every VM that has debugging enabled starts a "JDWP" thread.  The thread
  39 typically sits idle until DDMS or a debugger connects.  The thread is
  40 only responsible for handling requests from the debugger; VM-initated
  41 communication, such as notifying the debugger when the VM has stopped at
  42 a breakpoint, are sent from the affected thread.
  43 </p><p>
  44 When the VM is embedded in the Android framework,
  45 debugging is enabled in the VM unless the system property
  46 <code>ro.secure</code> is set to </code>1</code>.  On these
  47 "secure" devices, debugging is only enabled in app processes whose
  48 manifest contains <code>android:debuggable="true"</code> in the
  49 <code>&lt;application&gt;</code> element.
  50
  51 </p><p>
  52 The VM recognizes the difference between a connection from DDMS and a
  53 connection from a debugger (either directly or in concert with DDMS).
  54 A connection from DDMS alone doesn't result in a change in VM behavior,
  55 but when the VM sees debugger packets it allocates additional data
  56 structures and may switch to a different implementation of the interpreter.
  57 </p><p>
  58 Because Dalvik maps bytecode into memory read-only, some common
  59 techniques are difficult to implement without allocating additional memory.
  60 For example, suppose the debugger sets a breakpoint in a method.  The
  61 quick way to handle this is to insert a breakpoint instruction directly
  62 into the code.  When the instruction is reached, the breakpoint handler
  63 engages.  Without this, it's necessary to perform an "is there a breakpoint
  64 here" scan.  Even with some optimizations, the debug-enabled interpreter
  65 is much slower than the regular interpreter (perhaps 5x).
  66 </p><p>
  67 The JDWP protocol is stateless, so the VM handles individual debugger
  68 requests as they arrive, and posts events to the debugger as they happen.
  69 </p><p>
  70
  71
  72 <h2>Debug Data</h2>
  73 <p> Source code debug data, which includes mappings of source code to
  74 bytecode and lists describing which registers are used to hold method
  75 arguments and local variables, are optionally emitted by the Java compiler.
  76 When <code>dx</code> converts Java bytecode to Dalvik bytecode, it must
  77 also convert this debug data.
  78 </p><p>
  79 <code>dx</code> must also ensure that it doesn't perform operations
  80 that confuse the debugger.  For example, re-using registers that hold
  81 method arguments and the "<code>this</code>" pointer is allowed in
  82 Dalvik bytecode if the values are never used or no longer needed.
  83 This can be very confusing for the debugger (and the programmer)
  84 since the values have method scope and aren't expected to disappear.  For
  85 this reason, <code>dx</code> generates sub-optimal code in some situations
  86 when debugging support is enabled.
  87 </p><p>
  88 Some of the debug data is used for other purposes; in particular, having
  89 filename and line number data is necessary for generating useful exception
  90 stack traces.  This data can be omitted by <code>dx</code> to make the DEX
  91 file smaller.
  92 </p><p>
  93
  94
  95 <h2>Usage</h2>
  96
  97 <p>
  98 The Dalvik VM supports many of the same command-line flags that other popular
  99 desktop VMs do.  To start a VM with debugging enabled, you add a command-line
 100 flag with some basic options.  The basic incantation looks something
 101 like this:
 102
 103 <pre>-Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=y</pre>
 104 or
 105 <pre>-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=y</pre>
 106
 107 </p><p>
 108 After the initial prefix, options are provided as name=value pairs.  The
 109 options currently supported by the Dalvik VM are:
 110 <dl>
 111     <dt>transport (no default)</dt>
 112     <dd>Communication transport mechanism to use.  Dalvik supports
 113     TCP/IP sockets (<code>dt_socket</code>) and connection over USB
 114     through ADB (<code>dt_android_adb</code>).
 115     </dd>
 116
 117     <dt>server (default='n')</dt>
 118     <dd>Determines whether the VM acts as a client or a server.  When
 119     acting as a server, the VM waits for a debugger to connect to it.
 120     When acting as a client, the VM attempts to connect to a waiting
 121     debugger.
 122     </dd>
 123
 124     <dt>suspend (default='n')</dt>
 125     <dd>If set to 'y', the VM will wait for a debugger connection
 126     before executing application code.  When the debugger connects (or
 127     when the VM finishes connecting to the debugger), the VM tells the
 128     debugger that it has suspended, and will not proceed until told
 129     to resume.  If set to 'n', the VM just plows ahead.
 130     </dd>
 131
 132     <dt>address (default="")</dt>
 133     <dd>This must be <code>hostname:port</code> when <code>server=n</code>,
 134     but can be just <code>port</code> when <code>server=y</code>.  This
 135     specifies the IP address and port number to connect or listen to.
 136     <br>
 137     Listening on port 0 has a special meaning: try to
 138     listen on port 8000; if that fails, try 8001, 8002, and so on.  (This
 139     behavior is non-standard and may be removed from a future release.)
 140     <br>This option has no meaning for <code>transport=dt_android_adb</code>.
 141     </dd>
 142
 143     <dt>help (no arguments)</dt>
 144     <dd>If this is the only option, a brief usage message is displayed.
 145     </dd>
 146
 147     <dt>launch, onthrow, oncaught, timeout</dt>
 148     <dd>These options are accepted but ignored.
 149     </dd>
 150 </dl>
 151
 152 </p><p>
 153 To debug a program on an Android device using DDMS over USB, you could
 154 use a command like this:
 155 <pre>% dalvikvm -agentlib:jdwp=transport=dt_android_adb,suspend=y,server=y -cp /data/foo.jar Foo</pre>
 156
 157 This tells the Dalvik VM to run the program with debugging enabled, listening
 158 for a connection from DDMS, and waiting for a debugger.  The program will show
 159 up with an app name of "?" in the process list, because it wasn't started
 160 from the Android application framework.  From here you would connect your
 161 debugger to the appropriate DDMS listen port (e.g.
 162 <code>jdb -attach localhost:8700</code> after selecting it in the app list).
 163
 164 </p><p>
 165 To debug a program on an Android device using TCP/IP bridged across ADB,
 166 you would first need to set up forwarding:
 167 <pre>% adb forward tcp:8000 tcp:8000
 168 % adb shell dalvikvm -agentlib:jdwp=transport=dt_socket,address=8000,suspend=y,server=y -cp /data/foo.jar Foo</pre>
 169 and then <code>jdb -attach localhost:8000</code>.
 170 </p><p>
 171 (In the above examples, the VM will be suspended when you attach.  In jdb,
 172 type <code>cont</code> to continue.)
 173 </p><p>
 174 The DDMS integration makes the <code>dt_android_adb</code> transport much
 175 more convenient when debugging on an Android device, but when working with
 176 Dalvik on the desktop it makes sense to use the TCP/IP transport.
 177 </p><p>
 178
 179
 180 <h2>Known Issues and Limitations</h2>
 181
 182 </p><p>
 183 Most of the optional features JDWP allows are not implemented.  These
 184 include field access watchpoints and better tracking of monitors.
 185 </p><p>
 186 Not all JDWP requests are implemented.  In particular, anything that
 187 never gets emitted by the debuggers we've used is not supported and will
 188 result in error messages being logged.  Support will be added when a
 189 use case is uncovered.
 190 </p><p>
 191 &nbsp;
 192 </p><p>
 193 The debugger and garbage collector are somewhat loosely
 194 integrated at present.  The VM currently guarantees that any object the
 195 debugger is aware of will not be garbage collected until after the
 196 debugger disconnects.  This can result in a build-up over time while the
 197 debugger is connected.
 198 </p><p>
 199 The situation is exacerbated by a flaw in the exception processing code,
 200 which results in nearly all exceptions being added to the "do not discard"
 201 list, even if the debugger never sees them.  Having a debugger attached
 202 to a program that throws lots of exceptions can result in out-of-memory
 203 errors.  This will be fixed in a future release.
 204 </p><p>
 205
 206
 207 <address>Copyright &copy; 2009 The Android Open Source Project</address>
 208 </p>
 209
 210 </body>
 211 </html>