252 lines
15 KiB
Plaintext
252 lines
15 KiB
Plaintext
page.title=Using the Dalvik Debug Monitor
|
|
@jd:body
|
|
|
|
<p>Android ships with a debugging tool called the Dalvik Debug Monitor Server (DDMS),
|
|
which provides port-forwarding services, screen capture on the device, thread
|
|
and heap information on the device, logcat, process, and radio state information,
|
|
incoming call and SMS spoofing, location data spoofing, and more. This page
|
|
provides a modest discussion of DDMS features; it is not an exhaustive exploration of
|
|
all the features and capabilities.</p>
|
|
|
|
<p>DDMS ships in the <code>tools/</code> directory of the SDK.
|
|
Enter this directory from a terminal/console and type <code>ddms</code> (or <code>./ddms</code>
|
|
on Mac/Linux) to run it. DDMS will work with both the emulator and a connected device. If both are
|
|
connected and running simultaneously, DDMS defaults to the emulator.</p>
|
|
|
|
<h2 id="how-ddms-works">How DDMS works</h2>
|
|
<p>DDMS acts as a middleman to connect the IDE to the applications running on
|
|
the device. On Android, every application runs in its own process,
|
|
each of which hosts its own virtual machine (VM). And each process
|
|
listens for a debugger on a different port.</p>
|
|
|
|
<p>When it starts, DDMS connects to <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> and
|
|
starts a device monitoring service between the two, which will notify DDMS when a device is
|
|
connected or disconnected. When a device is connected, a VM monitoring service is created
|
|
between adb and DDMS, which will notify DDMS when a VM on the device is started
|
|
or terminated. Once a VM is running, DDMS retrieves the the VM's process ID (pid), via adb,
|
|
and opens a connection to the VM's debugger, through the adb daemon (adbd) on the device.
|
|
DDMS can now talk to the VM using a custom wire protocol.</p>
|
|
|
|
<p>For each VM on the device, DDMS opens a port upon which it will listen for a debugger. For the first VM, DDMS listens for a debugger on port 8600, the next on 8601, and so on. When a debugger connects to one of these ports, all traffic is forwarded between the debugger and the associated VM. Debugging can then process like any remote debugging session.</p>
|
|
|
|
<p>DDMS also opens another local port, the DDMS "base port" (8700, by default), upon which it also listens for a debugger. When a debugger connects to this base port, all traffic is forwarded to the VM currently selected in DDMS, so this is typically where you debugger should connect.</p>
|
|
|
|
<p>For more information on port-forwarding with DDMS,
|
|
read <a href="{@docRoot}guide/developing/debug-tasks.html#ide-debug-port">Configuring your IDE to attach
|
|
to port 8700 for debugging</a>.</p>
|
|
|
|
<p class="note"><strong>Tip:</strong>
|
|
You can set a number of DDMS preferences in <strong>File</strong> > <strong>Preferences</strong>.
|
|
Preferences are saved to "$HOME/.ddmsrc". </p>
|
|
|
|
<p class="warning"><strong>Known debugging issues with Dalvik</strong><br/>
|
|
Debugging an application in the Dalvik VM should work the same as it does
|
|
in other VMs. However, when single-stepping out of synchronized code, the "current line"
|
|
cursor may jump to the last line in the method for one step.</p>
|
|
|
|
|
|
<h2 id="left-pane">Left Pane</h2>
|
|
<p>The left side of the Debug Monitor shows each emulator/device currently found, with a list of
|
|
all the VMs currently running within each.
|
|
VMs are identified by the package name of the application it hosts.</p>
|
|
<p>Use this list to find and attach to the VM
|
|
running the activity(ies) that you want to debug. Next to each VM in the
|
|
list is a "debugger pass-through" port (in the right-most column).
|
|
If you connect your debugger to one of the the ports listed, you
|
|
will be connected to the corresponding VM on the device. However, when using
|
|
DDMS, you need only connect to port 8700, as DDMS forwards all traffic here to the
|
|
currently selected VM. (Notice, as you select a VM in the list, the listed port includes 8700.)
|
|
This way, there's no need to reconfigure the debugger's port each time you switch between VMs.</p>
|
|
<p>When an application running on the device calls {@link android.os.Debug#waitForDebugger()}
|
|
(or you select this option in the <a href="{@docRoot}guide/developing/debug-tasks.html#additionaldebugging">developer
|
|
options</a>), a red icon will be shown next to the client name, while it waits for the
|
|
debugger to attach to the VM. When a debugger is connected, the icon will turn green. </p>
|
|
<p>If you see a crossed-out bug icon, this means that the DDMS was unable to complete a
|
|
connection between the debugger and the VM because it was unable to open the VM's local port.
|
|
If you see this for all VMs on the device, it is likely because you have another instance of
|
|
DDMS running (this includes the Eclipse plugin).</p>
|
|
<p>If you see a question mark in place of an application package, this means that,
|
|
once DDMS received the application pid from adb, it
|
|
somehow failed to make a successful handshake with the VM process. Try restarting DDMS.</p>
|
|
|
|
|
|
<h2 id="right-pane">Right pane</h2>
|
|
<p>On the right side, the Debug Monitor provides tabs that display useful information
|
|
and some pretty cool tools.</p>
|
|
|
|
<h3 id="info">Info</h3>
|
|
<p>This view shows some general information about the selected VM, including the process
|
|
ID, package name, and VM version.</p>
|
|
|
|
<h3 id="threads">Threads</h3>
|
|
<p> The threads view has a list of threads running in the process of the target VM.
|
|
To reduce the amount
|
|
of data sent over the wire, the thread updates are only sent when explicitly
|
|
enabled by toggling the "threads" button
|
|
in the toolbar. This toggle is maintained per VM. This tab includes the following
|
|
information: </p>
|
|
<ul>
|
|
<li> <strong>ID</strong> - a VM-assigned unique thread ID. In Dalvik, these are
|
|
odd numbers starting from 3. </li>
|
|
<li> <strong>Tid</strong> - the Linux thread ID. For the main thread in a process,
|
|
this will match the process ID. </li>
|
|
<li> <strong>Status</strong> - the VM thread status. Daemon threads are
|
|
shown with an asterisk (*). This will be one of the following:
|
|
<ul>
|
|
<li> <em>running</em> - executing application code </li>
|
|
<li> <em>sleeping</em> - called Thread.sleep() </li>
|
|
<li> <em>monitor</em> - waiting to acquire a monitor lock </li>
|
|
<li> <em>wait</em> - in Object.wait() </li>
|
|
<li> <em>native</em> - executing native code </li>
|
|
<li> <em>vmwait</em> - waiting on a VM resource </li>
|
|
<li> <em>zombie</em> - thread is in the process of dying </li>
|
|
<li> <em>init</em> - thread is initializing (you shouldn't see this) </li>
|
|
<li> <em>starting</em> - thread is about to start (you shouldn't see
|
|
this either) </li>
|
|
</ul>
|
|
</li>
|
|
<li> <strong>utime</strong> - cumulative time spent executing user code, in "jiffies" (usually
|
|
10ms). </li>
|
|
<li> <strong>stime</strong> - cumulative time spent executing system code, in "jiffies" (usually
|
|
10ms). </li>
|
|
<li> <strong>Name</strong> - the name of the thread</li>
|
|
</ul>
|
|
<p> "ID" and "Name" are set when the thread is started. The remaining
|
|
fields are updated periodically (default is every 4 seconds). </p>
|
|
|
|
<h3 id="vm-heap">VM Heap</h3>
|
|
<p> Displays some heap stats, updated during garbage collection. If, when a VM is selected,
|
|
the VM Heap view says that heap updates are not enabled, click the "Show heap updates" button,
|
|
located in the top-left toolbar. Back in the VM Heap view, click <strong>Cause GC</strong>
|
|
to perform garbage collection and update the heap stats.</p>
|
|
|
|
|
|
<h3 id="allocation-tracker">Allocation Tracker</h3>
|
|
<p>In this view, you can track the memory allocation of each virtual machine.
|
|
With a VM selected in the left pane, click <strong>Start Tracking</strong>, then
|
|
<strong>Get Allocations</strong> to view all allocations since tracking started.
|
|
The table below will be filled with all the relevant
|
|
data. Click it again to refresh the list.</p>
|
|
|
|
|
|
<h3 id="emulator-control">Emulator Control</h3>
|
|
<p>With these controls, you can simulate special device states and activities.
|
|
Features include:</p>
|
|
<ul>
|
|
<li><strong>Telephony Status</strong> - change the state of the phone's Voice and Data plans
|
|
(home, roaming, searching, etc.), and simulate different kinds of network Speed and Latency
|
|
(GPRS, EDGE, UTMS, etc.).</li>
|
|
<li><strong>Telephony Actions</strong> - perform simulated phone calls and SMS messages to the emulator.</li>
|
|
<li><strong>Location Controls</strong> - send mock location data to the emulator so that you can perform
|
|
location-aware operations like GPS mapping.
|
|
|
|
<p>To use the Location Controls, launch your application in the Android emulator and open DDMS.
|
|
Click the Emulator Controls tab and scroll down to Location Controls.
|
|
From here, you can:</p>
|
|
<ul class="listhead">
|
|
<li>Manually send individual longitude/latitude coordinates to the device.
|
|
<p>Click <strong>Manual</strong>,
|
|
select the coordinate format, fill in the fields and click <strong>Send</strong>.
|
|
</p>
|
|
</li>
|
|
<li>Use a GPX file describing a route for playback to the device.
|
|
<p>Click <strong>GPX</strong> and load the file. Once loaded,
|
|
click the play button to playback the route for your location-aware application.</p>
|
|
<p>When performing playback from GPX, you can adjust the speed of
|
|
playback from the DDMS panel and control playback with the pause and skip buttons.
|
|
DDMS will parse both the waypoints (<code><wpt></code>, in the first table),
|
|
and the tracks (<code><trk></code>,
|
|
in the second table, with support for multiple segments, <code><trkseg></code>,
|
|
although they are simply
|
|
concatenated). Only the tracks can be played. Clicking a waypoint in the first list simply
|
|
sends its coordinate to the device, while selecting a track lets you play it.</p>
|
|
</li>
|
|
<li>Use a KML file describing individual placemarks for sequenced playback to the device.
|
|
<p>Click <strong>KML</strong> and load the file. Once loaded,
|
|
click the play button to send the coordinates to your location-aware application.</p>
|
|
<p>When using a KML file, it is parsed for a <code><coordinates></code>
|
|
element. The value of which should be a single
|
|
set of longitude, latitude and altitude figures. For example:</p>
|
|
<pre><coordinates>-122.084143,37.421972,4</coordinates></pre>
|
|
<p>In your file, you may include multiple <code><Placemark></code> elements, each containing
|
|
a <code><coordinates></code> element. When you do so, the collection of placemarks will
|
|
be added as tracks. DDMS will send one placemark per second to the device.</p>
|
|
<p>One way to generate a suitable KML file is to find a location in Google Earth.
|
|
Right-click the location entry that appears on the left and select "Save place as..."
|
|
with the save format set to Kml.</p>
|
|
<p class="note"><strong>Note:</strong> DDMS does not support routes created with the
|
|
<code><MultiGeometry><LineString>lat1, long1, lat2, long2, ....</LineString></MultiGeometry></code> methods.
|
|
There is also currently no support for the <code><TimeStamp></code> node inside
|
|
the <code><Placemark></code>.
|
|
Future releases may support timed placement and routes within a single coordinate element.</p>
|
|
</li>
|
|
</ul>
|
|
<p>For <em>additional</em> methods of setting up mocks of location-based data, see the
|
|
<a href="{@docRoot}guide/topics/location/index.html">Location</a> topic.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
<!-- <h4>Event Log</h4> -->
|
|
|
|
|
|
<h2 id="file-explorer">File Explorer</h2>
|
|
<p>With the File Explorer, you can view the device file system and perform basic management,
|
|
like pushing and pulling files. This circumvents using the <a href="{@docRoot}guide/developing/tools/adb.html">adb</a>
|
|
<code>push</code> and <code>pull</code> commands, with a GUI experience.</p>
|
|
<p>With DDMS open, select <strong>Device</strong> > <strong>File Explorer...</strong> to open the
|
|
File Explorer window. You can drag-and-drop into the device directories, but cannot drag <em>out</em> of them.
|
|
To copy files from the device, select the file and click the <strong>Pull File from Device</strong>
|
|
button in the toolbar. To delete files, use the <strong>Delete</strong> button in the toolbar.</p>
|
|
<p>If you're interested in using an SD card image on the emulator, you're still required to use
|
|
the <code>mksdcard</code> command to create an image, and then mount it during emulator bootup.
|
|
For example, from the <code>/tools</code> directory, execute:</p>
|
|
<pre>
|
|
<b>$</b> mksdcard 1024M ./img
|
|
<b>$</b> emulator -sdcard ./img
|
|
</pre>
|
|
<p>Now, when the emulator is running, the DDMS File Explorer will be able to read and write to the
|
|
sdcard directory. However, your files may not appear automatically. For example, if you add an
|
|
MP3 file to the sdcard, the media player won't see them until you restart the emulator. (When restarting
|
|
the emulator from command line, be sure to mount the sdcard again.)</p>
|
|
<p>For more information on creating an SD card image, see the
|
|
<a href="{@docRoot}guide/developing/tools/othertools.html#mksdcard">Other Tools</a> document.</p>
|
|
|
|
<h2 id="screen-capture">Screen Capture</h2>
|
|
<p>You can capture screen images on the device or emulator by selecting <strong>Device</strong>
|
|
> <strong>Screen capture...</strong> in the menu bar, or press CTRL-S.
|
|
Be sure to select a device first.</p>
|
|
|
|
<h2 id="exploring-processes">Exploring Processes</h2>
|
|
<p>You can see the output of <code>ps -x</code> for a specific VM by selecting <strong>Device</strong>
|
|
> <strong>Show process status</strong>... in the menu bar.</p>
|
|
|
|
<h2 id="cause-a-gc-to-occur">Cause a GC to Occur</h2>
|
|
<p>Cause garbage collection to occur in the selected application by pressing the trash can button on the toolbar. </p>
|
|
|
|
<h2 id="running-dumpsys-and-dumpstate">Running Dumpsys and Dumpstate on the Device (logcat)<a name="logcat" id="logcat"></a> </h2>
|
|
<ul>
|
|
<li>To run <strong>dumpsys</strong> (logcat) from Dalvik, select <strong>Device</strong> >
|
|
<strong>Run logcat...</strong> in the menu bar.</li>
|
|
<li>To run <strong>dumpstate</strong> from Dalvik, select <strong>Device</strong> > <strong>Dump device
|
|
state...</strong> in the menu bar. </li>
|
|
</ul>
|
|
|
|
<h2 id="examine-radio-state">Examine Radio State</h2>
|
|
<p>By default, radio state is not output during a standard logcat (it is a lot of
|
|
information). To see radio information, either click <strong>Device</strong> > <strong>Dump radio
|
|
state...</strong> or run logcat as described in <a href="{@docRoot}guide/developing/debug-tasks.html#logradio">Logging
|
|
Radio Information</a>. </p>
|
|
|
|
<h2 id="stop-a-vitrual-machine">Stop a Virtual Machine </h2>
|
|
<p>You can stop a virtual machine by selecting <strong>Actions</strong> > <strong>Halt
|
|
VM</strong>. Pressing this button causes the VM to call <code>Runtime.halt(1)</code>.</p>
|
|
|
|
<h2 id="known-issues" style="color:#FF0000">Known issues with DDMS </h2>
|
|
<p>DDMS has the following known limitations:</p>
|
|
<ul>
|
|
<li>If you connect and disconnect a debugger, ddms drops and reconnects the
|
|
client so the VM realizes that the debugger has gone away. This will be fixed
|
|
eventually. </li>
|
|
</ul>
|