xref: /aosp_15_r20/dalvik/docs/debugger.html (revision 055d459012065f78d96b68be8421640240ddf631) 
1*055d4590SKeyi Gui<html>
2*055d4590SKeyi Gui<head>
3*055d4590SKeyi Gui<title>Dalvik Debugger Support</title>
4*055d4590SKeyi Gui</head>
5*055d4590SKeyi Gui
6*055d4590SKeyi Gui<body>
7*055d4590SKeyi Gui<h1>Dalvik Debugger Support</h1>
8*055d4590SKeyi Gui
9*055d4590SKeyi Gui<p>
10*055d4590SKeyi GuiThe Dalvik virtual machine supports source-level debugging with many popular
11*055d4590SKeyi Guidevelopment environments.  Any tool that allows remote debugging over JDWP
12*055d4590SKeyi Gui(the
13*055d4590SKeyi Gui<a href="http://java.sun.com/javase/6/docs/technotes/guides/jpda/jdwp-spec.html">
14*055d4590SKeyi GuiJava Debug Wire Protocol</a>) is expected work.  Supported debuggers
15*055d4590SKeyi Guiinclude jdb, Eclipse, IntelliJ, and JSwat.
16*055d4590SKeyi Gui</p><p>
17*055d4590SKeyi GuiThe VM does not support tools based on JVMTI (Java Virtual
18*055d4590SKeyi GuiMachine Tool Interface).  This is a relatively intrusive approach that
19*055d4590SKeyi Guirelies on bytecode insertion, something the Dalvik VM does not currently
20*055d4590SKeyi Guisupport.
21*055d4590SKeyi Gui</p><p>
22*055d4590SKeyi GuiDalvik's implementation of JDWP also includes hooks for supporting
23*055d4590SKeyi GuiDDM (Dalvik Debug Monitor) features, notably as implemented by DDMS
24*055d4590SKeyi Gui(Dalvik Debug Monitor Server) and the Eclipse ADT plugin.  The protocol
25*055d4590SKeyi Guiand VM interaction is described in some detail
26*055d4590SKeyi Gui<a href="debugmon.html">here</a>.
27*055d4590SKeyi Gui</p><p>
28*055d4590SKeyi GuiAll of the debugger support in the VM lives in the <code>dalvik/vm/jdwp</code>
29*055d4590SKeyi Guidirectory, and is almost entirely isolated from the rest of the VM sources.
30*055d4590SKeyi Gui<code>dalvik/vm/Debugger.c</code> bridges the gap.  The goal in doing so
31*055d4590SKeyi Guiwas to make it easier to re-use the JDWP code in other projects.
32*055d4590SKeyi Gui</p><p>
33*055d4590SKeyi Gui
34*055d4590SKeyi Gui
35*055d4590SKeyi Gui<h2>Implementation</h2>
36*055d4590SKeyi Gui
37*055d4590SKeyi Gui<p>
38*055d4590SKeyi GuiEvery VM that has debugging enabled starts a "JDWP" thread.  The thread
39*055d4590SKeyi Guitypically sits idle until DDMS or a debugger connects.  The thread is
40*055d4590SKeyi Guionly responsible for handling requests from the debugger; VM-initated
41*055d4590SKeyi Guicommunication, such as notifying the debugger when the VM has stopped at
42*055d4590SKeyi Guia breakpoint, are sent from the affected thread.
43*055d4590SKeyi Gui</p><p>
44*055d4590SKeyi GuiWhen the VM is started from the Android app framework, debugging is enabled
45*055d4590SKeyi Guifor all applications when the system property <code>ro.debuggable</code>
46*055d4590SKeyi Guiis set to </code>1</code> (use <code>adb shell getprop ro.debuggable</code>
47*055d4590SKeyi Guito check it).  If it's zero, debugging can be enabled via the application's
48*055d4590SKeyi Guimanifest, which must include <code>android:debuggable="true"</code> in the
49*055d4590SKeyi Gui<code>&lt;application&gt;</code> element.
50*055d4590SKeyi Gui
51*055d4590SKeyi Gui</p><p>
52*055d4590SKeyi GuiThe VM recognizes the difference between a connection from DDMS and a
53*055d4590SKeyi Guiconnection from a debugger (either directly or in concert with DDMS).
54*055d4590SKeyi GuiA connection from DDMS alone doesn't result in a change in VM behavior,
55*055d4590SKeyi Guibut when the VM sees debugger packets it allocates additional data
56*055d4590SKeyi Guistructures and may switch to a different implementation of the interpreter.
57*055d4590SKeyi Gui</p><p>
58*055d4590SKeyi GuiPre-Froyo implementations of the Dalvik VM used read-only memory mappings
59*055d4590SKeyi Guifor all bytecode, which made it necessary to scan for breakpoints by
60*055d4590SKeyi Guicomparing the program counter to a set of addresses.  In Froyo this was
61*055d4590SKeyi Guichanged to allow insertion of breakpoint opcodes.  This allows the VM
62*055d4590SKeyi Guito execute code more quickly, and does away with the hardcoded limit
63*055d4590SKeyi Guiof 20 breakpoints.  Even with this change, however, the debug-enabled
64*055d4590SKeyi Guiinterpreter is much slower than the regular interpreter (perhaps 5x).
65*055d4590SKeyi Gui</p><p>
66*055d4590SKeyi GuiThe JDWP protocol is stateless, so the VM handles individual debugger
67*055d4590SKeyi Guirequests as they arrive, and posts events to the debugger as they happen.
68*055d4590SKeyi Gui</p><p>
69*055d4590SKeyi Gui
70*055d4590SKeyi Gui
71*055d4590SKeyi Gui<h2>Debug Data</h2>
72*055d4590SKeyi Gui<p> Source code debug data, which includes mappings of source code to
73*055d4590SKeyi Guibytecode and lists describing which registers are used to hold method
74*055d4590SKeyi Guiarguments and local variables, are optionally emitted by the Java compiler.
75*055d4590SKeyi GuiWhen <code>dx</code> converts Java bytecode to Dalvik bytecode, it must
76*055d4590SKeyi Guialso convert this debug data.
77*055d4590SKeyi Gui</p><p>
78*055d4590SKeyi Gui<code>dx</code> must also ensure that it doesn't perform operations
79*055d4590SKeyi Guithat confuse the debugger.  For example, re-using registers that hold
80*055d4590SKeyi Guimethod arguments and the "<code>this</code>" pointer is allowed in
81*055d4590SKeyi GuiDalvik bytecode if the values are never used or no longer needed.
82*055d4590SKeyi GuiThis can be very confusing for the debugger (and the programmer)
83*055d4590SKeyi Guisince the values have method scope and aren't expected to disappear.  For
84*055d4590SKeyi Guithis reason, <code>dx</code> generates sub-optimal code in some situations
85*055d4590SKeyi Guiwhen debugging support is enabled.
86*055d4590SKeyi Gui</p><p>
87*055d4590SKeyi GuiSome of the debug data is used for other purposes; in particular, having
88*055d4590SKeyi Guifilename and line number data is necessary for generating useful exception
89*055d4590SKeyi Guistack traces.  This data can be omitted by <code>dx</code> to make the DEX
90*055d4590SKeyi Guifile smaller.
91*055d4590SKeyi Gui</p><p>
92*055d4590SKeyi Gui
93*055d4590SKeyi Gui
94*055d4590SKeyi Gui<h2>Usage</h2>
95*055d4590SKeyi Gui
96*055d4590SKeyi Gui<p>
97*055d4590SKeyi GuiThe Dalvik VM supports many of the same command-line flags that other popular
98*055d4590SKeyi Guidesktop VMs do.  To start a VM with debugging enabled, you add a command-line
99*055d4590SKeyi Guiflag with some basic options.  The basic incantation looks something
100*055d4590SKeyi Guilike this:
101*055d4590SKeyi Gui
102*055d4590SKeyi Gui<pre>-Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=y</pre>
103*055d4590SKeyi Guior
104*055d4590SKeyi Gui<pre>-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=y</pre>
105*055d4590SKeyi Gui
106*055d4590SKeyi Gui</p><p>
107*055d4590SKeyi GuiAfter the initial prefix, options are provided as name=value pairs.  The
108*055d4590SKeyi Guioptions currently supported by the Dalvik VM are:
109*055d4590SKeyi Gui<dl>
110*055d4590SKeyi Gui    <dt>transport (no default)</dt>
111*055d4590SKeyi Gui    <dd>Communication transport mechanism to use.  Dalvik supports
112*055d4590SKeyi Gui    TCP/IP sockets (<code>dt_socket</code>) and connection over USB
113*055d4590SKeyi Gui    through ADB (<code>dt_android_adb</code>).
114*055d4590SKeyi Gui    </dd>
115*055d4590SKeyi Gui
116*055d4590SKeyi Gui    <dt>server (default='n')</dt>
117*055d4590SKeyi Gui    <dd>Determines whether the VM acts as a client or a server.  When
118*055d4590SKeyi Gui    acting as a server, the VM waits for a debugger to connect to it.
119*055d4590SKeyi Gui    When acting as a client, the VM attempts to connect to a waiting
120*055d4590SKeyi Gui    debugger.
121*055d4590SKeyi Gui    </dd>
122*055d4590SKeyi Gui
123*055d4590SKeyi Gui    <dt>suspend (default='n')</dt>
124*055d4590SKeyi Gui    <dd>If set to 'y', the VM will wait for a debugger connection
125*055d4590SKeyi Gui    before executing application code.  When the debugger connects (or
126*055d4590SKeyi Gui    when the VM finishes connecting to the debugger), the VM tells the
127*055d4590SKeyi Gui    debugger that it has suspended, and will not proceed until told
128*055d4590SKeyi Gui    to resume.  If set to 'n', the VM just plows ahead.
129*055d4590SKeyi Gui    </dd>
130*055d4590SKeyi Gui
131*055d4590SKeyi Gui    <dt>address (default="")</dt>
132*055d4590SKeyi Gui    <dd>This must be <code>hostname:port</code> when <code>server=n</code>,
133*055d4590SKeyi Gui    but can be just <code>port</code> when <code>server=y</code>.  This
134*055d4590SKeyi Gui    specifies the IP address and port number to connect or listen to.
135*055d4590SKeyi Gui    <br>
136*055d4590SKeyi Gui    Listening on port 0 has a special meaning: try to
137*055d4590SKeyi Gui    listen on port 8000; if that fails, try 8001, 8002, and so on.  (This
138*055d4590SKeyi Gui    behavior is non-standard and may be removed from a future release.)
139*055d4590SKeyi Gui    <br>This option has no meaning for <code>transport=dt_android_adb</code>.
140*055d4590SKeyi Gui    </dd>
141*055d4590SKeyi Gui
142*055d4590SKeyi Gui    <dt>help (no arguments)</dt>
143*055d4590SKeyi Gui    <dd>If this is the only option, a brief usage message is displayed.
144*055d4590SKeyi Gui    </dd>
145*055d4590SKeyi Gui
146*055d4590SKeyi Gui    <dt>launch, onthrow, oncaught, timeout</dt>
147*055d4590SKeyi Gui    <dd>These options are accepted but ignored.
148*055d4590SKeyi Gui    </dd>
149*055d4590SKeyi Gui</dl>
150*055d4590SKeyi Gui
151*055d4590SKeyi Gui</p><p>
152*055d4590SKeyi GuiTo debug a program on an Android device using DDMS over USB, you could
153*055d4590SKeyi Guiuse a command like this:
154*055d4590SKeyi Gui<pre>% dalvikvm -agentlib:jdwp=transport=dt_android_adb,suspend=y,server=y -cp /data/foo.jar Foo</pre>
155*055d4590SKeyi Gui
156*055d4590SKeyi GuiThis tells the Dalvik VM to run the program with debugging enabled, listening
157*055d4590SKeyi Guifor a connection from DDMS, and waiting for a debugger.  The program will show
158*055d4590SKeyi Guiup with an app name of "?" in the process list, because it wasn't started
159*055d4590SKeyi Guifrom the Android application framework.  From here you would connect your
160*055d4590SKeyi Guidebugger to the appropriate DDMS listen port (e.g.
161*055d4590SKeyi Gui<code>jdb -attach localhost:8700</code> after selecting it in the app list).
162*055d4590SKeyi Gui
163*055d4590SKeyi Gui</p><p>
164*055d4590SKeyi GuiTo debug a program on an Android device using TCP/IP bridged across ADB,
165*055d4590SKeyi Guiyou would first need to set up forwarding:
166*055d4590SKeyi Gui<pre>% adb forward tcp:8000 tcp:8000
167*055d4590SKeyi Gui% adb shell dalvikvm -agentlib:jdwp=transport=dt_socket,address=8000,suspend=y,server=y -cp /data/foo.jar Foo</pre>
168*055d4590SKeyi Guiand then <code>jdb -attach localhost:8000</code>.
169*055d4590SKeyi Gui</p><p>
170*055d4590SKeyi Gui(In the above examples, the VM will be suspended when you attach.  In jdb,
171*055d4590SKeyi Guitype <code>cont</code> to continue.)
172*055d4590SKeyi Gui</p><p>
173*055d4590SKeyi GuiThe DDMS integration makes the <code>dt_android_adb</code> transport much
174*055d4590SKeyi Guimore convenient when debugging on an Android device, but when working with
175*055d4590SKeyi GuiDalvik on the desktop it makes sense to use the TCP/IP transport.
176*055d4590SKeyi Gui</p><p>
177*055d4590SKeyi Gui
178*055d4590SKeyi Gui
179*055d4590SKeyi Gui<h2>Known Issues and Limitations</h2>
180*055d4590SKeyi Gui
181*055d4590SKeyi Gui</p><p>
182*055d4590SKeyi GuiMost of the optional features JDWP allows are not implemented.  These
183*055d4590SKeyi Guiinclude field access watchpoints and better tracking of monitors.
184*055d4590SKeyi Gui</p><p>
185*055d4590SKeyi GuiNot all JDWP requests are implemented.  In particular, anything that
186*055d4590SKeyi Guinever gets emitted by the debuggers we've used is not supported and will
187*055d4590SKeyi Guiresult in error messages being logged.  Support will be added when a
188*055d4590SKeyi Guiuse case is uncovered.
189*055d4590SKeyi Gui</p><p>
190*055d4590SKeyi Gui&nbsp;
191*055d4590SKeyi Gui</p><p>
192*055d4590SKeyi GuiThe debugger and garbage collector are somewhat loosely
193*055d4590SKeyi Guiintegrated at present.  The VM currently guarantees that any object the
194*055d4590SKeyi Guidebugger is aware of will not be garbage collected until after the
195*055d4590SKeyi Guidebugger disconnects.  This can result in a build-up over time while the
196*055d4590SKeyi Guidebugger is connected.  For example, if the debugger sees a running
197*055d4590SKeyi Guithread, the associated Thread object will not be collected, even after
198*055d4590SKeyi Guithe thread terminates.
199*055d4590SKeyi Gui</p><p>
200*055d4590SKeyi GuiThe only way to "unlock" the references is to detach and reattach the
201*055d4590SKeyi Guidebugger.
202*055d4590SKeyi Gui</p><p>
203*055d4590SKeyi Gui&nbsp;
204*055d4590SKeyi Gui</p><p>
205*055d4590SKeyi GuiThe translation from Java bytecode to Dalvik bytecode may result in
206*055d4590SKeyi Guiidentical sequences of instructions being combined.  This can make it
207*055d4590SKeyi Guilook like the wrong bit of code is being executed.  For example:
208*055d4590SKeyi Gui<pre>    int test(int i) {
209*055d4590SKeyi Gui        if (i == 1) {
210*055d4590SKeyi Gui            return 0;
211*055d4590SKeyi Gui        }
212*055d4590SKeyi Gui        return 1;
213*055d4590SKeyi Gui    }</pre>
214*055d4590SKeyi GuiThe Dalvik bytecode uses a common <code>return</code> instruction for both
215*055d4590SKeyi Gui<code>return</code> statements, so when <code>i</code> is 1 the debugger
216*055d4590SKeyi Guiwill single-step through <code>return 0</code> and then <code>return 1</code>.
217*055d4590SKeyi Gui</p><p>
218*055d4590SKeyi Gui&nbsp;
219*055d4590SKeyi Gui</p><p>
220*055d4590SKeyi GuiDalvik handles synchronized methods differently from other VMs.
221*055d4590SKeyi GuiInstead of marking a method as <code>synchronized</code> and expecting
222*055d4590SKeyi Guithe VM to handle the locks, <code>dx</code> inserts a "lock"
223*055d4590SKeyi Guiinstruction at the top of the method and an "unlock" instruction in a
224*055d4590SKeyi Guisynthetic <code>finally</code> block.  As a result, when single-stepping
225*055d4590SKeyi Guia <code>return</code> statement, the "current line" cursor may jump to
226*055d4590SKeyi Guithe last line in the method.
227*055d4590SKeyi Gui</p><p>
228*055d4590SKeyi GuiThis can also affect the way the debugger processes exceptions.  The
229*055d4590SKeyi Guidebugger may decide to break on an
230*055d4590SKeyi Guiexception based on whether that exception is "caught" or "uncaught".  To
231*055d4590SKeyi Guibe considered uncaught, there must be no matching <code>catch</code> block
232*055d4590SKeyi Guior <code>finally</code> clause between the current point of execution and
233*055d4590SKeyi Guithe top of the thread.  An exception thrown within or below a synchronized
234*055d4590SKeyi Guimethod will always be considered "caught", so the debugger won't stop
235*055d4590SKeyi Guiuntil the exception is re-thrown from the synthetic <code>finally</code> block.
236*055d4590SKeyi Gui</p><p>
237*055d4590SKeyi Gui
238*055d4590SKeyi Gui
239*055d4590SKeyi Gui<address>Copyright &copy; 2009 The Android Open Source Project</address>
240*055d4590SKeyi Gui</p>
241*055d4590SKeyi Gui
242*055d4590SKeyi Gui</body>
243*055d4590SKeyi Gui</html>
244